Simple Inkscape Scripting provides a few features, described here, for querying and controlling Inkscape's graphical user interface (GUI). Changes affect only the GUI and are not considered by SVG viewers—although they are saved to the SVG file.

Guides

Inkscape lets users include guide lines in a document. Guides facilitate precise alignment of objects by enabling points on objects to snap to guide lines. Simple Inkscape Scripting provides the following mechanisms for adding, removing, and modifying guides:

Variable: guides (type list)

guides is a list of all guides in the document. It is pre-populated with all guides present in the document at the time the invoking script was run. Guides can be added to or removed from the document—or even altered in place—by assigning to guides. Each element of guides is an object produced by the following function:

Function: guide((x, y), angle, color, label)

guide creates a new guide at position (x, y) and oriented angle degrees clockwise. If the optional color argument is provided, the guide is colored with the corresponding color instead of with Inkscape's default guide color. If the optional label argument is provided, the guide is labeled on-screen with that string. Guides are not automatically added to the document; they must be added explicitly by appending them to the guides list.

Example:

g1 = guide((0, 0), 10)
g2 = guide((canvas.width, canvas.height), 10, color='#00ff00', label='Bottom')
guides.extend([g1, g2])

The preceding example defines a guide g1 that intersects the upper-right corner of the document and is oriented 10° clockwise. It then defines a guide g2 that intersects the lower-right corner of the document and is also oriented 10° clockwise. While g1 is drawn in the default color and with no label, g2 specifies a pure-green color and a label of "Bottom". The final line of the example adds both g1 and g2 to the list of guides appearing in the document.

Once a guide is created (including those already appearing in the guides list), it can be read and modified using the following properties:

Property: position (type tuple)

position is an (x, y) tuple representing an arbitrary point on the guide line.

Property: angle (type float)

angle is the clockwise rotation in degrees of the guide line around its position coordinates.

Property: color (type str)

color is the guide line's color or None to indicate the default color.

Property: label (type str)

label is the guide line's textual label or None if no label was specified.

Grids

Inkscape lets users display one or more grids on the canvas to help with aligning objects. Simple Inkscape Scripting provides the following mechanisms for adding, removing, and modifying grids:

Variable: grids (type list)

grids is a list of all grids in the document. It is pre-populated with all grids present in the document at the time the invoking script was run. Grids can be added to or removed from the document—or even altered in place—by assigning to grids. Each element of grids is an object produced by the following function:

Function: grid(param=value, …)

grid creates a new grid based on a set of parameters. (See below.) Where a parameter is not specified, a default value is used. Grids are not automatically added to the document; they must be added explicitly by appending them to the grids list.

Objects created by grid support the following properties, which also can be used as parameters to grid when a grid is first created. All properties can be both read and written.

Property: type (type str)

type is the type of grid to display. It takes the following values:

• xygrid (default): a rectangular (Cartesian) grid
• axonomgrid: an axonometric grid
• modular: a modular grid

These grid types are illustrated below:

Property: spacing (type tuple)

This (x, y) tuple controls the distance between minor grid lines in the x and y dimensions. Each of x and y can be either a string comprising a length and a unit (e.g., "4mm") or a floating-point value (with an implicit unit of px). The spacing is expressed in terms of the document's viewport (physical dimensions), not its viewbox (logical dimensions). The default value for spacing is 1 document unit, where the document unit (a.k.a. display unit) is set in the Document Properties dialog box.

Property: major_freq (type int)

A major grid line is draw every major_freq minor grid lines.

Property: major_color (type inkex.Color)

Each major grid line is colored major_color, which can be either an inkex.Color or a type that is convertible to one (e.g., "green" or "#0099e5" or 0xff000040). A typical major_color contains some amount of transparency.

Property: minor_color (type inkex.Color)

Each minor grid line is colored minor_color, which can be either an inkex.Color or a type that is convertible to one (e.g., "green" or "#0099e5" or 0xff000040). A typical minor_color contains more transparency than the associated major_color.

Property: origin (type tuple)

A grid is offset by an (x, y) tuple specified by origin. Each of x and y can be either a string comprising a length and a unit (e.g., "2.5cm") or a floating-point value (with an implicit unit of px). The offset is expressed in terms of the document's viewport (physical dimensions), not its viewbox (logical dimensions). The default value for origin is (0, 0).

Property: draw_with (type str)

If draw_with is "lines" (the default), lines connect adjacent grid points. If draw_with is "dots", only the grid points themselves are rendered. draw_with has no effect on non-rectangular grids. (See the type property above.)

Property: snap (type str)

Inkscape does not always display all grid lines. Depending on the zoom level, minor and minor grid lines may be omitted from the view. snap controls snapping behavior as a function of grid-line visibility. If snap is "visible" (the default), objects snap only to visible grid lines. If snap is "all", objects snap to all grid lines.

Property: visible (type bool)

If visible is True, the grid is displayed overlaid on the background. If visible is False, the grid is not displayed. The default value for visible is True.

Property: enabled (type bool)

If enabled is True, the grid is enabled, meaning that objects will snap to the grid when snapping is turned on in the GUI. If enabled is False, the grid is kept in the document but is invisible and has no effect on object snapping.

Property: units (type str)

units indicates the units used to present the grid spacing and grid origin in the Inkscape GUI. It does not affect the grid itself.

In addition to the preceding properties, grid objects expose the following method:

Method: align_to_page(anchor)

As a convenient alternative to assigning origin directly, align_to_page aligns the grid such that a major grid line coincides with the given anchor position. anchor can be any one of the following strings:

• c or center. Align the grid with the page's center.
• ul or nw. Align the grid with the page's upper-left (northwest) corner.
• ur or ne. Align the grid with the page's upper-right (northeast) corner.
• ll or sw. Align the grid with the page's lower-left (southwest) corner.
• lr or se. Align the grid with the page's lower-right (southeast) corner.
• n. Align the grid with the page's top-center (north) point.
• e. Align the grid with the page's middle-right (east) point.
• s. Align the grid with the page's bottom-center (south) point.
• w. Align the grid with the page's middle-left (west) point.

Window attributes

Variable: gui (type SimpleUserInterface)

Inkscape-generated SVG files contain a <sodipodi:namedview> element that stores a variety of attributes related to the GUI window's color scheme and positioning. A Simple Inkscape Scripting script can access these attributes through the gui object, which provides a convenient dict-like interface.

While all attributes can be read, not all modifications to attribute values are honored by Inkscape. Furthermore, at least at the time of this writing, attempts to delete attributes are silently ignored.

Example:

for key, val in gui.items():
    print(f'{key}: {val}')

which outputs key-value pairs similar to these:

inkscape:deskcolor: #d1d1d1
inkscape:pagecheckerboard: 0
inkscape:showpageshadow: 2
inkscape:document-rotation: 0
inkscape:window-maximized: 1
inkscape:window-y: 0
inkscape:window-x: 0
inkscape:window-height: 1029
inkscape:window-width: 1920
showgrid: False
inkscape:current-layer: layer1
inkscape:document-units: px
inkscape:cy: 384
inkscape:cx: 512
inkscape:zoom: 1
inkscape:pageshadow: 2
inkscape:pageopacity: 0.0
borderopacity: 1.0
bordercolor: #666666
pagecolor: #ffffff
id: base

Example:

gui['inkscape:pagecheckerboard'] = 1
gui['inkscape:deskcolor'] = '#ffd0d0'
gui['pagecolor'] = 'yellow'
gui['bordercolor'] = 'green'