Polylines¶

class py123d.geometry.Polyline2D[source]¶

Represents a interpolatable 2D polyline.

Example

>>> import numpy as np
>>> from py123d.geometry import Polyline2D
>>> polyline = Polyline2D.from_array(np.array([[0.0, 0.0], [1.0, 1.0], [2.0, 0.0]]))
>>> polyline.length
2.8284271247461903
>>> polyline.interpolate(np.sqrt(2))
Point2D(array=[1. 1.])

Public Data Attributes:

`linestring`	The shapely LineString representation of the polyline.
`array`	The numpy array representation of shape (N, 2), indexed by `Point2DIndex`.
`polyline_se2`	The `PolylineSE2` representation of the polyline, with inferred yaw angles.
`length`	Returns the length of the polyline.

Inherited from ArrayMixin

`array`	The array representation of the geometric entity.
`shape`	Return the shape of the array.

Public Methods:

`from_linestring`(linestring)	Creates a `Polyline2D` from a Shapely LineString.
`from_array`(array[, copy])	Creates a `Polyline2D` from a (N, 2) or (N, 3) shaped numpy array.
`interpolate`(distances[, normalized])	Interpolates the `Polyline2D` at the given distances.
`project`(point[, normalized])	Projects a point onto the polyline and returns the distance along the polyline to the closest point.
`subline`(start_distance, end_distance[, ...])	Extracts a sub-polyline between `start_distance` and `end_distance` along the path.

Inherited from ArrayMixin

`from_array`(array[, copy])	Create an instance from a NumPy array.
`from_list`(values)	Create an instance from a list of values.
`tolist`()	Convert the array to a Python list.
`to_list`()	Convert the array to a Python list.
`copy`()	Return a copy of the object with a copied array.

classmethod from_linestring(linestring)[source]¶

Creates a Polyline2D from a Shapely LineString. If the LineString has Z-coordinates, they are ignored.

Parameters:: linestring (LineString) – A shapely LineString object.
Return type:: Polyline2D
Returns:: A Polyline2D instance.

classmethod from_array(array, copy=True)[source]¶

Creates a Polyline2D from a (N, 2) or (N, 3) shaped numpy array. Assumes […,:2] slices are XY coordinates.

Parameters:

polyline_array – A numpy array of shape (N, 2) or (N, 3), e.g. indexed by Point2DIndex or Point3DIndex.
array (ndarray[tuple[Any, ...], dtype[float64]])
copy (bool)

Raises:

ValueError – If the input array is not of the expected shape.

Return type:

Polyline2D

Returns:

A Polyline2D instance.

property linestring: LineString¶: The shapely LineString representation of the polyline.

property array: ndarray[tuple[Any, ...], dtype[float64]]¶: The numpy array representation of shape (N, 2), indexed by Point2DIndex.

property polyline_se2: PolylineSE2¶: The PolylineSE2 representation of the polyline, with inferred yaw angles.

property length: float¶: Returns the length of the polyline.

interpolate(distances, normalized=False)[source]¶

Interpolates the Polyline2D at the given distances.

Parameters:

distances (Union[float, ndarray[tuple[Any, ...], dtype[float64]]]) – Array-like or float distances along the polyline to interpolate.
normalized (bool)

Return type:

Union[Point2D, ndarray[tuple[Any, ...], dtype[float64]]]

Returns:

The interpolated point(s) on the polyline.

project(point, normalized=False)[source]¶

Projects a point onto the polyline and returns the distance along the polyline to the closest point.

Parameters:

point (Union[Point, Point2D, PoseSE2, ndarray[tuple[Any, ...], dtype[float64]]]) – The point to project onto the polyline.
normalized (bool) – Whether to return the normalized distance, defaults to False.

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

The distance along the polyline to the closest point.

subline(start_distance, end_distance, normalized=False)[source]¶

Extracts a sub-polyline between start_distance and end_distance along the path.

Distances outside [0, length] are clipped. If start_distance > end_distance after clipping, the values are swapped (matching shapely.ops.substring()).

Parameters:

start_distance (float) – Start distance along the polyline.
end_distance (float) – End distance along the polyline.
normalized (bool) – If True, distances are interpreted as fractions of length.

Raises:

ValueError – If start_distance == end_distance after clipping.

Return type:

Polyline2D

Returns:

A new Polyline2D containing the sub-range.

copy()¶

Return a copy of the object with a copied array.

Return type:: ArrayMixin

classmethod from_list(values)¶

Create an instance from a list of values.

Return type:: Self
Parameters:: values (list)

property shape: tuple¶: Return the shape of the array.

