# 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

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>