scapex 1.0.2

The command-line Inkscape eXporter, Makefile and LaTeX friendly

ScapeX — The command-line Inkscape eXporter, Makefile and LaTeX friendly

ScapeX is a Python utility that invokes Inkscape to export an SVG drawing into a single PDF file or a set of PDFs.

It is designed to export high-quality drawings, graphics, and diagrams, hence the choice of the PDF format for vector graphics. The design of the command-line interface makes it suitable for on-the-fly usage or integration in a Makefile-based build system (e.g., for LaTeX). In addition, thanks to its fragments export feature, this tool can be used to create animated slides (e.g., using Beamer).

Features

• Command-line interface with autocompletion
• Each figure export can be configured via a sidecar TOML file
• The fragments export mode creates multiple PDFs based on arbitrary layer combinations
• Fonts rendering can be performed either by Inkscape during export or by LaTeX during compilation
• Out-of-tree export capability

Installation

The easiest way to install ScapeX is to use PipX, a Pip wrapper that automatically creates a virtual environment.

pipx install scapex

To enable Zsh autocompletion, add the following to your ~/.zshrc:

[!WARNING] This must be added before the very first call to compinit (which initializes the autocompletion system).

which scapex >/dev/null && fpath+=($(scapex --completions-zsh))

Restart your shell and you are ready to go!

[!TIP] Want to try it directly from the repository? See CONTRIBUTING.md!

Usage

The simplest usage is to export a single PDF file, optionally into another build directory:

scapex -o BUILD_DIRECTORY INPUT.svg

Fragments (animations)

To create animated exports, first generate a TOML configuration file for your diagram:

scapex --generate INPUT.svg

Open the file and adjust its configuration according to the layer identifiers defined in Inkscape:

vim INPUT.toml

Once ready, perform the fragments export:

scapex --fragments INPUT.svg

Interfacing with LaTeX (fonts rendering)

Fonts rendering can be delegated to LaTeX using the --fonts-engine=latex option. This will create a .pdf_tex sidecar file to the .pdf, containing the text that will be processed by LaTeX when including the exported PDF with \input{FILE.pdf_tex}:

scapex --fonts-engine=latex INPUT.svg

Interfacing with Makefile

ScapeX can also be used inside a Makefile, enabling automatic export when a drawing is modified and proper dependency handling. See the self-documented example under examples/Makefile.

Getting help

For additional usage, see scapex -h:

usage: scapex [-h] [-v] [-o OUTPUT_DIR] [--generate]
              [--fonts-engine {latex,inkscape}] [--fragments | --no-fragments]
              [--completions-zsh]
              [SVG_FILE]

The command-line Inkscape eXporter, Makefile and LaTeX friendly

positional arguments:
  SVG_FILE              Inkscape drawing in SVG format to export

options:
  -h, --help            show this help message and exit
  -v, --verbose         Increase verbosity if set
  -o, --output-dir OUTPUT_DIR
                        Set the output directory [default = .]
  --generate            Generate a TOML template configuration file for input
                        SVG file (instead of exporting)
  --fonts-engine {latex,inkscape}
                        Set the font rendering engine [default = inkscape]
  --fragments, --no-fragments
                        Enable (or disable) fragments exportation (instead of
                        full exportation) [default = False]
  --completions-zsh     Print the path of the directory containing the Zsh
                        autocompletion script (instead of exporting)

Contributing

See CONTRIBUTING.md.