Simple Inkscape Scripting v5.3.0

This release of Simple Inkscape Scripting introduces a few handy features:

• All Simple Inkscape Scripting objects define a get_id method that returns the SVG ID of the underlying inkex object.
• An align function provides a flexible means of aligning objects à la Inkscape's Object → Align and Distribute… dialog box.
• The Simple Inkscape Scripting dialog box includes an "Ignore missing/broken Python packages" checkbox, which instructs Simple Inkscape Scripting to issue only a warning message upon failure to import NumPy and/or Pillow. Operations that require those packages will crash, but all other operations will run as normal.
• The translate method accepts a relocate argument, which can be used to rewrite the object's coordinates rather than apply a transformation matrix.

A few nasty bugs have been squashed as well.

See the Simple Inkscape Scripting commit log for details of all of the above. Also, a PDF version of the complete online documentation is provided as a release asset named sis-docs.pdf.

Simple Inkscape Scripting v5.2.0

This release of Simple Inkscape Scripting introduces a number of (I hope) useful features:

• Page objects, such as those created by page or retrieved using all_pages, expose an all_shapes method, which can return either all shapes that intersect the page or all shapes fully contained by the page.
• Characteristics of Inkscape's user interface can be queried and modified using the gui object.
• Rectangular, axonometric, and modular grids can be added to the document. Grids also can be removed and modified.
• The top-level all_shapes function now truly returns all shapes in the document, including those not created by the user's script.
• An all_layers function returns a list of all layers in the document.

In addition, get_parent should behave as expected when invoked on an object not created by the user's script.

See the Simple Inkscape Scripting commit log for details of all of the above. Also, a PDF version of the complete online documentation is provided as a release asset named sis-docs.pdf.

Simple Inkscape Scripting v5.1.0

This is a minor release of Simple Inkscape Scripting which provides a number of small improvements relative to the last major release:

• repr produces meaningful output for all Simple Inkscape Scripting objects.
• Even images specified by URL can be embedded in a document. Previously, only local files could be embedded.
• A new example, examples/pixels_to_rectangles.py, shows how to call the Python Imaging Library from within a Simple Inkscape Scripting script.
• The extension has been made compatible with Inkscape versions up to 1.5.
• Support is provided for using Simple Inkscape Scripting functions and classes in other extensions. See the new Derived Extensions wiki page.

There is also one very small breaking change:

• The second argument to shape-transformation methods rotate, scale, and skew is now called anchor instead of around.

Because the documentation has always referred to this argument as anchor, I'm considering the correction to the code a minor change rather than a major change.

See the Simple Inkscape Scripting commit log for details of all of the above.

Simple Inkscape Scripting v5.0.0

This is a major new release of Simple Inkscape Scripting. It includes only one—very small—breaking change plus a lot of new features and other improvements.

Breaking change: ungroup applies the group's transform to each ungrouped object.
Reason: Retaining an object's appearance when it is ungrouped matches Inkscape's behavior and should be more intuitive.
Replacement: Pass preserve_transform=False as the final argument to ungroup to recover the pre-v5.0.0 behavior.

In addition to the above and the usual sorts of bug fixes, Simple Inkscape Scripting v5.0.0 provides a long list of new features:

• Foreign XML can be included in an SVG file with the foreign function. This enables, for instance, the embedding of arbitrary HTML within an SVG document.
• Document metadata (title, author, copyright, description, etc.) can be both read and written via the metadata variable.
• A script can query its own filename with the script_filename variable.
• Guides can be assigned labels. Labels of existing guides can be read and modified.
• Inkscape actions can be invoked from a script using the apply_action function. Most operations the Inkscape GUI can perform are backed by an action, making apply_action a very powerful addition to Simple Inkscape Scripting. Run inkscape --action-list for a list of available actions.
• A specialization of apply_action called apply_path_operation simplifies the invocation of path operations such as path union, path intersection, and path difference.
• As a convenience, +, -, *, ^, /, and // can be applied to path objects to perform respectively path union, path difference, path intersection, path exclusion, path division, and path cut.
• Simple Inkscape Scripting has been updated to work with Inkscape 1.3.
• When saving an SVG document to a Simple Inkscape Scripting script, paths are written in terms of inkex PathCommands instead of strings. That is, instead of

path(['M', 8.7, 4.0, 'L', -2.2, 0.02, 'L', 8.7, -4.0, 'C', 7.0, -1.6, 7.0, 1.6, 8.7, 4.0, 'z'])

the generated script will contain

path([Move(8.7, 4.0), Line(-2.2, 0.02), Line(8.7, -4.0), Curve(7.0, -1.6, 7.0, 1.6, 8.7, 4.0), zoneClose()])

• Transformation methods (translate, rotate, scale, and skew) can be chained. Thus,

