2.2. Meshes

class raysect.primitive.mesh.mesh.Mesh

Bases: raysect.core.scenegraph.primitive.Primitive

This primitive defines a polyhedral surface with triangular faces.

To define a new mesh, a list of vertices and triangles must be supplied. A set of vertex normals, used for smoothing calculations may also be provided.

The mesh vertices are supplied as an Nx3 list/array of floating point values. For each Vertex, x, y and z coordinates must be supplied. e.g.

vertices = [[0.0, 0.0, 1.0], [1.0, 0.0, 0.0], ...]

Vertex normals are similarly defined. Note that vertex normals must be correctly normalised.

The triangle array is either Mx3 or Mx6 - Mx3 if only vertices are defined or Mx6 if both vertices and vertex normals are defined. Triangles are defined by indexing into the vertex and vertex normal arrays. i.e:

triangles = [[v1, v2, v3, n1, n2, n3], ...]

where v1, v2, v3 are the vertex array indices specifying the triangle’s vertices and n1, n2, n3 are the normal array indices specifying the triangle’s surface normals at each vertex location. Where normals are not defined, n1, n2 and n3 are omitted.

The mesh may be an open surface (which does not enclose a volume) or a closed surface (which defines a volume). The nature of the mesh must be specified using the closed argument. If closed is True (default) then the mesh must be watertight and the face normals must be facing so they point out of the volume. If the mesh is open then closed must be set to False. Incorrectly setting the closed argument may result in undefined behaviour, depending on the application of the ray-tracer.

If vertex normals are defined for some or all of the triangles of the mesh then normal interpolation may be enabled for the mesh. For optical models this will result in a (suitably defined) mesh appearing smooth rather than faceted. If the triangles do not have vertex normals defined, the smoothing argument is ignored.

An alternate option for creating a new mesh is to create an instance of an existing mesh. An instance is a “clone” of the original mesh. Mesh instances hold references to the internal data of the target mesh, they are therefore very memory efficient (particularly for detailed meshes) compared to creating a new mesh from scratch. A new instance of a mesh can be created using the instance() method.

If a mesh contains degenerate triangles (common for meshes generated from CAD models), enable tolerant mode to automatically remove them during mesh initialisation. A degenerate triangle is one where two or more vertices are coincident or all the vertices lie on the same line. Degenerate triangles will produce rendering error if encountered even though they are “infinitesimally” thin. A ray can still intersect them if they perfectly align as the triangle edges are treated as part of the triangle surface).

The kdtree_* arguments are tuning parameters for the kd-tree construction. For more information see the documentation of KDTree3D. The default values should result in efficient construction of the mesh’s internal kd-tree. Generally there is no need to modify these parameters unless the memory used by the kd-tree must be controlled. This may occur if very large meshes are used.

Parameters:
  • vertices (object) – An N x 3 list of vertices.
  • triangles (object) – An M x 3 or N x 6 list of vertex/normal indices defining the mesh triangles.
  • normals (object) – An K x 3 list of vertex normals or None (default=None).
  • smoothing (bool) – True to enable normal interpolation (default=True).
  • closed (bool) – True is the mesh defines a closed volume (default=True).
  • tolerant (bool) – Mesh will automatically correct meshes with degenerate triangles if set to True (default=True).
  • kdtree_max_depth (int) – The maximum tree depth (automatic if set to 0, default=0).
  • kdtree_min_items (int) – The item count threshold for forcing creation of a new leaf node (default=1).
  • kdtree_hit_cost (double) – The relative computational cost of item hit evaluations vs kd-tree traversal (default=20.0).
  • kdtree_empty_bonus (double) – The bonus applied to node splits that generate empty leaves (default=0.2).
  • parent (Node) – Attaches the mesh to the specified scene-graph node (default=None).
  • transform (AffineMatrix3D) – The co-ordinate transform between the mesh and its parent (default=unity matrix).
  • material (Material) – The surface/volume material (default=Material() instance).
  • name (str) – A human friendly name to identity the mesh in the scene-graph (default=””).
bounding_box()

Returns a world space bounding box that encloses the mesh.

The box is padded by a small margin to reduce the risk of numerical accuracy problems between the mesh and box representations following coordinate transforms.

Returns:A BoundingBox3D object.
contains()

Identifies if the point lies in the volume defined by the mesh.

If a mesh is open, this method will always return False.

This method will fail if the face normals of the mesh triangles are not oriented to be pointing out of the volume surface.

Parameters:p – The point to test.
Returns:True if the point lies in the volume, False otherwise.
from_file()

Instances a new Mesh using data from a file object or filename.

The mesh must be stored in a RaySect Mesh (RSM) format file. RSM files are created with the Mesh save() method.

Parameters:
  • file (object) – File object or string path.
  • parent (Node) – Attaches the mesh to the specified scene-graph node.
  • transform (AffineMatrix3D) – The co-ordinate transform between the mesh and its parent.
  • material (Material) – The surface/volume material.
  • name (str) – A human friendly name to identity the mesh in the scene-graph.
hit()

Returns the first intersection with the mesh surface.

If an intersection occurs this method will return an Intersection object. The Intersection object will contain the details of the ray-surface intersection, such as the surface normal and intersection point.

If no intersection occurs None is returned.

Parameters:ray – A world-space ray.
Returns:An Intersection or None.
load()

Loads the mesh specified by a file object or filename.

The mesh must be stored in a RaySect Mesh (RSM) format file. RSM files are created with the Mesh save() method.

Parameters:file – File object or string path.
next_intersection()

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

This method may only be called following a call to hit(). If the ray has further intersections with the mesh, these may be obtained by repeatedly calling the next_intersection() method. Each call to next_intersection() will return the next ray-mesh 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.

Returns:An Intersection or None.
save()

Saves the mesh to the specified file object or filename.

The mesh in written in RaySect Mesh (RSM) format. The RSM format contains the mesh geometry and the mesh acceleration structures.

Parameters:file – File object or string path.
raysect.primitive.mesh.obj.import_obj(cls, filename, scaling=1.0, **kwargs)

Create a mesh instance from a Wavefront OBJ mesh file (.obj).

Some engineering meshes are exported in different units (mm for example) whereas Raysect units are in m. Applying a scale factor of 0.001 would convert the mesh into m for use in Raysect.

Parameters:
  • filename (str) – Mesh file path.
  • scaling (double) – Scale the mesh by this factor (default=1.0).
  • **kwargs

    Accepts optional keyword arguments from the Mesh class.

Return type:

Mesh

raysect.primitive.mesh.stl.import_stl(cls, filename, scaling=1.0, mode=0, **kwargs)

Create a mesh instance from a STereoLithography (STL) mesh file (.stl).

Some engineering meshes are exported in different units (mm for example) whereas Raysect units are in m. Applying a scale factor of 0.001 would convert the mesh into m for use in Raysect.

Parameters:
  • filename (str) – Mesh file path.
  • scaling (double) – Scale the mesh by this factor (default=1.0).
  • **kwargs

    Accepts optional keyword arguments from the Mesh class.

Return type:

Mesh