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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
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 [R114].

[R114]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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
tile(ncols, nrows) Automatically tile the panels of the figure.
tostr() Export SVG as a string
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.

tostr()[source]

Export SVG as a string

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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
tostr() String representation of the element
class svgutils.compose.MplFigure(fig, **kws)[source]

Matplotlib figure

Parameters:

fig : matplotlib Figure isinstanc

instance of Figure to be converted

kws :

keyword arguments passed to matplotlib’s savefig method

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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
tostr() String representation of the element
class svgutils.compose.SVG(fname=None)[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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
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.
scale_xy([x, y]) Scale element separately across the two axes x and y.
skew([x, y]) Skew the element by x and y degrees
skew_x(x) Skew element along the x-axis by the given angle.
skew_y(y) Skew element along the y-axis by the given angle.
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.