Canvas3D

class scenepic.Canvas3D

Represents a ScenePic Canvas3D - a 3D viewport that can contain a number of Frame3Ds.

property camera

Set of Camera parameters for the Canvas.

Type:

Camera

property canvas_id

A unique identifier for the canvas

Type:

str

clear_script()

Call this if you are dumping a ScenePic script in multiple parts, e.g. for client-server interactions, or when chunking a large visualization into multiple files.

create_frame(frame_id='', focus_point=None, meshes=None, camera=None)

Creates a new Frame3D object and appends to the list of Frame3Ds in the Canvas3D.

Parameters:

  • frame_id (str) – a unique identifier for the Frame3D (will be automatically populated if not provided).

  • focus_point (FocusPoint) – optional 3D focus point for this frame (with optional 3D rotation for orientation lock), used in the ScenePic user interface.

  • meshes (List[Union[Mesh, MeshUpdate, str]]) – optionally pre-populate this Frame3D with a set of Meshes, for convenience.

  • camera (Camera) – optionally set a camera for this frame

Returns:

a new Frame3D object

Return type:

Frame3D

property focus_point

Default focus point for the canvas.

Type:

FocusPoint

property height

The height of the Canvas

Type:

float

property media_id

The ID of the attached media file.

This file will be used to drive playback, i.e. frames will be displayed in time with the playback of the media file.

Type:

str

set_layer_settings(layer_settings)

Specify the visibilities and opacities of certain mesh layers.

Description:

Each Mesh object can optionally be part of a user-identified layer (see Mesh constructor). Calling set_layer_settings will result in an additional drop-down selector in the ScenePic user interface.

Parameters:

  • self (Canvas3D) – the self reference

  • layer_settings (Mapping[str, Union[dict, LayerSettings]]) – a LayerSettings object or a dictionary. See LayerSettings for details.

property shading

Set of Shading parameters for the Canvas.

Type:

Shading

property ui_parameters

Set of user interface parameters

Type:

UIParameters

property width

The width of the Canvas

Type:

float

Frame3D

class scenepic.Frame3D

Represents a frame of an animation which contains a number of transformed Mesh objects.

add_label()

Add a label to the frame.

Parameters:

  • label (Label) – the label to add

  • position (np.ndarray) – the float32 [x, y, z] position at which to put the label

add_mesh(mesh, transform=None)

Adds a mesh to the frame.

Parameters:

  • mesh (Union[Mesh, MeshUpdate, str]) – The mesh, mesh update, or mesh ID

  • transform (np.ndarray, optional) – An optional transform to apply to the mesh. Defaults to None.

add_meshes(meshes, transform=None)

Adds meshes to the frame.

Parameters:

  • meshes (List[Union[Mesh, MeshUpdate, str]]) – A list of meshes and mesh updates (or their IDs)

  • transform (np.ndarray, optional) – an optional transform to apply to each mesh. Defaults to None.

property camera

The camera for the frame. This property can be used to create cinematic camera movement within a ScenePic, but the user can choose to override the camera track at any time. If they reset to the original camera, however, it will make subsequent frames use the specified camera parameters.

Type:

Camera

property focus_point

The focus point of the frame

Type:

FocusPoint

set_layer_settings(layer_settings)

Specify the visibilities and opacities of certain mesh layers.

Description:

Each Mesh object can optionally be part of a user-identified layer (see Mesh constructor). Calling set_layer_settings will result in an additional drop-down selector in the ScenePic user interface.

Parameters:

layer_settings (Mapping[str, Union[dict, LayerSettings]]) – a LayerSettings object or a dictionary. See LayerSettings for details.

Mesh

class scenepic.Mesh

The basic ScenePic mesh class, containing vertex, triangle, and line buffers. To allow for compatibility with Numpy, we use row major order, so each data point is stored as a row for efficiency. Vertex buffer contains float32 elements with structure: x,y,z, and the normal buffer contains elements: nx,ny,nz.

If shared_color is set then per-vertex color [cr,cg,cb,ca] in the color buffer is omitted to save memory.

