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).
flip_normals (bool) – Inverts the direction of the surface normals (default=False).
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=””).

Variables

data (MeshData) – A class instance containing all the mesh data.

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.

>>> from raysect.optical import World, translate, rotate, ConstantSF, Sellmeier, Dielectric
>>> from raysect.primitive import Mesh
>>>
>>> world = World()
>>>
>>> diamond = Dielectric(Sellmeier(0.3306, 4.3356, 0.0, 0.1750**2, 0.1060**2, 0.0), ConstantSF(1.0))
>>>
>>> mesh = Mesh.from_file("my_mesh.rsm", parent=world, material=diamond,
>>>                       transform=translate(0, 0, 0)*rotate(165, 0, 0))

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.

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.

>>> mesh
<raysect.primitive.mesh.mesh.Mesh at 0x7f2c09eac2e8>
>>> mesh.save("my_mesh.rsm")

Warning

Some engineering meshes are exported in different units (mm for example) whereas Raysect units are in m. Therefore, all import functions have an optional scaling factor argument that allows you to convert the mesh units on import. For example, if a given engineering mesh was in mm, applying a scale factor of 0.001 would convert the mesh into m for use in Raysect.

raysect.primitive.mesh.obj.import_obj(filename, scaling=1.0, **kwargs)¶

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

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

>>> from raysect.optical import World, translate, rotate, ConstantSF, Sellmeier, Dielectric
>>> from raysect.primitive import import_obj
>>>
>>> world = World()
>>>
>>> diamond = Dielectric(Sellmeier(0.3306, 4.3356, 0.0, 0.1750**2, 0.1060**2, 0.0),
>>>                      ConstantSF(1.0))
>>>
>>> bunny_mesh = import_obj("resources/stanford_bunny.obj", scaling=1, parent=world,
>>>                         transform=translate(0, 0, 0)*rotate(165, 0, 0), material=diamond)

raysect.primitive.mesh.obj.export_obj(mesh, filename)¶

Write a mesh instance to a Wavefront OBJ (.obj) mesh file.

Parameters

mesh (Mesh) – The Raysect mesh instance to write to OBJ.
filename (str) – Mesh file path.

>>> bunny_mesh
<raysect.primitive.mesh.mesh.Mesh at 0x7f2c09eac2e8>
>>> from raysect.primitive import export_obj
>>> export_obj(bunny_mesh, 'my_mesh.obj')        

raysect.primitive.mesh.stl.import_stl(filename, scaling=1.0, mode='auto', **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).
mode (str) – The file format to load: ‘ascii’, ‘binary’, ‘auto’ (default=’auto’).
kwargs – Accepts optional keyword arguments from the Mesh class.

Return type

Mesh

>>> from raysect.optical import World, translate, rotate, ConstantSF, Sellmeier, Dielectric
>>> from raysect.primitive import import_stl
>>>
>>> world = World()
>>>
>>> diamond = Dielectric(Sellmeier(0.3306, 4.3356, 0.0, 0.1750**2, 0.1060**2, 0.0),
>>>                      ConstantSF(1.0))
>>>
>>> mesh = import_stl("my_mesh.stl", scaling=1, mode='binary', parent=world,
>>>                   transform=translate(0, 0, 0)*rotate(165, 0, 0), material=diamond)

raysect.primitive.mesh.stl.export_stl(mesh, filename, mode='binary')¶

Write a mesh instance to a STereoLithography (STL) mesh file (.stl).

Parameters

mesh (Mesh) – The Raysect mesh instance to write to STL.
filename (str) – Mesh file path.
mode (str) – The file format to write: ‘ascii’ or ‘binary’ (default=’ascii’).

>>> mesh
<raysect.primitive.mesh.mesh.Mesh at 0x7f2c09eac2e8>
>>> from raysect.primitive import export_stl
>>> export_stl(mesh, 'my_mesh.stl', mode='ascii')

raysect.primitive.mesh.ply.import_ply(filename, scaling=1.0, mode='auto', **kwargs)¶

Create a mesh instance from a Polygon File Format (PLY) mesh file (.ply). Note PLY is also known as the Stanford Triangle Format.

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).
mode (str) – The file format to load: ‘ascii’, ‘binary’, ‘auto’ (default=’auto’).
kwargs – Accepts optional keyword arguments from the Mesh class.

Return type

Mesh

>>> from raysect.optical import World, translate, rotate, ConstantSF, Sellmeier, Dielectric
>>> from raysect.primitive import import_ply
>>>
>>> world = World()
>>>
>>> diamond = Dielectric(Sellmeier(0.3306, 4.3356, 0.0, 0.1750**2, 0.1060**2, 0.0),
>>>                      ConstantSF(1.0))
>>>
>>> mesh = import_ply("your_mesh.ply", scaling=1, mode='binary', parent=world,
>>>                   transform=translate(0, 0, 0)*rotate(165, 0, 0), material=diamond)

raysect.primitive.mesh.ply.export_ply(mesh, filename, mode='binary', comment='Generated by Raysect')¶

Write a mesh instance to a Polygon File Format (PLY) mesh file (.ply). Note PLY is also known as the Stanford Triangle Format.

Parameters

mesh (Mesh) – The Raysect mesh instance to write as PLY.
filename (str) – Mesh file path.
mode (str) – The file format to write: ‘ascii’, ‘binary’ (default=’ascii’).
comment (str) – An optional string comment to include in the output file, can be multiple lines.

>>> mesh
<raysect.primitive.mesh.mesh.Mesh at 0x7f2c09eac2e8>
>>> from raysect.primitive import export_ply
>>> export_ply(mesh, 'my_mesh.ply', mode='ascii', comment='My mesh')

raysect.primitive.mesh.vtk.import_vtk(filename, scaling=1.0, mode='auto', **kwargs)¶

Create a mesh instance from a VTK mesh data file (.vtk).

Warning

Currently only supports VTK DataFile v2.0 and unstructured grid data with 3 element (triangular) cells.

Parameters

filename (str) – Mesh file path.
scaling (double) – Scale the mesh by this factor (default=1.0).
mode (str) – The file format to load: ‘ascii’, ‘binary’, ‘auto’ (default=’auto’).
kwargs – Accepts optional keyword arguments from the Mesh class.

Return type

Mesh

raysect.primitive.mesh.vtk.export_vtk(mesh, filename, triangle_data=None, vertex_data=None, mode='ascii')¶

Write a mesh instance to a vtk mesh file (.vtk) with optional cell and point data.

Parameters

mesh (Mesh) – The Raysect mesh instance to write as VTK.
filename (str) – Mesh file path.
triangle_data (dict) – A dictionary of triangle face datasets to be saved along with the mesh. The dictionary keys will be the variable names. Each array must be 1D with length equal to the number of triangles in the mesh.
vertex_data (dict) – A dictionary of vertex datasets to be saved along with the mesh. The dictionary keys will be the variable names. Each array must be 1D with length equal to the number of vertices in the mesh.
mode (str) – The file format to write: ‘ascii’ or ‘binary’ (default=’ascii’).