Document layout
In addition to creating and modifying objects, Simple Inkscape Scripting also can modify the document structure itself.
SVG relies on two mechanisms for describing the size of the drawing canvas. The first, called the viewport, specifies the natural size at which to display the document. (The user may zoom in or out, but the viewport indicates the 100% zoom size.) The viewport corresponds to the Width and Height fields in the File → Document Properties… dialog's Display tab in Inkscape 1.2+ or the Page tab in earlier versions of Inkscape. For example, the viewport might specify a document of size 22.9cm×16.2cm.
The second mechanism, called the viewbox and labeled as such in Inkscape's document properties, defines the bounds of the canvas. It is defined in terms of four, unitless numbers: left, top, width, and height. Coordinates to the left of left, to the right of left + width, above top, or below top + height lie out of bounds—regardless of the viewport size.
Together, the viewport and viewbox answer the question, "How big is 1
unit when rendered?" For instance, if the viewport is 85mm×55mm and
the viewbox is 0 0 85 55 then "1" in user coordinates implies 1mm. Hence, the Simple Inkscape Scripting command rect((0, 0), (1, 1), stroke_width=1*pt) (see Rectangles) draws a 1mm×1mm square in the upper-left corner of the canvas. If the viewbox were instead -42 -27 85 55 then the same command would draw the square at the same size but centered on the canvas. If the viewbox were 0 0 8.5 5.5 then "1" would imply 10mm. Hence, the same rect command would draw the square ten times larger in each dimension.
In Simple Inkscape Scripting, the canvas variable's true_width and true_height properties correspond to the viewport, and the canvas variable's width and height properties correspond to the viewbox. These, and related properties and methods, are described below.
Variable: canvas (type SimpleCanvas)
canvas provides access to the document's dimensions, both viewbox and viewport.
The following all work with user coordinates, which are unitless numbers.
Property: width (type float)
Property: height (type float)
The width and height in user coordinates of the canvas can be retrieved and modified via the width and height properties.
Property: viewbox (type [float])
The viewbox property represents the canvas's viewbox as a list of four floats: [ left, top, width, height ]. When viewbox is read, it will always take that form. When viewbox is written, it must be given either a list of four floats, a string of four space-separated floats, or an inkex.transforms.BoundingBox.
Method: bounding_box()
To facilitate positioning on the canvas of shape objects, the bounding_box method returns the viewbox as an inkex.transforms.BoundingBox, which provides access to width, height, top, left, bottom, right, center_x, center_y, and other properties.
Property: true_width (type float or str)
Property: true_height (type float or str)
The size of the document as it should be displayed in a web browser or other viewer is determined by true_width and true_height. When read, these values are returned in units of pixels (1/96" or 0.265mm). When written, they accept either a float, indicating pixels, or a string comprising a number and a unit. Hence the number 472.4 and the string '12.5cm' indicate the same width (or height).
Method: get_size_by_name(name, landscape)
As a convenience for determining common values to assign to true_width and true_height, get_size_by_name maps a named viewport size to a (width, height) tuple, with each element measured in pixels. If landscape is False (the default), the method returns portrait-mode dimensions (width ≤ height). If landscape is True, the method returns landscape-mode dimensions (width ≥ height). At the time of this writing, the following values are accepted for name:
| Name | Width | Height |
|---|---|---|
A0 |
841mm | 1189mm |
A1 |
594mm | 841mm |
A2 |
420mm | 594mm |
A3 |
297mm | 420mm |
A4 |
210mm | 297mm |
A5 |
148mm | 210mm |
A6 |
105mm | 148mm |
A7 |
74mm | 105mm |
A8 |
52mm | 74mm |
A9 |
37mm | 52mm |
US Letter |
8.5in | 11in |
US Legal |
8.5in | 14in |
Ledger/Tabloid |
11in | 17in |
Video HD 720p |
720px | 1280px |
Video HD 1080p |
1080px | 1920px |
Video UHD 4k |
2160px | 3840px |
Video UHD 8k |
4320px | 7680px |
Method: resize_by_name(name, landscape)
resize_by_name resizes the canvas to the named size (see get_size_by_name above), setting true_width and true_height accordingly then adjusting the viewbox to place the origin at (0, 0) and set a 1:1 scale between user coordinates and pixels. For example, canvas.resize_by_name('A7', True) is shorthand for
canvas.true_width = '105mm'
canvas.true_height = '74mm'
canvas.viewbox = [0, 0, 396.850, 279.685]Method: resize_to_content([obj, …])
This method scales and translates the viewbox to fit exactly the given shape object or list of shape objects. If no argument is provided, resize_to_content resizes the viewbox to fit all shape objects in the document. Once the viewbox is translated and scaled, the method proportionally scales the viewport.
As an example, set the canvas to have a viewport of 20cm×15cm and a viewbox of 0 0 1000 750. Then execute the following script, which draws a set of objects whose upper-left point lies at (100, 100) and lower-right point lies at (400, 400).
suppose that the canvas originally has a viewport of 20cm×15cm and a viewbox of 0 0 1000 750. If resize_to_content is invoked on a set of objects whose upper-left point lies at (100, 100) and lower-right point lies at (400, 400), the result will be a viewport of 6cm×6cm and a viewbox of 100 100 300 300.
Example:
r1 = rect((100, 100), (200, 200), fill='firebrick', stroke_width='6pt')
r2 = rect((300, 150), (400, 250), fill='gold', stroke_width='6pt')
r3 = rect((200, 300), (300, 400), fill='royalblue', stroke_width='6pt')
canvas.resize_to_content([r1, r2, r3])
Unlike Inkscape's Resize to content button (found in the File → Document Properties… dialog), resize_to_content does not
- translate the viewbox so that its origin lies at (0, 0) or
- take stroke widths or filter effects into consideration.
As can be seen in the example output above, edges on the viewbox border have strokes that straddle the viewbox and therefore are rendered only partially.
As of version 1.2, Inkscape supports the creation of multi-page documents. A page is merely a viewbox-like region that may or may not coincide with the document's viewbox. When a multi-page Inkscape SVG file is viewed in a web browser, only the part of the image lying within the document's viewbox is visible, as normal. However, when Inkscape is instructed to print a multi-page SVG file, it uses the page viewboxes to determine the content to print on each page.
Function: page(name, pos, size)
Pages are created using the page function. All arguments are optional. name assigns a name to the page, which is displayed in Inkscape when the page is selected using the Pages tool. By default, no name is assigned. pos is an (x, y) tuple that specifies the upper-left corner of the new page. It defaults to the upper right corner of the previous page (thereby laying out pages horizontally left-to-right) or the viewbox's (left, top) position if there is no previous page. size is a tuple that specifies the horizontal and vertical dimensions of the new page in (unitless) user coordinates. It defaults to the viewbox's (width, height) size. The page function refers to a Simple Inkscape Scripting object that provides the following properties and methods. All properties are read-only.
Property: viewbox (type [float])
The viewbox property returns a list of four floats: [ left, top, width, height ]. It is in fact the concatenation of page's pos and size arguments into a list.
Property: width (type float)
Property: height (type float)
These properties represent the width and height of the page, i.e., size[0] and size[1].
Method: bounding_box()
The bounding_box method returns the pages position and size as an inkex.transforms.BoundingBox, which provides properties that name various positions on the page (left, right, horizontal center, etc.).
The following example first sets the canvas to the size of an A6 sheet of paper. It then creates a 2×2 grid of A6 pages named respectively "1", "2", "3", and "4". The first page exactly matches the canvas. Hence, if the resulting document is viewed in a web browser, only the first page is visible. However, if the document is printed from Inkscape or saved to PDF using File → Save a Copy…, all four pages will appear.
Example:
import string
canvas.resize_by_name('A6')
style(font_family=['DejaVu Serif', 'serif'], font_weight='bold', font_size='200pt', text_anchor='middle', fill='#330080')
for y in range(2):
for x in range(2):
i = y*2 + x
pg = page(i + 1, (x*canvas.width, y*canvas.height))
bbox = pg.bounding_box()
text(string.ascii_uppercase[i], (bbox.center_x, bbox.center_y + 72*pt))
Function: all_pages()
The all_pages function returns a list of all pages in the document as Simple Inkscape Scripting objects, regardless of how they originally were created.