LineCollection#
- class LineCollection(lines: Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing] = (), metadata: Optional[dict[str, Any]] = None)#
LineCollection
encapsulate a list of piecewise linear lines (or paths). Lines are implemented as 1D numpy arrays of complex numbers whose real and imaginary parts represent the X, respectively Y, coordinates of point in the paths.An instance of
LineCollection
is used to model a single layer in vpype’s pipeline. The complete pipeline is modelled by aDocument
instance, which essentially is a mapping ofint
(layer ID) toLineCollection
.Although the actual
list
is stored as private data member inLineCollection
instances, the class provides a sequence API similar tolist
:>>> import vpype, numpy as np >>> lc = vpype.LineCollection() >>> lc.append(np.array([0, 10. + 10.j])) >>> lc.append(np.array([10.j, 5. + 5.j])) >>> len(lc) 2 >>> lc[0] array([ 0. +0.j, 10.+10.j]) >>> for line in lc: ... print(repr(line)) ... array([ 0. +0.j, 10.+10.j]) array([0.+10.j, 5. +5.j])
In addition to Numpy arrays, the class accepts paths expressed in a variety of format including Python
list
or Shapely objects:>>> from shapely.geometry import LineString, LinearRing, MultiLineString >>> lc = vpype.LineCollection() >>> lc.append([5, 5+5j]) >>> lc.append(LineString([(1, 1), (3, 2)])) >>> lc.append(LinearRing([(0, 0), (1, 0), (1, 1), (0, 1)])) >>> lc.extend(MultiLineString([[(0, 0), (10, 0)], [(4, 4), (0, 4)]])) >>> lc LineCollection([array([5.+0.j, 5.+5.j]), array([1.+1.j, 3.+2.j]), array([0.+0.j, 1.+0.j, 1.+1.j, 0.+1.j, 0.+0.j]), array([ 0.+0.j, 10.+0.j]), array([4.+4.j, 0.+4.j])])
Instances can also be converted to Shapely’s MultiLineString:
>>> mls = lc.as_mls() >>> print(mls) MULTILINESTRING ((5 0, 5 5), (1 1, 3 2), (0 0, 1 0, 1 1, 0 1, 0 0), (0 0, 10 0), (4 4, 0 4))
Finally,
LineCollection
implements a number of operations such as geometrical transformation, cropping, merging, etc. (see member function documentation for details).- Parameters:
Methods
Append a single line.
Converts the LineCollection to a
MultiLineString
.Returns the geometries' bounding box.
Creates a new
LineCollection
with the same metadata.Crop all lines to a rectangular area.
Append lines from a collection.
Remove lines from the
LineCollection
for which key returns False.Returns the total height of the geometries.
Check for emptiness.
Return the total length of the paths.
Merge lines whose endings overlap or are very close.
Returns statistics on the pen-up distance corresponding to the path.
Returns a LineCollection containing the pen-up trajectories.
Randomizes the seam of closed paths.
Reverse order of the lines.
Rotates the geometry by
angle
amount.Scale the geometry.
Returns the total number of segment across all lines.
Skew the geometry by some angular amounts along X and Y axes.
Translates all line by a given offset.
Returns the total width of the geometries.
Attributes
Returns the list of line.
Methods#
- LineCollection.append(line: Union[LineString, LinearRing, Iterable[complex]]) None #
Append a single line.
This function accepts an iterable of complex or a Shapely geometry (
LineString
orLinearRing
).- Parameters:
line (LineLike) -- line to append
- Return type:
None
- LineCollection.as_mls() MultiLineString #
Converts the LineCollection to a
MultiLineString
.- Returns:
a MultiLineString Shapely object
- Return type:
- LineCollection.bounds() tuple[float, float, float, float] | None #
Returns the geometries’ bounding box.
- LineCollection.clone(lines: Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing] = ()) LineCollection #
Creates a new
LineCollection
with the same metadata.If
lines
is provided, its content is added to the newLineCollection
instance.- Parameters:
lines (Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing]) -- path to add to the new
LineCollection
instance- Returns:
the new
LineCollection
instance- Return type:
- LineCollection.crop(x1: float, y1: float, x2: float, y2: float) None #
Crop all lines to a rectangular area.
- LineCollection.extend(lines: Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing]) None #
Append lines from a collection.
This function accepts an iterable of iterable of complex, another
LineCollection
instance, or a Shapely geometry (MultiLineString
,LineString
orLinearRing
).Shapely’s LineString and LinearRing are occasionally obtained when a MultiLineString is actually expected. As a result, they are accepted as input even though they are not, strictly speaking, a line collection.
- Parameters:
lines (LineCollectionLike) -- lines to append
- Return type:
None
- LineCollection.filter(key: Callable[[ndarray], bool]) None #
Remove lines from the
LineCollection
for which key returns False.
- LineCollection.height() float #
Returns the total height of the geometries.
- Returns:
the width (ymax - ymin) or 0.0 if the LineCollection is empty
- Return type:
- LineCollection.is_empty() bool #
Check for emptiness.
- Returns:
True if the instance does not contain any line, False otherwise.
- Return type:
- LineCollection.length() float #
Return the total length of the paths.
- Returns:
the total length
- Return type:
- LineCollection.merge(tolerance: float, flip: bool = True) None #
Merge lines whose endings overlap or are very close.
- LineCollection.pen_up_length() tuple[float, float, float] #
Returns statistics on the pen-up distance corresponding to the path.
The total, mean, and median distance are returned. The pen-up distance is the distance between a path’s end and the next path’s beginning.
- LineCollection.pen_up_trajectories() LineCollection #
Returns a LineCollection containing the pen-up trajectories.
- Return type:
- LineCollection.reloop(tolerance: float) None #
Randomizes the seam of closed paths. Paths are considered closed when their first and last point are closer than tolerance.
- Parameters:
tolerance (float) -- tolerance to determine if a path is closed
- Return type:
None
- LineCollection.rotate(angle: float) None #
Rotates the geometry by
angle
amount.The angle is expressed in radian. Positive value rotate clockwise.
The rotation is performed about the coordinates origin (0, 0). To rotate around a specific location, appropriate translations must be performed before and after the scaling:
>>> import vpype >>> lc = vpype.LineCollection([(-1+1j, 1+1j)]) >>> lc.translate(0, -1) >>> lc.rotate(1.2) >>> lc.translate(0, 1)
- Parameters:
angle (float) -- rotation angle in rad
- Return type:
None
- LineCollection.scale(sx: float, sy: Optional[float] = None) None #
Scale the geometry.
The scaling is performed about the coordinates origin (0, 0). To scale around a specific location, appropriate translations must be performed before and after the scaling:
>>> import vpype >>> lc = vpype.LineCollection([(-1+1j, 1+1j)]) >>> lc.translate(0, -1) >>> lc.scale(1.2) >>> lc.translate(0, 1) >>> lc LineCollection([array([-1.2+1.j, 1.2+1.j])])
- LineCollection.segment_count() int #
Returns the total number of segment across all lines.
- Returns:
the total number of segments in the geometries
- Return type:
- LineCollection.skew(ax: float, ay: float) None #
Skew the geometry by some angular amounts along X and Y axes.
The angle is expressed in radians.
The skew is performed about the coordinates origin (0, 0). To rotate around a specific location, appropriate translations must be performed before and after the scaling:
>>> import vpype >>> lc = vpype.LineCollection([(-1+1j, 1+1j)]) >>> lc.translate(0, -1) >>> lc.skew(0., 1.2) >>> lc.translate(0, 1)
Attributes#
- LineCollection.lines#
Returns the list of line.
- Returns:
list of line