# trimesh.path.entities¶

## entities.py¶

Basic geometric primitives which only store references to vertex indices rather than vertices themselves.

Classes:

 `Arc`(points[, closed, layer, color]) `BSpline`(points, knots[, layer]) An open or closed B- Spline. `Bezier`(points[, closed, layer, color]) An open or closed Bezier curve `Curve`(points[, closed, layer, color]) The parent class for all wild curves in space. `Entity`(points[, closed, layer, color]) `Line`(points[, closed, layer, color]) A line or poly-line entity `Text`(origin, text[, height, vector, normal, …]) Text to annotate a 2D or 3D path.

Functions:

 `arc_center`(points[, return_normal, return_angle]) Given three points on a 2D or 3D arc find the center, radius, normal, and angular span. `discretize_arc`(points[, close, scale]) Returns a version of a three point arc consisting of line segments. `discretize_bezier`(points[, count, scale]) param points Control points of the bezier curve `discretize_bspline`(control, knots[, count, …]) Given a B-Splines control points and knot vector, return a sampled version of the curve.
class `trimesh.path.entities.``Arc`(points, closed=None, layer=None, color=None, **kwargs)

Methods:

 `bounds`(vertices) Return the AABB of the arc entity. `center`(vertices, **kwargs) Return the center information about the arc entity. `discrete`(vertices[, scale]) Discretize the arc entity into line sections.

Attributes:

 `closed` A boolean flag for whether the arc is closed (a circle) or not. `is_valid` Is the current Arc entity valid.
`bounds`(vertices)

Return the AABB of the arc entity.

Parameters

vertices ((n, dimension) float) – Vertices in space

Returns

bounds – Coordinates of AABB in (min, max) form

Return type

(2, dimension) float

`center`(vertices, **kwargs)

Return the center information about the arc entity.

Parameters

vertices ((n, dimension) float) – Vertices in space

Returns

info – With keys: ‘radius’, ‘center’

Return type

dict

property `closed`

A boolean flag for whether the arc is closed (a circle) or not.

Returns

closed – If set True, Arc will be a closed circle

Return type

bool

`discrete`(vertices, scale=1.0)

Discretize the arc entity into line sections.

Parameters
• vertices ((n, dimension) float) – Points in space

• scale (float) – Size of overall scene for numerical comparisons

Returns

discrete – Path in space made up of line segments

Return type

(m, dimension) float

property `is_valid`

Is the current Arc entity valid.

Returns

valid – Does the current Arc have exactly 3 control points

Return type

bool

class `trimesh.path.entities.``BSpline`(points, knots, layer=None, **kwargs)

An open or closed B- Spline.

Methods:

 `discrete`(vertices[, count, scale]) Discretize the B-Spline curve. Returns a dictionary with all of the information about the entity.
`discrete`(vertices, count=None, scale=1.0)

Discretize the B-Spline curve.

Parameters
• vertices ((n, 2) or (n, 3) float) – Points in space

• scale (float) – Scale of overall drawings (for precision)

• count (int) – Number of segments to return

Returns

discrete – Curve as line segments

Return type

(m, 2) or (m, 3) float

`to_dict`()

Returns a dictionary with all of the information about the entity.

class `trimesh.path.entities.``Bezier`(points, closed=None, layer=None, color=None, **kwargs)

An open or closed Bezier curve

Methods:

 `discrete`(vertices[, scale, count]) Discretize the Bezier curve.
`discrete`(vertices, scale=1.0, count=None)

Discretize the Bezier curve.

Parameters
• vertices ((n, 2) or (n, 3) float) – Points in space

• scale (float) – Scale of overall drawings (for precision)

• count (int) – Number of segments to return

Returns

discrete – Curve as line segments

Return type

(m, 2) or (m, 3) float

class `trimesh.path.entities.``Curve`(points, closed=None, layer=None, color=None, **kwargs)

The parent class for all wild curves in space.

Attributes:

 `nodes` Returns an (n,2) list of nodes, or vertices on the path.
property `nodes`

Returns an (n,2) list of nodes, or vertices on the path. Note that this generic class function assumes that all of the reference points are on the path which is true for lines and three point arcs.

If you were to define another class where that wasn’t the case (for example, the control points of a bezier curve), you would need to implement an entity- specific version of this function.

The purpose of having a list of nodes is so that they can then be added as edges to a graph so we can use functions to check connectivity, extract paths, etc.

The slicing on this function is essentially just tiling points so the first and last vertices aren’t repeated. Example:

self.points = [0,1,2] returns: [[0,1], [1,2]]

class `trimesh.path.entities.``Entity`(points, closed=None, layer=None, color=None, **kwargs)

Bases: `object`

Methods:

 `bounds`(vertices) Return the AABB of the current entity. Return a copy of the current entity. Split the entity into multiple entities. `length`(vertices) Return the total length of the entity. `reverse`([direction]) Reverse the current entity in place. Returns a dictionary with all of the information about the entity.

Attributes:

 `closed` If the first point is the same as the end point the entity is closed `end_points` Returns the first and last points. `is_valid` Is the current entity valid. `nodes` Returns an (n,2) list of nodes, or vertices on the path.
`bounds`(vertices)

Return the AABB of the current entity.

Parameters

vertices ((n, dimension) float) – Vertices in space

Returns

bounds – Coordinates of AABB, in (min, max) form

Return type

(2, dimension) float

