LineCollection¶
-
class
LineCollection
(lines=())¶ 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).Methods
Create a LineCollection instance from an iterable of lines.
- rtype
Return repr(self).
Append a single line.
Converts the LineCollection to a
MultiLineString
.Returns the geometries’ bounding box.
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.
__getitem__
(item)¶
-
LineCollection.
__init__
(lines=())¶ Create a LineCollection instance from an iterable of lines.
- Parameters
lines (LineCollectionLike) -- iterable of line (accepts the same input as
append()
).
-
LineCollection.
__iter__
()¶
-
LineCollection.
__repr__
()¶ Return repr(self).
-
LineCollection.
append
(line)¶ 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
-
LineCollection.
as_mls
()¶ Converts the LineCollection to a
MultiLineString
.- Return type
MultiLineString
- Returns
a MultiLineString Shapely object
-
LineCollection.
bounds
()¶ Returns the geometries’ bounding box.
-
LineCollection.
crop
(x1, y1, x2, y2)¶ Crop all lines to a rectangular area.
-
LineCollection.
extend
(lines)¶ 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
-
LineCollection.
filter
(key)¶ Remove lines from the
LineCollection
for which key returns False.
-
LineCollection.
height
()¶ Returns the total height of the geometries.
- Return type
- Returns
the width (ymax - ymin) or 0.0 if the LineCollection is empty
-
LineCollection.
is_empty
()¶ Check for emptiness.
- Return type
- Returns
True if the instance does not contain any line, False otherwise.
-
LineCollection.
length
()¶ Return the total length of the paths.
- Return type
- Returns
the total length
-
LineCollection.
merge
(tolerance, flip=True)¶ Merge lines whose endings overlap or are very close.
-
LineCollection.
pen_up_length
()¶ 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
()¶ Returns a LineCollection containing the pen-up trajectories.
- Return type
LineCollection
-
LineCollection.
reloop
(tolerance)¶ Randomizes the seam of closed paths. Paths are considered closed when their first and last point are closer than tolerance.
-
LineCollection.
rotate
(angle)¶ 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)
-
LineCollection.
scale
(sx, sy=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
()¶ Returns the total number of segment across all lines.
- Return type
- Returns
the total number of segments in the geometries
-
LineCollection.
skew
(ax, ay)¶ 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)
-
LineCollection.
translate
(dx, dy)¶ Translates all line by a given offset.