Document

class Document(line_collection=None, metadata=None, page_size=None)

This class is the core data model of vpype and represent the data that is passed from one command to the other. At its core, a Document is a collection of layers identified by non-zero positive integers and each represented by a LineCollection.

In addition, the Document class maintains a page_size attribute which describe the physical size of the document. This attribute is not strictly linked to the actual Document’s content, but can be set based on it.

Parameters

line_collection (Optional[LineCollection]) -- if provided, used as layer 1
metadata (Optional[Dict[str, Any]]) -- if provided, used as global metadata
page_size (Optional[Tuple[float, float]]) -- if provided, used as page size

Methods

`add`	Add a the content of a `LineCollection` to a given layer.
`add_to_sources`	Add a path to the source list.
`bounds`	Compute bounds of the document.
`clear_layer_metadata`	Clear all metadata from the document.
`clone`	Create an empty copy of this document with the same metadata.
`count`	Returns the total number of layers.
`crop`	Crop all layers to a rectangular area.
`empty_copy`	Create an empty copy of this document with the same metadata.
`exists`	Test existence of a layer.
`extend`	Extend a Document with the content of another Document.
`extend_page_size`	Adjust the page sized according to the following logic:
`fit_page_size_to_content`	Set `page_size` to the current geometries' width and height and move the geometries so that their bounds align to (0, 0).
`free_id`	Returns the lowest unused layer id.
`ids`	Returns the list of layer IDs
`is_empty`	Returns True if all layers are empty.
`layers_from_ids`	Returns an iterator that yield layers corresponding to the provided IDs, provided they exist.
`length`	Return the total length of the paths.
`pen_up_length`	Returns the total pen-up distance corresponding to the path.
`pop`	Removes a layer from the Document.
`replace`	Replaces the content of a layer.
`rotate`	Rotate the Document's content..
`scale`	Scale the geometry.
`segment_count`	Returns the total number of segment across all lines.
`swap_content`	Swap the content of two layers.
`translate`	Translates all line by a given offset.

Attributes

layers

Returns a reference to the layer dictionary.

page_size

Returns the page size or None if it hasn't been set.

sources

rtype: Set[Path]

Methods

Document.add(lines, layer_id=None, with_metadata=False)

Add a the content of a LineCollection to a given layer.

If the given layer ID is None, a new layer with the lowest available layer ID is created and initialized with the content of lc.

The destination layer’s metadata is unchanged, unless with_metadata is True.

Parameters

lines (Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing]) -- lines to add to the layer
layer_id (Optional[int]) -- the destination layer ID, or None for a new layer
with_metadata (bool) -- copies/update the metadata to the destination layer (if any)

Return type

None

Document.add_to_sources(path)

Add a path to the source list.

If path cannot be converted to a pathlib.Path or the file doesn’t exist, it is ignored and not added to the source list.

Parameters: path -- file path
Return type: None

Document.bounds(layer_ids=None)

Compute bounds of the document.

If layer_ids is provided, bounds are computed only for the corresponding IDs.

Note: the bounds are computed based on the actual geometries contained in this Document instance. The document’s page size, if any, is not taken into account by this calculation.

Parameters: layer_ids (Optional[Iterable[int]]) -- layers to consider in the bound calculation
Return type: Optional[Tuple[float, float, float, float]]
Returns: boundaries of the geometries

Document.clear_layer_metadata()

Clear all metadata from the document.

Return type: None

Document.clone(keep_layers=False)

Create an empty copy of this document with the same metadata.

By default, the cloned document doest not contain any layer. If keep_layers is set to true, empty layers with metadata will be created to match the source document’s layer.

Parameters: keep_layers (bool) -- if True, empty layers matching the source document’s layers and metadata
Return type: Document
Returns: the cloned document

Document.count()

Returns the total number of layers.

Return type: int
Returns: total number of layer

Document.crop(x1, y1, x2, y2)

Crop all layers 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

Document.empty_copy(keep_layers=False)

Create an empty copy of this document with the same metadata.