If texture_id is None then per-vertex texture coordinates [tu, tv] in the uv buffer are omitted to save memory.

Right handed coordinate system used throughout.

Triangle winding order is counter clockwise.

Parameters:

  • shared_color (Color, optional) – shared color for all objects in the mesh. Defaults to None.

  • texture_id (str, optional) – The ID of the Image to use as a texture. Defaults to None.

add_camera_frustum()

Add a camera frustum visualization to this Mesh.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • fov_y_degrees (float, optional) – vertical field of view in degrees. Defaults to 45.0.

  • aspect_ratio (float, optional) – aspect ratio of field of view (width/height). Defaults to 16/9.

  • depth (float, optional) – depth of the frustum. Defaults to 1.0.

  • thickness (float, optional) – thickness of the edges. Defaults to 0.02.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

Add a camera frustum visualization to this Mesh.

Parameters:

  • camera (Camera, optional) – the camera to use for the frustum

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • thickness (float, optional) – thickness of the edges. Defaults to 0.02.

  • depth (float, optional) – depth of the frustum. Defaults to 1.0.

add_camera_image()

Add the image plane for a camera into the scene.

Parameters:

  • camera (Camera, optional) – the ScenePic Camera corresponding to the image.

  • depth (float, optional) – depth of the frustum. Defaults to 1.0.

add_cone()

Add a cone to this Mesh. The cone has base center at [0.5, 0., 0.] and apex at [-0.5, 0., 0.].

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • truncation_height (float, optional) – draws a truncated cone of this height. Defaults to 1.

  • lat_count (int, optional) – number of discrete samples in latitude. Defaults to 10.

  • long_count (int, optional) – number of discrete samples in longitude. Defaults to 10.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_coordinate_axes()

Add a set of coordinate axes to this Mesh. xyz axes map to RGB colors.

Parameters:

  • length (float, optional) – length of axes. Defaults to 1.0.

  • thickness (float, optional) – thickness of axes. Defaults to 0.1.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

add_cube()

Add a unit diameter cube to this mesh.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform matrix. Defaults to None.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_cylinder()

Add a x-axis aligned unit diameter cylinder to this Mesh.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • segment_count (int, optional) – number of segments in the cylinder. Defaults to 10.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_disc()

Add a x-axis aligned unit diameter disc to this Mesh.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • segment_count (int, optional) – number of segments in the disc. Defaults to 10.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_icosphere()

Add a unit diameter ico-sphere to this Mesh

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • steps (int, optional) – number of subdivision steps to apply to the icosahedron base primitive. Defaults to 0.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_image()

Add an image as a textured quad to this Mesh. The Mesh must have a texture_id.

Parameters:

  • origin (np.ndarray, optional) – bottom left corner of image. Defaults to (-0.5, -0.5, 0).

  • x_axis (np.ndarray, optional) – direction and length of the x-axis of the image in world space. Defaults to (1, 0, 0).

  • y_axis (np.ndarray, optional) – direction and length of the y-axis of the image in world space. Defaults to (0, 1, 0).

  • normal (np.ndarray, optional) – will be computed automatically if None. Defaults to None.

  • uv_0 (np.ndarray, optional) – the bottom left uv coordinate. Defaults to (0, 0).

  • uv_1 (np.ndarray, optional) – the top left uv coordinate. Defaults to (1, 0).

  • uv_2 (np.ndarray, optional) – the tp right uv coordinate. Defaults to (1, 1).

  • uv_3 (np.ndarray, optional) – the bottom right uv coordinate. Defaults to (0, 1).

  • double_sided (bool, optional) – whether the image should be shown on both sides. Defaults to True.

  • transform (np.ndarray, optional) – a 3D homogeneous transform matrix. Defaults to None.

add_lines()

Add a line cloud to this Mesh.

Parameters:

  • start_points (np.ndarray) – float32 matrix of [N, 3] line start positions (or [N, 6] positions with colors)

  • end_points (np.ndarray) – float32 matrix of [N, 3] line end positions (or [N, 6] positions with colors)

  • color (np.ndarray, optional) – if provided, will override any per-point colors stored in start_colors and end_colors. Defaults to None.

  • transform (np.ndarray) – homogeneous 3D transform. Defaults to None.

