Metadata-Version: 2.4
Name: svg2many
Version: 1.0.1
Summary: Convert an SVG file to raster images of multiple sizes, optionally splitting into background and foreground images
Author-email: Alexander Iurovetski <aiurovet@gmail.com>
Maintainer-email: Alexander Iurovetski <aiurovet@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/aiurovet/svg2many
Project-URL: Repository, https://github.com/aiurovet/svg2many.git
Project-URL: Documentation, https://github.com/aiurovet/svg2many/blob/main/README.md
Project-URL: Changelog, https://github.com/aiurovet/svg2many/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/aiurovet/svg2many/issues
Keywords: image,svg,raster,svg2many,png,webp
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: envara>=0.7.0
Requires-Dist: pillow>=12.3.0
Requires-Dist: resvg-py>=0.3.3
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Dynamic: license-file

# svg2many (C) Alexander Iurovetski 2025-2026

## Convert an SVG file to raster images of multiple sizes, optionally splitting into background and foreground images

This application produces all raster images you need (`.png`, `.webp`, or others) from a single `.svg` file. Since the `SVG` format is text (XML), there is a rational way to manipulate width, height, scale, offset and visibility of layers.

Dependencies:

- [envara](https://pypi.org/project/envara/): a package for the comprehensive environment variable expansion on various platforms
- [resvg-py](https://pypi.org/project/resvg_py/): a safe and high-level binding for the [resvg project](https://github.com/linebender/resvg) that is used to convert an `.svg` to a `.png` (you can still use any external application of your choice instead)
- [pillow](https://pypi.org/project/pillow/): the current implementation of The Python Imaging Library, used to convert between various raster image formats

### Usage

This example can be used to generate all launcher icons for a _Flutter_
project. See also _JSON Configuration File Format_ below.

1. Install `svg2many` from _PyPI_.

2. Create your SVG image. Avoid percentages for coordinates or sizes —
   those are scaled inconsistently. A 100x100 pixel image is a good base:

   ```xml
   <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
     <g class="background">
       <!-- actual background -->
     </g>
     <g class="foreground">
       <!-- actual foreground -->
     </g>
   </svg>
   ```

   Do **not** use ``transform`` or ``display`` attributes/styles on
   these ``<g>`` elements — they will be overwritten at export time.
   See the [repo's examples](https://github.com/aiurovet/svg2many/tree/main/src/svg2many/examples).

3. Create a JSON configuration file (or adapt one from the examples).

4. Create ``env`` file(s) if needed.

5. Ensure ``svg2many`` is on ``PATH``.

6. Run:

   ```sh
   svg2many [OPTIONS] [ARGUMENTS]
   ```

### Command-line options

`-h`, `--help`
:   Help screen.

`-D`, `--demo` _DEMO_
:   Run a demo for: Android, Flutter (default), iOS, Linux, macOS, Web,
    Windows (case-insensitive). Creates ``~/Projects/my_app`` with output
    images. Android demo requires ``cwebp``.

`-c`, `--config` _CONFIG_
:   JSON configuration — a file path, comma-separated glob patterns, or
    inline JSON (surrounded by ``{}``). Default: read from ``stdin``.

`-d`, `--delete`
:   Delete generated files (directories are kept).

`-e`, `--env` _DIR_
:   Directory with ``.env`` files. Files are loaded in order: ``.env``,
    then platform-specific ones (``posix.env``, ``windows.env``, etc.),
    then ``svg2many.env``. Lines follow ``name = value`` format. The
    first non-empty leading character selects the expansion rules
    (``#`` = POSIX, ``::`` = Windows, ``!`` = OpenVMS).

`-q`, `--quiet`
:   Suppress all output. Mutually exclusive with ``-v``.

`-v`, `--verbose`
:   Detailed logging for troubleshooting. Mutually exclusive with ``-q``.

_ARGUMENTS_
:   Extra positional arguments referenced as ``$1``, ``$2`` (POSIX) or
    ``%1``, ``%2`` (Windows) inside the config. E.g. a project name used
    in output paths.

### How conversion works

The SVG is modified (scaled, layer-visibility applied) and then fed to an
external command defined by the ``export`` or ``after`` config keys. The
command receives the SVG via ``stdin`` (or a temp file when ``{i}`` is
present). You can use any rasterizer:

- **`{resvg}`** (built-in, recommended) — uses ``resvg-py`` for fast,
  high-quality conversion. Supports an extra ``-T`` / ``--out-type``
  option to further convert from the initial ``PNG`` to any Pillow-supported format.
- ``rsvg-convert`` — works well on Linux; Windows support is limited.
- ``magick`` (ImageMagick), Inkscape, headless Chrome.

#### Inline examples

```sh
# Linux / macOS / PowerShell
svg2many -c '{"export":"{resvg} {i} {o}","inpFile":"...","targets":[{"outDir":"...","output":[{"size":"64","file":"{n}.png"}]}]}'
```

```bat
REM Windows cmd (caret escaping)
svg2many -c "{^"export^":^"{resvg} {i} {o}^",^"inpFile^":^"...^",^"targets^":[{^"outDir^":^"...^",^"output^":[{^"size^":^"64^",^"file^":^"{n}.png^"}]}]}"
```

For PowerShell use `` ` `` (backtick) as the escape character instead of
`` ^ ``.

## JSON Configuration File Format

### Root-level nodes

`$.rootDir`
:   Top directory for input/output files. Defaults to the config file's
    directory (or ``cwd`` if config is read from ``stdin``).

`$.inpFile`
:   Input SVG file path. Read from ``stdin`` when ``null``, empty, or
    ``"-"``.

`$.export`
:   Command to export an SVG to a raster image. Overridden by
    ``$.targets.target.export``.

`$.after`
:   Post-export command (e.g. ``{png2ico}``). Overridden by
    ``$.targets.target.after``.

`$.bkgClass`
:   CSS class for the background layer (default: ``"background"``).

`$.frgClass`
:   CSS class for the foreground layer (default: ``"foreground"``).

`$.outType`
:   Output file type without leading dot (e.g. ``png``, ``webp``).

`$.targets`
:   Array of per-image rule sets (see below).

### Target-level nodes (``$.targets[n]``)

`$.targets.target.title`
:   Log label.

`$.targets.target.check`
:   Glob pattern(s) for incremental-build timestamp checks.
    Examples: ``{O}/*.ico``, ``{O}/{n}.ico``.

`$.targets.target.delete`
:   If ``true``, delete all files listed under this target after
    conversion.

`$.targets.target.outDir`
:   Output sub-directory (relative to ``rootDir``) or absolute path.

`$.targets.target.output`
:   Array of output size/filename entries.  Each entry has:

- ``size``: Dimensions as ``WxH`` or a single number (square).  An
    optional foreground size follows after a space.
- ``file``: Output filename (sub-path relative to ``outDir``).

`$.targets.target.export`
:   Overrides ``$.export`` for this target.

`$.targets.target.after`
:   Overrides ``$.after`` for this target.

`$.targets.target.bkgClass`
:   Overrides ``$.bkgClass`` for this target.

`$.targets.target.frgClass`
:   Overrides ``$.frgClass`` for this target.

`$.targets.target.outType`
:   Overrides ``$.outType`` for this target.

### Built-in Commands

Commands prefixed with ``{...}`` resolve to internal methods:

`{resvg}`
:   The default SVG-to-PNG converter using ``resvg-py``. Supports
    ``-T`` / ``--out-type`` to output any Pillow format.

`{png2gif}`
:   Convert one or more PNGs into a single GIF (animated if multiple
    inputs).
    ``-c`` _TEXT_ — add a comment
    ``-d`` _N_ — disposal (0=none, 1=keep, 2=restore bg, 3=restore prev)
    ``-f`` _N_ — frames per second (0–25, default 12)
    ``-l`` _N_ — loop count (0 = forever)
    ``-o`` — optimize palette (default)
    ``-t`` _N_ — transparency colour index

`{png2ico}`
:   Convert one or more PNGs into a single ICO.
    ``-b`` — save as uncompressed bitmaps

`{png2jpg}`
:   Convert a PNG into a JPEG.
    ``-c`` _TEXT_ — add a comment
    ``-k`` — keep RGB (don't convert to YCbCr)
    ``-o`` — optimize Huffman tables (slower, smaller)
    ``-p`` — progressive JPEG
    ``-q`` _N_ — quality 0–100 (default 75)
    ``-s`` _N_ — smoothing factor (0 = off)

`{png2pdf}`
:   Convert one or more PNGs into a PDF (animated if multiple inputs).
    ``-A`` _TEXT_ — document author
    ``-C`` _TEXT_ — creator name
    ``-c`` _TEXT_ — creation date/time
    ``-d`` _N_ — DPI resolution (default 72)
    ``-k`` _TEXT_ — keywords
    ``-l`` _TEXT_ — document language (PDF 2.0)
    ``-m`` _TEXT_ — modification date/time
    ``-O`` — disable deflate compression (default: on)
    ``-p`` _W,H_ or _WxH_ or — page size (e.g. ``8.5x11``; default: image size in pt)
    ``-P`` _TEXT_ — producer name
    ``-S`` _TEXT_ — subject
    ``-T`` _TEXT_ — document title

`{png2webp}`
:   Convert one or more PNGs into a single WebP.
    ``-a`` _N_ — alpha quality 0–100
    ``-e`` — preserve transparent RGB values
    ``-l`` — lossless compression
    ``-m`` _N_ — method 0 (fast) to 6 (slow/best)
    ``-q`` _N_ — quality 0–100 (default 80)

Use ``-`` in place of any filename to indicate ``stdin`` or ``stdout``.

Built-ins can be chained with pipes: the command must start with a
built-in, and all built-ins must be connected by pipes. A single
external app may follow the last built-in.

### Placeholders

Do **not** wrap placeholders in quotes (even when paths may contain
spaces — the framework handles escaping).

`{i}`
:   Input SVG file path. If absent from the command, the SVG content is
    fed via ``stdin``; otherwise written to a temp file.

`{n}`
:   Input filename without extension(s).

`{o}`
:   Current output file path.

`{t}`
:   Current output file type (from ``outType``).

`{w}`
:   Output image width (largest of background/foreground).

`{h}`
:   Output image height (largest of background/foreground).

`{I}`
:   Input directory path.

`{O}`
:   Output directory path.

### Extra Expansions

References to the environment variables will be expanded:

- Portable: `$ABC`, `${ABC:-$DEF}`.
- Windows: `%ABC%`.

References to the arguments passed to the script will also be expanded:

- Portable: `$1`, `${2:-abc}`.
- Windows: `%1`, `%2`.

<!-- markdownlint-disable MD026 -->
## Good Luck!
<!-- markdownlint-enable MD026 -->
