meshcat

library0.3.2pypypi✓ verified 21d ago

MeshCat is a remotely-controllable WebGL-based 3D visualizer for Python, built on top of three.js. It allows users to create 3D visualizations of geometries, mechanisms, and robots with a scene graph approach, communicating with a browser-based viewer via WebSockets. The current version is 0.3.2.

web-framework http-networking data

pip install meshcat

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MESHCAT

meshcat

web-frameworkpythonv0.3.2

Install

8.7s avg

Import

1321ms

Disk

190MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.360s · 197.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 8.7s · import 1.282s · 191MB

190MB installed

● package 190MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Visualizer

✓ import meshcat vis = meshcat.Visualizer()

geometry

✓ import meshcat.geometry as g

transformations

✓ import meshcat.transformations as tf

Initializes a MeshCat visualizer, opens it in a web browser, and displays a red box and a blue sphere. The example demonstrates setting objects at the root and at a sub-path, and applying transformations.

import meshcat import meshcat.geometry as g import meshcat.transformations as tf # Create a new visualizer. This will launch a local server # and typically open a browser window with the visualization. vis = meshcat.Visualizer().open() # You can also get the URL to open it manually: # print(f"MeshCat URL: {vis.url()}") # Set a red box at the root of the scene vis.set_object(g.Box([0.2, 0.2, 0.2]), g.MeshPhongMaterial(color=0xff0000)) # Move the box slightly along the x-axis vis.set_transform(tf.translation_matrix([0.5, 0, 0])) # Add a blue sphere at a sub-path within the scene tree vis["sphere"].set_object(g.Sphere(0.1), g.MeshPhongMaterial(color=0x0000ff)) vis["sphere"].set_transform(tf.translation_matrix([0, 0.5, 0])) print("Visualization created. Check your browser window or the URL printed above.")

meshcat-server --version

Debug

Known issues

deprecatedThe `zmq.eventloop.ioloop` module used internally by older `meshcat` versions is deprecated in `pyzmq` 17+. While `meshcat` typically handles this gracefully, direct usage or older environments might show warnings.

fix

Upgrade `meshcat` and `pyzmq` if available; otherwise, be aware of the warning. The `meshcat-python` project mentions this issue but has not released a new version since `0.3.2`.

affects: <=0.3.2

gotchaMeshCat has known limitations with DAE (Collada) files, particularly regarding scaling and display. They may not appear or scale correctly in the viewer.

fix

Consider converting DAE files to other supported formats like STL, or manually adjusting `meshScale` if using a wrapper like `pinocchio.visualize.MeshcatVisualizer`.

affects: All

gotchaWhen integrating with simulation environments (e.g., Drake), the default visualization update frequency of MeshCat might cause initial conditions or very fast state changes to be visually missed or incorrectly displayed. The visualization might lag behind the simulation's true initial state.

fix

Increase the `frames_per_second` parameter when initializing or recording the MeshCat visualization if your integration allows.

affects: All

gotchaConverting MeshCat animations to video files requires `ffmpeg` to be installed on your system. If `ffmpeg` is not found, the video conversion functions will fail silently or with an error about `ffmpeg` not being callable.

fix

Ensure `ffmpeg` is installed and accessible in your system's PATH. For Linux, `sudo apt install ffmpeg` or similar. For macOS, `brew install ffmpeg`.

affects: All

Errors

Common errors & fixes

ERR_CONNECTION_REFUSED

This error typically indicates that the browser could not connect to the MeshCat server, often due to the server not running, a firewall blocking the port, a port conflict, or issues in virtualized environments like WSL or Docker where localhost forwarding might be misconfigured.

fix

Ensure the MeshCat server is running (e.g., by calling `vis.open()` in your Python script or `meshcat-server` in a terminal). Check for other processes using the same port. If in WSL, ensure port forwarding is correctly set up between WSL2 and Windows. For Docker, ensure ports are exposed and mapped correctly. Sometimes, trying `127.0.0.1` instead of `localhost` in the browser URL can help.

AttributeError: 'pydrake.geometry.Meshcat' object has no attribute 'SetCameraPose'

This `AttributeError` often occurs when trying to use a method that was recently added to the `meshcat` or `pydrake` library, and the installed version is too old to contain that specific function.

fix

Upgrade your `meshcat` and/or `pydrake` installation to a newer version that includes the desired method. For `pydrake`, this might involve using a nightly build or a more recent stable release.

meshcat-server not working / WARNING:tornado.access:404 GET /static/

When trying to start the MeshCat server from the command line, `meshcat-server` might not be correctly found in the system's PATH, or the server itself might start but fail to serve static files, leading to a 404 error in the browser.

fix

Instead of just `meshcat-server`, try running the server using `python -m meshcat.servers.zmqserver` or `python -m meshcat` if that entry point is configured. This explicitly tells Python to run the module, bypassing potential PATH issues.

MeshCat not displaying models (only origin axes visible) in Jupyter/Colab

In environments like Jupyter Notebooks, JupyterLab, or Google Colab, MeshCat visualizations might fail to display complex models, sometimes showing only the coordinate axes. This can be due to `ngrok` limitations (historically on Colab), issues with embedding iframes, or the default `frames_per_second` being too low for dynamic simulations.

fix

For Google Colab or Jupyter, ensure you are using `vis.jupyter_cell()` or `vis.url()` to get the correct display or URL. If models are still not showing, consider converting DAE files to other formats like STL if possible, as DAE loading can be problematic. When animating, increase the `frames_per_second` parameter during initialization or recording to ensure all state changes are visualized.

Upgrade

Version history

0.3.2latest on PyPI · released Nov 7, 2021

Audit

Dependencies

pyzmqrequiredCore library for ZeroMQ communication with the MeshCat server.

tornadorequiredUsed for the MeshCat web server backend.

u-msgpack-pythonrequiredEfficient MessagePack serialization for transferring data to the viewer.

numpyrequiredCommonly used for defining geometries and transformations.

PillowoptionalRequired for using image textures in MeshCat geometries.

pyngrokoptionalEnables exposing the local MeshCat server publicly, e.g., for use in cloud notebooks like Google Colab.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/rdeits/meshcat-python ↗

packagehttps://pypi.org/project/meshcat/ ↗

homepagehttps://meshcat.mit.edu ↗