add_mesh()

Add a triangle mesh to this ScenePic Mesh, with normals computed automatically.

Parameters:

  • mesh_info (MeshInfo) – object containing the vertices, triangles, and uvs/colors.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • reverse_triangle_order (bool, optional) – whether to reverse the triangle winding order. Defaults to False.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_mesh_with_normals()

Add a triangle mesh to this ScenePic Mesh.

Parameters:

  • vertices (np.ndarray) – float32 matrix of [N, 3] vertex positions

  • normals (np.ndarray) – float32 matrix of [N, 3] vertex normals

  • triangles (np.ndarray) – uint32 matrix of [N, 3] triangle vertex indices

  • colors (np.ndarray, optional) – float32 matrix of [N, 3] per-vertex RGB color vectors. Defaults to None.

  • uvs (np.ndarray, optional) – float32 matrix of [N, 2] per-vertex UV coordinates. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • reverse_triangle_order (bool, optional) – whether to reverse the triangle winding order. Defaults to False.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_mesh_without_normals()

Add a triangle mesh to this ScenePic Mesh, with normals computed automatically.

Parameters:

  • vertices (np.ndarray) – float32 matrix of [N, 3] vertex positions

  • triangles (np.ndarray) – uint32 matrix of [N, 3] triangle vertex indices

  • colors (np.ndarray, optional) – float32 matrix of [N, 3] per-vertex RGB color vectors. Defaults to None.

  • uvs (np.ndarray, optional) – float32 matrix of [N, 2] per-vertex UV coordinates. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • reverse_triangle_order (bool, optional) – whether to reverse the triangle winding order. Defaults to False.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_quad()

Adds a quad to the mesh. All points are assumed to lie on the same plane.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • p0 (np.ndarray, optional) – the first vertex. Defaults to [0, -0.5, -0.5].

  • p1 (np.ndarray, optional) – the second vertex. Defaults to [0, 0.5, -0.5].

  • p2 (np.ndarray, optional) – the third vertex. Defaults to [0, 0.5, 0.5].

  • p3 (np.ndarray, optional) – the fourth vertex. Defaults to [0, -0.5, 0.5].

  • normal (np.ndarray, optional) – will be computed automatically if None. Defaults to None.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

  • transform (np.ndarray, optional) – 3D homogeneous transform matrix. Defaults to None.

  • uv_0 (np.ndarray, optional) – first UV coordinate (for UV meshes). Defaults to (0, 0).

  • uv_1 (np.ndarray, optional) – second UV coordinate (for UV meshes). Defaults to (1, 0).

  • uv_2 (np.ndarray, optional) – third UV coordinate (for UV meshes). Defaults to (1, 1).

  • uv_3 (np.ndarray, optional) – fourth UV coordinate (for UV meshes). Defaults to (0, 1).

add_sphere()

Add a default (ico) unit diameter sphere primitive to the mesh.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_thickline()

Add a thick line to this Mesh.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • start_point (np.ndarray, optional) – the start point of the line. Defaults to [-0.5, 0, 0].

  • end_point (np.ndarray, optional) – the end point of the line. Defaults to [0.5, 0, 0].

  • start_thickness (float, optional) – the start thickness of the line. Defaults to 0.1.

  • end_thickness (float, optional) – the end thickness of the line. Defaults to 0.1.

  • transform (np.ndarray, optional) – homogeneous 3D transform matrix. Defaults to None.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

add_triangle()

Adds a triangle to the mesh.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • p0 (np.ndarray, optional) – the first vertex. Defaults to [0, 0, 0].

  • p1 (np.ndarray, optional) – the second vertex. Defaults to [1, 0, 0].

  • p2 (np.ndarray, optional) – the third vertex. Defaults to [0, 1, 0].

  • normal (np.ndarray, optional) – will be computed automatically if None. Defaults to None.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

  • uv_0 (np.ndarray, optional) – first UV coordinate (for UV meshes). Defaults to (0, 0).

  • uv_1 (np.ndarray, optional) – second UV coordinate (for UV meshes). Defaults to (1, 0).

  • uv_2 (np.ndarray, optional) – third UV coordinate (for UV meshes). Defaults to (0, 1).

