1.3. Scenegraph Module¶

class raysect.core.scenegraph.node.Node¶

The scene-graph node class.

The basic constituent of a scene-graph tree. Nodes can be linked together by parenting one Node to another to form a tree structure. Each node in a scene-graph represents a distinct co-ordinate system. An affine transform associated with each node describes the relationship between a node and its parent’s coordinate system. By combining the transforms (and inverse transforms) along the path between two nodes in the tree, the direct transform between any two arbitrary nodes, and thus their co-ordinate systems, can be calculated. Using this transform it is then possible to transform vectors and points between the two co-ordinate systems.

Parameters

parent (Node) – Assigns the Node’s parent to the specified scene-graph object.
transform (AffineMatrix3D) – Sets the affine transform associated with the Node.
name (str) – A string defining the node name.

Variables

children (list) – A list of child nodes for which this node is the parent.
meta (dict) – A dictionary for the storage of any extra user specified meta data.
root (Node) – A reference to the root node of this node’s scene-graph (i.e. the parent of all parents.

name¶

The name of this node.

Return type: str

parent¶

The parent of this node in the scenegraph.

Return type: Node

to()¶

Returns an affine transform that, when applied to a vector or point, transforms the vector or point from the co-ordinate space of the calling node to the co-ordinate space of the target node.

For example, if space B is translated +100 in x compared to space A and A.to(B) is called then the matrix returned would represent a translation of -100 in x. Applied to point (0,0,0) in A, this would produce the point (-100,0,0) in B as B is translated +100 in x compared to A.

Parameters: node (_NodeBase) – The target node.
Returns: An AffineMatrix3D describing the coordinate transform.
Rtyoe: AffineMatrix3D

to_local()¶

Returns an affine transform from world space into this nodes local coordinate space.

Return type: AffineMatrix3D

to_root()¶

Returns an affine transform from local space into the parent node’s coordinate space.

Return type: AffineMatrix3D

transform¶

The transform for this node’s coordinate system in relation to the parent node.

Return type: AffineMatrix3D

class raysect.core.scenegraph.observer.Observer¶

A scene-graph class for observing the world.

An observer class is intended to launch rays and sample the world. This is a base class and the observe function must be implemented by a deriving class. This object is the fundamental abstraction for items such as cameras, fibre optics and other sampling objects.

observe()¶

Virtual method - to be implemented by derived classes.

Triggers the exploration of the scene by emitting rays according to the model defined by the derived class implementing the method.

class raysect.core.scenegraph.primitive.Primitive¶

Bases: raysect.core.scenegraph.node.Node

A scene-graph object representing a ray-intersectable surface/volume.

A primitive class defines an open surface or closed surface (volume) that can be intersected by a ray. For example, this could be a geometric primitive such as a sphere, or more complicated surface such as a polyhedral mesh. The primitive class is the only class in the scene-graph with which a ray can interact.

This is a base class, its functionality must be implemented fully by the deriving class.

Parameters

parent (Node) – Assigns the Node’s parent to the specified scene-graph object.
transform (AffineMatrix3D) – Sets the affine transform associated with the Node.
material (Material) – An object representing the material properties of the primitive.
name (str) – A string defining the node name.

bounding_box()¶

Virtual method - to be implemented by derived classes.

When the primitive is connected to a scene-graph containing a World object at its root, this method should return a bounding box that fully encloses the primitive’s surface (plus a small margin to avoid numerical accuracy problems). The bounding box must be defined in the world’s coordinate space.

If this method is called when the primitive is not connected to a scene-graph with a World object at its root, it must throw a TypeError exception.

Returns: A world space BoundingBox3D object.
Return type: BoundingBox3D

bounding_sphere()¶

When the primitive is connected to a scene-graph containing a World object at its root, this method should return a bounding sphere that fully encloses the primitive’s surface (plus a small margin to avoid numerical accuracy problems). The bounding sphere must be defined in the world’s coordinate space.

If this method is called when the primitive is not connected to a scene-graph with a World object at its root, it must throw a TypeError exception.

The default implementation is to wrap the the primitive’s bounding box with a sphere. If the bounding sphere can be more optimally calculated for the primitive, it should override this method.

Returns: A world space BoundingSphere3D object.
Return type: BoundingSphere3D

contains()¶

Virtual method - to be implemented by derived classes.

Must returns True if the Point3D lies within the boundary of the surface defined by the Primitive. False is returned otherwise.

Parameters: p (Point3D) – The Point3D to test.
Returns: True if the Point3D is enclosed by the primitive surface, False otherwise.
Return type: bool

hit()¶

Virtual method - to be implemented by derived classes.

Calculates the closest intersection of the Ray with the Primitive surface, if such an intersection exists.

If a hit occurs an Intersection object must be returned, otherwise None is returned. The intersection object holds the details of the intersection including the point of intersection, surface normal and the objects involved in the intersection.

Parameters: ray (Ray) – The ray to test for intersection.
Returns: An Intersection object or None if no intersection occurs.
Return type: Intersection

instance()¶

Returns a new instance of the primitive with the same geometry.

Parameters

parent (Node) – Assigns the Node’s parent to the specified scene-graph object.
transform (AffineMatrix3D) – Sets the affine transform associated with the Node.
material (Material) – An object representing the material properties of the primitive.
name (str) – A string defining the node name.

Returns

material¶

The material class for this primitive.

Return type: Material

next_intersection()¶

Virtual method - to be implemented by derived classes.

Returns the next intersection of the ray with the primitive along the ray path.

This method may only be called following a call to hit(). If the ray has further intersections with the primitive, these may be obtained by repeatedly calling the next_intersection() method. Each call to next_intersection() will return the next ray-primitive intersection along the ray’s path. If no further intersections are found or intersections lie outside the ray parameters then next_intersection() will return None.

If any geometric elements of the primitive, ray and/or scene-graph are altered between a call to hit() and calls to next_intersection() the data returned by next_intersection() may be invalid. Primitives may cache data to accelerate next_intersection() calls which will be invalidated by geometric alterations to the scene. If the scene is altered the data returned by next_intersection() is undefined.

Return type: Intersection

notify_geometry_change()¶

Notifies the scene-graph root of a change to the primitive’s geometry.

This method must be called by primitives when their geometry changes. The notification informs the root node that any caching structures used to accelerate ray-tracing calculations are now potentially invalid and must be recalculated, taking the new geometry into account.

notify_material_change()¶

Notifies the scene-graph root of a change to the primitive’s material.

This method must be called by primitives when their material changes. The notification informs the root node that any caching structures used to accelerate ray-tracing calculations are now potentially invalid and must be recalculated, taking the new material into account.

class raysect.core.scenegraph.world.World¶

The root node of the scene-graph.

The world node tracks all primitives and observers in the world. It maintains acceleration structures to speed up the ray-tracing calculations. The particular acceleration algorithm used is selectable. The default acceleration structure is a kd-tree.

Parameters: name – A string defining the node name.

accelerator¶: The acceleration structure used for this world’s scene-graph.

build_accelerator()¶

This method manually triggers a rebuild of the Acceleration object.

If the Acceleration object is already in a consistent state this method will do nothing unless the force keyword option is set to True.

The Acceleration object is used to accelerate hit() and contains() calculations, typically using a spatial sub-division method. If changes are made to the scene-graph structure, transforms or to a primitive’s geometry the acceleration structures may no longer represent the geometry of the scene and hence must be rebuilt. This process is usually performed automatically as part of the first call to hit() or contains() following a change in the scene-graph. As calculating these structures can take some time, this method provides the option of triggering a rebuild outside of hit() and contains() in case the user wants to be able to perform a benchmark without including the overhead of the Acceleration object rebuild.

Parameters: force (bool) – If set to True, forces rebuilding of acceleration structure.

contains()¶

Returns a list of Primitives that contain the specified point within their surface.

An empty list is returned if no Primitives contain the Point3D.

This method automatically rebuilds the Acceleration object that is used to optimise the contains calculation - if a Primitive’s geometry or a transform affecting a primitive has changed since the last call to hit() or contains(), the Acceleration structure used to optimise the contains calculation is rebuilt to represent the new scene-graph state.

Parameters: point (Point3D) – The point to test.
Returns: A list containing all Primitives that enclose the Point3D.
Return type: list

hit()¶

Calculates the closest intersection of the Ray with the Primitives in the scene-graph, if such an intersection exists.

If a hit occurs an Intersection object is returned which contains the mathematical details of the intersection. None is returned if the ray does not intersect any primitive.

This method automatically rebuilds the Acceleration object that is used to optimise hit calculations - if a Primitive’s geometry or a transform affecting a primitive has changed since the last call to hit() or contains(), the Acceleration structure used to optimise hit calculations is rebuilt to represent the new scene-graph state.

Parameters: ray (Ray) – The ray to test.
Returns: An Intersection object or None if no intersection occurs.
Return type: Intersection

name¶

The name for this world node.

Return type: str

observers¶

The list of observers in this scene-graph.

Return type: list

primitives¶

The list of primitives maintained in this scene-graph.

Return type: list

to()¶

Returns an affine transform that, when applied to a vector or point, transforms the vector or point from the co-ordinate space of the calling node to the co-ordinate space of the target node.

For example, if space B is translated +100 in x compared to space A and A.to(B) is called then the matrix returned would represent a translation of -100 in x. Applied to point (0,0,0) in A, this would produce the point (-100,0,0) in B as B is translated +100 in x compared to A.

Parameters: node (Node) – The target node.
Returns: An AffineMatrix3D describing the coordinate transform.
Return type: AffineMatrix3D

raysect.core.scenegraph.utility.print_scenegraph()¶

Pretty-prints a scene-graph.

This function will print the scene-graph that contains the specified node. The specified node will be highlighted in the tree by post-fixing the node with the string: “[referring node]”.

Parameters: node (Node) – The target node.

>>> from raysect.core import Point3D, translate, print_scenegraph
>>> from raysect.primitive import Cylinder, Sphere, Box
>>> from raysect.optical import World
>>>
>>> world = World()
>>>
>>> cyl_x = Cylinder(1, 4.2, transform=translate(0, 0, -2.1), parent=world)
>>> sphere = Sphere(2.0, parent=world)
>>> cube = Box(Point3D(-1.5, -1.5, -1.5), Point3D(1.5, 1.5, 1.5), world)
>>>
>>> print_scenegraph(sphere)
<World at 0x7f11eee98e08>
 |
 |_ <Cylinder at 0x7f11e40c9588>
 |
 |_ <Sphere at 0x7f11ec063678> [referring node]
 |
 |_ <Box at 0x7f11e40c9648>