scenepic 1.1.0
3D Visualization Made Easy
Public Member Functions | List of all members
scenepic::Scene Class Reference

Top level container representing an entire ScenePic. More...

#include <scene.h>

Public Member Functions

 Scene (const std::string &scene_id="")
 Constructor. More...
 
void grid (const std::string &width, const std::string &grid_template_rows="", const std::string &grid_template_cols="")
 Defines a CSS layout grid for the canvases of the ScenePic. More...
 
void place (const std::string &canvas_id, const std::string &grid_row, const std::string &grid_column)
 Places a canvas at a specific place in the ScenePic grid. More...
 
std::shared_ptr< Canvas3Dcreate_canvas_3d (const std::string &canvas_id="", double width=400, double height=400, const std::string &html_id="", const Camera &camera=Camera::None(), const Shading &shading=Shading(), const UIParameters &ui_parameters=UIParameters(), const std::string &media_id="")
 Create a new 3D Canvas and append to the Scene. More...
 
std::shared_ptr< Canvas2Dcreate_canvas_2d (const std::string &canvas_id="", double width=400, double height=400, const std::string &html_id="", const Color &background_color=Colors::Black, const std::string &media_id="")
 Create a new 2D Canvas and append to the Scene. More...
 
std::shared_ptr< Graphcreate_graph (const std::string &canvas_id="", double width=400, double height=400, const std::string &name_align="left", const std::string &value_align="right", const std::string &html_id="", const Color &background_color=Colors::White, const Graph::Margin &margin=Graph::Margin(), const std::string &font_family="sans-serif", float name_size=12.0, float value_size=12.0, const std::string &media_id="")
 Create a new graph canvas and append to the Scene. More...
 
std::shared_ptr< AudioTrackcreate_audio (const std::string &audio_id="")
 Create a new AudioTrack and add directly to the Scene. More...
 
std::shared_ptr< Videocreate_video (const std::string &video_id="")
 Create a new Video and add directly to the Scene. More...
 
std::shared_ptr< Meshcreate_mesh (const std::string &mesh_id="", const std::string &layer_id="", bool double_sided=false, bool camera_space=false, const Color &shared_color=Color::None(), const std::string &texture_id="", bool nn_texture=true, bool use_texture_alpha=false, bool is_billboard=false, bool is_label=false)
 Create a new Mesh and append to the Scene. More...
 
std::shared_ptr< MeshUpdateupdate_mesh (const std::string &base_mesh_id, const ConstVectorBufferRef &positions, const ConstVectorBufferRef &normals, const ConstVectorBufferRef &colors, const std::string &mesh_id="")
 Create a new Mesh by updating a base mesh with new vertex positions. More...
 
std::shared_ptr< MeshUpdateupdate_instanced_mesh (const std::string &base_mesh_id, const ConstVectorBufferRef &positions, const ConstQuaternionBufferRef &rotations, const ConstVectorBufferRef &colors, const std::string &mesh_id="")
 Create a new Mesh by updating a base mesh with new vertex positions. More...
 
std::shared_ptr< MeshUpdateupdate_mesh_without_normals (const std::string &base_mesh_id, const ConstVectorBufferRef &positions, const std::string &mesh_id="")
 
std::shared_ptr< MeshUpdateupdate_mesh_positions (const std::string &base_mesh_id, const ConstVectorBufferRef &positions, const std::string &mesh_id="")
 Create a new Mesh by updating a base mesh with new vertex positions. More...
 
std::shared_ptr< Imagecreate_image (const std::string &image_id="")
 Create a new Image and append to the Scene. More...
 
std::shared_ptr< Labelcreate_label (const std::string &label_id="", const std::string &text="Text", const Color &color=Colors::White, double size_in_pixels=12.0, const std::string &font_family="sans-serif", const std::string &layer_id="", const std::string &horizontal_align="left", const std::string &vertical_align="middle", double offset_distance=0.1, bool camera_space=false)
 Create a new Label and append to the Scene. More...
 
std::shared_ptr< TextPanelcreate_text_panel (const std::string &text_panel_id="", const std::string &html_id="", bool add_input_box=false)
 Create a new TextPanel and add directly to the HTML page. More...
 