to_list()¶

Convert the array to a Python list.

Return type:: list

tolist()¶

Convert the array to a Python list.

Return type:: list

class py123d.geometry.PolylineSE2[source]¶

Represents a interpolatable SE2 polyline.

Example

>>> import numpy as np
>>> from py123d.geometry import PolylineSE2
>>> polyline_se2 = PolylineSE2.from_array(np.array([[0.0, 0.0, 0.0], [1.0, 1.0, np.pi/4], [2.0, 0.0, 0.0]]))
>>> polyline_se2.length
2.8284271247461903
>>> polyline_se2.interpolate(np.sqrt(2))
PoseSE2(array=[1.         1.         0.78539816])

Public Data Attributes:

`linestring`	The shapely LineString representation of the polyline.
`array`	The numpy array representation of shape (N, 3), indexed by `PoseSE2Index`.
`length`	Returns the length of the polyline.

Inherited from ArrayMixin

`array`	The array representation of the geometric entity.
`shape`	Return the shape of the array.

Public Methods:

`from_linestring`(linestring)	Creates a `PolylineSE2` from a shapely LineString.
`from_array`(array[, copy])	Creates a `PolylineSE2` from a numpy array.
`interpolate`(distances[, normalized])	Interpolates the polyline at the given distances.
`project`(point[, normalized])	Projects a point onto the polyline and returns the distance along the polyline to the closest point.
`subline`(start_distance, end_distance[, ...])	Extracts a sub-polyline between `start_distance` and `end_distance` along the path.

Inherited from ArrayMixin

`from_array`(array[, copy])	Create an instance from a NumPy array.
`from_list`(values)	Create an instance from a list of values.
`tolist`()	Convert the array to a Python list.
`to_list`()	Convert the array to a Python list.
`copy`()	Return a copy of the object with a copied array.

classmethod from_linestring(linestring)[source]¶

Creates a PolylineSE2 from a shapely LineString. The yaw angles are inferred from the LineString coordinates.

Parameters:: linestring (LineString) – The LineString to convert.
Return type:: PolylineSE2
Returns:: A PolylineSE2 representing the same path as the LineString.

classmethod from_array(array, copy=True)[source]¶

Creates a PolylineSE2 from a numpy array.

Parameters:

polyline_array – The input numpy array representing, either indexed by Point2DIndex or PoseSE2Index.
copy (bool) – Whether to copy the input array or not (ignored).
array (ndarray[tuple[Any, ...], dtype[float64]])

Raises:

ValueError – If the input array is not of the expected shape.

Return type:

PolylineSE2

Returns:

A PolylineSE2 representing the same path as the input array.

property linestring: LineString¶: The shapely LineString representation of the polyline.

property array: ndarray[tuple[Any, ...], dtype[float64]]¶: The numpy array representation of shape (N, 3), indexed by PoseSE2Index.

property length: float¶: Returns the length of the polyline.

interpolate(distances, normalized=False)[source]¶

Interpolates the polyline at the given distances.

Parameters:

distances (Union[float, ndarray[tuple[Any, ...], dtype[float64]]]) – The distances along the polyline to interpolate.
normalized (bool) – Whether the distances are normalized (0 to 1), defaults to False

Return type:

Union[PoseSE2, ndarray[tuple[Any, ...], dtype[float64]]]

Returns:

The interpolated PoseSE2 or an array of interpolated states, according to

project(point, normalized=False)[source]¶

Projects a point onto the polyline and returns the distance along the polyline to the closest point.

Parameters:

point (Union[Point, Point2D, PoseSE2, ndarray[tuple[Any, ...], dtype[float64]]]) – The point to project onto the polyline.
normalized (bool) – Whether to return the normalized distance, defaults to False.

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

The distance along the polyline to the closest point.

subline(start_distance, end_distance, normalized=False)[source]¶

Extracts a sub-polyline between start_distance and end_distance along the path.

Distances outside [0, length] are clipped. If start_distance > end_distance after clipping, the values are swapped (matching shapely.ops.substring()). The yaw column is left in the unwrapped frame of the parent polyline so that the new PolylineSE2 constructor produces a consistent unwrap.

Parameters:

start_distance (float) – Start distance along the polyline.
end_distance (float) – End distance along the polyline.
normalized (bool) – If True, distances are interpreted as fractions of length.

Raises:

ValueError – If start_distance == end_distance after clipping.

Return type:

PolylineSE2

Returns:

A new PolylineSE2 containing the sub-range.

copy()¶

Return a copy of the object with a copied array.

Return type:: ArrayMixin

