API

This part of the documentation covers all the interfaces of ScenePic.

Scene

class scenepic.Scene

Top level container representing an entire ScenePic Scene.

Parameters:

scene_id (str, optional) – a unique identifier for the Scene (will be automatically populated if not provided). Defaults to None.

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. Immediately after this, a call to get_script() will returnempty.

configure_user_interface()

Set user interface parameters across all Canvases with given UIParameters instance.

Parameters:

ui_parameters (UIParameters) – global UI parameters to set

create_audio()

Create a new AudioTrack object and append it to the Scene. Audio tracks are Scene-wide resources that can be attached to multiple canvases.

Parameters:

audio_id (str, optional) – a unique identifier for the Audio track (will be automatically populated if not provided). Defaults to None.

Returns:

a reference to an Audio track object

Return type:

AudioTrack

create_canvas_2d()

Create a new 2D Canvas and append to the Scene.

Parameters:

• canvas_id (str, optional) – a unique identifier for the Canvas (will be automatically populated if not provided). Defaults to None.

• width (int, optional) – the width in pixels of the Canvas on the HTML page. Defaults to 400.

• height (int, optional) – the height in pixels of the Canvas on the HTML page. Defaults to 400.

• html_id (str, optional) – id of an HTML element to use as this Canvas’s parent in the HTML DOM (otherwise simply appended to document). Defaults to None.

• background_color (np.ndarray, optional) – the background color of the canvas. Defaults to Black.

• media_id (str, optional) – optional ID of a media file to attach to the canvas. This file will be used to drive playback, i.e. frames will be displayed in time with the playback of the media file.

Returns:

a reference to the new Canvas object

Return type:

Canvas2D

create_canvas_3d()

Create a new 3D Canvas and append to the Scene.

Parameters:

• canvas_id (str, optional) – a unique identifier for the Canvas (will be automatically populated if not provided). Defaults to None.

• width (int, optional) – the width in pixels of the Canvas on the HTML page. Defaults to 400.

• height (int, optional) – the height in pixels of the Canvas on the HTML page. Defaults to 400.

• html_id (str, optional) – id of an HTML element to use as this Canvas’s parent in the HTML DOM (otherwise simply appended to document). Defaults to None.

• camera (Camera, optional) – Camera parameters for the Canvas. See Camera for defaults.

• shading (Shading, optional) – Set of Shading parameters for the Canvas. See Shading for defaults.

• ui_parameters (UIParameters, optional) – Set of user interface parameters. See UIParameters for defaults.

• media_id (str, optional) – optional ID of a media file to attach to the canvas. This file will be used to drive playback, i.e. frames will be displayed in time with the playback of the media file.

Returns:

a reference to the new Canvas object

Return type:

Canvas3D

create_drop_down_menu()

Create a new DropDownMenu and add directly to the HTML page.

Keyword Arguments:

• drop_down_menu_id (str, optional) – a unique identifier for the DropDownMenu (will be automatically populated if not provided). Defaults to None.

• title (str, optional) – a title for the drop down box. Defaults to None.

• html_id (str, optional) – optional id of an HTML element to use as this TextPanel’s parent in the HTML DOM (otherwise will simply be appended to document). Defaults to None.

Returns:

a reference to the new DropDownMenu object

Return type:

DropDownMenu

create_graph()

Create a new Graph canvas and append to the Scene.

Parameters:

• canvas_id (str, optional) – a unique identifier for the Canvas (will be automatically populated if not provided). Defaults to None.

• width (int, optional) – the width in pixels of the Canvas on the HTML page. Defaults to 400.

• height (int, optional) – the height in pixels of the Canvas on the HTML page. Defaults to 400.

• name_align (str, optional) – How to align the sparkline label (one of ‘left’, ‘right’, ‘top’, or ‘bottom’). Defaults to ‘left’.

• value_align (str, optional) – How to align the sparkline value (one of ‘left’, ‘right’, ‘top’, or ‘bottom’). Defaults to ‘right’.

• html_id (str, optional) – id of an HTML element to use as this Canvas’s parent in the HTML DOM (otherwise simply appended to document). Defaults to None.

