inkext.inksvg

A simple library for SVG output - but more Inkscape-centric.

class inkext.inksvg.InkscapeSVGContext(document: TDocument)

SVG Context with Inkscape-specific methods.

create_layer(layer_name: str, opacity: float | None = None, clear: bool = True, incr_suffix: bool = False, flipy: bool = False, tag: str | None = None, parent: TElement | None = None) → TElement

Create an Inkscape layer or return an existing layer.

Parameters:

  • layer_name – The name of the layer to create.

  • opacity – Layer opacity (0.0 to 1.0).

  • clear – If a layer of the same name already exists then erase it first if True otherwise just return it. Default is True.

  • incr_suffix – If a layer of the same name already exists and it is non-empty then add an auto-incrementing numeric suffix to the name (overrides clear).

  • flipy – Add transform to flip Y axis.

  • tag – A layer tag added as an extended attribute. Uses utlco namespace. This can be used to tag layers with a custom label.

  • parent – An optional parent element to append the new layer.

Returns:

A new layer or an existing layer of the same name.

find(path: str) → TElement | None

Find an element in the current document.

Parameters:

path – XPath path.

Returns:

The first matching element or None if not found.

find_layer(layer_name: str) → TElement | None

Find an Inkscape layer by Inkscape layer name.

If there is more than one layer by that name then just the first one will be returned.

Parameters:

layer_name – The Inkscape layer name to find.

Returns:

The layer Element node or None.

get_document_name() → str

Return the name of this document. Default is ‘untitled’.

get_layer_elements(layer: TElement) → list[TElement]

Get document elements by layer.

Returns all the visible child elements of the given layer.

Parameters:

layer – The layer root element.

Returns:

A (possibly empty) list of visible elements.

get_layer_name(layer: TElement) → str | None

Return the name of the Inkscape layer.

get_parent_layer(node: TElement) → TElement | None

Get the layer that the node resides in.

Returns:

A layer, or None if the node is not in a layer.

get_shape_elements(elements: Iterable[TElement] | None = None, shapetags: Iterable[str] = ('path', 'rect', 'line', 'circle', 'ellipse', 'polyline', 'polygon'), parent_transform: tuple | None = None, skip_layers: list[str] | None = None, accumulate_transform: bool = True) → list[tuple[TElement, geom2d.TMatrix | None]]

Get all shape elements in an element tree.

Traverse a tree of SVG nodes and flatten it to a list of tuples containing an SVG shape element and its accumulated transform.

This does a depth-first traversal of <g> and <use> elements.

Hidden elements are ignored.

Parameters:

  • elements – An iterable collection of element nodes. This will be all top level elements (docroot) by default.

  • shapetags – List of shape element tags that can be fetched. Default is (‘path’, ‘rect’, ‘line’, ‘circle’, ‘ellipse’, ‘polyline’, ‘polygon’). Anything else is ignored.

  • parent_transform – Transform matrix to add to each node’s transforms. If None the node’s parent transform (if any) is used.

  • skip_layers – A list of layer names (as regexes) to ignore

  • accumulate_transform – Apply parent transform(s) to element node if True. Default is True.

Returns:

A possibly empty list of 2-tuples consisting of SVG element and accumulated transform.

get_shape_elements_layers(elements: Iterable[TElement] | None = None, shapetags: Iterable[str] = ('path', 'rect', 'line', 'circle', 'ellipse', 'polyline', 'polygon'), parent_transform: tuple | None = None, skip_layers: list[str] | None = None, accumulate_transform: bool = True) → list[list[tuple[TElement, geom2d.TMatrix | None]]]

Get all shape elements in an element tree.

Separate top-level layers into an array of layer sub-elements.

Traverse a tree of SVG nodes and flatten it to a list of tuples containing an SVG shape element and its accumulated transform.

This does a depth-first traversal of <g> and <use> elements.

Hidden elements are ignored.

Parameters:

  • elements – An iterable collection of element nodes. This will be all top level elements (docroot) by default.

  • shapetags – List of shape element tags that can be fetched. Default is (‘path’, ‘rect’, ‘line’, ‘circle’, ‘ellipse’, ‘polyline’, ‘polygon’). Anything else is ignored.

  • parent_transform – Transform matrix to add to each node’s transforms. If None the node’s parent transform (if any) is used.

  • skip_layers – A list of layer names (as regexes) to ignore

  • accumulate_transform – Apply parent transform(s) to element node if True. Default is True.

Returns:

A possibly empty list of 2-tuples consisting of SVG element and accumulated transform.

get_visible_layers() → list[TElement]

Get a list of visible layers.

is_layer(node: TElement) → bool

Determine if the element is an Inkscape layer node.

layer_is_locked(layer: TElement) → bool

Check if the layer is locked.

margin_cliprect(mtop: float, *args: float) → Box

Create a clipping rectangle for document margins.

Margin argument order follows CSS margin property rules.

Parameters:

  • mtop – Top margin (user units)

  • *args – Optional right, bottom, and left margins. By default right, bottom, and left margins will be set to top value. If right is specified then by default left is set to right value.

Returns:

A geom2d.Box clipping rectangle

set_document_background(color: str) → None

Set the document background color.

Parameters:

color (string) – A CSS color (ie. ‘#ffffff’)

set_layer_name(layer: TElement, name: str) → None

Rename an Inkscape layer.

inkext.inksvg.create_inkscape_document(width: float, height: float, doc_units: str = 'px', doc_id: str | None = None, doc_name: str | None = None, layer_name: str | None = None, layer_id: str = 'defaultlayer') → TDocument

Create a minimal Inkscape-compatible SVG document.

Parameters:

  • width – The width of the document.

  • height – The height of the document.

  • doc_units – The document unit type (i.e. ‘in’, ‘mm’, ‘pt’, ‘em’, etc.) By default this will be ‘px’.

  • doc_id – The id attribute of the enclosing svg element. If None (default) then a random id will be generated.

  • doc_name – The name of the document (i.e. ‘MyDrawing.svg’).

  • layer_name – Display name of default layer. By default no default layer will be created.

  • layer_id – Id attribute value of default layer. Default id is ‘defaultlayer’.

Returns:

An lxml.etree.ElementTree

inkext.inksvg.inkscape_ns(tag: str) → str

Prepend the inkscape namespace to an element tag.

inkext.inksvg.sodipodi_ns(tag: str) → str

Prepend the sodipodi namespace to an element tag.

inkext.inksvg.utlco_ns(tag: str) → str

Prepend the utlco namespace to an element tag.