Metadata-Version: 2.4
Name: svg2many
Version: 0.3.1
Summary: Export a single SVG to raster images of multiple resolutions
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.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: envara>=0.5.1
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

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

This application allows to produce all raster images you need (`.png`, `.webp`, or others) from a single `.svg` file. It is based on search-and-replace of the width, height and the presence of foreground and background in the content of the source file. The main idea is that since the `SVG` format is text (XML), there is a rational way to find spots where the default width, height, scale, offset and visibility should be substituted with required ones.

Dependencies: `envara`.

Pre-requisites (external dependencies):

1. An exporter from an `.svg` to a raster image file (`.png`, `.webp`, or others). This could be even your browser running in the headless mode, like _Chromium_-based one (Google Chrome, Microsoft Edge, Opera, Vivaldi, etc.) or _Firefox-based_ (Firefox, Tor, LibreWolf, etc.). The preferred exporter, however, is `rsvg-convert` from the GNOME's `librsvg2`. Depending on the OS you are running, it can be installed via `apt`, `yum`, `brew` or `chocolatey`. This exporter is faster than any headless browser or tools like `ImageMagick` or `Inkscape`, and produces images of good quality.

2. A converter from a set of raster images to `.ico` if you need to generate Windows native icons. Preferred converter is ImageMagick's `magick` (see the examples). You'll use that in the `after` attribute of configuration file.

3. There is no converter from a set of raster image files to a single `.icns` one, as the latter is deprecated by Apple (still supported for the sake of legacy though). That's why the examples for Flutter and macOS application icons do not utilise that. You are welcome to utilise that in your configuration files if you like. Please note however, that I had issues adding a 64x64 image to `.icns` using `png2icns` on Linux, and decided it is not worth the effort.

### Usage

This example can be used to generate all launcher icons for a _Flutter_ project. See also: _How Do I Use It_ at the end of this document

1. Install `svg2many` from _PyPI_

2. Create your beautiful SVG image. It is highly recommended NOT to use percentages as co-ordinates or sizes: those are getting scaled inconsistently, and so far, I have no solution that does not attempt a full-scale to parseing of an SVG. You can define a 100x100 pixel image that will essentially express the same. Example:

   ```xml
   <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
     <g class="background" display="" transform="scale(1, 1) translate(0, 0)">
       <!--Place your actual background drawing here-->
     </g>
     <g class="foreground" display="" transform="scale(1, 1) translate(0, 0)">
       <!--Place your actual foreground drawing here-->
     </g>
   </svg>
   ```

