2.2. compose – easy figure composing

compose module is a wrapper on top of svgutils.transform that simplifies composing SVG figures. Here is a short example of how a figure could be constructed:

Figure( "10cm", "5cm",
        SVG('svg_logo.svg').scale(0.2),
        Image(120, 120, 'lion.jpeg').move(120, 0)
      ).save('test.svg')

SVG definitions designed for easy SVG composing

Features:

  • allow for wildcard import

  • defines a mini language for SVG composing

  • short but readable names

  • easy nesting

  • method chaining

  • no boilerplate code (reading files, extracting objects from svg,

    transversing XML tree)

  • universal methods applicable to all element types

  • dont have to learn python

class svgutils.compose.Element(xml_element, defs=None)[source]

Base class for new SVG elements.

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
scale(factor) Scale SVG element.
tostr() String representation of the element
find_id(element_id)[source]

Find a single element with the given ID.

Parameters:

element_id : str

ID of the element to find
Returns:

found element
find_ids(element_ids)[source]

Find elements with given IDs.

Parameters:

element_ids : list of strings

list of IDs to find
Returns:

a new Panel object which contains all the found elements.
move(x, y)[source]

Move the element by x, y.

Parameters:

x,y : int, str

amount of horizontal and vertical shift

Notes

The x, y can be given with a unit (for example, “3px”, “5cm”). If no unit is given the user unit is assumed (“px”). In SVG all units are defined in relation to the user unit [R1].

[R1]W3C SVG specification: https://www.w3.org/TR/SVG/coords.html#Units
scale(factor)[source]

Scale SVG element.

Parameters:

factor : float

The scaling factor.

Factor > 1 scales up, factor < 1 scales down.
class svgutils.compose.Figure(width, height, *svgelements)[source]

Main figure class.

This should be always the top class of all the generated SVG figures.

Parameters:

width, height : float or str

Figure size. If unit is not given, user units (px) are assumed.

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
save(fname) Save figure to SVG file.
scale(factor) Scale SVG element.
tile(ncols, nrows) Automatically tile the panels of the figure.
tostr() String representation of the element
save(fname)[source]

Save figure to SVG file.

Parameters:

fname : str

Full path to file.
tile(ncols, nrows)[source]

Automatically tile the panels of the figure.

This will re-arranged all elements of the figure (first in the hierarchy) so that they will uniformly cover the figure area.

Parameters:

ncols, nrows : type

The number of columns and rows to arange the elements into.

Notes

ncols * nrows must be larger or equal to number of elements, otherwise some elements will go outside the figure borders.

class svgutils.compose.Grid(dx, dy, size=8)[source]

Line grid with coordinate labels to facilitate placement of new elements.

Parameters:

dx : float

Spacing between the vertical lines.

dy : float

Spacing between horizontal lines.

size : float or str

Font size of the labels.

Notes

This element is mainly useful for manual placement of the elements.

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
scale(factor) Scale SVG element.
tostr() String representation of the element
class svgutils.compose.Image(width, height, fname)[source]

Raster or vector image

Parameters:

width : float

height : float

image dimensions

fname : str

full path to the file

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
scale(factor) Scale SVG element.
tostr() String representation of the element
class svgutils.compose.Line(points, width=1, color='black')[source]

Line element connecting given points.

Parameters:

points : sequence of tuples

List of point x,y coordinates.

width : float, optional

Line width.

color : str, optional

Line color. Any of the HTML/CSS color definitions are allowed.

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
scale(factor) Scale SVG element.
tostr() String representation of the element
class svgutils.compose.Panel(*svgelements)[source]

Figure panel.

Panel is a group of elements that can be transformed together. Usually it relates to a labeled figure panel.

Parameters:

svgelements : objects derving from Element class

one or more elements that compose the panel

Notes

The grouped elements need to be properly arranged in scale and position.

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
scale(factor) Scale SVG element.
tostr() String representation of the element
class svgutils.compose.SVG(fname)[source]

SVG from file.

Parameters:

fname : str

full path to the file

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
scale(factor) Scale SVG element.
tostr() String representation of the element
class svgutils.compose.Text(text, x=None, y=None, **kwargs)[source]

Text element.

Parameters:

text : str

content

x, y : float or str

Text position. If unit is not given it will assume user units (px).

size : float, optional

Font size.

weight : str, optional

Font weight. It can be one of: normal, bold, bolder or lighter.

font : str, optional

Font family.

Methods

copy() Make a copy of the element
find_id(element_id) Find a single element with the given ID.
find_ids(element_ids) Find elements with given IDs.
move(x, y) Move the element by x, y.
moveto(x, y[, scale]) Move and scale element.
rotate(angle[, x, y]) Rotate element by given angle around given pivot.
scale(factor) Scale SVG element.
tostr() String representation of the element
class svgutils.compose.Unit(measure)[source]

Implementaiton of SVG units and conversions between them.

Parameters:

measure : str

value with unit (for example, ‘2cm’)

Methods

to(unit) Convert to a given unit.
to(unit)[source]

Convert to a given unit.

Parameters:

unit : str

Name of the unit to convert to.
Returns:

u : Unit

new Unit object with the requested unit and computed value.