pythreejs

2.4.2 · active · verified Fri Apr 17

pythreejs provides interactive 3D graphics for the Jupyter Notebook and JupyterLab environments, leveraging the popular Three.js JavaScript library and Jupyter Widgets. It allows Python users to create and manipulate 3D scenes directly within their notebooks. The current version is 2.4.2, and it typically sees a few releases per year, often tracking updates in Three.js or Jupyter widgets.

Common errors

```
ModuleNotFoundError: No module named 'pythreejs'
```
cause The pythreejs library is not installed in your Python environment.

fix Run `pip install pythreejs` to install the package.
```
Widget Javascript not detected. Please confirm the Jupyter server is running the widgetsnbextension.
```
cause Jupyter's widget extension is not properly enabled or detected by your Jupyter server, which is necessary for interactive widgets like pythreejs to display.

fix Try restarting your Jupyter kernel. If the issue persists, ensure `ipywidgets` is installed (`pip install ipywidgets`) and for older Jupyter versions, you might need to manually enable the extension: `jupyter nbextension enable --py widgetsnbextension --sys-prefix` and `jupyter labextension install @jupyter-widgets/jupyterlab-manager` for JupyterLab.
```
The 3D canvas appears blank or shows an empty grey box, even after running the code.
```
cause Common causes include an incorrectly positioned camera (too far, too close, or pointing away), no light sources in the scene (if using `MeshStandardMaterial`), or objects being outside the camera's view frustum.

fix Verify camera position, target, and `fov`. Ensure there are appropriate light sources (e.g., `DirectionalLight`, `AmbientLight`) in your scene, especially if using materials that react to light. Check object positions relative to the origin and camera.

Warnings

gotcha pythreejs is a Jupyter widget. It will only render correctly within a Jupyter Notebook or JupyterLab environment. Running code outside of these environments (e.g., in a standard Python script or IDE console) will not display the 3D output.
Fix: Ensure you are running your pythreejs code within a Jupyter Notebook or JupyterLab. For older Jupyter installations, you might need to manually enable the widgetsnbextension (`jupyter nbextension enable --py widgetsnbextension`).
gotcha Performance can degrade rapidly with very complex scenes or a large number of objects. While pythreejs leverages the efficient Three.js library, rendering in a browser context through Jupyter still has limitations.
Fix: Optimize your scene: use `BufferGeometry` for custom meshes, merge static meshes where possible, reduce polygon count, and be mindful of the number of active lights and post-processing effects.
breaking pythreejs closely follows the Three.js API. While it aims to abstract most changes, significant updates in underlying Three.js versions can occasionally lead to changes in how certain properties are set or how objects are constructed.
Fix: Always consult the pythreejs documentation or examples for your specific version if you encounter unexpected behavior after an update, especially if it relates to object properties or constructor arguments.

Install

pip install pythreejs Install pythreejs

Imports

Scene
```
from pythreejs import Scene
```
PerspectiveCamera
```
from pythreejs import PerspectiveCamera
```
WebGLRenderer
```
from pythreejs import WebGLRenderer
```
Mesh
```
from pythreejs import Mesh
```
BoxGeometry
```
from pythreejs import BoxGeometry
```

MeshStandardMaterial

from pythreejs import MeshStandardMaterial

OrbitControls
```
from pythreejs import OrbitControls
```
Used for interactive camera control within the renderer.

Quickstart

This quickstart demonstrates how to create a simple 3D scene with a red cube, set up a camera, and render it using `pythreejs` within a Jupyter Notebook or JupyterLab environment. It also includes `OrbitControls` for interactive camera navigation.

from pythreejs import Scene, PerspectiveCamera, WebGLRenderer, Mesh, BoxGeometry, MeshStandardMaterial, OrbitControls
from IPython.display import display

# Create a basic scene with a red cube
scene = Scene(children=[
    Mesh(
        geometry=BoxGeometry(1, 1, 1),
        material=MeshStandardMaterial(color='red')
    )
])

# Set up a camera
camera = PerspectiveCamera(position=[3, 3, 3], fov=60, aspect=1.5)

# Create a WebGL renderer and attach the scene and camera
# Add OrbitControls for interactive camera movement
renderer = WebGLRenderer(
    scene=scene,
    camera=camera,
    controls=[OrbitControls(controlling=camera)]
)
renderer.width = 600
renderer.height = 400

# Display the interactive 3D renderer in a Jupyter environment
display(renderer)

view raw JSON →