trimesh.primitives module¶
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:
- 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:
- 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:
- 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:
- 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:
- 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
- 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:
- 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