Introduction

The pythreejs API attempts to mimic the three.js API as closely as possible, so any resource on its API should also be helpful for understanding pythreejs. See for example the official three.js documentation.

The major difference between the two is the render loop. As we normally do not want to call back to the kernel for every rendered frame, some helper classes have been created to allow for user interaction with the scene with minimal overhead:

Renderer classes

While the WebGLRenderer class mimics its three.js counterpart in only rendering frames on demand (one frame per call to its render() method), the Renderer class sets up an interactive render loop allowing for Interactive controls and Animation views. Similarly, a Preview widget allows for a quick visualization of various threejs objects.

Interactive controls

These are classes for managing user interaction with the WebGL canvas, and translating that into actions. One example is the OrbitControls class, which allows the user to control the camera by zooming, panning, and orbital rotation around a target. Another example is the Picker widget, which allows for getting the objects and surface coordinates underneath the mouse cursor.

To use controls, pass them to the renderer, e.g.:

Renderer(controls=[OrbitControls(...), ...], ...)

Animation views

The view widgets for the AnimationAction class gives interactive controls to the user for controlling a threejs animation.

Other notable deviations from the threejs API are listed below:

  • Buffers are based on numpy arrays, with their inbuilt knowledge of shape and dtype. As such, most threejs APIs that take a buffer are slightly modified (fewer options need to be specified explicitly).

  • The generative geometry objects (e.g. SphereGeometry and BoxBufferGeometry) do not sync their vertices or similar data by default. To gain acess to the generated data, convert them to either the Geometry or BufferGeometry type with the from_geometry() factory method.

  • Methods are often not mirrored to the Python side. However, they can be executed with the exec_three_obj_method() method. Consider contributing to make methods directly available. Possibly, these can be auto-generated as well.