classmethod from_list(values)¶

Create an instance from a list of values.

Return type:: Self
Parameters:: values (list)

property shape: tuple¶: Return the shape of the array.

to_list()¶

Convert the array to a Python list.

Return type:: list

tolist()¶

Convert the array to a Python list.

Return type:: list

class py123d.geometry.PolylineSE3[source]¶

Represents an interpolatable SE3 polyline (3D position + quaternion rotation).

Supports pluggable rotation interpolation strategies: SLERP (default) and NLERP.

Example

>>> import numpy as np
>>> from py123d.geometry import PolylineSE3
>>> poses = np.array([
...     [0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...     [2.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
... ])
>>> polyline = PolylineSE3.from_array(poses)
>>> polyline.length
2.0
>>> polyline.interpolate(1.0)
PoseSE3(array=[1. 0. 0. 1. 0. 0. 0.])

Public Data Attributes:

`array`	The numpy array representation of shape (N, 7), indexed by `PoseSE3Index`.
`length`	Returns the translational path length of the SE3 polyline.
`rotation_interpolation`	The rotation interpolation strategy used by this polyline.

Inherited from ArrayMixin

`array`	The array representation of the geometric entity.
`shape`	Return the shape of the array.

Public Methods:

`from_array`(array[, copy, rotation_interpolation])	Creates a `PolylineSE3` from a numpy array.
`interpolate`(distances[, normalized])	Interpolates the SE3 polyline at the given distances.
`subline`(start_distance, end_distance[, ...])	Extracts a sub-polyline between `start_distance` and `end_distance` along the path.

Inherited from ArrayMixin

`from_array`(array[, copy])	Create an instance from a NumPy array.
`from_list`(values)	Create an instance from a list of values.
`tolist`()	Convert the array to a Python list.
`to_list`()	Convert the array to a Python list.
`copy`()	Return a copy of the object with a copied array.

classmethod from_array(array, copy=True, rotation_interpolation='slerp')[source]¶

Creates a PolylineSE3 from a numpy array.

Parameters:

array (ndarray[tuple[Any, ...], dtype[float64]]) – A numpy array of shape (N, 7) representing SE3 poses, indexed by PoseSE3Index.
copy (bool) – Whether to copy the input array. Defaults to True.
rotation_interpolation (str) – Rotation interpolation strategy, either "slerp" or "nlerp".

Return type:

PolylineSE3

Returns:

A PolylineSE3 instance.

property array: ndarray[tuple[Any, ...], dtype[float64]]¶: The numpy array representation of shape (N, 7), indexed by PoseSE3Index.

property length: float¶: Returns the translational path length of the SE3 polyline.

property rotation_interpolation: str¶: The rotation interpolation strategy used by this polyline.

interpolate(distances, normalized=False)[source]¶

Interpolates the SE3 polyline at the given distances.

Translation is interpolated linearly; rotation is interpolated using the configured strategy.

Parameters:

distances (Union[float, ndarray[tuple[Any, ...], dtype[float64]]]) – A float or numpy array of distances along the polyline.
normalized (bool) – Whether to interpret the distances as fractions of the length.

Return type:

Union[PoseSE3, ndarray[tuple[Any, ...], dtype[float64]]]

Returns:

A PoseSE3 instance for scalar input, or a numpy array of shape (N, 7).

subline(start_distance, end_distance, normalized=False)[source]¶

Extracts a sub-polyline between start_distance and end_distance along the path.

Distances outside [0, length] are clipped. If start_distance > end_distance after clipping, the values are swapped (matching shapely.ops.substring()). Endpoint rotations are interpolated via the active strategy (SLERP or NLERP); the strategy is propagated to the returned polyline.

Parameters:

start_distance (float) – Start distance along the polyline.
end_distance (float) – End distance along the polyline.
normalized (bool) – If True, distances are interpreted as fractions of length.

Raises:

ValueError – If start_distance == end_distance after clipping.

Return type:

PolylineSE3

Returns:

A new PolylineSE3 containing the sub-range.

copy()¶

Return a copy of the object with a copied array.

Return type:: ArrayMixin

classmethod from_list(values)¶

Create an instance from a list of values.

Return type:: Self
Parameters:: values (list)

property shape: tuple¶: Return the shape of the array.

to_list()¶

Convert the array to a Python list.

Return type:: list

tolist()¶

Convert the array to a Python list.

Return type:: list

class py123d.geometry.Polyline3D[source]¶

Represents a interpolatable 3D polyline.

Example

>>> import numpy as np
>>> from py123d.geometry import Polyline3D
>>> polyline_3d = Polyline3D.from_array(np.array([[0.0, 0.0, 0.0], [1.0, 1.0, 1.0], [2.0, 0.0, 0.0]]))
>>> polyline_3d.length
3.4641016151377544
>>> polyline_3d.interpolate(np.sqrt(3))
Point3D(array=[1. 1. 1.])

Public Data Attributes:

`linestring`	The shapely LineString representation of the 3D polyline.
`array`	The numpy array representation of shape (N, 3), indexed by `Point3DIndex`.
`polyline_2d`	The `Polyline2D` representation of the 3D polyline.
`polyline_se2`	The `PolylineSE2` representation of the 3D polyline.
`length`	Returns the length of the 3D polyline.

Inherited from ArrayMixin

`array`	The array representation of the geometric entity.
`shape`	Return the shape of the array.

Public Methods:

`from_linestring`(linestring)	Creates a `Polyline3D` from a shapely LineString.
`from_array`(array[, copy])	Creates a `Polyline3D` from a numpy array.
`interpolate`(distances[, normalized])	Interpolates the 3D polyline at the given distances.
`project`(point[, normalized])	Projects a point onto the 3D polyline and returns the distance along the polyline to the closest point.
`subline`(start_distance, end_distance[, ...])	Extracts a sub-polyline between `start_distance` and `end_distance` along the path.

Inherited from ArrayMixin

`from_array`(array[, copy])	Create an instance from a NumPy array.
`from_list`(values)	Create an instance from a list of values.
`tolist`()	Convert the array to a Python list.
`to_list`()	Convert the array to a Python list.
`copy`()	Return a copy of the object with a copied array.

classmethod from_linestring(linestring)[source]¶

Creates a Polyline3D from a shapely LineString. If the LineString does not have Z-coordinates, the coordinate is zero-padded.

Parameters:: linestring (LineString) – The input LineString.
Return type:: Polyline3D
Returns:: A Polyline3D instance.

classmethod from_array(array, copy=True)[source]¶

Creates a Polyline3D from a numpy array.

Parameters:

array (ndarray[tuple[Any, ...], dtype[float64]]) – A numpy array of shape (N, 3) representing 3D points, e.g. indexed by Point3DIndex.
copy (bool)

Return type:

Polyline3D

Returns:

A Polyline3D instance.

property linestring: LineString¶: The shapely LineString representation of the 3D polyline.

property array: ndarray[tuple[Any, ...], dtype[float64]]¶: The numpy array representation of shape (N, 3), indexed by Point3DIndex.

property polyline_2d: Polyline2D¶: The Polyline2D representation of the 3D polyline.

property polyline_se2: PolylineSE2¶: The PolylineSE2 representation of the 3D polyline.

property length: float¶: Returns the length of the 3D polyline.

interpolate(distances, normalized=False)[source]¶

Interpolates the 3D polyline at the given distances.

Parameters:

distances (Union[float, ndarray[tuple[Any, ...], dtype[float64]]]) – A float or numpy array of distances along the polyline.
normalized (bool) – Whether to interpret the distances as fractions of the length.

Return type:

Union[Point3D, ndarray[tuple[Any, ...], dtype[float64]]]

Returns:

A Point3D instance or a numpy array of shape (N, 3) representing the interpolated points.

project(point, normalized=False)[source]¶

Projects a point onto the 3D polyline and returns the distance along the polyline to the closest point.

Parameters:

point (Union[Point, Point2D, Point3D, ndarray[tuple[Any, ...], dtype[float64]]]) – The point to project.
normalized (bool) – Whether to return normalized distances, defaults to False.

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

The distance along the polyline to the closest point.

subline(start_distance, end_distance, normalized=False)[source]¶

Extracts a sub-polyline between start_distance and end_distance along the path.

Distances outside [0, length] are clipped. If start_distance > end_distance after clipping, the values are swapped (matching shapely.ops.substring()).

Parameters:

start_distance (float) – Start distance along the polyline.
end_distance (float) – End distance along the polyline.
normalized (bool) – If True, distances are interpreted as fractions of length.

Raises:

ValueError – If start_distance == end_distance after clipping.

Return type:

Polyline3D

Returns:

A new Polyline3D containing the sub-range.

copy()¶

Return a copy of the object with a copied array.

Return type:: ArrayMixin

classmethod from_list(values)¶

Create an instance from a list of values.

Return type:: Self
Parameters:: values (list)

property shape: tuple¶: Return the shape of the array.

to_list()¶

Convert the array to a Python list.

Return type:: list

tolist()¶

Convert the array to a Python list.

Return type:: list