By default, the cloned document doest not contain any layer. If keep_layers is set to true, empty layers with metadata will be created to match the source document’s layer.

Parameters: keep_layers (bool) -- if True, empty layers matching the source document’s layers and metadata
Return type: Document
Returns: the cloned document

Document.exists(layer_id)

Test existence of a layer.

Note that existence of a layer does not necessarily imply that it isn’t empty. Always return False if layer_id is None.

Parameters: layer_id (Optional[int]) -- layer ID to test
Return type: bool
Returns: True if the layer ID exists

Document.extend(doc)

Extend a Document with the content of another Document.

The layer structure of the source Document is maintained and geometries are either appended to the destination’s corresponding layer or new layers are created, depending on if the layer existed or not in the destination Document.

The page_size attribute is adjusted using extend_page_size().

The source’s metadata is copied over to the destination, overriding any existing property. Properties existing in the destination but not in the source are preserved.

Parameters: doc (Document) -- source Document
Return type: None

Document.extend_page_size(page_size)

Adjust the page sized according to the following logic:

if page_size is None, the the page size is unchanged

if self.page_size is None, it is set to page_size

if both page sizes are not None, the page size is set to the largest value in both direction

Parameters: page_size (Optional[Tuple[float, float]]) -- page dimension to use to update self.page_size
Return type: None

Document.fit_page_size_to_content()

Set page_size to the current geometries’ width and height and move the geometries so that their bounds align to (0, 0).

Return type: None

Document.free_id()

Returns the lowest unused layer id.

Return type: int
Returns: the unused layer ID

Document.ids()

Returns the list of layer IDs

Return type: Iterable[int]

Document.is_empty()

Returns True if all layers are empty.

Return type: bool
Returns: True if all layers are empty

Document.layers_from_ids(layer_ids)

Returns an iterator that yield layers corresponding to the provided IDs, provided they exist. This is typically used to process a command’s layer list option, in combination with multiple_to_layer_ids().

Non-existent layer IDs in the input are ignored.

Parameters: layer_ids (Iterable[int]) -- iterable of layer IDs
Return type: Iterator[LineCollection]
Returns: layer iterator

Document.length()

Return the total length of the paths.

Return type: float
Returns: the total length

Document.pen_up_length()

Returns the total pen-up distance corresponding to the path.

This function does not account for the pen-up distance between layers.

Return type: float
Returns: total pen-up distances

Document.pop(layer_id)

Removes a layer from the Document.

Parameters: layer_id (int) -- ID of the layer to be removed
Return type: LineCollection
Returns: the LineCollection corresponding to the removed layer

Document.replace(lines, layer_id, *, with_metadata=False)

Replaces the content of a layer.

This method replaces the content of layer layer_id with lines. The layer must exist, otherwise a ValueError exception is raised.

The destination layer retains its metadata, unless with_metadata is True, in which case lines must have a metadata attribute.

Parameters

lines (Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing]) -- line data to assign to the layer
layer_id (int) -- layer ID of the layer whose content is to be replaced
with_metadata (bool) --

Return type

None

Document.rotate(angle)

Rotate the Document’s content..

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 (see LineCollection.rotate()).

Parameters: angle (float) -- rotation angle (radian)
Return type: None

Document.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 (see LineCollection.scale()).

Parameters

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

Return type

None

Document.segment_count()

Returns the total number of segment across all lines.

Return type: int
Returns: the total number of segments in the geometries

Document.swap_content(lid1, lid2)

Swap the content of two layers.

This method swaps the content between two layers. Each layer retains its original metadata.

A ValueError is raised if either of the layer ID do not exist.

Parameters

lid1 (int) -- first layer
lid2 (int) -- second layer

Return type

None

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

Attributes

Document.layers: Returns a reference to the layer dictionary. :rtype: Dict[int, LineCollection] :returns: the internal layer dictionary

Document.page_size

Returns the page size or None if it hasn’t been set.

Return type: Optional[Tuple[float, float]]

Document.sources

Return type: Set[Path]