scenepic 1.1.0
3D Visualization Made Easy
|
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< Canvas3D > | 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. More... | |
std::shared_ptr< Canvas2D > | 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. More... | |
std::shared_ptr< Graph > | 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. More... | |
std::shared_ptr< AudioTrack > | create_audio (const std::string &audio_id="") |
Create a new AudioTrack and add directly to the Scene. More... | |
std::shared_ptr< Video > | create_video (const std::string &video_id="") |
Create a new Video and add directly to the Scene. More... | |
std::shared_ptr< Mesh > | 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. More... | |
std::shared_ptr< MeshUpdate > | 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. More... | |
std::shared_ptr< MeshUpdate > | 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. More... | |
std::shared_ptr< MeshUpdate > | update_mesh_without_normals (const std::string &base_mesh_id, const ConstVectorBufferRef &positions, const std::string &mesh_id="") |
std::shared_ptr< MeshUpdate > | 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. More... | |
std::shared_ptr< Image > | create_image (const std::string &image_id="") |
Create a new Image and append to the Scene. More... | |
std::shared_ptr< Label > | 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. More... | |
std::shared_ptr< TextPanel > | 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. More... | |
std::shared_ptr< DropDownMenu > | 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. 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, QuantizationInfo > | 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. 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... | |
Top level container representing an entire ScenePic.
scenepic::Scene::Scene | ( | const std::string & | scene_id = "" | ) |
Constructor.
scene_id | a unique identifier for the Scene (will be automatically populated if not provided). |
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.
void scenepic::Scene::configure_user_interface | ( | const UIParameters & | ui_parameters | ) |
Set user interface parameters across all Canvases with given UIParameters instance.
ui_parameters | global UI parameters to set |
std::shared_ptr< AudioTrack > scenepic::Scene::create_audio | ( | const std::string & | audio_id = "" | ) |
Create a new AudioTrack and add directly to the Scene.
audio_id | a unique identifier for the AudioTrack (will be automatically populated if not provided). |
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.
canvas_id | a unique identifier for the Canvas (will be automatically populated if not provided). |
width | the width in pixels of the Canvas on the HTML page |
height | the height in pixels of the Canvas on the HTML page |
html_id | optional id of an HTML element to use as this Canvas's parent in the HTML DOM (otherwise simply appended to document). |
background_color | optional background color for the canvas |
media_id | 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. |
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.
canvas_id | a unique identifier for the Canvas (will be automatically populated if not provided). |
width | the width in pixels of the Canvas on the HTML page |
height | the height in pixels of the Canvas on the HTML page |
html_id | optional id of an HTML element to use as this Canvas's parent in the HTML DOM (otherwise simply appended to document). |
camera | optional set of Camera parameters for the canvas |
shading | optional set of shading parameters for the canvas |
ui_parameters | optional set of user interface parameters |
media_id | 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. |
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.
drop_down_menu_id | a unique identifier for the DropDownMenu (will be automatically populated if not provided). |
title | a title for the drop down box |
html_id | optional id of an HTML element to use as this TextPanel's parent in the HTML DOM (otherwise will simply be appended to document). |
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.
canvas_id | a unique identifier for the Canvas (will be automatically populated if not provided). |
width | the width in pixels of the Canvas on the HTML page |
height | the height in pixels of the Canvas on the HTML page |
name_align | How to align the sparkline label (one of 'left', 'right', 'top', or 'bottom') |
value_align | How to align the sparkline value (one of 'left', 'right', 'top', or 'bottom') |
html_id | optional id of an HTML element to use as this Canvas's parent in the HTML DOM (otherwise simply appended to document). |
background_color | optional background color for the canvas |
margin | the outer margin of the graph |
font_family | the font family used for the graph labels |
name_size | the text size in pixels used for the graph labels |
value_size | the text size in pixels used for the graph values |
media_id | 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. |
std::shared_ptr< Image > scenepic::Scene::create_image | ( | const std::string & | image_id = "" | ) |
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.
label_id | a unique identifier for the Label (will be automatically populated if not provided). |
text | the text to use in the label |
color | the color to use |
size_in_pixels | the size in pixels to display the label at |
font_family | HTML font family name. |
layer_id | an 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_distance | distance in world space to offset the label by when using left/right/top/bottom alignment. |
camera_space | whether the label should be created in camera space |
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.
mesh_id | a unique identifier for the Mesh (will be automatically populated if not provided). |
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(). |
double_sided | whether to turn off back face culling and draw the Mesh's triangles as double sided. |
camera_space | whether this Mesh is defined in camera space (cannot be moved in the ScenePic user interface) or world space (standard). |
shared_color | see Mesh constructor. |
texture_id | see Mesh constructor. |
nn_texture | whether the shader should use nearest-neighbor texture interpolation. |
use_texture_alpha | whether to use the alpha channel in the texture for transparency (only relevant for textured Meshes). |
is_billboard | draw this Mesh as a billboard (i.e. always facing the user) rather than rotating with the rest of the world. |
is_label | this mesh will be treated specially as a label. Not for public use. |
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.
text_panel_id | a unique identifier for the TextPanel (will be automatically populated if not provided). |
html_id | optional 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_box | whether to add an input box to the TextPanel |
std::shared_ptr< Video > scenepic::Scene::create_video | ( | const std::string & | video_id = "" | ) |
float scenepic::Scene::framerate | ( | ) | const |
The number of frames per second that will be displayed by this scene.
void scenepic::Scene::framerate | ( | float | fps | ) |
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.
width | CSS declaration for the width of the ScenePic. |
grid_template_rows | CSS declaration defining the rows of the ScenePic |
grid_template_cols | CSS declaration defining the columns of the ScenePic |
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().
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.
canvas_ids | the canvases which should have linked events |
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.
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.
canvas_id | the unique ID of the Canvas to place. |
grid_row | the CSS row specification for the Canvas |
grid_column | the CSS column specification for the Canvas |
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.
relative_error_threshold | the maximum expected error as a multiple of the range of values in the base mesh |
absolute_error_threshold | the maximum expected error in absolute units |
base_mesh_id | optional base mesh where quantization is applied. Otherwise all mesh updates are quantized. |
per_frame_range | whether to use the most accurate range per update, increasing accuracy but reducing compression. |
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.
path | the path to the file on disk |
title | the HTML title |
head_html | the raw HTML to place in the HEAD tag |
body_html | the raw HTML to place in the BODY tag |
script_path | desired relative path for the script. Empty string indicates to embed the script in the HTML page. |
library_path | desired relative path for the library. Empty string indicates to embed the library in the HTML page. |
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.
path | the path to the file on disk |
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.
path | the path to the file on disk |
standalone | whether to include the library in the 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().
bool scenepic::Scene::script_cleared | ( | ) | const |
Whether the script has been cleared.
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.
canvas_id | ID of the canvas on which to fire off this event. |
keypresses | the key values |
const std::string & scenepic::Scene::status_bar_visibility | ( | ) | const |
The CSS visibility of the status bar.
void scenepic::Scene::status_bar_visibility | ( | const std::string & | visibility | ) |
JsonValue scenepic::Scene::to_json | ( | ) | const |
Convert this object into ScenePic json.
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.
base_mesh_id | the id of the base mesh to update |
positions | the new instance positions |
rotations | the new instance rotations |
colors | the new instance colors |
mesh_id | a unique identifier for the Mesh (will be automatically populated if not provided). |
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.
base_mesh_id | the id of the base mesh to update |
positions | the new vertex positions |
mesh_id | a unique identifier for the Mesh (will be automatically populated if not provided). |
normals | the new vertex normals |
colors | the new vertex colors |
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.
base_mesh_id | the id of the base mesh to update |
positions | the new vertex positions |
mesh_id | a unique identifier for the Mesh (will be automatically populated if not provided). |
std::shared_ptr< MeshUpdate > scenepic::Scene::update_mesh_without_normals | ( | const std::string & | base_mesh_id, |
const ConstVectorBufferRef & | positions, | ||
const std::string & | mesh_id = "" |
||
) |