property `closed`

If the first point is the same as the end point the entity is closed

Returns

closed – Is the entity closed or not?

Return type

bool

`copy`()

Return a copy of the current entity.

Returns

copied – Copy of current entity

Return type

Entity

property `end_points`

Returns the first and last points. Also note that if you define a new entity class where the first and last vertices in self.points aren’t the endpoints of the curve you need to implement this function for your class.

Returns

ends – Indices of the two end points of the entity

Return type

(2,) int

`explode`()

Split the entity into multiple entities.

Returns

explode – Current entity split into multiple entities if necessary

Return type

list of Entity

property `is_valid`

Is the current entity valid.

Returns

valid – Is the current entity well formed

Return type

bool

`length`(vertices)

Return the total length of the entity.

Parameters

vertices ((n, dimension) float) – Vertices in space

Returns

length – Total length of entity

Return type

float

property `nodes`

Returns an (n,2) list of nodes, or vertices on the path. Note that this generic class function assumes that all of the reference points are on the path which is true for lines and three point arcs.

If you were to define another class where that wasn’t the case (for example, the control points of a bezier curve), you would need to implement an entity- specific version of this function.

The purpose of having a list of nodes is so that they can then be added as edges to a graph so we can use functions to check connectivity, extract paths, etc.

The slicing on this function is essentially just tiling points so the first and last vertices aren’t repeated. Example:

self.points = [0,1,2] returns: [[0,1], [1,2]]

`reverse`(direction=- 1)

Reverse the current entity in place.

Parameters

direction (int) – If positive will not touch direction If negative will reverse self.points

`to_dict`()

Returns a dictionary with all of the information about the entity.

Returns

as_dict – Has keys ‘type’, ‘points’, ‘closed’

Return type

dict

class `trimesh.path.entities.``Line`(points, closed=None, layer=None, color=None, **kwargs)

A line or poly-line entity

Methods:

 `discrete`(vertices[, scale]) Discretize into a world- space path. If the current Line entity consists of multiple line break it up into n Line entities.

Attributes:

 `is_valid` Is the current entity valid.
`discrete`(vertices, scale=1.0)

Discretize into a world- space path.

Parameters
• vertices ((n, dimension) float) – Points in space

• scale (float) – Size of overall scene for numerical comparisons

Returns

discrete – Path in space composed of line segments

Return type

(m, dimension) float

`explode`()

If the current Line entity consists of multiple line break it up into n Line entities.

Returns

exploded

Return type

(n,) Line entities

property `is_valid`

Is the current entity valid.

Returns

valid – Is the current entity well formed

Return type

bool

class `trimesh.path.entities.``Text`(origin, text, height=None, vector=None, normal=None, align=None, layer=None)

Text to annotate a 2D or 3D path.

Methods:

 `angle`(vertices) If Text is 2D, get the rotation angle in radians. `discrete`(*args, **kwargs) `length`(vertices) Return the total length of the entity. `plot`(vertices[, show]) Plot the text using matplotlib.

Attributes:

 `closed` If the first point is the same as the end point the entity is closed `end_points` Returns the first and last points. `is_valid` Is the current entity valid. `nodes` Returns an (n,2) list of nodes, or vertices on the path. `normal` A point representing the plane normal along the vector: vertices[normal] - vertices[origin] `origin` The origin point of the text. `vector` A point representing the text direction along the vector: vertices[vector] - vertices[origin]
`angle`(vertices)

If Text is 2D, get the rotation angle in radians.

Parameters

vertices ((n, 2) float) – Vertices in space referenced by self.points

Returns

angle – Rotation angle in radians

Return type

float

property `closed`

If the first point is the same as the end point the entity is closed

Returns

closed – Is the entity closed or not?

Return type

bool

`discrete`(*args, **kwargs)
property `end_points`

Returns the first and last points. Also note that if you define a new entity class where the first and last vertices in self.points aren’t the endpoints of the curve you need to implement this function for your class.

Returns

ends – Indices of the two end points of the entity

Return type

(2,) int

property `is_valid`

Is the current entity valid.

Returns

valid – Is the current entity well formed

Return type

bool

`length`(vertices)

Return the total length of the entity.

Parameters

vertices ((n, dimension) float) – Vertices in space

Returns

length – Total length of entity

Return type

float

property `nodes`

Returns an (n,2) list of nodes, or vertices on the path. Note that this generic class function assumes that all of the reference points are on the path which is true for lines and three point arcs.

If you were to define another class where that wasn’t the case (for example, the control points of a bezier curve), you would need to implement an entity- specific version of this function.

The purpose of having a list of nodes is so that they can then be added as edges to a graph so we can use functions to check connectivity, extract paths, etc.

The slicing on this function is essentially just tiling points so the first and last vertices aren’t repeated. Example:

self.points = [0,1,2] returns: [[0,1], [1,2]]

property `normal`

A point representing the plane normal along the vector: vertices[normal] - vertices[origin]

Returns

normal – Index of vertex

Return type

int

property `origin`

The origin point of the text.

Returns

origin – Index of vertices

Return type

int

`plot`(vertices, show=False)

Plot the text using matplotlib.

Parameters
• vertices ((n, 2) float) – Vertices in space

• show (bool) – If True, call plt.show()

property `vector`

A point representing the text direction along the vector: vertices[vector] - vertices[origin]

Returns

vector – Index of vertex

Return type

int