std::shared_ptr< DropDownMenucreate_drop_down_menu (const std::string &drop_down_menu_id="", const std::string &title="", const std::string &html_id="")
 Create a new DropDownMenu and add directly to the HTML page. More...
 
void configure_user_interface (const UIParameters &ui_parameters)
 Set user interface parameters across all Canvases with given UIParameters instance. More...
 
void link_canvas_events (const std::vector< std::string > &canvas_ids)
 Specify that all input events should be linked across the provided set of Canvases. More...
 
void simulate_key_presses (const std::string &canvas_id, const std::vector< std::string > &keypresses)
 Simulates one or more keypresses to fire off events in the ScenePic UI at startup, e.g. More...
 
JsonValue to_json () const
 Convert this object into ScenePic json. More...
 
void clear_script ()
 Call this if you are dumping a ScenePic script in multiple parts, e.g. More...
 
std::string json () const
 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 the last call to clear_script(). More...
 
std::string script () const
 Returns a JSONP (https://en.wikipedia.org/wiki/JSONP) script representing the Scene. More...
 
float framerate () const
 The number of frames per second that will be displayed by this scene. More...
 
void framerate (float fps)
 
const std::string & status_bar_visibility () const
 The CSS visibility of the status bar. More...
 
void status_bar_visibility (const std::string &visibility)
 
void save_as_json (const std::string &path) const
 Save the scene as a JSON file. More...
 
void save_as_script (const std::string &path, bool standalone=false) const
 Save the scene as a ScenePic script file (JavaScript JSONP format). More...
 
std::map< std::string, QuantizationInfoquantize_updates (float relative_error_threshold=1e-5, float absolute_error_threshold=-1.0, const std::string &base_mesh_id="", bool per_frame_range=true)
 Quantize the mesh updates. More...
 
std::map< std::string, std::size_t > measure_command_size () const
 Returns a breakdown of the number of bytes used by each command type. More...
 
void save_as_html (const std::string &path, const std::string &title="ScenePic", const std::string &head_html="", const std::string &body_html="", const std::string &script_path="", const std::string &library_path="")
 Save the scene as a html file. More...
 
bool script_cleared () const
 Whether the script has been cleared. More...
 

Detailed Description

Top level container representing an entire ScenePic.

Constructor & Destructor Documentation

◆ Scene()

scenepic::Scene::Scene ( const std::string &  scene_id = "")

Constructor.

Parameters
scene_ida unique identifier for the Scene (will be automatically populated if not provided).

Member Function Documentation

◆ clear_script()

void scenepic::Scene::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 return empty.

◆ configure_user_interface()

void scenepic::Scene::configure_user_interface ( const UIParameters ui_parameters)

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

Parameters
ui_parametersglobal UI parameters to set

◆ create_audio()

std::shared_ptr< AudioTrack > scenepic::Scene::create_audio ( const std::string &  audio_id = "")

Create a new AudioTrack and add directly to the Scene.

Parameters
audio_ida unique identifier for the AudioTrack (will be automatically populated if not provided).
Returns
a reference to the new AudioTrack object

◆ create_canvas_2d()

std::shared_ptr< Canvas2D > scenepic::Scene::create_canvas_2d ( const std::string &  canvas_id = "",
double  width = 400,
double  height = 400,
const std::string &  html_id = "",
const Color background_color = Colors::Black,
const std::string &  media_id = "" 
)

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

Parameters
canvas_ida unique identifier for the Canvas (will be automatically populated if not provided).
widththe width in pixels of the Canvas on the HTML page
heightthe height in pixels of the Canvas on the HTML page
html_idoptional id of an HTML element to use as this Canvas's parent in the HTML DOM (otherwise simply appended to document).
background_coloroptional background color for the canvas
media_idoptional 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

◆ create_canvas_3d()

std::shared_ptr< Canvas3D > scenepic::Scene::create_canvas_3d ( const std::string &  canvas_id = "",
double  width = 400,
double  height = 400,
const std::string &  html_id = "",
const Camera camera = Camera::None(),
const Shading shading = Shading(),
const UIParameters ui_parameters = UIParameters(),
const std::string &  media_id = "" 
)

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

Parameters
canvas_ida unique identifier for the Canvas (will be automatically populated if not provided).
widththe width in pixels of the Canvas on the HTML page
heightthe height in pixels of the Canvas on the HTML page
html_idoptional id of an HTML element to use as this Canvas's parent in the HTML DOM (otherwise simply appended to document).
cameraoptional set of Camera parameters for the canvas
shadingoptional set of shading parameters for the canvas
ui_parametersoptional set of user interface parameters
media_idoptional 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

◆ create_drop_down_menu()

std::shared_ptr< DropDownMenu > scenepic::Scene::create_drop_down_menu ( const std::string &  drop_down_menu_id = "",
const std::string &  title = "",
const std::string &  html_id = "" 
)

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

Parameters
drop_down_menu_ida unique identifier for the DropDownMenu (will be automatically populated if not provided).
titlea title for the drop down box
html_idoptional id of an HTML element to use as this TextPanel's parent in the HTML DOM (otherwise will simply be appended to document).
Returns
an reference to the new DropDownMenu object

◆ create_graph()

std::shared_ptr< Graph > scenepic::Scene::create_graph ( const std::string &  canvas_id = "",
double  width = 400,
double  height = 400,
const std::string &  name_align = "left",
const std::string &  value_align = "right",
const std::string &  html_id = "",
const Color background_color = Colors::White,
const Graph::Margin margin = Graph::Margin(),
const std::string &  font_family = "sans-serif",
float  name_size = 12.0,
float  value_size = 12.0,
const std::string &  media_id = "" 
)

Create a new graph canvas and append to the Scene.

Parameters
canvas_ida unique identifier for the Canvas (will be automatically populated if not provided).
widththe width in pixels of the Canvas on the HTML page
heightthe height in pixels of the Canvas on the HTML page
name_alignHow to align the sparkline label (one of 'left', 'right', 'top', or 'bottom')
value_alignHow to align the sparkline value (one of 'left', 'right', 'top', or 'bottom')
html_idoptional id of an HTML element to use as this Canvas's parent in the HTML DOM (otherwise simply appended to document).
background_coloroptional background color for the canvas
marginthe outer margin of the graph
font_familythe font family used for the graph labels
name_sizethe text size in pixels used for the graph labels
value_sizethe text size in pixels used for the graph values
media_idoptional 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

◆ create_image()

std::shared_ptr< Image > scenepic::Scene::create_image ( const std::string &  image_id = "")

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_ida unique identifier for the Image (will be automatically populated if not provided).
Returns
a reference to the new Image object

◆ create_label()

std::shared_ptr< Label > scenepic::Scene::create_label ( const std::string &  label_id = "",
const std::string &  text = "Text",
const Color color = Colors::White,
double  size_in_pixels = 12.0,
const std::string &  font_family = "sans-serif",
const std::string &  layer_id = "",
const std::string &  horizontal_align = "left",
const std::string &  vertical_align = "middle",
double  offset_distance = 0.1,
bool  camera_space = false 
)

Create a new Label and append to the Scene.

Labels are Scene-wide resources that can be reused across multiple Meshes.

Parameters
label_ida unique identifier for the Label (will be automatically populated if not provided).
textthe text to use in the label
colorthe color to use
size_in_pixelsthe size in pixels to display the label at
font_familyHTML font family name.
layer_idan identifier to allow several labels to be grouped together into a "layer". Layers should be used in conjunction with set_layer_settings().
horizontal_align(one of 'left', 'center', 'right'): how to align the label horizontally.
vertical_align(one of 'top', 'middle', 'bottom'): how to align the label vertically.
offset_distancedistance in world space to offset the label by when using left/right/top/bottom alignment.
camera_spacewhether the label should be created in camera space
Returns
a reference to the new Label object

◆ create_mesh()

std::shared_ptr< Mesh > scenepic::Scene::create_mesh ( const std::string &  mesh_id = "",
const std::string &  layer_id = "",
bool  double_sided = false,
bool  camera_space = false,
const Color shared_color = Color::None(),
const std::string &  texture_id = "",
bool  nn_texture = true,
bool  use_texture_alpha = false,
bool  is_billboard = false,
bool  is_label = false 
)

Create a new Mesh and append to the Scene.

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

Parameters
mesh_ida unique identifier for the Mesh (will be automatically populated if not provided).
layer_idan identifier to allow several Meshes to be grouped together into a "layer". Layers should be used in conjunction with Canvas3D.set_layer_settings().
double_sidedwhether to turn off back face culling and draw the Mesh's triangles as double sided.
camera_spacewhether this Mesh is defined in camera space (cannot be moved in the ScenePic user interface) or world space (standard).
shared_colorsee Mesh constructor.
texture_idsee Mesh constructor.
nn_texturewhether the shader should use nearest-neighbor texture interpolation.
use_texture_alphawhether to use the alpha channel in the texture for transparency (only relevant for textured Meshes).
is_billboarddraw this Mesh as a billboard (i.e. always facing the user) rather than rotating with the rest of the world.
is_labelthis mesh will be treated specially as a label. Not for public use.
Returns
a reference to the new Mesh object

◆ create_text_panel()

std::shared_ptr< TextPanel > scenepic::Scene::create_text_panel ( const std::string &  text_panel_id = "",
const std::string &  html_id = "",
bool  add_input_box = false 
)

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

Parameters
text_panel_ida unique identifier for the TextPanel (will be automatically populated if not provided).
html_idoptional id of an HTML element to use as this TextPanel's parent in the HTML DOM (otherwise will simply be appended to document).
add_input_boxwhether to add an input box to the TextPanel
Returns
a reference to the new TextPanel object

◆ create_video()

std::shared_ptr< Video > scenepic::Scene::create_video ( const std::string &  video_id = "")

Create a new Video and add directly to the Scene.

Parameters
video_ida unique identifier for the Video (will be automatically populated if not provided).
Returns
a reference to the new Video object

◆ framerate() [1/2]

float scenepic::Scene::framerate ( ) const

The number of frames per second that will be displayed by this scene.

◆ framerate() [2/2]

void scenepic::Scene::framerate ( float  fps)

◆ grid()

void scenepic::Scene::grid ( const std::string &  width,
const std::string &  grid_template_rows = "",
const std::string &  grid_template_cols = "" 
)

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

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
widthCSS declaration for the width of the ScenePic.
grid_template_rowsCSS declaration defining the rows of the ScenePic
grid_template_colsCSS declaration defining the columns of the ScenePic

◆ json()

std::string scenepic::Scene::json ( ) const

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 the last call to clear_script().

Returns
a JSON string representing the Scene

◆ link_canvas_events()

void scenepic::Scene::link_canvas_events ( const std::vector< std::string > &  canvas_ids)

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

Parameters
canvas_idsthe canvases which should have linked events

◆ measure_command_size()

std::map< std::string, std::size_t > scenepic::Scene::measure_command_size ( ) const

Returns a breakdown of the number of bytes used by each command type.

◆ place()

void scenepic::Scene::place ( const std::string &  canvas_id,
const std::string &  grid_row,
const std::string &  grid_column 
)

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

See also
scenepic::Scene::grid.
Parameters
canvas_idthe unique ID of the Canvas to place.
grid_rowthe CSS row specification for the Canvas
grid_columnthe CSS column specification for the Canvas

◆ quantize_updates()

std::map< std::string, QuantizationInfo > scenepic::Scene::quantize_updates ( float  relative_error_threshold = 1e-5,
float  absolute_error_threshold = -1.0,
const std::string &  base_mesh_id = "",
bool  per_frame_range = true 
)

Quantize the mesh updates.

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_thresholdthe maximum expected error as a multiple of the range of values in the base mesh
absolute_error_thresholdthe maximum expected error in absolute units
base_mesh_idoptional base mesh where quantization is applied. Otherwise all mesh updates are quantized.
per_frame_rangewhether to use the most accurate range per update, increasing accuracy but reducing compression.
Returns
the per-frame quantization information

◆ save_as_html()

void scenepic::Scene::save_as_html ( const std::string &  path,
const std::string &  title = "ScenePic",
const std::string &  head_html = "",
const std::string &  body_html = "",
const std::string &  script_path = "",
const std::string &  library_path = "" 
)

Save the scene as a html file.

Parameters
paththe path to the file on disk
titlethe HTML title
head_htmlthe raw HTML to place in the HEAD tag
body_htmlthe raw HTML to place in the BODY tag
script_pathdesired relative path for the script. Empty string indicates to embed the script in the HTML page.
library_pathdesired relative path for the library. Empty string indicates to embed the library in the HTML page.

◆ save_as_json()

void scenepic::Scene::save_as_json ( const std::string &  path) const

Save the scene as a JSON file.

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
paththe path to the file on disk

◆ save_as_script()

void scenepic::Scene::save_as_script ( const std::string &  path,
bool  standalone = false 
) const

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
paththe path to the file on disk
standalonewhether to include the library in the script

◆ script()

std::string scenepic::Scene::script ( ) const

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

◆ script_cleared()

bool scenepic::Scene::script_cleared ( ) const

Whether the script has been cleared.

◆ simulate_key_presses()

void scenepic::Scene::simulate_key_presses ( const std::string &  canvas_id,
const std::vector< std::string > &  keypresses 
)

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

video playback.

Parameters
canvas_idID of the canvas on which to fire off this event.
keypressesthe key values

◆ status_bar_visibility() [1/2]

const std::string & scenepic::Scene::status_bar_visibility ( ) const

The CSS visibility of the status bar.

◆ status_bar_visibility() [2/2]

void scenepic::Scene::status_bar_visibility ( const std::string &  visibility)

◆ to_json()

JsonValue scenepic::Scene::to_json ( ) const

Convert this object into ScenePic json.

Returns
a json value

◆ update_instanced_mesh()

std::shared_ptr< MeshUpdate > scenepic::Scene::update_instanced_mesh ( const std::string &  base_mesh_id,
const ConstVectorBufferRef &  positions,
const ConstQuaternionBufferRef &  rotations,
const ConstVectorBufferRef &  colors,
const std::string &  mesh_id = "" 
)

Create a new Mesh by updating a base mesh with new vertex positions.

Meshes are Scene-wide resources that can be reused across multiple Frames in multiple Canvas3Ds. This method can be used to create a new mesh which is simply a repositioning of an existing mesh, thus saving the cost of defining the entire topology every time the mesh is instantiated. The base mesh is not modified by this operation.

Parameters
base_mesh_idthe id of the base mesh to update
positionsthe new instance positions
rotationsthe new instance rotations
colorsthe new instance colors
mesh_ida unique identifier for the Mesh (will be automatically populated if not provided).
Returns
a references to the new Mesh object

◆ update_mesh()

std::shared_ptr< MeshUpdate > scenepic::Scene::update_mesh ( const std::string &  base_mesh_id,
const ConstVectorBufferRef &  positions,
const ConstVectorBufferRef &  normals,
const ConstVectorBufferRef &  colors,
const std::string &  mesh_id = "" 
)

Create a new Mesh by updating a base mesh with new vertex positions.

Meshes are Scene-wide resources that can be reused across multiple Frames in multiple Canvas3Ds. This method can be used to create a new mesh which is simply a repositioning of an existing mesh, thus saving the cost of defining the entire topology every time the mesh is instantiated. The base mesh is not modified by this operation.

Parameters
base_mesh_idthe id of the base mesh to update
positionsthe new vertex positions
mesh_ida unique identifier for the Mesh (will be automatically populated if not provided).
normalsthe new vertex normals
colorsthe new vertex colors
Returns
a references to the new Mesh object

◆ update_mesh_positions()

std::shared_ptr< MeshUpdate > scenepic::Scene::update_mesh_positions ( const std::string &  base_mesh_id,
const ConstVectorBufferRef &  positions,
const std::string &  mesh_id = "" 
)

Create a new Mesh by updating a base mesh with new vertex positions.

Meshes are Scene-wide resources that can be reused across multiple Frames in multiple Canvas3Ds. This method can be used to create a new mesh which is simply a repositioning of an existing mesh, thus saving the cost of defining the entire topology every time the mesh is instantiated. The base mesh is not modified by this operation. Normals will be computed automatically from the provided positions.

Parameters
base_mesh_idthe id of the base mesh to update
positionsthe new vertex positions
mesh_ida unique identifier for the Mesh (will be automatically populated if not provided).
Returns
a references to the new Mesh object

◆ update_mesh_without_normals()

std::shared_ptr< MeshUpdate > scenepic::Scene::update_mesh_without_normals ( const std::string &  base_mesh_id,
const ConstVectorBufferRef &  positions,
const std::string &  mesh_id = "" 
)
Deprecated:
This method has been deprecated for clarity and naming purposes.
See also
Scene::update_mesh_positions

The documentation for this class was generated from the following file: