From 1db4cbe5f097b67679ef333ccd6b290cf6f815c2 Mon Sep 17 00:00:00 2001 From: Kostas Karmas Date: Fri, 29 Jan 2021 17:22:49 +0100 Subject: Add images and text about the 3D scene graph CURA-7502 --- .../images/components_interacting_with_scene.jpg | Bin 0 -> 215791 bytes .../images/components_interacting_with_scene.png | Bin 0 -> 177707 bytes docs/scene/images/layer_data_scene_node.jpg | Bin 0 -> 83599 bytes docs/scene/images/scene_example.png | Bin 0 -> 505200 bytes docs/scene/images/scene_example_scene_graph.jpg | Bin 0 -> 335346 bytes docs/scene/scene.md | 80 +++++++++++++++++---- 6 files changed, 66 insertions(+), 14 deletions(-) create mode 100644 docs/scene/images/components_interacting_with_scene.jpg create mode 100644 docs/scene/images/components_interacting_with_scene.png create mode 100644 docs/scene/images/layer_data_scene_node.jpg create mode 100644 docs/scene/images/scene_example.png create mode 100644 docs/scene/images/scene_example_scene_graph.jpg (limited to 'docs') diff --git a/docs/scene/images/components_interacting_with_scene.jpg b/docs/scene/images/components_interacting_with_scene.jpg new file mode 100644 index 0000000000..a78d7cffea Binary files /dev/null and b/docs/scene/images/components_interacting_with_scene.jpg differ diff --git a/docs/scene/images/components_interacting_with_scene.png b/docs/scene/images/components_interacting_with_scene.png new file mode 100644 index 0000000000..a01a138811 Binary files /dev/null and b/docs/scene/images/components_interacting_with_scene.png differ diff --git a/docs/scene/images/layer_data_scene_node.jpg b/docs/scene/images/layer_data_scene_node.jpg new file mode 100644 index 0000000000..e153953213 Binary files /dev/null and b/docs/scene/images/layer_data_scene_node.jpg differ diff --git a/docs/scene/images/scene_example.png b/docs/scene/images/scene_example.png new file mode 100644 index 0000000000..3fee5ae8dd Binary files /dev/null and b/docs/scene/images/scene_example.png differ diff --git a/docs/scene/images/scene_example_scene_graph.jpg b/docs/scene/images/scene_example_scene_graph.jpg new file mode 100644 index 0000000000..5ca91a1041 Binary files /dev/null and b/docs/scene/images/scene_example_scene_graph.jpg differ diff --git a/docs/scene/scene.md b/docs/scene/scene.md index 5539df4a67..70361e3786 100644 --- a/docs/scene/scene.md +++ b/docs/scene/scene.md @@ -2,6 +2,15 @@ Scene ==== The 3D scene in Cura is designed as a [Scene Graph](https://en.wikipedia.org/wiki/Scene_graph), which is common in many 3D graphics applications. The scene graph of Cura is usually very flat, but has the possibility to have nested objects which inherit transformations from each other. +Class Diagram +==== + +The following class diagram depicts the classes that interact with the Scene + +![alt text](images/components_interacting_with_scene.jpg) + +The scene lives in the Controller of the Application, and it is primarily interacting with SceneNode objects, which are the components of the Scene Graph. + Scene Graph ---- Cura's scene graph is a mere tree data structure. This tree contains all scene nodes, which represent the objects in the 3D scene. @@ -10,17 +19,60 @@ The main idea behind the scene tree is that each scene node has a transformation A Typical Scene ---- -Cura's scene has a few nodes that are always present, and a few nodes that are repeated for every object that the user loads onto their build plate. To give an idea of how a scene normally looks, this is an overview of a typical scene tree for Cura. - -* Root - * Camera - * [Build volume](build_volume.md) - * Platform - * Object 1 - * Group 1 - * Object 2 - * Object 3 - * Object 1 convex hull node - * Object 2 convex hull node - * Object 3 convex hull node - * Group 1 convex hull node \ No newline at end of file +Cura's scene has a few nodes that are always present, and a few nodes that are repeated for every object that the user loads onto their build plate. The root of the scene graph is a SceneNode that lives inside the Scene and contains all the other children SceneNodes of the scene. Typically, inside the root you can find the SceneNodes that are always loaded, such as the Cameras and the [BuildVolume](build_volume.md) (which contains the Platform), and the objects that are loaded on the platform. + +Let's take the following example Scene: + +![scene_example.png](images/scene_example.png) + +The scene graph in this case is the following: + + +![scene_example_scene_graph.png](images/scene_example_scene_graph.jpg) + +As it is visible, aside from the BuildVolume, the Cameras, and the objects, the root SceneNode also contains all the ConvexHullNodes, which are used to display the convex hull of each object and each group of objects. A ConvexHullNode is always loaded for each of the existing CuraSceneNodes + + +Accessing SceneNodes in the Scene +---- + +SceneNodes can be accessed using a BreadthFirstIterator or a DepthFirstIterator. Each iterator traverses the scene graph and returns a Python iterator, which yield all the SceneNodes and their children. + +``` python +for node in BreadthFirstIterator(scene.getRoot()): + # do stuff with the node +``` + +Example result when iterating the above scene graph: + +```python +[i for i in BreadthFirstIterator(self._root)] +``` + * 00 = {SceneNode} + * 01 = {BuildVolume} + * 02 = {Camera} + * 03 = {CuraSceneNode} + * 04 = {CuraSceneNode} + * 05 = {Camera} + * 06 = {CuraSceneNode} + * 07 = {ConvexHullNode} + * 08 = {ConvexHullNode} + * 09 = {ConvexHullNode} + * 10 = {ConvexHullNode} + * 11 = {ConvexHullNode} + * 12 = {ConvexHullNode} + * 13 = {ConvexHullNode} + * 14 = {Platform} + * 15 = {CuraSceneNode} + * 16 = {CuraSceneNode} + * 17 = {CuraSceneNode} + * 18 = {CuraSceneNode} + +Layer Data +---- + +Once the Slicing has completed and the CuraEngine has returned the slicing data, Cura creates a CuraSceneNode inside the BuildVolume which holds all the layer data. This CuraSceneNode can be identified via its LayerDataDecorator. + +Layer Data Scene Node + +**Note:** This CuraSceneNode is created once Cura has completed processing the Layer data (after the user clicks on the Preview tab after slicing). The CuraSceneNode then is destroyed once any action that changes the Scene occurs (e.g. if the user moves/rotates/scales an object or changes a setting value). \ No newline at end of file -- cgit v1.2.3