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:
Methods
Add a the content of a
LineCollection
to a given layer.Add a path to the source list.
Compute bounds of the document.
Clear all metadata from the document.
Create an empty copy of this document with the same metadata.
Returns the total number of layers.
Crop all layers to a rectangular area.
Create an empty copy of this document with the same metadata.
Test existence of a layer.
Extend a Document with the content of another Document.
Adjust the page sized according to the following logic:
Set
page_size
to the current geometries' width and height and move the geometries so that their bounds align to (0, 0).Returns the lowest unused layer id.
Returns the list of layer IDs
Returns True if all layers are empty.
Returns an iterator that yield layers corresponding to the provided IDs, provided they exist.
Return the total length of the paths.
Returns the total pen-up distance corresponding to the path.
Removes a layer from the Document.
Replaces the content of a layer.
Rotate the Document's content..
Scale the geometry.
Returns the total number of segment across all lines.
Swap the content of two layers.
Translates all line by a given offset.
Attributes
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 oflc
.The destination layer’s metadata is unchanged, unless
with_metadata
isTrue
.- 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 layerwith_metadata (bool) -- copies/update the metadata to the destination layer (if any)
- 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.
- 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.
- Document.count() int #
Returns the total number of layers.
- Returns:
total number of layer
- Return type:
- Document.crop(x1: float, y1: float, x2: float, y2: float) None #
Crop all layers to a rectangular area.
- 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.
- 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.
- 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 usingextend_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 unchangedif
self.page_size
is None, it is set topage_size
if both page sizes are not None, the page size is set to the largest value in both direction
- 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:
- Document.is_empty() bool #
Returns True if all layers are empty.
- Returns:
True if all layers are empty
- Return type:
- 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:
- Returns:
layer iterator
- Return type:
- Document.length() float #
Return the total length of the paths.
- Returns:
the total length
- Return type:
- 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:
- 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:
- 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
withlines
. The layer must exist, otherwise aValueError
exception is raised.The destination layer retains its metadata, unless
with_metadata
is True, in which caselines
must have ametadata
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: 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()
).
- Document.segment_count() int #
Returns the total number of segment across all lines.
- Returns:
the total number of segments in the geometries
- Return type:
- 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.
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#