add_uv_sphere()

Add a unit diameter UV sphere to this Mesh.

Description:

If the mesh has a texture attached, this method will automatically create a set of vertex UVs which unwraps the sphere to map to the full UV space.

Parameters:

  • color (np.ndarray, optional) – required unless Mesh was constructed with shared_color argument. Defaults to None.

  • transform (np.ndarray, optional) – homogeneous 3D transform. Defaults to None.

  • lat_count (int, optional) – number of discrete samples in latitude. Defaults to 10.

  • long_count (int, optional) – number of discrete samples in longitude. Defaults to 10.

  • fill_triangles (bool, optional) – whether to fill the primitive. Defaults to True.

  • add_wireframe (bool, optional) – whether to add a wireframe outline. Defaults to False.

append_mesh()

Append another mesh object to this mesh

Parameters:

mesh (Mesh) – the mesh to append

apply_rotation()

Apply a 3D homogeneous matrix rotation (i.e. 4x4 matrix) to all vertices (and appropriately to the normals) in the Mesh. Separated out from apply_transform() so that a matrix inverse is not required, for speed.

Parameters:

transform (np.ndarray) – a 3D homogeneous rotation matrix

apply_transform()

Apply a 3D homogeneous matrix transform (i.e. 4x4 matrix) to all vertices (and appropriately to the normals) in the Mesh.

Parameters:

transform (np.ndarray) – a 3D homogeneous transform

property camera_space

Whether this Mesh is defined in camera space (cannot be moved in the ScenePic user interface) or world space (standard).

Type:

bool

property center_of_mass

The mean of mesh vertex positions

Type:

np.ndarray

count_vertices()

The number of vertices in the mesh.

property double_sided

Whether to turn off back face culling and draw the Mesh’s triangles as double sided.

Type:

bool

enable_instancing()

Makes ScenePic render this Mesh with multiple instances, e.g. for point-cloud visualizations. Can be used to make point clouds, for example. The whole contents of the Mesh will be rendered multiple times.

Parameters:

  • positions (np.ndarray) – float32 matrix of [N, 3] instance positions

  • rotations (np.ndarray, optional) – float32 matrix of [N, 4] per-point quaternion rotations. Defaults to None.

  • colors (np.ndarray, optional) – float32 matrix of [N, 3] colors. If provided, overrides a Mesh’s shared_color or per-vertex color. Defaults to None.

get_rotated()

Get a rotated copy of this Mesh.

Parameters:

transform (np.ndarray) – a 3D homogeneous transform

Returns:

a transformed copy of this mesh

Return type:

Mesh

get_transformed()

Get a transformed copy of this Mesh.

Parameters:

transform (np.ndarray) – a 3D homogeneous transform

Returns:

a transformed copy of this mesh

Return type:

Mesh

property is_billboard

Draw this Mesh as a billboard (i.e. always facing the user) rather than rotating with the rest of the world.

Type:

bool

property layer_id

An identifier to allow several Meshes to be grouped together into a “layer”. Layers should be used in conjunction with Canvas3D.set_layer_settings().

Type:

str

property mesh_id

A unique identifier for the Mesh

Type:

str

property nn_texture

Whether the shader should use nearest-neighbor texture interpolation.

Type:

bool

reverse_triangle_order()

Reverses the winding order of all triangles in this mesh. Useful when interoping with existing codebases that use opposite convention

property shared_color

Whole-mesh color (reduces memory requirements but makes Mesh monochrome).

Type:

np.ndarray

property texture_id

Specifies the id of a ScenePic Image to be used as a texture in this Mesh.

Type:

str

property use_texture_alpha

Whether to use the alpha channel in the texture for transparency (only relevant for textured Meshes).

