trimesh.primitives¶

primitives.py¶

Subclasses of Trimesh objects that are parameterized as primitives.

Useful because you can move boxes and spheres around and then use trimesh operations on them at any point.

class trimesh.primitives.Box(extents=None, transform=None, bounds=None, mutable=True)¶

Bases: Primitive

__init__(extents=None, transform=None, bounds=None, mutable=True)¶

Create a Box Primitive as a subclass of Trimesh

Parameters:

extents (Optional[ndarray] (3,) float) – Length of each side of the 3D box.
transform (Optional[ndarray] (4, 4) float) – Homogeneous transformation matrix for box center.
bounds (Optional[ndarray] (2, 3) float) – Axis aligned bounding box, if passed extents and transform will be derived from this.
mutable (bool) – Are extents and transform mutable after creation.

as_outline()¶

Return a Path3D containing the outline of the box.

Returns:: outline – Outline of box primitive
Return type:: trimesh.path.Path3D

property is_oriented¶: Returns whether or not the current box is rotated at all.

sample_grid(count=None, step=None)¶

Return a 3D grid which is contained by the box. Samples are either ‘step’ distance apart, or there are ‘count’ samples per box side.

Parameters:

count (int or (3,) int) – If specified samples are spaced with np.linspace
step (float or (3,) float) – If specified samples are spaced with np.arange

Returns:

grid – Points inside the box

Return type:

(n, 3) float

sample_volume(count)¶

Return random samples from inside the volume of the box.

Parameters:: count (int) – Number of samples to return
Returns:: samples – Points inside the volume
Return type:: (count, 3) float

to_dict()¶

Get a copy of the current Box primitive as a JSON-serializable dict that matches the schema in trimesh/resources/schema/box.schema.json

Returns:: as_dict – Serializable data for this primitive.
Return type:: dict

property transform¶

The transform of the Primitive object.

Returns:: transform – Homogeneous transformation matrix
Return type:: (4, 4) float

property volume¶

Volume of the box Primitive.

Returns:: volume – Volume of box.
Return type:: float

class trimesh.primitives.Capsule(radius=1.0, height=10.0, transform=None, sections=32, mutable=True)¶

Bases: Primitive

__init__(radius=1.0, height=10.0, transform=None, sections=32, mutable=True)¶

Create a Capsule Primitive, a subclass of Trimesh.

Parameters:

radius (float) – Radius of cylinder
height (float) – Height of cylinder
transform ((4, 4) float) – Transformation matrix
sections (int) – Number of facets in circle
mutable (bool) – Are extents and transform mutable after creation.

property direction¶

The direction of the capsule’s axis.

Returns:: axis – Vector along the cylinder axis
Return type:: (3,) float

to_dict()¶

Get a copy of the current Capsule primitive as a JSON-serializable dict that matches the schema in trimesh/resources/schema/capsule.schema.json

Returns:: as_dict – Serializable data for this primitive.
Return type:: dict

property transform¶

The transform of the Primitive object.

Returns:: transform – Homogeneous transformation matrix
Return type:: (4, 4) float

class trimesh.primitives.Cylinder(radius=1.0, height=1.0, transform=None, sections=32, mutable=True)¶

Bases: Primitive

__init__(radius=1.0, height=1.0, transform=None, sections=32, mutable=True)¶

Create a Cylinder Primitive, a subclass of Trimesh.

Parameters:

radius (float) – Radius of cylinder
height (float) – Height of cylinder
transform ((4, 4) float) – Homogeneous transformation matrix
sections (int) – Number of facets in circle.
mutable (bool) – Are extents and transform mutable after creation.

buffer(distance)¶

Return a cylinder primitive which covers the source cylinder by distance: radius is inflated by distance height by twice the distance.

Parameters:: distance (float) – Distance to inflate cylinder radius and height
Returns:: buffered – Cylinder primitive inflated by distance
Return type:: Cylinder

property direction¶

The direction of the cylinder’s axis.

Returns:: axis
Return type:: (3,) float, vector along the cylinder axis

property moment_inertia¶

The analytic inertia tensor of the cylinder primitive.

Returns:: tensor – 3D inertia tensor
Return type:: (3, 3) float

property segment¶

A line segment which if inflated by cylinder radius would represent the cylinder primitive.

Returns:: segment – Points representing a single line segment
Return type:: (2, 3) float

to_dict()¶

Get a copy of the current Cylinder primitive as a JSON-serializable dict that matches the schema in trimesh/resources/schema/cylinder.schema.json

Returns:: as_dict – Serializable data for this primitive.
Return type:: dict

property volume¶

The analytic volume of the cylinder primitive.

Returns:: volume – Volume of the cylinder
Return type:: float

class trimesh.primitives.Extrusion(polygon=None, transform=None, height=1.0, mutable=True)¶

Bases: Primitive

__init__(polygon=None, transform=None, height=1.0, mutable=True)¶

Create an Extrusion primitive, which is a subclass of Trimesh.

Parameters:

polygon (shapely.geometry.Polygon) – Polygon to extrude
transform ((4, 4) float) – Transform to apply after extrusion
height (float) – Height to extrude polygon by
mutable (bool) – Are extents and transform mutable after creation.

property area¶

The surface area of the primitive extrusion.

Calculated from polygon and height to avoid mesh creation.

Returns:: area – Surface area of 3D extrusion
Return type:: float

property bounding_box_oriented¶

An oriented bounding box for the current mesh.

Returns:: obb – Box object with transform and extents defined representing the minimum volume oriented bounding box of the mesh
Return type:: trimesh.primitives.Box

buffer(distance, distance_height=None, **kwargs)¶

Return a new Extrusion object which is expanded in profile and in height by a specified distance.

Parameters:

