Metadata-Version: 2.4
Name: svgsubfig
Version: 0.1.0
Summary: Compose raster and vector images to publication-ready figures for scientific journals
License-Expression: MIT
License-File: LICENSE.txt
Author: Felix Faber
Author-email: felix.faber@ovgu.de
Requires-Python: >=3.12
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: lxml (>=6.0.2,<7.0.0)
Requires-Dist: pillow (>=12.1.1,<13.0.0)
Project-URL: Repository, https://github.com/fefafe/svgsubfig
Description-Content-Type: text/markdown

# svgsubfig

A python package for swift arrangement of raster images and vector graphics into a single figure based on SVG.

This package is focussed on the preparation of high quality figures that consist of several subimages, both vector and raster graphics, for publication in scientific journals. A label is inserted below each subimage, e.g. ``(a)``, ``(b)``, ...

Font family, size and gaps can be adjusted based on a JSON configuration. An example figure created with ``svgsubfig`` could look like this:

![example figure created with svgsubfig](./assets/plots.png)

## Basic usage

### Configuration

Create a JSON configuration file with the following structure, use relative filenames for the individual (sub-)images (the directory of the config file acts as base directory).

```json
{
    "gap-between": 5,
    "gap-label": 3,
    "width": 150,
    "font-size": 9,
    "font-family": "Arial, Helvetica, sans-serif",
    "images": [
        "img/dog.jpeg",
        "img/population.svg"
    ]
}
```

Following keys are available for the config file:

- ``font-family``: Typeface used in the SVG file for text.
- ``font-size``: Size of the labeling of the images in **pt**.
- ``gab-between``: Spacing between the subimages in **mm**.
- ``gap-label``: Spacing between labels and lower boundary of the images in **mm**.
- ``images``: Array of file paths of the images to include into the figure.
- ``index-offset``: Offset of the first subimage index, e.g. if ``index-offset = 3``, the first label will be ``(d)``
- ``width``: Width of the figure in **mm**.

To use automatic conversion of the created SVG figure file into PDF and PNG file formats, [Inkscape](https://inkscape.org/) needs to be installed and accessible on PATH.

### Figure composition

To create the final figure using the JSON configuration, a small ``svgsubfig`` command line utility can be used, but also scripting is possible.

#### Command line utility

To use the ``svgsubfig`` module to create the final figure file, use following command in your terminal:

```terminal
python -m svgsubfig [--noconvert] CONFIG_PATH
```

Replace ``CONFIG_PATH`` with the path of the JSON config file. Option ``--noconvert`` prevents conversion of the created SVG into PDF and PNG with Inkscape, which is useful in case Inkscape is not installed, or manual edits on the created SVG file are necessary.

#### Script

```python
import svgsubfig.utility as util

from svgsubfig import SVGSubFigure
from pathlib import Path

pth_config = Path("figure.json")
pth_svg = pth_config.with_suffix(".svg")

fig = SVGSubFigure.from_json(pth_config)
fig.save(pth_svg)

util.convert_svg(pth_svg)
```

