Document#

class Document(line_collection: Optional[LineCollection] = None, metadata: Optional[dict[str, Any]] = None, page_size: Optional[tuple[float, float]] = 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 (LineCollection) -- if provided, used as layer 1

  • metadata (dict[str, Any] | None) -- if provided, used as global metadata

  • page_size (tuple[float, float] | None) -- 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

Methods#

Document.add(lines: Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing], layer_id: Optional[int] = None, with_metadata: bool = False) None#

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:
Return type:

None

Document.add_to_sources(path) None#

Add a path to the source list.

This function sets the vp_source property to provided path and adds it to the vp_sources property.

Parameters:

path -- file path

Return type:

None

Document.bounds(layer_ids: Optional[Iterable[int]] = None) tuple[float, float, float, float] | 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

Returns:

boundaries of the geometries

Return type:

tuple[float, float, float, float] | None

Document.clear_layer_metadata() None#

Clear all metadata from the document.

Return type:

None

Document.clone(keep_layers: bool = False) Document#

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

Returns:

the cloned document

Return type:

Document

Document.count() int#

Returns the total number of layers.

Returns:

total number of layer

Return type:

int

Document.crop(x1: float, y1: float, x2: float, y2: float) None#

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: bool = False) Document#

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

Returns:

the cloned document

Return type:

Document

Document.exists(layer_id: int | None) bool#

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 (int | None) -- layer ID to test

Returns:

True if the layer ID exists

Return type:

bool

Document.extend(doc: Document) None#

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: tuple[float, float] | None) None#

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 (tuple[float, float] | None) -- page dimension to use to update self.page_size

Return type:

None

Document.fit_page_size_to_content() None#

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() int#

Returns the lowest unused layer id.

Returns:

the unused layer ID

Return type:

int

Document.ids() Iterable[int]#

Returns the list of layer IDs

Return type:

Iterable[int]

Document.is_empty() bool#

Returns True if all layers are empty.

Returns:

True if all layers are empty

Return type:

bool

Document.layers_from_ids(layer_ids: Iterable[int]) Iterator[LineCollection]#

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

Returns:

layer iterator

Return type:

Iterator[LineCollection]

Document.length() float#

Return the total length of the paths.

Returns:

the total length

Return type:

float

Document.pen_up_length() float#

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

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

Returns:

total pen-up distances

Return type:

float

Document.pop(layer_id: int) LineCollection#

Removes a layer from the Document.

Parameters:

layer_id (int) -- ID of the layer to be removed

Returns:

the LineCollection corresponding to the removed layer

Return type:

LineCollection

Document.replace(lines: Union[Iterable[Union[LineString, LinearRing, Iterable[complex]]], MultiLineString, LineCollection, LineString, LinearRing], layer_id: int, *, with_metadata: bool = False) None#

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:
Return type:

None

Document.rotate(angle: float) None#

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: 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 (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() int#

Returns the total number of segment across all lines.

Returns:

the total number of segments in the geometries

Return type:

int

Document.swap_content(lid1: int, lid2: int) None#

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: float, dy: float) None#

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. :returns: the internal layer dictionary

Document.page_size#

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

Document.sources#