• background_color (np.ndarray, optional) – the background color of the canvas. Defaults to White.

• margin (Margin, optional) – the outer margin of the graph. Defaults to Margin(10).

• font_family (str, optional) – the font family used for the graph labels. Defaults to “sans-serif”.

• name_size (float, optional) – the text size in pixels used for the graph labels. Defaults to 12.0.

• value_size (float, optional) – the text size in pixels used for the graph values. Defaults to 12.0.

• media_id (str, optional) – optional ID of a media file to attach to the canvas. This file will be used to drive playback, i.e. frames will be displayed in time with the playback of the media file.

Returns:

a reference to the new Graph object

Return type:

Graph

create_image()

Create a new Image and append to the Scene. Images are Scene-wide resources that can be reused as textures across multiple Meshes and Frame2Ds.

Parameters:

image_id (str, optional) – a unique identifier for the Image (will be automatically populated if not provided). Defaults to None.

Returns:

a reference to the Image object

Return type:

Image

create_label()

Create a new Label and append to the Scene. Labels are Scene-wide resources that can be reused across multiple Meshes.

Parameters:

• label_id (str, optional) – a unique identifier for the Label (will be automatically populated if not provided). Defaults to None.

• text (str, optional) – the text to use in the label. Defaults to “Text”.

• color (np.ndarray, optional) – the color to use. Defaults to White.

• size_in_pixels (float, optional) – the size in pixels to display the label at. Defaults to 12.0.

• font_family (str, optional) – HTML font family name. Defaults to “sans-serif”.

• layer_id (str, optional) – an identifier to allow several labels to be grouped together into a “layer”. Layers should be used in conjunction with Canvas3D.set_layer_settings(). Defaults to None.

• horizontal_align (str, optional) – one of ‘left’, ‘center’, ‘right’. how to align the label horizontally. Defaults to “left”.

• vertical_align (str, optional) – one of ‘top’, ‘middle’, ‘bottom’. how to align the label vertically. Defaults to “middle”.

• offset_distance (float, optional) – distance in world space to offset the label by when using left/right/top/bottom alignment. Defaults to 0.1.

• camera_space (bool, optional) – whether the label should be created in camera space. Defaults to False.

Returns:

a reference to the new Label object

Return type:

Label

create_mesh(mesh_id='', **kwargs)

Create a new Mesh and append to the Scene.

Description:

Meshes are Scene-wide resources that can be reused across multiple Frames in multiple Canvas3Ds.

Parameters:

• mesh_id (str, optional) – a unique identifier for the Mesh (will be automatically populated if not provided). Defaults to None.

• layer_id (str, optional) – an identifier to allow several Meshes to be grouped together into a “layer”. Layers should be used in conjunction with Canvas3D.set_layer_settings(). Defaults to None.

• double_sided (bool, optional) – whether to turn off back face culling and draw the Mesh’s triangles as double sided. Defaults to False.

• camera_space (bool, optional) – whether this Mesh is defined in camera space (cannot be moved in the ScenePic user interface) or world space (standard). Defaults to False.

• shared_color (np.ndarray, optional) – see Mesh constructor.

• texture_id (Union[Image, str], optional) – see Mesh constructor.

• nn_texture (bool, optional) – whether the shader should use nearest-neighbor texture interpolation. Defaults to True.

• use_texture_alpha (bool, optional) – whether to use the alpha channel in the texture for transparency (only relevant for textured Meshes). Defaults to True.

• is_billboard (bool, optional) – draw this Mesh as a billboard (i.e. always facing the user) rather than rotating with the rest of the world. Defaults to False.

• is_label (bool, optional) – this mesh will be treated specially as a label. Not for public use. Defaults to False.

Returns:

a reference to the new Mesh object

Return type:

Mesh

create_text_panel()

Create a new TextPanel and add directly to the HTML page.

Parameters:

• text_panel_id (str, optional) – a unique identifier for the TextPanel (will be automatically populated if not provided). Defaults to None.

• html_id (str, optional) – optional id of an HTML element to use as this TextPanel’s parent in the HTML DOM (otherwise will simply be appended to document). Defaults to None.