Type:

bool

property vertex_buffer

The raw vertex buffer.

MeshUpdate

class scenepic.MeshUpdate

A new mesh formed by updated an existing mesh.

property base_mesh_id

The unique identifier for the base mesh

Type:

str

difference_range(vertex_buffer)

Returns the absolute range of values in the difference between this update and the buffer.

Parameters:
Returns:

the absolute range (from minimum to maximum) in the per-index difference between

this update and the reference.

Return type:

float

property frame_index

The position in the creation order for this update

Type:

int

property mesh_id

The unique identifier of the newly created mesh

Type:

str

quantize(keyframe_index, fixed_point_range, keyframe_vertex_buffer)

Quantize the mesh update.

Parameters:

  • self (MeshUpdate) – self reference

  • keyframe_index (int) – Index of the keyframe to use in quantizing this update

  • fixed_point_range (float) – The range to use for the fixed point representation.

  • keyframe_vertex_buffer (VertexBuffer) – The keyframe vertex buffer

property vertex_buffer

The raw vertex buffer.

MeshInfo

class scenepic.MeshInfo

Class which holds information needed to construct a mesh object, like the vertex positions, the triangulation, and either per-vertex UV coordinates or Color (if present).

property colors

A reference to the color buffer.

Type:

np.ndarray

property has_normals

Whether the mesh info contains vertex normals.

property normals

A reference to the normal buffer

Type:

np.ndarray

property positions

A reference to the position buffer.

Type:

np.ndarray

subdivide()

Subdivide this mesh using loop subdivision.

Parameters:

  • steps (int, optional) – specifies how many steps of subdivision to apply. Defaults to 1.

  • project_to_limit (bool, optional) – specifies whether the vertices should be projected onto the limit surface in the final step of subdivision. Defaults to false.

Returns:

a subdivided version of this mesh

Return type:

MeshInfo

property triangles

A reference to the triangle buffer.

Type:

np.ndarray

property uvs

A reference to the uv buffer.

Type:

np.ndarray

scenepic.load_obj()

Loads a WaveFront OBJ file from disk as a MeshInfo object.

Parameters:

path (str) – the path to the OBJ file on disk

Returns:

contains the positions, a triangulation, and UVs (if present)

Return type:

MeshInfo

VertexBuffer

class scenepic.VertexBuffer(values)

Camera

class scenepic.Camera

A camera type

Note

The camera can be created either with the look at paradigm (center, look_at, up_dir), with center and rotation, or with an explicit world-to-camera matrix.

Parameters:

  • center (np.ndarray, optional) – the camera center. Defaults to [0, 0, 4].

  • look_at (np.ndarray, optional) – where the camera is looking. Defaults to [0, 0, 0].

  • up_dir (np.ndarray, optional) – the direction that is “up” for the camera. Defaults to [0, 1, 0].

  • fov_y_degrees (float, optional) – vertical field of view in degrees. Defaults to 45.0.

  • near_crop_distance (float, optional) – the near clipping plane of the view frustum. Defaults to 0.01.

  • far_crop_distance (float, optional) – the far clipping plane of the view frustum. Defaults to 20.0.

  • rotation (np.ndarray, optional) – a homogeneous rotation transform.

  • world_to_camera (np.ndarray, optional) – a homogeneous 3D transform mapping world coordinates to camera space.

  • projection (np.ndarray, optional) – the WebGL projection matrix from camera view coordinates to NDC.

  • aspect_ratio (float, optional) – The aspect ratio of the camera. Defaults to 1.0.

property aspect_ratio

Update the aspect ratio of the camera

Type:

float

property camera_to_world

Homogeneous 3D transform that places the camera in the scene

Type:

np.ndarray

property center

The camera center

Type:

np.ndarray

property look_at

Where the camera is looking

Type:

np.ndarray

orbit()

Creates a sequence of cameras which move in an orbit around the origin.