my_shape.scale(1.5, 'ul')
my_shape.rotate(14, 'c')

can be written more tersely as

my_shape.scale(1.5, 'ul').rotate(14, 'c')

• Transformation methods accept nw, ne, se, and sw as synonyms for the anchor points ul, ur, lr, and ll, respectively. Additional anchor points n, e, s, and w are supported.
• The to_path method now works on text objects.
• A new z_sort function sorts a list of Simple Inkscape Scripting objects by increasing Z-order.
• A shape's parent object (group or layer) can be retrieved with the get_parent method.

See the Simple Inkscape Scripting commit log for details of all of the above.

Simple Inkscape Scripting v4.0.0

This is a major new release of Simple Inkscape Scripting. It includes two changes that break existing code but that provide improved functionality:

Change #1: width and height are no longer defined.
Replacement: Use canvas.width and canvas.height.
Reason: canvas.width and canvas.height not only are readable but also are writable, which is not achievable in Python with top-level variables.

Change #2: Group objects (as returned by group or layer) no longer define an add method.
Replacement: Use append for a single addition or extend for a list of additions.
Reason: Group objects now honor a rich set of standard list operations (append, extend, pop, len, etc.).

In addition to the above and the usual sorts of bug fixes, Simple Inkscape Scripting v4.0.0 provides a long list of new features:

• The image function can embed SVG files, not just PNG and JPEG files, as images.
• An objects_from_svg_file function merges SVG objects from another document into the current document.
• The ungroup method returns a list of objects that were released from the group.
• The clip_path and mask functions accept a list of objects in addition to a single object.
• Scripts can accept command-line arguments, provided via the user_args variable.
• The Simple Inkscape Scripting extension itself (an inkex.extensions.EffectExtension object) is accessible as extension.
• Path objects support translate_path, rotate_path, scale_path, and skew_path methods, which modify the path's control points themselves.
• An unremove method re-adds to the document an object that was removed with remove.
• The save_file function saves the current document to an SVG file.
• Two Simple Inkscape Scripting objects are considered equal if they share an underlying inkex object.
• The Simple Inkscape Scripting dialog box lets the user specify the input-file encoding (currently system-default, UTF-8, UTF-16, or Windows-1252).
• The font_family style attribute accepts not only a single string but also a list of strings. Hence, font_family='"New Century Schoolbook", "Times New Roman", serif' can be expressed more naturally as font_family=['New Century Schoolbook', 'Times New Roman', 'serif'].
• A new canvas object supports querying and modifying the canvas's viewport (physical size) and viewbox (coordinate system).
• Multi-page documents can be created in Inkscape 1.2+ using the page command.
• The all_pages function returns a list of all pages in the document.
• An inkex.colors.Color can be used directly in a style attribute (typically fill and stroke).
• The randcolor function returns a random color. Color channels optionally can be constrained to particular values.

See the Simple Inkscape Scripting commit log for details of all of the above.

Simple Inkscape Scripting v3.2.0

Here's what's noteworthy in this release of Simple Inkscape Scripting:

• accurate bounding-box calculations for text and images,
• support by all shape constructors for applying a transparency mask,
• the ability to remove and group SVG objects converted to Simple Inkscape Scripting objects with all_shapes, selected_shapes, or inkex_object,
• an auto_region parameter to filter_effect that selects between automatic and manually specified filter regions,
• code restructuring to support Visual Studio Code integration (see #55),
• improved compatibility across past, current, and forthcoming versions of Inkscape, and
• multiple code improvements and bug fixes.

See the Simple Inkscape Scripting commit log for details of all of the above.

Simple Inkscape Scripting v3.1.0

The main feature introduced in this minor release is support for creating and modifying Inkscape guides. In addition, scripts can now safely invoke sys.exit if they want to terminate prematurely.

Simple Inkscape Scripting v3.0.0

This is a long overdue, major release of Simple Inkscape Scripting. It includes a large number of changes, a few of which are breaking changes and may require modifications to existing scripts.

• The extension is now compatible with Inkscape 1.2-dev.

• The text_path.py example no longer includes UTF-8-encoded characters because these confuse Windows, which expects Windows-1252 or some other non-standard encoding.

• Objects can be removed by invoking their remove method (analogous to Inkscape's Edit → Delete).

• Objects can be ungrouped by invoking ungroup on their containing group (analogous to Inkscape's Object → Ungroup).

• Shape objects provide a to_path method that converts them to a path (analogous to Inkscape's Path → Object to Path).

• Simple Inkscape Scripting objects provide a get_inkex_object method that returns the underlying inkex object, which can be used for low-level SVG manipulation.

• A duplicate method creates an independent copy of an object (analogous to Inkscape's Edit → Duplicate).

• push_defaults and pop_defaults methods save and restore the current default transform and style.

• A shape's style can be read and modified via the style method.

• Inkscape live path effects (LPEs) can be instantiated using the path_effect function and applied to a path using the apply_path_effect method.

• Objects created by Simple Inkscape Scripting no longer are grouped automatically but rather are applied individually to the canvas as one would expect.

• Existing objects can more easily be modified using transform, rotate, scale, and skew methods.

• For debugging, an svg method returns an object's underlying SVG code as a string.

• Filters (analogous to Inkscape's Filters) can be created using the filter_effect function and applied to an object using its filter attribute.

• Paths can be reversed using the reverse method (analogous to Inkscape's Path → Reverse).

• Paths can be appended using the append method, which can be used for cutting holes in closed paths.

• Objects can be reordered within their group or layer by invoking their z_order method (analogous to Inkscape's Object → Raise to Top, Raise, Lower, and Lower to Bottom).

• An object's underlying SVG element's tag (e.g., circle or g or image) can be retrieved using the tag method.

• Attributes of an underlying SVG object can be read with the svg_get and written with the svg_set method.

• Existing shapes on a canvas can be retrieved using the all_shapes and selected_shapes functions.

• A number of unit tests are defined and scheduled to run automatically via GitHub Actions on each push to the repository.

• The more_text function has been replaced by an add_text method on text objects.

Simple Inkscape Scripting v2.1.0

Simple Inkscape Scripting has added a lot of nice, new features since the previous release. Here's what you can look forward to if you upgrade:

• Clipping paths can be applied to objects.

• Transformations can be applied/modified after object creation.

• Objects can be animated. (Inkscape doesn't display SVG animations, but most Web browsers do.)

• Objects can be converted to definitions. This is useful for creating template objects then instantiating (cloning) them with different transformations applied.

• Markers (e.g., arrowheads) can be created and applied to paths.

• Objects can be made into hyperlinks that can be followed when the SVG image is viewed in a Web browser.

• Pre-defined conversion constants px, mm, cm, pt, and inch are provided to facilitate the use of absolute sizes and distances.

Simple Inkscape Scripting v2.0.0

This is a major new release of Simple Inkscape Scripting. You'll definitely want to upgrade to pick up all the exciting new features!

Breaking API changes

The API has been made more consistent in terms of scalar versus tuple/list arguments. Items serving the same purpose are now consistently 2-tuples (for two of the same item) or lists (for varying numbers of items). For example, x and y radii are now specified as a single tuple, and lists of coordinates are now specified as a list rather than as an arbitrary number of individual arguments. These changes affect, in particular, ellipse, polyline, polygon, arc, and path. Please update your existing Simple Inkscape Scripting scripts accordingly.

For convenience, arc accepts a scalar radius as a shorthand for a tuple containing two of the same radii; and path can accept a single string in addition to a list of terms, as the former may be helpful when copying and pasting from an existing SVG path string.

Other improvements

There are a lot these. Look at all the good things you get when you upgrade to Simple Inkscape Scripting v2.0.0:

• The distribution includes an output extension that lets you save an SVG image as a Simple Inkscape Scripting script. Go to File → Save a Copy… and select Simple Inkscape Scripting script (*.py) from the pull-down menu.

• SVG filter effects can be defined using the new filter function.

• All Simple Inkscape Scripting shape objects provide a new bounding_box method.

• rect can additionally draw rounded rectangles.

• Simple Inkscape Scripting objects define a Python __str__ method that converts them to a string of the form url(#object-id). This enables them to be used as style values (which are automatically converted to strings). For example, text can be flowed into a frame with shape_inside=frame object.

• text accepts an optional path argument that typesets the text along a path.

• New linear_gradient and radial_gradient functions (and the corresponding add_stop method) support the creation of gradient patterns, which can be used as arguments to fill and stroke.

• Scripts no longer need to declare their own functions as global in order to invoke them.

• Simple Inkscape Scripting's print statement has been redefined to accept multiple arguments, just like Python's built-in print statement.

• For advanced users, the root of the SVG XML tree is made available via an svg_root variable.

• Layers can be created with the new layer function.

• The add method on group- and layer-produced objects accepts a list of objects in addition to a single object.

• All of inkex.paths is imported into the script's namespace. This provides convenient access to path-element constructors such as Move, Line, and Curve.

• Transform from inkex.transforms is imported into the script's namespace. This provides a rich mechanism for manipulating object transformations. Transform objects can be used as a shape-creation function's transform parameter.

Whew! More examples are included in the examples/ directory to demonstrate usage of these new features. There are also myriad improvements to the Simple Inkscape Scripting code itself, making it cleaner and more robust, but that are not visible to users.