3. Create configuration file or take that from `examples/` in the application bundle or from the [repo's examples](https://github.com/aiurovet/svg2many/tree/main/examples)

4. Create `.env` file(s) or take those from `examples/` if you need. You can skip this step and make decision later.

5. Ensure the installation directory for `svg2many` is listed in `PATH` (or use an explicit path inside a wrapper script).

6. Run with options in any order:

   ```
   svg2many -c (your-config-file) [-r (top-dir)] [-i (input-svg)]
   ```

All options:

- `-h, --help`

   Help screen (similar to this list)

- `-c, --config CONFIG`

   A file in JSON format that holds rules of conversion (see full description below). This setting is mandatory.

- `-d, --delete`

   Delete all generated files, but not directories.

- `-e, --env ENV`

   A text file containing lines in the `name = value` format with any number of spaces in between: `CMD_RSVG="rsvg-convert"`, then `CMD_RSVG_OUT_FILE="$CMD_RSVG --output {o}"`. It allows you to define extra environment variables to use in different configuration files. You can put there comments as well (starting with #). The application will load the content from `.env`, then `any.env`, then `posix.env` on POSIX-compatible OSes (Linux, BSD, macOS, AIX), then `bsd.env` (for FreeBSD, NetBSD, etc.), then `<OS>.env` (\<OS\> is what Python's `platform.system()` call returns, or also `macos.env` on macOS). On Windows, it would be `.env`, `windows.env`, Then, if this option is specified, that particular file. The order is important: from generic to more and more specific ones, having the later similar value overriding the earlier one. All these files will be scanned and taken from either the directory of the specified ENV or the config file's one otherwise. You do not have to have them all: the application will pick only those that are present without any warning or error that some are missing. This approach allows you to make portable (OS-independent) conversions if you need. For instance, generating images under GitHub actions, you have a luxury of automatic choice: $HOME on UNIX-like systems, $USERPROFILE on Windows, speciific paths to exporters on macOS like _"Applications/Google Chrome.app/Contents/MacOS/Google Chrome"_, and _google-chrome_ on Linux.

- `-q, --quiet`

   Do not print any information to the console. Mutually exclusive with `-v, --verbose`.

- `-v, --verbose`

   Detailed logging, primarily, to trace issues. Mutually exclusive with `-q` or `--quiet`.

The default SVG-to-raster exporter is `rsvg-convert` (to PNG), created and maintained by the GNOME project. This is the fastest and accurate way to create raster images. If you need to export to another raster image format, there is a good chance you can do that by directing the output to `stdout`, then reading into the next exporter via `stdin` (piping). See the `export` attribute in th sample configuration files.

ImageMagick and Inkscape are less performant, and also earlier, were producing images of lower quality. It looks like this area was improved. However, when I tried to use ImageMagick's `convert`, it failed. After I installed Inkscape, it suddenly started working. Please verify yourself if you would like to use it. My own preference, though, is `rsvg-convert`

Headless Chrome is another option: it supports more SVG features, but runs slower. More importantly, it is frequently broken (and it is now, as of December 2025, on Kubuntu 25.04), and the fix might take a while to come. To my memory, it was broken at least twice within a few years. The issues, in fact, were in Chromium, which is even worse, as it impacts a wider range of browsers.

Last but not least comes headless Firefox. As of December 2025, on Kubuntu 25.04, it seems to have an issue similar to Chromium. It is by far the slowest one, as it is not cached like the Chromium-based browsers. It will fail when another instance is open (e.g. you are viewing a website with it). Also, it will fail to export when SVG content is sent via stdin rather than a file, so you must use `{i}` in the command.

Please note that most of these exporters convert SVG to PNG only

## JSON Configuration File Format

### Nodes

- `$.after`, `$.targets.target.after`

  Default command to run upon completion of all exports in a target (like `convert` for Windows icons). The latter overrides the former.

- `$.export`, `$.targets.target.export`

  Command to export an input SVG image to an output raster image file. The latter overrides the former. Might be useful to generate `webp` icons for `Android` icons specifically.

- `$.rootDir`

  Top directory for the input and output files. Can be overridden by the `-r ROOT` option with argument

- `$.inpFile`

  Input SVG file. Can be overridden by the `-i INPUT` option with argument

- `$.bkgClass`, `$.targets.target.bkgClass`

  CSS class to detect background. Default for the former: "background". The latter overrides the former.

- `$.frgClass`, `$.targets.target.frgClass`

  CSS class to detect foreground. Default for the former: "foreground". The latter overrides the former.

- `$.outType`, `$.targets.target.outType`

  The output file type (no leading dot): png, webp, etc. The latter overrides the former.

- `$.targets`

  Array of rules for each output image file defined as follows:

- `$.targets.target.title`

  Plain text to log the progress

- `$.targets.target.delete`

  If `true`, delete all files listed under the target (useful if, for instance, all images have been converted to a single `.ico` file)

- `$.targets.target.outDir`

  Output sub-directory (relative to the top-level `rootDir`) or an absolute path

- `$.targets.target.output`

  Array of the output dimensions and filenames (under `outDir` or a path)

- `$.targets.target.output.size`

  Dimensions in pixels of the background as a single number (square) or `WxH` (rectangle).It migt be followed by dimensions of the foreground. Use space(s) to separate foreground size from the background one.

- `$.targets.target.output.file`

  Name of the output image file (sub-path relative to `outDir`)

### Placeholders to use in commands

Do not wrap those in quotes unless necessary, and not for being "safe" with possible spaces inside:

- `{i}`

  Input (SVG) file path as passed to the utility, if not present in the full command, the content will be fed to the respective application via pipe

- `{n}`

  Input filename without type (extension). When having multiple, without any: up to the first dot.

- `{o}`

  Current output file path.

- `{t}`

  Current output file type defined in `outType`.

- `{w}`

  Current output image width: largest of two widths (background and foreground).

- `{h}`

  Current output image height: largest of two heights (background and foreground).

### 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 be also expanded:

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

## __Good Luck!__