Parameters:

  • num_frames (int) – the number of frames in the sequence

  • distance (float) – the distance of the camera from the origin

  • num_times (int) – the number of times to orbit

  • min_altitude (float) – the minimum altitude of the orbit

  • max_altitude (float) – the maximum altitude of the orbit

  • up_dir (np.ndarray) – the direct that is up (as a normalized vector)

  • forward_dir (np.ndarray) – the direction that is forward (as a normalized vector)

  • fov_y_degrees (float) – the field of the view of the camera in degrees

  • aspect_ratio (float) – the aspect ratio of the camera

  • near_crop_distance (float) – the near clipping plane of the view frustum

  • far_crop_distance (float) – the far clipping plane of the view frustum

Returns:

a sequence of cameras moving in an orbit

Return type:

List[Camera]

property projection

WebGL projection matrix from camera view coordinates to NDC

Type:

np.ndarray

property rotation

The rotation matrix

Type:

np.ndarray

property up_dir

The direction that is “up” for the camera

Type:

np.ndarray

property world_to_camera

Homogeneous 3D transform mapping world coordinates to camera space

Type:

np.ndarray

FocusPoint

class scenepic.FocusPoint

3D focus point for this frame (with optional 3D rotation for orientation lock), used in the ScenePic user interface.

property orientation_axis_angle

The orientation axis angle

Type:

np.ndarray

property position

The position of the focus point

Type:

np.ndarray

Shading

class scenepic.Shading

Parameters of the shaders

Parameters:

  • bg_color (np.ndarray, optional) – background color. Defaults to Black.

  • ambient_light_color (np.ndarray, optional) – color of ambient light. Defaults to [0.7, 0.7, 0.7].

  • directional_light_color (np.ndarray, optional) – color of directional light. Defaults to [0.3, 0.3, 0.3].

  • directional_light_dir (np.ndarray, optional) – direction of directional light. Defaults to [2, 1, 2].

property ambient_light_color

the color of ambient light

Type:

np.ndarray

property bg_color

the background color

Type:

np.ndarray

property directional_light_color

the directional light color

Type:

np.ndarray

property directional_light_dir

the direction of the directional light

Type:

np.ndarray

Transforms

class scenepic.Transforms

Static class with convenience methods for creating various 3D homogeneous transforms.

static AxisAngleRotationToRotateXAxisToAlignWithAxis(axis)

Find the axis and angle of rotation that will ensure the x-axis aligns with the provided axis.

Note

One degree of freedom is underconstrained.

Parameters:

axis (np.ndarray) – the axis to which to align the x-axis

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

static QuaternionFromAxisAngle(axis, angle)

Convert rotation axis and angle to a quaternion.

Parameters:

  • axis (np.ndarray) – the axis of rotation

  • angle (float) – the angle to rotate in radians

Returns:

a 3D homgenous transform matrix

Return type:

np.ndarray

static QuaternionToRotateXAxisToAlignWithAxis(axis)

Creates a quaternion rotation vector that will ensure the x-axis aligns with the provided axis.

Note

One degree of freedom is underconstrained.

Parameters:

axis (np.ndarray) – the axis to which to align the x-axis

Returns:

a quaternion

Return type:

np.ndarray

static RotationAboutXAxis(angle)

Creates a 3D homogeneous rotation matrix about the x-axis.

Parameters:

angle (float) – the angle to rotation in radians

Returns:

a 3D homogeous transform matrix

Return type:

np.ndarray

static RotationAboutYAxis(angle)

Creates a 3D homogeneous rotation matrix about the y-axis.

Parameters:

angle (float) – the angle to rotation in radians

Returns:

a 3D homogeous transform matrix

Return type:

np.ndarray

static RotationAboutZAxis(angle)

Creates a 3D homogeneous rotation matrix about the z-axis.

Parameters:

angle (float) – the angle to rotation in radians

Returns:

a 3D homogeous transform matrix

Return type:

np.ndarray

static RotationMatrixFromAxisAngle(axis, angle)

Creates a 3D homogeneous scale matrix from axis and angle.

Parameters:

  • axis (np.ndarray) – the axis of rotation

  • angle (float) – the angle to rotate in radians

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

