trimesh.path.path

path.py

A module designed to work with vector paths such as those stored in a DXF or SVG file.

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.

__init__(entities=None, vertices=None, metadata=None, process=True, colors=None, **kwargs)

Instantiate a path object.

Parameters

• entities ((m,) trimesh.path.entities.Entity) – Contains geometric entities

• vertices ((n, dimension) float) – The vertices referenced by entities

• metadata (dict) – Any metadata about the path

• process (bool) – Run simple cleanup or not

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 – Linear segment path.

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

(n,) trimesh.path.entities.Entity

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 – Summed length of every entity

Return type

float

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

Notes

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

Notes

self.entities: shortened

remove_unreferenced_vertices()

Removes all vertices which aren’t used by an entity.

Notes

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

Notes

entity.points in self.entities

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.

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 – Total area of polygons minus interiors

Return type

float

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 – {index of self.paths of shell : [indexes of holes]}

Return type

dict

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 – Unique identifier

Return type

(5,) float

property identifier_md5

Return an MD5 of the identifier.

Returns

hashed – Hashed identifier.

Return type

str

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 – Indexes of self.paths self.polygons_closed

which are valid polygons.

Return type

(n,) bool

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 or (2,) float) – Length(s) in model space of pixel edges

• 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 – Rasterized version of closed regions.

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 – List of indexes

Return type

(n,) int

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

Path2D

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 – 3D version of current path

Return type

Path3D

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.

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