distance (float) – Distance to buffer polygon
distance_height (float) – Distance to buffer above and below extrusion
kwargs (dict) – Passed to Extrusion constructor

Returns:

buffered – Extrusion object with new values

Return type:

primitives.Extrusion

property direction¶

Based on the extrudes transform what is the vector along which the polygon will be extruded.

Returns:: direction – Unit direction vector
Return type:: (3,) float

property origin¶

Based on the extrude transform what is the origin of the plane it is extruded from.

Returns:: origin – Origin of extrusion plane
Return type:: (3,) float

slide(distance)¶

Alter the transform of the current extrusion to slide it along its extrude_direction vector

Parameters:: distance (float) – Distance along self.extrude_direction to move

to_dict()¶

Get a copy of the current Extrusion primitive as a JSON-serializable dict that matches the schema in trimesh/resources/schema/extrusion.schema.json

Returns:: as_dict – Serializable data for this primitive.
Return type:: dict

property transform¶

The transform of the Primitive object.

Returns:: transform – Homogeneous transformation matrix
Return type:: (4, 4) float

property volume¶

The volume of the Extrusion primitive. Calculated from polygon and height to avoid mesh creation.

Returns:: volume – Volume of 3D extrusion
Return type:: float

class trimesh.primitives.Primitive¶

Bases: Trimesh

Geometric Primitives which are a subclass of Trimesh. Mesh is generated lazily when vertices or faces are requested.

__init__()¶

A Trimesh object contains a triangular 3D mesh.

Parameters:

vertices ((n, 3) float) – Array of vertex locations
faces ((m, 3) or (m, 4) int) – Array of triangular or quad faces (triangulated on load)
face_normals ((m, 3) float) – Array of normal vectors corresponding to faces
vertex_normals ((n, 3) float) – Array of normal vectors for vertices
metadata (dict) – Any metadata about the mesh
process (bool) – if True, Nan and Inf values will be removed immediately and vertices will be merged
validate (bool) – If True, degenerate and duplicate faces will be removed immediately, and some functions will alter the mesh to ensure consistent results.
use_embree (bool) – If True try to use pyembree raytracer. If pyembree is not available it will automatically fall back to a much slower rtree/numpy implementation
initial_cache (dict) – A way to pass things to the cache in case expensive things were calculated before creating the mesh object.
visual (ColorVisuals or TextureVisuals) – Assigned to self.visual

apply_transform(matrix)¶

Apply a transform to the current primitive by applying a new transform on top of existing self.primitive.transform. If the matrix contains scaling it will change parameters like radius or height automatically.

Parameters:: matrix ((4, 4) float) – Homogeneous transformation

copy(**kwargs)¶

Return a copy of the Primitive object.

Returns:: copied – Copy of current primitive
Return type:: object

property face_normals¶

Return the unit normal vector for each face.

If a face is degenerate and a normal can’t be generated a zero magnitude unit vector will be returned for that face.

Returns:: normals – Normal vectors of each face
Return type:: (len(self.faces), 3) float64

property faces¶

The faces of the mesh.

This is regarded as core information which cannot be regenerated from cache and as such is stored in self._data which tracks the array for changes and clears cached values of the mesh altered.

Returns:: faces – References for self.vertices for triangles.
Return type:: (n, 3) int64

abstract to_dict()¶: Should be implemented by each primitive.

to_mesh(**kwargs)¶

Return a copy of the Primitive object as a Trimesh.

Parameters:: kwargs (dict) – Passed to the Trimesh object constructor.
Returns:: mesh – Tessellated version of the primitive.
Return type:: trimesh.Trimesh

property transform¶

The transform of the Primitive object.

Returns:: transform – Homogeneous transformation matrix
Return type:: (4, 4) float

property vertices¶

The vertices of the mesh.

This is regarded as core information which cannot be generated from cache and as such is stored in self._data which tracks the array for changes and clears cached values of the mesh if this is altered.

Returns:: vertices – Points in cartesian space referenced by self.faces
Return type:: (n, 3) float

class trimesh.primitives.PrimitiveAttributes(parent, defaults, kwargs, mutable=True)¶

Bases: object

__init__(parent, defaults, kwargs, mutable=True)¶

Hold the attributes for a Primitive.

Parameters:

parent (Primitive) – Parent object reference.
defaults (dict) – The default values for this primitive type.
kwargs (dict) – User-passed values, i.e. {‘radius’: 10.0}

Bases: Primitive

Create a Sphere Primitive, a subclass of Trimesh.

Parameters:

radius – Radius of sphere
center (None or (3,) float) – Center of sphere.
transform (None or (4, 4) float) – Full homogeneous transform. Pass center OR `transform.
subdivisions – Number of subdivisions for icosphere.
mutable – Are extents and transform mutable after creation.

property area¶

Surface area of the current sphere primitive.

Returns:: area
Return type:: float, surface area of the sphere Primitive

property bounding_box_oriented¶

An oriented bounding box for the current mesh.

Returns:: obb – Box object with transform and extents defined representing the minimum volume oriented bounding box of the mesh
Return type:: trimesh.primitives.Box

property bounds¶

The axis aligned bounds of the faces of the mesh.

Returns:: bounds – Bounding box with [min, max] coordinates If mesh is empty will return None
Return type:: (2, 3) float or None

property center¶

property moment_inertia¶

The analytic inertia tensor of the sphere primitive.

Returns:: tensor – 3D inertia tensor.
Return type:: (3, 3) float

to_dict()¶

Get a copy of the current Sphere primitive as a JSON-serializable dict that matches the schema in trimesh/resources/schema/sphere.schema.json

Returns:: as_dict – Serializable data for this primitive.
Return type:: dict

property volume¶

Volume of the current sphere primitive.

Returns:: volume
Return type:: float, volume of the sphere Primitive