Running

Python code to Inkscape

This represents ordinary Simple Inkscape Scripting usage. Launch the Simple Inkscape Scripting extension from Inkscape via Extensions → Render → Simple Inkscape Scripting…. This will bring up a dialog box that gives you the option to enter a filename for a Python program or enter Python code directly in a text box:

The filename and direct-code options are not mutually exclusive; if both are used, the Python code in the file will be executed first, followed by the Python code in the text box. This enables one, for example, to define functions in a file and invoke them with different parameters from the text box.

If Python complains about bad bytes in the input, this may imply that your script was written using a different character encoding from your operating system's native encoding. The "Input encoding" combo box can be used to tell Simple Inkscape Scripting explicitly what character encoding to use.

Simple Inkscape Scripting imports two common Python packages that are neither provided by Inkscape nor are Python base packages: NumPy and Pillow. If Simple Inkscape Scripting complains about import errors, these packages should be installed with pip. The following are typical installation commands:

python -m pip uninstall PIL
python -m pip install --upgrade numpy pillow

(The PIL package is obsolete. Pillow is a drop-in replacement and is even imported as "PIL".) If you have more than one version of Python installed, be sure to run the same python executable that Inkscape uses!

As a last resort, marking the "Ignore missing/broken Python packages" checkbox instructs Simple Inkscape Scripting to issue only a warning message upon failure to import NumPy and/or Pillow. Simple Inkscape Scripting features that require NumPy (e.g., transformations) or Pillow (e.g., images) will throw an exception when used, but other features remain available.

Inkscape to Python code

Simple Inkscape Scripting can also save illustrations from the Inkscape GUI to a Python script that, when run from the Simple Inkscape Scripting extension, reproduces the original illustration. (Note, though, that not all Inkscape features are currently supported.) From File → Save a Copy…, simply select Simple Inkscape Scripting script (*.py) from the pull-down menu at the bottom of the dialog box. This can be useful, for instance, for manually drawing a complex object then using Simple Inkscape Scripting to replicate and transform it.

Command-line execution

Simple Inkscape Scripting, like any Inkscape extension, can be run from the command line, not just from the Inkscape GUI:

$ python ./simpinkscr/simple_inkscape_scripting.py --help
usage: simple_inkscape_scripting.py [-h] [--output OUTPUT] [--tab TAB]
                                    [--program PROGRAM]
                                    [--py-source PY_SOURCE]
                                    [--encoding ENCODING]
                                    [--import-workaround IMPORT_WORKAROUND]
                                    [--id IDS]
                                    [--selected-nodes SELECTED_NODES]
                                    [INPUT_FILE] [USER_ARGS ...]

Help the user create Inkscape objects with a simple API.

positional arguments:
  INPUT_FILE            Filename of the input file or "-" for stdin (default
                        is stdin)
  USER_ARGS             Additional arguments to pass to Python code via the
                        user_args global variable

options:
  -h, --help            show this help message and exit
  --output OUTPUT       Optional output filename for saving the result
                        (default is stdout).
  --tab TAB             The selected UI tab when OK was pressed
  --program PROGRAM     Python code to execute
  --py-source PY_SOURCE
                        Python source file to execute
  --encoding ENCODING   Character encoding for input code
  --import-workaround IMPORT_WORKAROUND
                        Ignore numpy and PIL import errors
  --id IDS              id attribute of object to manipulate
  --selected-nodes SELECTED_NODES
                        id:subpath:position of selected nodes, if any

If you receive a ModuleNotFoundError: No module named 'inkex' error, you may need to add the Inkscape extensions directory to your PYTHONPATH, e.g., via

export PYTHONPATH="/usr/share/inkscape/extensions:$PYTHONPATH"

As a basic example, the following command applies the code in my-script.py to input.svg to produce output.svg:

python "$SISDIR/simple_inkscape_scripting.py" --py-source=my-script.py --output=output.svg input.svg

(where SISDIR may be something like $HOME/.config/inkscape/extensions/simple_inkscape_scripting/simpinkscr).

Script-specific arguments can be included on the command line after the name of the input file. These are made available to scripts via the user_args global variable, which is a list of strings.

