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 a Document instance, which essentially is a mapping of int (layer ID) to LineCollection.

Although the actual list is stored as private data member in LineCollection instances, the class provides a sequence API similar to list:

>>> 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

__getitem__

__init__

Create a LineCollection instance from an iterable of lines.

__iter__

__len__

rtype

int

__repr__

Return repr(self).

append

Append a single line.

as_mls

Converts the LineCollection to a MultiLineString.

bounds

Returns the geometries' bounding box.

crop

Crop all lines to a rectangular area.

extend

Append lines from a collection.

filter

Remove lines from the LineCollection for which key returns False.

height

Returns the total height of the geometries.

is_empty

Check for emptiness.

length

Return the total length of the paths.

merge

Merge lines whose endings overlap or are very close.

pen_up_length

Returns statistics on the pen-up distance corresponding to the path.

pen_up_trajectories

Returns a LineCollection containing the pen-up trajectories.

reloop

Randomizes the seam of closed paths.

reverse

Reverse order of the lines.

rotate

Rotates the geometry by angle amount.

scale

Scale the geometry.

segment_count

Returns the total number of segment across all lines.

skew

Skew the geometry by some angular amounts along X and Y axes.

translate

Translates all line by a given offset.

width

Returns the total width of the geometries.

Attributes

lines

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.__len__()
Return type

int

LineCollection.__repr__()

Return repr(self).

LineCollection.append(line)

Append a single line.

This function accepts an iterable of complex or a Shapely geometry (LineString or LinearRing).

Parameters

line (LineLike) -- line to append

Return type

None

LineCollection.as_mls()

Converts the LineCollection to a MultiLineString.

Return type

MultiLineString

Returns

a MultiLineString Shapely object

LineCollection.bounds()

Returns the geometries’ bounding box.

Return type

Optional[Tuple[float, float, float, float]]

Returns

tuple (xmin, ymin, xmax, ymax) for the bounding box or None if the LineCollection is empty

LineCollection.crop(x1, y1, x2, y2)

Crop all lines to a rectangular area.

Parameters
  • x1 (float) -- first corner of the crop area

  • y1 (float) -- first corner of the crop area

  • x2 (float) -- second corner of the crop area

  • y2 (float) -- second corner of the crop area

Return type

None

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 or LinearRing).

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)

Remove lines from the LineCollection for which key returns False.

Parameters

key (Callable[[ndarray], bool]) -- filter (returns True if the line should be kept or False otherwise)

Return type

None

LineCollection.height()

Returns the total height of the geometries.

Return type

float

Returns

the width (ymax - ymin) or 0.0 if the LineCollection is empty

LineCollection.is_empty()

Check for emptiness.

Return type

bool

Returns

True if the instance does not contain any line, False otherwise.

LineCollection.length()

Return the total length of the paths.

Return type

float

Returns

the total length

LineCollection.merge(tolerance, flip=True)

Merge lines whose endings overlap or are very close.

Parameters
  • tolerance (float) -- max distance between line ending that may be merged

  • flip (bool) -- allow flipping line direction for further merging

Return type

None

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.

Return type

Tuple[float, float, float]

Returns

tuple (total, mean, median) for the pen-up distances

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.

Parameters

tolerance (float) -- tolerance to determine if a path is closed

Return type

None

LineCollection.reverse()

Reverse order of the lines.

Return type

None

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)
Parameters

angle (float) -- rotation angle in rad

Return type

None

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])])
Parameters
  • sx (float) -- scale factor along x

  • sy (Optional[float]) -- scale factor along y (if None, then sx is used)

Return type

None

LineCollection.segment_count()

Returns the total number of segment across all lines.

Return type

int

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)
Parameters
  • ax (float) -- skew angle in rad along X axis

  • ay (float) -- skew angle in rad along Y axis

Return type

None

LineCollection.translate(dx, dy)

Translates all line by a given offset.

Parameters
  • dx (float) -- offset along X axis

  • dy (float) -- offset along Y axis

Return type

None

LineCollection.width()

Returns the total width of the geometries.

Return type

float

Returns

the width (xmax - xmin) or 0.0 if the LineCollection is empty

Attributes

LineCollection.lines

Returns the list of line.

Return type

List[ndarray]

Returns

list of line