static RotationToRotateXAxisToAlignWithAxis(axis)

Creates a 3D homogeneous rotation matrix that will ensure the x-axis aligns with the provided axis.

Note

One degree of freedom is underconstrained.

Parameters:

axis (np.ndarray) – the axis to which to align the x-axis

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

static Scale(scale)

Creates a 3D homogeneous scale matrix.

Parameters:

scale (Union[np.ndarray, float]) – the axis-specific scale values

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

static Translate(vec)

Creates a 3D homogeneous scale matrix.

Parameters:

vec (np.ndarray) – the movement vector

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

axis_angle_to_align_x_to_axis()

Find the axis and angle of rotation that will ensure the x-axis aligns with the provided axis.

Note

One degree of freedom is underconstrained.

Parameters:

axis (np.ndarray) – the axis to which to align the x-axis

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

euler_angles_to_matrix()

Creates a rotation matrix from three Euler angles.

Description:

Creates a 3D homogeneous rotation matrix from three euler angles using the specified convention. See https://en.wikipedia.org/wiki/Euler_angles for more information on valid conventions. Conventions are specified as a three character string indicating the convention order, with values taken from [X, Y, Z].

Parameters:

  • euler_angles (np.ndarray) – the Euler angles to use in constructing the matrix

  • convention (str, optional) – the convention to use in interpreting the angles. Defaults to “XYZ”

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

gl_projection()

Creates a WebGL projection transform.

Description:

A WebGL projection transform is a matrix that maps from camera view coordinates to NDC, or normalized device coordinates. A good description of this can be found here: http://ksimek.github.io/2013/06/03/calibrated_cameras_in_opengl/

Parameters:

  • fov_y_degrees (float) – the field of view of the camera in degrees

  • aspect_ratio (float) – the aspect ratio of the camera

  • znear (float) – the z value of the near clipping plane of the viewing frustum

  • zfar (float) – the z value of the far clipping plane of the view frustum

Returns:

a 3D WebGL projection matrix

Return type:

np.ndarray

Creates a WebGL projection transform.

Description:

A WebGL projection transform is a matrix that maps from camera view coordinates to NDC, or normalized device coordinates. A good description of this can be found here: http://ksimek.github.io/2013/06/03/calibrated_cameras_in_opengl/

Parameters:

  • camera_matrix (np.ndarray) – an OpenCV-style camera intrinsic matrix

  • width (int) – the width of the calibration image

  • height (int) – the height of the calibration image

  • znear (float) – the z value of the near clipping plane of the viewing frustum

  • zfar (float) – the z value of the far clipping plane of the view frustum

Returns:

a 3D WebGL projection matrix

Return type:

np.ndarray

gl_world_to_camera()

Creates a WebGL view transform.

Description:

A WebGL view transform goes from world coordinates to camera view coordinates. This method will create one from an OpenCV-style camera extrinsic matrix.

Parameters:

extrinsic (np.ndarray) – the camera-to-world matrix, which places the camera in the scene

Returns:

a WebGL view matrix

Return type:

np.ndarray

look_at_rotation()

Creates a rotation to look at a point in space.

Description:

Creates a 3D homogeneous rotation matrix that will cause an object with the specified center to look at the specified location, with the up direction as given.

Parameters:

  • center (np.ndarray) – the center of the object

  • look_at (np.ndarray) – the position to look at

  • up_dir (np.ndarray) – the position that is “up”

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

quaternion_from_axis_angle()

Convert rotation axis and angle to a quaternion.

Parameters:

  • axis (np.ndarray) – the axis of rotation

  • angle (float) – the angle to rotate in radians

Returns:

a 3D homogenous transform matrix

Return type:

np.ndarray

quaternion_multiply()

Multiply two quaternions together.

Parameters:

  • a (np.ndarray) – the first quaternion

  • b (np.ndarray) – the second quaternion

Returns:

the result of a * b

Return type:

np.ndarray

quaternion_to_align_x_to_axis()

Creates a quaternion rotation vector that will ensure the x-axis aligns with the provided axis.

Note