Variable: user_args (type [string])

As an example, the following script accepts a width, a height, and a color and draws a rectangle of the specified size and color:

wd, ht = float(user_args[0]), float(user_args[1])
clr = user_args[2]
rect((0, 0), (wd, ht), fill=clr)

This script might be run as follows:

python "$SISDIR/simple_inkscape_scripting.py" --py-source=draw-rect.py --output=red-rect.svg /usr/share/inkscape/templates/default.svg 50 40 red

As a more sophisticated example, the following script uses Python's argparse module to parse the script-specific arguments and supports a default value for each option:

import argparse

# Parse the command line.
parser = argparse.ArgumentParser()
parser.add_argument('--shape', choices=['square', 'circle'], default='square')
parser.add_argument('--size', type=float, default=100)
parser.add_argument('--color', default='#008000')
args = parser.parse_args(user_args)

# Draw either a square or a circle.
style(fill=args.color)
sz = args.size
if args.shape == 'square':
    rect((0, 0), (sz, sz))
elif args.shape == 'circle':
    circle((sz/2, sz/2), sz/2)
else:
    raise ValueError(f'unknown shape {args.shape}')

Note that parser.parse_args is passed user_args. Otherwise, it would attempt to parse the entire command line, not just the script-specific subset.

One might run the preceding script as follows:

python "$SISDIR/simple_inkscape_scripting.py" --py-source=draw-shape.py --output=orange-circle.svg /usr/share/inkscape/templates/default.svg -- --shape=circle --size=120 --color='#ff8040'

Note the use of -- to separate the script-specific arguments from the arguments intended for processing by Simple Inkscape Scripting.

Caveat: If script-specific arguments are provided but an input file is not (because it will be read from the standard input device), Simple Inkscape Scripting will mistake the first script-specific argument for the filename. In this case, - should be used as the name of the input file to indicate explicitly that input is provided via standard input. The following command is equivalent to the previous but reads from standard input instead of from a named file:

cat /usr/share/inkscape/templates/default.svg | python "$SISDIR/simple_inkscape_scripting.py" --py-source=draw-shape.py --output=orange-circle.svg - -- --shape=circle --size=120 --color='#ff8040'

Visual Studio Code

Visual Studio Code can be used to construct and execute Simple Inkscape Scripting scripts and even supports IntelliSense. Configure your environment by ensuring that the Python interpreter that Visual Studio Code launches knows how to find Simple Inkscape Scripting and Inkscape's inkex module. In Linux, this can be achieved with a shell command like,

export PYTHONPATH="$HOME/.config/inkscape/extensions/simple_inkscape_scripting:/usr/share/inkscape/extensions:$PYTHONPATH"

An OS-independent alternative would be to install an additional copy of Simple Inkscape Scripting directly into Python's package directory:

pip install git+https://github.com/spakin/SimpInkScr#egg=simpinkscr

To run Simple Inkscape Scripting scripts directly from the Visual Studio Code run icons or menu items, add a launch.json configuration like the following to your workspace (Run → Add Configuration… → Python File):

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "/home/user/.config/inkscape/extensions/SimpInkScr/simpinkscr/simple_inkscape_scripting.py",
            "args": ["--py-source=${file}", "--output=/home/user/my-output.svg", "/home/user/.config/inkscape/templates/default.svg"],
            "console": "integratedTerminal",
            "justMyCode": true
        }
    ]
}

Be sure to edit program and args appropriately.

Python scripts run from the Simple Inkscape Scripting extension have all of the Simple Inkscape Scripting functions and variables preloaded. To inform Visual Studio Code of this context without affecting the script at runtime, Python type hints can be used:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # Import all simpinkscr functions that are available when the script
    # is executed from the Simple Inkscape Scripting extension.
    from simpinkscr import *
    # Import additional types for simpinkscr variable typing.
    from simpinkscr.simple_inkscape_scripting import SimpleCanvas

# Typing of available simpinkscr variables.
# Extend with other available variables as needed:
# https://github.com/spakin/SimpInkScr/wiki/Quick-reference#variables
canvas: SimpleCanvas
user_args: list[str]

# Your script here
# ...