1.3. Scenegraph Module¶

class
raysect.core.scenegraph.node.
Node
¶ The scenegraph node class.
The basic constituent of a scenegraph tree. Nodes can be linked together by parenting one Node to another to form a tree structure. Each node in a scenegraph represents a distinct coordinate 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 coordinate systems, can be calculated. Using this transform it is then possible to transform vectors and points between the two coordinate systems.
Parameters:  parent (_NodeBase) – Assigns the Node’s parent to the specified scenegraph object.
 transform (AffineMatrix3D) – Sets the affine transform associated with the Node.
 name (str) – A string defining the node name.

name
¶ The name of this node.
Getter: Returns this node’s name. Setter: Sets this node’s name. Return type: str

parent
¶ The parent of this node in the scenegraph.
Getter: Returns this node’s parent node. Setter: Sets this node’s parent. Return type: Node

to
()¶ Returns an affine transform that, when applied to a vector or point, transforms the vector or point from the coordinate space of the calling node to the coordinate 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.
Getter: Returns this node’s affine transform matrix. Setter: Sets this node’s affine transform matrix. Return type: AffineMatrix3D

class
raysect.core.scenegraph.observer.
Observer
¶ A scenegraph 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
¶ A scenegraph object representing a rayintersectable 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 scenegraph with which a ray can interact.
This is a base class, its functionality must be implemented fully by the deriving class.
Parameters:  parent (_NodeBase) – Assigns the Node’s parent to the specified scenegraph 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 scenegraph 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 scenegraph 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 scenegraph 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 scenegraph 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 (_NodeBase) – Assigns the Node’s parent to the specified scenegraph 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.
Getter: Returns this primitive’s material. Setter: Sets this primitive’s material. 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 rayprimitive 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 scenegraph 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 scenegraph 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 raytracing calculations are now potentially invalid and must be recalculated, taking the new geometry into account.

notify_material_change
()¶ Notifies the scenegraph 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 raytracing 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 scenegraph.
The world node tracks all primitives and observers in the world. It maintains acceleration structures to speed up the raytracing calculations. The particular acceleration algorithm used is selectable. The default acceleration structure is a kdtree.
Parameters: name – A string defining the node name. 
accelerator
¶ The acceleration structure used for this world’s scenegraph.
Getter: Returns this world node’s acceleration structure. Setter: Sets this world node’s acceleration structure.

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 subdivision method. If changes are made to the scenegraph 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 scenegraph. 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 scenegraph 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 scenegraph, 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 scenegraph 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.
Getter: Returns this world node’s name. Setter: Sets this world node’s name. Return type: str

observers
¶ The list of observers in this scenegraph.
Getter: Returns this world node’s observers. Return type: list

primitives
¶ The list of primitives maintained in this scenegraph.
Getter: Returns this world node’s primitive list. Return type: list

to
()¶ Returns an affine transform that, when applied to a vector or point, transforms the vector or point from the coordinate space of the calling node to the coordinate 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. Return type: AffineMatrix3D


raysect.core.scenegraph.utility.
print_scenegraph
()¶ Prettyprints a scenegraph.
This function will print the scenegraph that contains the specified node. The specified node will be highlighted in the tree by postfixing the node with the string: “[referring node]”.
Parameters: node (_NodeBase) – The target node.