One degree of freedom is underconstrained.

Parameters:

axis (np.ndarray) – the axis to which to align the x-axis

Returns:

a quaternion

Return type:

np.ndarray

quaternion_to_matrix()

Creates a 3D homogeneous rotation matrix from a quaternion.

Parameters:

quaternion (np.ndarray) – the quaternion to use in constructing the matrix

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

rotation_about_x()

Creates a 3D homogeneous rotation matrix about the x-axis.

Parameters:

angle (float) – the angle to rotation in radians

Returns:

a 3D homogeous transform matrix

Return type:

np.ndarray

rotation_about_y()

Creates a 3D homogeneous rotation matrix about the y-axis.

Parameters:

angle (float) – the angle to rotation in radians

Returns:

a 3D homogeous transform matrix

Return type:

np.ndarray

rotation_about_z()

Creates a 3D homogeneous rotation matrix about the z-axis.

Parameters:

angle (float) – the angle to rotation in radians

Returns:

a 3D homogeous transform matrix

Return type:

np.ndarray

rotation_matrix_from_axis_angle()

Creates a 3D homogeneous scale matrix from axis and angle.

Parameters:

  • axis (np.ndarray) – the axis of rotation

  • angle (float) – the angle to rotate in radians

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

rotation_to_align_x_to_axis()

Creates a 3D homogeneous rotation matrix that will ensure the x-axis aligns with the provided axis.

Note

One degree of freedom is underconstrained.

Parameters:

axis (np.ndarray) – the axis to which to align the x-axis

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

scale()

Creates a 3D homogeneous scale matrix.

Parameters:

scale (float) – the scale to use across all axes

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

Creates a 3D homogeneous scale matrix.

Parameters:

scale (np.ndarray) – the axis-specific scale values

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

translate()

Creates a 3D homogeneous scale matrix.

Parameters:

vec (np.ndarray) – the movement vector

Returns:

a 3D homogeneous transform matrix

Return type:

np.ndarray

Label

class scenepic.Label

A ScenePic label type

property fill_color

The color to use.

Type:

np.ndarray

property font_family

HTML font family name.

Type:

str

property horizontal_align

How to align the label horizontally (one of ‘left’, ‘center’, ‘right’)

Type:

str

property label_id

A unique identifier for the Label

Type:

str

property mesh_id

The mesh associated with this label

Type:

str

property offset_distance

Distance in world space to offset the label by when using left/right/top/bottom alignment.

Type:

float

property size_in_pixels

The size in pixels to display the label at.

Type:

float

property text

The text to use in the label.

Type:

str

property vertical_align

How to align the label vertically (one of ‘top’, ‘middle’, ‘bottom’)

Type:

str

LoopSubdivisionStencil

class scenepic.LoopSubdivisionStencil

This class enables efficient Loop subdivision of triangle meshes.

The subdivision stencil specifies what linear combinations of existing vertices are needed, and stencils can be reused across meshes with different vertex positions but identical triangle topologies. Thus, the constructor only takes the triangles, and caches the stencil. The stencil can be applied to a set of vertices using the apply() method.

apply()

Applies the stencil to a vertex buffer.

Description:

This method takes a set of vertices and subdivides them (using the stencil) to create the vertices of a more detailed mesh.

Parameters:

vertices (np.ndarray) – a (N, 3) buffer of vertices

Returns:

a (S, 3) buffer of subdivided vertices

Return type:

np.ndarray

static create()

Creates a new stencil by subdividing the provided triangles.

Parameters:

  • triangles (np.ndarray) – the initial triangle indices

  • steps (int, optional) – specifies how many steps of subdivision to apply. Defaults to 1.

  • project_to_limit (bool, optional) – specifies whether the vertices should be projected onto the limit surface in the final step of subdivision. Defaults to false.

Returns:

LoopSubdivisionStencil

property triangle_count

The number of triangles in the subdivided mesh

Type:

int

property triangles

The triangles of the subdivided mesh

Type:

np.ndarray

property vertex_count

The number of vertices in the subdivided mesh

Type:

int