Document

class Document(line_collection=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.

Methods

`__getitem__`
`__init__`	Create a Document, optionally providing a `LayerCollection` for layer 1.
`__setitem__`
`add`	Add a the content of a `LineCollection` to a given layer.
`bounds`	Compute bounds of the document.
`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 page size.
`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.
`rotate`	Rotate the Document's content..
`scale`	Scale the geometry.
`segment_count`	Returns the total number of segment across all lines.
`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.

Methods

Document.__getitem__(layer_id)

Document.__init__(line_collection=None, page_size=None)

Create a Document, optionally providing a LayerCollection for layer 1.

Parameters: line_collection (Optional[LineCollection]) -- if provided, used as layer 1

Document.__setitem__(layer_id, value)

Document.add(lc, layer_id=None)

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

If the given layer is None, the input LineCollection is used to create a new layer using the lowest available layer ID.

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.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()

Create an empty copy of this document with the same page size.

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

Parameters: layer_id (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().

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