Transformations

All of the functions presented under Shape construction and Copying objects accept an additional transform parameter. transform takes either a string representing an SVG transform (rotate, scale, etc.) or an inkex.Transform object and applies that transform to the object.

Example (original shape):

text('Transform', (canvas.width/2, canvas.height/2),
     font_family=['URW Bookman', 'serif'],
     font_weight='bold',
     font_size=24*pt,
     text_align='center',
     text_anchor='middle',
     fill='#003380')

Example (rotated then translated):

text('Transform', (canvas.width/2, canvas.height/2),
     transform='translate(%.5f, %.5f) rotate(-15, %.5f, %.5f)' % (30*pt, -12*pt, canvas.width/2, canvas.height/2),
     font_family=['URW Bookman', 'serif'],
     font_weight='bold',
     font_size=24*pt,
     text_align='center',
     text_anchor='middle',
     fill='#003380')

Example (same as above but using an inkex.Transform instead of a string):

tr = inkex.Transform()
tr.add_translate(30*pt, -12*pt)
tr.add_rotate(-15, canvas.width/2, canvas.height/2)
text('Transform', (canvas.width/2, canvas.height/2),
     transform=tr,
     font_family=['URW Bookman', 'serif'],
     font_weight='bold',
     font_size=24*pt,
     text_align='center',
     text_anchor='middle',
     fill='#003380')

Connector avoidance

All of the functions presented under Shape construction and Copying objects accept an additional conn_avoid parameter. conn_avoid takes a Boolean argument. If True, connectors created with connector will route around the shape. If False (the default), connectors will ignore the shape and route through it.

Example:

r1 = rect((100, 0), (150, 50), fill='#fff6d5')
r2 = rect((200, 400), (250, 450), fill='#fff6d5')
connector(r1, r2, ctype='orthogonal', curve=100)
circle((225, 225), 25, fill='red', conn_avoid=True)

Clipping paths

All of the functions presented under Shape construction and Copying objects accept an additional clip_path parameter, which specifies one or more objects to use as a clipping path. This object is normally created using the following function, also called clip_path:

Function: clip_path(obj, clip_units)

obj is an object or list of objects created using any of the Shape construction and Copying objects functions and that defines the shape of the clipping path. obj ceases being visible once passed to clip_path. The optional clip_units parameter must be either userSpaceOnUse (the default) or objectBoundingBox and specifies whether the coordinates used in obj should represent absolute coordinates or coordinates relative to the target object's bounding box, scaled to (0, 0)–(1, 1).

Example:

c = circle((200, 200), 225)
cp = clip_path(c)
rect((0, 0), (400, 400), clip_path=cp, stroke_width=20, fill='#ffcc00')

The preceding example clips a rectangle to a circular clipping path. The first line defines a circle, c. The second line converts c to a clipping path, cp. The third line draws a rectangle, specifying cp as its clipping path. As a result, only the parts of the rectangle that lie within c are visible.

For convenience, a shape function's clip_path parameter can accept a shape object that was not constructed using the clip_path function. In this case, the clip_path function will be invoked implicitly and with default arguments.

Masks

All of the functions presented under Shape construction and Copying objects accept an additional mask parameter, which specifies one or more objects to use as a transparency mask. A mask object is normally created using the following function, also called mask:

Function: mask(obj, mask_units)

obj is an object or list of objects created using any of the Shape construction and Copying objects functions and that defines the shape and transparency characteristics of the mask. obj ceases being visible once passed to mask. The optional mask_units parameter must be either userSpaceOnUse (the default) or objectBoundingBox and specifies whether the coordinates used in obj should represent absolute coordinates or coordinates relative to the target object's bounding box, scaled to (0, 0)–(1, 1).

Portions of a mask object that are colored white are fully opaque; portions of a mask object that are colored black are fully transparent; and grays lie in between.

Example:

rect((200, 200), (600, 600), stroke_width=20, fill='#00ccff')
c1 = circle((200, 200), 250, stroke='none', fill='white')
c2 = circle((200, 200), 200, stroke='none', fill='gray')
c3 = circle((200, 200), 100, stroke='none', fill='black')
circle_mask = mask(group([c1, c2, c3]))
rect((0, 0), (400, 400), mask=circle_mask, stroke_width=20, fill='#ffcc00')

The preceding example first draws an ordinary cyan rectangle in the background. It then constructs a mask composed of three circles. The outer circle is white, indicating full opacity. The middle circle is 50% gray, implying half transparency. The inner circle is black, indicating full transparency. Finally, a yellow rectangle using this mask and partially overlapping the cyan rectangle is created.

For convenience, a shape function's mask parameter can accept a shape object that was not constructed using the mask function. In this case, the mask function will be invoked implicitly and with default arguments.

Masks require Inkscape 1.2 or later.

Styles

Trailing key=value arguments passed to any of the functions presented under Shape construction and Copying objects are treated as style parameters. Use _ instead of - in key. For example, write stroke_width=2 to represent the SVG style stroke-width:2.

Example:

polyline([(64,128), (320,64), (384,128), (640, 64)],
         stroke='#005544',
         stroke_width=32,
         stroke_linecap='round',
         stroke_linejoin='round',
         stroke_dasharray=[32, 32, 64, 32])

Simple Inkscape Scripting is smart about converting Python data types to strings, which are the required type for SVG attributes. For example, in the preceding code, the integer 32 is converted automatically to the SVG string "32", and the list [32, 32, 64, 32] is converted automatically to the SVG string "32 32 64 32".