• add_input_box (bool, optional) – whether to add an input box to the TextPanel. Defaults to False.

Returns:

a reference to the new TextPanel object

create_video()

Create a new Video object and append it to the Scene. Videos are Scene-wide resources that can be attached to multiple canvases.

Parameters:

video_id (str, optional) – a unique identifier for the Video (will be automatically populated if not provided). Defaults to None.

Returns:

a reference to an Video object

Return type:

Video

property framerate

Number of frames to display per second

Type:

float

get_json()

Returns a JSON-serialized representation of the Scene as a string.

If you use clear_script() then this will return updates to the Scene since thelast call to clear_script().

Returns:

a JSON string representing the Scene

Return type:

str

get_script()

Returns a JSONP (https://en.wikipedia.org/wiki/JSONP) script representing the Scene. If you use clear_script() then this will return updates to the Scene since the last call to clear_script().

Returns:

a JSONP script representing the Scene

Return type:

str

grid()

Defines a CSS layout grid for the canvases of the ScenePic.

Description:

Should not be used in conjunction with html_id for individual canvases. See https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout for more information.

Parameters:

• width (str) – CSS declaration for the width of the ScenePic.

• grid_template_rows (str) – CSS declaration defining the rows of the ScenePic

• grid_template_columns (str) – CSS declaration defining the columns of the ScenePic

link_canvas_events(*canvases)

Specify that all input events should be linked across the provided set of Canvases.

Parameters:

• self (Scene) – self reference

• canvases – the canvases which should have linked events

measure_command_size()

Measures the number of bytes used by command type.

Returns:

the number of bytes per command type

Return type:

Mapping[str, int]

place()

Places a canvas at a specific place in the ScenePic grid.

Note

For use with Scene.grid

Parameters:

• canvas_id (str) – The unique ID of the canvas to place

• grid_row (str) – the CSS row specification for the Canvas

• grid_column (str) – the CSS column specification for the Canvas

quantize_updates()

Quantize the mesh updates.

Description:

Each update will be reduced in size in such a way as to minimize the expected per-value error from quantization. The number of keyframes (and thus the level of compression) can be controlled via two thresholds: the relative error threshold, and the absolute error threshold. The relative threshold is evaluated as a fraction of max(positions) - min(positions). The absolute threshold is measured in raw units.

If the relative error threshold has a positive value but the absolute error threshold is negative, only the relative threshold will be used. Conversely, if the relative threshold is negative and the absolute threshold is positive then only the absolute threshold will be used. If both are positive, then they will both be applied. If both are negative, an exception will be raised.

The quantization process will complete in such a way that (quantized - actual).abs().max() < threshold. In essence, each x, y, and z coordinate will individually be different by no more than this threshold after quantization. Thus, a possible result of quantization will that every frame is a keyframe, i.e. no quantization occurs. More typically, however, the algorithm finds a few “keyframe” meshes which minimize the expected error across the remaining (quantized) meshes.

Parameters:

• relative_error_threshold (float, optional) – the maximum expected error as a multiple of the range of values in the base mesh. Defaults to 1e-5.

• absolute_error_threshold (float, optional) – the maximum expected error in absolute units. Defaults to -1.0.

• base_mesh_id (str, optional) – ID of the base mesh to use as a filter on quantization. Defaults to None.

• per_frame_range (bool, optional) – Whether to use the most accurate range per frame, increasing accuracy but reducing compression. Defaults to True.

Returns:

information on the per-mesh quantization process

Return type:

Mapping[str, QuantizationInfo]

save_as_html()

Save the scene as a self-contained html file with no dependencies.

Parameters:

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

• title (str, optional) – the HTML title. Defaults to “ScenePic”.

• head_html (str, optional) – the raw HTML to place in the HEAD tag. Defaults to None.

• body_html (str, optional) – the raw HTML to place in the BODY tag. Defaults to None.

• script_path (str, optional) – desired relative path for the script. A value of None indicates to embed the script in the HTML page. Defaults to None.

• library_path (str, optional) – desired relative path for the library. A value of None indicates to embed the library in the HTML page. Defaults to None.

save_as_json()

To view the JSON, you will need to separately code up the wrapper html and provide the scenepic.min.js library file. Alternatively, use save_as_html() to make a self-contained HTML file.

Parameters:

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

save_as_script()

Save the scene as a ScenePic script file (JavaScript JSONP format). To view the script, you will need to separately code up the wrapper html. Alternatively, use save_as_html() to make a self-contained HTML file.

Parameters:

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

• standalone (bool) – whether to make the script standalone by including the library

property script_cleared

Whether the script has been cleared

Type:

bool

simulate_key_presses(canvas_id, *keypresses)

Simulates one or more keypresses to fire off events in the ScenePic UI at startup, e.g. video playback.

Parameters:

• self (Scene) – self reference

• canvas_id (Union[Canvas3D, Canvas2D, str]) – ID of the canvas on which to fire off this event.

• keypresses – the key values

property status_bar_visibility

CSS visibility for the status bar

Type:

str

update_instanced_mesh()

Create a new mesh from an existing one by replacing its vector positions and normals.

Parameters:

• base_mesh_id (str) – the unique identifier of the original base mesh. Must already have been created.

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

• rotations (np.ndarray, optional) – float32 matrix of [N, 4] new rotations. Defaults to None, indicating no change to the rotations.

• colors (np.ndarray, optional) – float32 matrix of [N, 3] new colors

• mesh_id (str, optional) – a unique identifier for the new updated Mesh (will be automatically populated if not provided). Defaults to None.

Returns:

a reference to the MeshUpdate object

Return type:

MeshUpdate

update_mesh()

Create a new mesh from an existing one by replacing its vector positions, normals, and/or colors.

Parameters:

• base_mesh_id (str) – the unique identifier of the original base mesh. Must already have been created.

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

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

• colors (np.ndarray, optional) – float32 matrix of [N, 3] new colors.

• mesh_id (str, optional) – a unique identifier for the new updated Mesh (will be automatically populated if not provided). Defaults to None.

Returns:

a reference to the MeshUpdate object

Return type:

MeshUpdate

update_mesh_positions()

Create a new mesh from an existing one by replacing its vector positions and compute normal values.

Parameters:

• base_mesh_id (str) – the unique identifier of the original base mesh. Must already have been created.

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

• mesh_id (str, optional) – a unique identifier for the new updated Mesh (will be automatically populated if not provided). Defaults to None.

Returns:

a reference to the MeshUpdate object

Return type:

MeshUpdate

update_mesh_without_normals()

Deprecated.

3D Graphics

• Canvas3D
  • Canvas3D
    • Canvas3D.camera
    • Canvas3D.canvas_id
    • Canvas3D.clear_script()
    • Canvas3D.create_frame()
    • Canvas3D.focus_point
    • Canvas3D.height
    • Canvas3D.media_id
    • Canvas3D.set_layer_settings()
    • Canvas3D.shading
    • Canvas3D.ui_parameters
    • Canvas3D.width
• Frame3D
  • Frame3D
    • Frame3D.add_label()
    • Frame3D.add_mesh()
    • Frame3D.add_meshes()
    • Frame3D.camera
    • Frame3D.focus_point
    • Frame3D.set_layer_settings()
• Mesh
  • Mesh
    • Mesh.add_camera_frustum()
    • Mesh.add_camera_image()
    • Mesh.add_cone()
    • Mesh.add_coordinate_axes()
    • Mesh.add_cube()
    • Mesh.add_cylinder()
    • Mesh.add_disc()
    • Mesh.add_icosphere()
    • Mesh.add_image()
    • Mesh.add_lines()
    • Mesh.add_mesh()
    • Mesh.add_mesh_with_normals()
    • Mesh.add_mesh_without_normals()
    • Mesh.add_quad()
    • Mesh.add_sphere()
    • Mesh.add_thickline()
    • Mesh.add_triangle()
    • Mesh.add_uv_sphere()
    • Mesh.append_mesh()
    • Mesh.apply_rotation()
    • Mesh.apply_transform()
    • Mesh.camera_space
    • Mesh.center_of_mass
    • Mesh.count_vertices()
    • Mesh.double_sided
    • Mesh.enable_instancing()
    • Mesh.get_rotated()
    • Mesh.get_transformed()
    • Mesh.is_billboard
    • Mesh.layer_id
    • Mesh.mesh_id
    • Mesh.nn_texture
    • Mesh.reverse_triangle_order()
    • Mesh.shared_color
    • Mesh.texture_id
    • Mesh.use_texture_alpha
    • Mesh.vertex_buffer
• MeshUpdate
  • MeshUpdate
    • MeshUpdate.base_mesh_id
    • MeshUpdate.difference_range()
    • MeshUpdate.frame_index
    • MeshUpdate.mesh_id
    • MeshUpdate.quantize()
    • MeshUpdate.vertex_buffer
• MeshInfo
  • MeshInfo
    • MeshInfo.colors
    • MeshInfo.has_normals
    • MeshInfo.normals
    • MeshInfo.positions
    • MeshInfo.subdivide()
    • MeshInfo.triangles
    • MeshInfo.uvs
  • load_obj()
• VertexBuffer
  • VertexBuffer
• Camera
  • Camera
    • Camera.aspect_ratio
    • Camera.camera_to_world
    • Camera.center
    • Camera.look_at
    • Camera.orbit()
    • Camera.projection
    • Camera.rotation
    • Camera.up_dir
    • Camera.world_to_camera
• FocusPoint
  • FocusPoint
    • FocusPoint.orientation_axis_angle
    • FocusPoint.position
• Shading
  • Shading
    • Shading.ambient_light_color
    • Shading.bg_color
    • Shading.directional_light_color
    • Shading.directional_light_dir
• Transforms
  • Transforms
    • Transforms.AxisAngleRotationToRotateXAxisToAlignWithAxis()
    • Transforms.QuaternionFromAxisAngle()
    • Transforms.QuaternionToRotateXAxisToAlignWithAxis()
    • Transforms.RotationAboutXAxis()
    • Transforms.RotationAboutYAxis()
    • Transforms.RotationAboutZAxis()
    • Transforms.RotationMatrixFromAxisAngle()
    • Transforms.RotationToRotateXAxisToAlignWithAxis()
    • Transforms.Scale()
    • Transforms.Translate()
    • Transforms.axis_angle_to_align_x_to_axis()
    • Transforms.euler_angles_to_matrix()
    • Transforms.gl_projection()
    • Transforms.gl_world_to_camera()
    • Transforms.look_at_rotation()
    • Transforms.quaternion_from_axis_angle()
    • Transforms.quaternion_multiply()
    • Transforms.quaternion_to_align_x_to_axis()
    • Transforms.quaternion_to_matrix()
    • Transforms.rotation_about_x()
    • Transforms.rotation_about_y()
    • Transforms.rotation_about_z()
    • Transforms.rotation_matrix_from_axis_angle()
    • Transforms.rotation_to_align_x_to_axis()
    • Transforms.scale()
    • Transforms.translate()
• Label
  • Label
    • Label.fill_color
    • Label.font_family
    • Label.horizontal_align
    • Label.label_id
    • Label.mesh_id
    • Label.offset_distance
    • Label.size_in_pixels
    • Label.text
    • Label.vertical_align
• LoopSubdivisionStencil
  • LoopSubdivisionStencil
    • LoopSubdivisionStencil.apply()
    • LoopSubdivisionStencil.create()
    • LoopSubdivisionStencil.triangle_count
    • LoopSubdivisionStencil.triangles
    • LoopSubdivisionStencil.vertex_count

2D Graphics

• Canvas2D
  • Canvas2D
    • Canvas2D.background_color
    • Canvas2D.canvas_id
    • Canvas2D.clear_script()
    • Canvas2D.create_frame()
    • Canvas2D.height
    • Canvas2D.media_id
    • Canvas2D.set_layer_settings()
    • Canvas2D.width
• Frame2D
  • Frame2D
    • Frame2D.add_circle()
    • Frame2D.add_image()
    • Frame2D.add_line()
    • Frame2D.add_rectangle()
    • Frame2D.add_text()
    • Frame2D.add_video()
• Graph
  • Graph
    • Graph.Margin
      • Graph.Margin.bottom
      • Graph.Margin.left
      • Graph.Margin.right
      • Graph.Margin.top
    • Graph.VerticalRule
      • Graph.VerticalRule.color
      • Graph.VerticalRule.frame
      • Graph.VerticalRule.line_width
    • Graph.add_sparkline()
    • Graph.background_color
    • Graph.canvas_id
    • Graph.font_family
    • Graph.margin
    • Graph.media_id
    • Graph.name_align
    • Graph.name_size
    • Graph.value_align
    • Graph.value_size

User Interface

• LayerSettings
  • LayerSettings
    • LayerSettings.filled
    • LayerSettings.opacity
    • LayerSettings.render_order
    • LayerSettings.wireframe
• DropDownMenu
  • DropDownMenu
    • DropDownMenu.clear_script()
    • DropDownMenu.items
    • DropDownMenu.selection
    • DropDownMenu.set_disabled()
    • DropDownMenu.title
• TextPanel
  • TextPanel
    • TextPanel.clear_script()
    • TextPanel.input_text
    • TextPanel.text
    • TextPanel.title
• UIParameters
  • UIParameters
    • UIParameters.key_press_speed
    • UIParameters.layer_dropdown_visibility
    • UIParameters.mouse_wheel_translation_speed
    • UIParameters.pointer_alt_key_multiplier
    • UIParameters.pointer_rotation_speed

Media

• Image
  • Image
    • Image.data
    • Image.ext
    • Image.from_numpy()
    • Image.image_id
    • Image.load()
    • Image.load_from_buffer()
• AudioTrack
  • AudioTrack
    • AudioTrack.audio_id
    • AudioTrack.data
    • AudioTrack.load()
    • AudioTrack.load_from_buffer()
• Video
  • Video
    • Video.data
    • Video.load()
    • Video.load_from_buffer()
    • Video.video_id
• VideoWriter
  • VideoWriter
    • VideoWriter.clear_frame()
    • VideoWriter.frame
    • VideoWriter.start()
    • VideoWriter.stop()
    • VideoWriter.text
    • VideoWriter.text_color
    • VideoWriter.write_frame()

Color

class scenepic.Colors

Class containing standard colors.

Black

(0, 0, 0)

Type:

np.ndarray

White

(255, 255, 255)

Type:

np.ndarray

Red

(255, 0, 0)

Type:

np.ndarray

Maroon

(128, 0, 0)

Type:

np.ndarray

Pink

(255, 200, 220)

Type:

np.ndarray

Brown

(170, 110, 40)

Type:

np.ndarray

Orange

(255, 150, 0)

Type:

np.ndarray

Coral

(255, 215, 180)

Type:

np.ndarray

Olive

(128, 128, 0)

Type:

np.ndarray

Yellow

(255, 235, 0)

Type:

np.ndarray

Beige

(255, 250, 200)

Type:

np.ndarray

Lime

(190, 255, 0)

Type:

np.ndarray

Green

(0, 190, 0)

Type:

np.ndarray

Mint

(170, 255, 195)

Type:

np.ndarray

Teal

(0, 128, 128)

Type:

np.ndarray

Cyan

(100, 255, 255)

Type:

np.ndarray

Navy

(0, 0, 128)

Type:

np.ndarray

Blue

(67, 133, 255)

Type:

np.ndarray

Purple

(130, 0, 150)

Type:

np.ndarray

Lavender

(230, 190, 255)

Type:

np.ndarray

Magenta

(255, 0, 255)

Type:

np.ndarray

Gray

(128, 128, 128)

Type:

np.ndarray

scenepic.Color(r, g, b)

Convenience method for creating a numpy 3-vector from R,G,B float values.

Parameters:

• r (float) – red value [0,1].

• g (float) – green value [0,1].

• b (float) – blue value [0,1].

Raises:

ValueError – Will raise this if the values are out of range

Returns:

a color array

Return type:

np.ndarray

scenepic.ColorFromBytes()

Construct a color object from byte values.

Parameters:

• red – Red channel

• green – Green channel

• blue – Blue channel

Returns:

a valid color object

Return type:

np.ndarray