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}

class trimesh.primitives.Sphere(radius: float | floating | int | integer | unsignedinteger = 1.0, center: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, transform: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, subdivisions: int | integer | unsignedinteger = 3, mutable: bool = True)#

Bases: Primitive

__init__(radius: float | floating | int | integer | unsignedinteger = 1.0, center: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, transform: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, subdivisions: int | integer | unsignedinteger = 3, mutable: bool = True)#

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