trimesh.path.path¶
path.py¶
A module designed to work with vector paths such as those stored in a DXF or SVG file.
Classes:
|
A Path object consists of vertices and entities. |
|
Hold multiple vector curves (lines, arcs, splines, etc) in 3D. |
|
Hold multiple vector curves (lines, arcs, splines, etc) in 3D. |
-
class
trimesh.path.path.
Path
(entities=None, vertices=None, metadata=None, process=True, colors=None, **kwargs)¶ Bases:
trimesh.parent.Geometry
A Path object consists of vertices and entities. Vertices are a simple (n, dimension) float array of points in space.
Entities are a list of objects representing geometric primitives, such as Lines, Arcs, BSpline, etc. All entities reference vertices by index, so any transform applied to the simple vertex array is applied to the entity.
Methods:
apply_layer
(name)Apply a layer name to every entity in the path.
apply_transform
(transform)Apply a transformation matrix to the current path in- place
A CRC of the current entity colors.
convert_units
(desired[, guess])Convert the units of the current drawing in place.
copy
()Get a copy of the current mesh
crc
()A CRC of the current vertices and entities.
discretize_path
(path)Given a list of entities, return a list of connected points.
explode
()Turn every multi- segment entity into single segment entities in- place.
export
([file_obj, file_type])Export the path to a file object or return data.
fill_gaps
([distance])Find vertices without degree 2 and try to connect to other vertices.
md5
()An MD5 hash of the current vertices and entities.
merge_vertices
([digits])Merges vertices which are identical and replace references by altering self.entities and self.vertices
process
()Apply basic cleaning functions to the Path object in- place.
Remove entities that are duplicated
remove_entities
(entity_ids)Remove entities by index.
Remove entities which declare themselves invalid
Removes all vertices which aren’t used by an entity.
Replace the vertex index references in every entity.
rezero
()Translate so that every vertex is positive in the current mesh is positive.
scene
()Get a scene object containing the current Path3D object.
to_dict
()Attributes:
Return the axis aligned bounding box of the current path.
Return the centroid of axis aligned bounding box enclosing all entities of the path object.
Colors are stored per-entity.
List of entities that aren’t included in a closed path
A sequence of connected vertices in space, corresponding to self.paths.
The actual entities making up the path.
The size of the axis aligned bounding box.
Are all entities connected to other entities.
Are any entities defined for the current path.
A KDTree object holding the vertices of the path.
Get a list of the layer for every entity.
The total discretized length of every entity.
Sequence of closed paths, encoded by entity index.
Which vertices are referenced by an entity.
What is a representitive number that reflects the magnitude of the world holding the paths, for numerical comparisons.
If there are units defined in self.metadata return them.
Return a networkx.Graph object for the entity connectiviy
Get a list of which vertex indices are nodes, which are either endpoints or points where the entity makes a direction change.
-
apply_layer
(name)¶ Apply a layer name to every entity in the path.
- Parameters
name (str) – Apply layer name to every entity
-
apply_transform
(transform)¶ Apply a transformation matrix to the current path in- place
- Parameters
transform ((d+1, d+1) float) – Homogeneous transformations for vertices
-
property
bounds
¶ Return the axis aligned bounding box of the current path.
- Returns
bounds – AABB with (min, max) coordinates
- Return type
(2, dimension) float
-
property
centroid
¶ Return the centroid of axis aligned bounding box enclosing all entities of the path object.
- Returns
centroid – Approximate centroid of the path
- Return type
(d,) float
-
property
colors
¶ Colors are stored per-entity.
- Returns
colors – RGBA colors for each entity
- Return type
(len(entities), 4) uint8
-
colors_crc
()¶ A CRC of the current entity colors.
- Returns
crc – CRC of the current entity colors
- Return type
int
-
convert_units
(desired, guess=False)¶ Convert the units of the current drawing in place.
- Parameters
desired (str) – Unit system to convert to
guess (bool) – If True will attempt to guess units
-
copy
()¶ Get a copy of the current mesh
- Returns
copied – Copy of self
- Return type
Path object
-
crc
()¶ A CRC of the current vertices and entities.
- Returns
crc – CRC of entity points and vertices
- Return type
int
-
property
dangling
¶ List of entities that aren’t included in a closed path
- Returns
dangling – Index of self.entities
- Return type
(n,) int
-
property
discrete
¶ A sequence of connected vertices in space, corresponding to self.paths.
- Returns
discrete – A sequence of (m*, dimension) float
- Return type
(len(self.paths),)
-
discretize_path
(path)¶ Given a list of entities, return a list of connected points.
- Parameters
path ((n,) int, indexes of self.entities) –
- Returns
discrete
- Return type
(m, dimension)
-
property
entities
¶ The actual entities making up the path.
- Returns
entities – Entities such as Line, Arc, or BSpline curves
- Return type
-
explode
()¶ Turn every multi- segment entity into single segment entities in- place.
-
export
(file_obj=None, file_type=None, **kwargs)¶ Export the path to a file object or return data.
- Parameters
file_obj (None, str, or file object) – File object or string to export to
file_type (None or str) – Type of file: dxf, dict, svg
- Returns
exported – Exported as specified type
- Return type
bytes or str
-
property
extents
¶ The size of the axis aligned bounding box.
- Returns
extents – Edge length of AABB
- Return type
(dimension,) float
-
fill_gaps
(distance=0.025)¶ Find vertices without degree 2 and try to connect to other vertices. Operations are done in-place.
- Parameters
distance (float) – Connect vertices up to this distance
-
property
is_closed
¶ Are all entities connected to other entities.
- Returns
closed – Every entity is connected at its ends
- Return type
bool
-
property
is_empty
¶ Are any entities defined for the current path.
- Returns
empty – True if no entities are defined
- Return type
bool
-
property
kdtree
¶ A KDTree object holding the vertices of the path.
- Returns
kdtree – Object holding self.vertices
- Return type
scipy.spatial.cKDTree
-
property
layers
¶ Get a list of the layer for every entity.
- Returns
layers – Whatever is stored in each entity.layer
- Return type
(len(entities), ) any
-
property
length
¶ The total discretized length of every entity.
- Returns
length
- Return type
float, summed length of every entity
-
md5
()¶ An MD5 hash of the current vertices and entities.
- Returns
md5 – Appended MD5 hashes
- Return type
str
-
merge_vertices
(digits=None)¶ Merges vertices which are identical and replace references by altering self.entities and self.vertices
- Parameters
digits (None, or int) – How many digits to consider when merging vertices
-
property
paths
¶ Sequence of closed paths, encoded by entity index.
- Returns
paths – Referencing self.entities
- Return type
(n,) sequence of (*,) int
-
process
()¶ Apply basic cleaning functions to the Path object in- place.
-
property
referenced_vertices
¶ Which vertices are referenced by an entity.
- Returns
referenced_vertices
- Return type
(n,) int, indexes of self.vertices
-
remove_duplicate_entities
()¶ Remove entities that are duplicated
self.entities: length same or shorter
-
remove_entities
(entity_ids)¶ Remove entities by index.
- Parameters
entity_ids ((n,) int) – Indexes of self.entities to remove
-
remove_invalid
()¶ Remove entities which declare themselves invalid
self.entities: shortened
-
remove_unreferenced_vertices
()¶ Removes all vertices which aren’t used by an entity.
self.vertices: reordered and shortened self.entities: entity.points references updated
-
replace_vertex_references
(mask)¶ Replace the vertex index references in every entity.
- Parameters
mask ((len(self.vertices), ) int) – Contains new vertex indexes
Alters –
------------ –
in self.entities (entity.points) – Replaced by mask[entity.points]
-
rezero
()¶ Translate so that every vertex is positive in the current mesh is positive.
- Returns
matrix – Homogeneous transformations that was applied to the current Path object.
- Return type
(dimension + 1, dimension + 1) float
-
property
scale
¶ What is a representitive number that reflects the magnitude of the world holding the paths, for numerical comparisons.
- Returns
scale – Approximate size of the world holding this path
- Return type
float
-
scene
()¶ Get a scene object containing the current Path3D object.
- Returns
scene
- Return type
trimesh.scene.Scene object containing current path
-
to_dict
()¶
-
property
units
¶ If there are units defined in self.metadata return them.
- Returns
units – Current unit system
- Return type
str
-
property
vertex_graph
¶ Return a networkx.Graph object for the entity connectiviy
- graphnetworkx.Graph
Holds vertex indexes
-
property
vertex_nodes
¶ Get a list of which vertex indices are nodes, which are either endpoints or points where the entity makes a direction change.
- Returns
nodes – Indexes of self.vertices which are nodes
- Return type
(n, 2) int
-
property
vertices
¶
-
-
class
trimesh.path.path.
Path2D
(entities=None, vertices=None, metadata=None, process=True, colors=None, **kwargs)¶ Bases:
trimesh.path.path.Path
Hold multiple vector curves (lines, arcs, splines, etc) in 3D.
Methods:
Transform the current path so that its OBB is axis aligned and OBB center is at the origin.
apply_scale
(scale)Apply a 2D scale to the current Path2D.
connected_paths
(path_id[, include_self])Given an index of self.paths find other paths which overlap with that path.
extrude
(height, **kwargs)Extrude the current 2D path into a 3D mesh.
medial_axis
([resolution, clip])Find the approximate medial axis based on a voronoi diagram of evenly spaced points on the boundary of the polygon.
plot_discrete
([show, annotations])Plot the closed curves of the path.
plot_entities
([show, annotations, color])Plot the entities of the path, with no notion of topology
rasterize
(pitch, origin[, resolution, fill, …])Rasterize a Path2D object into a boolean image (“mode 1”).
sample
(count, **kwargs)Use rejection sampling to generate random points inside a polygon.
show
([annotations])Plot the current Path2D object using matplotlib.
simplify
(**kwargs)Return a version of the current path with colinear segments merged, and circles entities replacing segmented circular paths.
simplify_spline
([smooth, verbose])Convert paths into b-splines.
split
(**kwargs)If the current Path2D consists of n ‘root’ curves, split them into a list of n Path2D objects
to_3D
([transform])Convert 2D path to 3D path on the XY plane.
triangulate
(**kwargs)Create a region- aware triangulation of the 2D path.
Attributes:
Return the area of the polygons interior.
Networkx Graph object of polygon enclosure.
Networkx DiGraph of polygon enclosure
A dictionary of path indexes which are ‘shell’ paths, and values of ‘hole’ paths.
A unique identifier for the path.
Return an MD5 of the identifier
Get a transform that centers and aligns the OBB of the referenced vertices with the XY axis.
returns: path_valid – which are valid polygons :rtype: (n,) bool, indexes of self.paths self.polygons_closed
Cycles in the vertex graph, as shapely.geometry.Polygons.
A list of shapely.geometry.Polygon objects with interiors created by checking which closed polygons enclose which other polygons.
Which indexes of self.paths/self.polygons_closed are root curves.
-
apply_obb
()¶ Transform the current path so that its OBB is axis aligned and OBB center is at the origin.
- Returns
obb – Homogeneous transformation matrix
- Return type
(3, 3) float
-
apply_scale
(scale)¶ Apply a 2D scale to the current Path2D.
- Parameters
scale (float or (2,) float) – Scale to apply in-place.
-
property
area
¶ Return the area of the polygons interior.
- Returns
area
- Return type
float, total area of polygons minus interiors
-
property
body_count
¶
-
connected_paths
(path_id, include_self=False)¶ Given an index of self.paths find other paths which overlap with that path.
- Parameters
path_id (int) – Index of self.paths
include_self (bool) – Should the result include path_id or not
- Returns
path_ids – Indexes of self.paths that overlap input path_id
- Return type
(n, ) int
-
property
enclosure
¶ Networkx Graph object of polygon enclosure.
-
property
enclosure_directed
¶ Networkx DiGraph of polygon enclosure
-
property
enclosure_shell
¶ A dictionary of path indexes which are ‘shell’ paths, and values of ‘hole’ paths.
- Returns
corresponding
- Return type
dict, {index of self.paths of shell : [indexes of holes]}
-
extrude
(height, **kwargs)¶ Extrude the current 2D path into a 3D mesh.
- Parameters
height (float, how far to extrude the profile) –
kwargs (passed directly to meshpy.triangle.build:) –
- triangle.build(mesh_info,
verbose=False, refinement_func=None, attributes=False, volume_constraints=True, max_volume=None, allow_boundary_steiner=True, allow_volume_steiner=True, quality_meshing=True, generate_edges=None, generate_faces=False, min_angle=None)
- Returns
mesh
- Return type
trimesh object representing extruded polygon
-
property
identifier
¶ A unique identifier for the path.
- Returns
identifier
- Return type
(5,) float, unique identifier
-
property
identifier_md5
¶ Return an MD5 of the identifier
-
medial_axis
(resolution=None, clip=None)¶ Find the approximate medial axis based on a voronoi diagram of evenly spaced points on the boundary of the polygon.
- Parameters
resolution (None or float) – Distance between each sample on the polygon boundary
clip (None, or (2,) float) – Min, max number of samples
- Returns
medial – Contains only medial axis of Path
- Return type
Path2D object
-
property
obb
¶ Get a transform that centers and aligns the OBB of the referenced vertices with the XY axis.
- Returns
obb – Homogeneous transformation matrix
- Return type
(3, 3) float
-
property
path_valid
¶ returns: path_valid – which are valid polygons :rtype: (n,) bool, indexes of self.paths self.polygons_closed
-
plot_discrete
(show=False, annotations=True)¶ Plot the closed curves of the path.
-
plot_entities
(show=False, annotations=True, color=None)¶ Plot the entities of the path, with no notion of topology
-
property
polygons_closed
¶ Cycles in the vertex graph, as shapely.geometry.Polygons. These are polygon objects for every closed circuit, with no notion of whether a polygon is a hole or an area. Every polygon in this list will have an exterior, but NO interiors.
- Returns
polygons_closed
- Return type
(n,) list of shapely.geometry.Polygon objects
-
property
polygons_full
¶ A list of shapely.geometry.Polygon objects with interiors created by checking which closed polygons enclose which other polygons.
- Returns
full – Polygons containing interiors
- Return type
(len(self.root),) shapely.geometry.Polygon
-
rasterize
(pitch, origin, resolution=None, fill=True, width=None, **kwargs)¶ Rasterize a Path2D object into a boolean image (“mode 1”).
- Parameters
pitch (float, length in model space of a pixel edge) –
origin ((2,) float, origin position in model space) –
resolution ((2,) int, resolution in pixel space) –
fill (bool, if True will return closed regions as filled) –
width (int, if not None will draw outline this wide (pixels)) –
- Returns
raster
- Return type
PIL.Image object, mode 1
-
property
root
¶ Which indexes of self.paths/self.polygons_closed are root curves. Also known as ‘shell’ or ‘exterior.
- Returns
root
- Return type
(n,) int, list of indexes
-
sample
(count, **kwargs)¶ Use rejection sampling to generate random points inside a polygon.
- Parameters
count (int) – Number of points to return If there are multiple bodies, there will be up to count * bodies points returned
factor (float) – How many points to test per loop IE, count * factor
max_iter (int,) – Maximum number of intersection loops to run, total points sampled is count * factor * max_iter
- Returns
hit – Random points inside polygon
- Return type
(n, 2) float
-
show
(annotations=True)¶ Plot the current Path2D object using matplotlib.
-
simplify
(**kwargs)¶ Return a version of the current path with colinear segments merged, and circles entities replacing segmented circular paths.
- Returns
simplified
- Return type
Path2D object
-
simplify_spline
(smooth=0.0002, verbose=False)¶ Convert paths into b-splines.
- Parameters
smooth (float) – How much the spline should smooth the curve
verbose (bool) – Print detailed log messages
- Returns
simplified – Discrete curves replaced with splines
- Return type
-
split
(**kwargs)¶ If the current Path2D consists of n ‘root’ curves, split them into a list of n Path2D objects
- Returns
split – Each connected region and interiors
- Return type
(n,) list of Path2D objects
-
to_3D
(transform=None)¶ Convert 2D path to 3D path on the XY plane.
- Parameters
transform ((4, 4) float) – If passed, will transform vertices. If not passed and ‘to_3D’ is in metadata that transform will be used.
- Returns
path_3D
- Return type
Path3D version of current path
-
triangulate
(**kwargs)¶ Create a region- aware triangulation of the 2D path.
- Parameters
**kwargs (dict) – Passed to trimesh.creation.triangulate_polygon
- Returns
vertices ((n, 2) float) – 2D vertices of triangulation
faces ((n, 3) int) – Indexes of vertices for triangles
-
-
class
trimesh.path.path.
Path3D
(entities=None, vertices=None, metadata=None, process=True, colors=None, **kwargs)¶ Bases:
trimesh.path.path.Path
Hold multiple vector curves (lines, arcs, splines, etc) in 3D.
Methods:
show
(**kwargs)Show the current Path3D object.
to_planar
([to_2D, normal, check])Check to see if current vectors are all coplanar.
-
show
(**kwargs)¶ Show the current Path3D object.
-
to_planar
(to_2D=None, normal=None, check=True)¶ Check to see if current vectors are all coplanar.
If they are, return a Path2D and a transform which will transform the 2D representation back into 3 dimensions
- Parameters
to_2D ((4,4) float) – Homogeneous transformation matrix to apply, If not passed a plane will be fitted to vertices.
normal ((3,) float, or None) – Approximate normal of direction of plane If to_2D is not specified sign will be applied to fit plane normal
check (bool) – If True: Raise a ValueError if points aren’t coplanar
- Returns
planar (trimesh.path.Path2D) – Current path transformed onto plane
to_3D ((4,4) float) – Homeogenous transformations to move planar back into 3D space
-