Metadata-Version: 2.4
Name: svg2many
Version: 0.5.2
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.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: envara>=0.5.7
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 find spots where the width, height, scale, offset and visibility should be substituted with the required ones.

Dependencies: [envara](https://pypi.org/project/envara/) by the same author (a package for the comprehensive environment variable expansion on various platforms).

### 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 the `resvg` utility (if you use text(s) in your SVG, you should list the font families in the `style` section or as an attribute).

2. Install `cwebp` if you plan to generate `*.webp` files for `Android` projects or to run demo for the `Android` target

3. Install `ImageMagick` if you plan to generate an `.ico` file from (multiple) `.png` file(s) or to run demo for the `Windows` target

4. Install `svg2many` from _PyPI_.

5. Create your beautiful SVG image. It is highly recommended NOT to use percentages as co-ordinates or sizes: those are scaled inconsistently. You can define a 100x100 pixel image, and all absolute co-ordinates and sizes 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>
   ```

   You can also look at `examples/assets/images/app_icon.svg` in the application bundle or from the [repo's examples](https://github.com/aiurovet/svg2many/tree/main/examples)

6. Create configuration file or take that from the source mentioned above.

7. Create `env` file(s) or take those from the source mentioned above if you need. You can skip this step and decide later.

8. Ensure the installation directory for `svg2many` is listed in `PATH`.

9. Run:

   ```
   svg2many -c CONFIG [-e ENV] [-d] [-q] [-v] [ARGUMENTS]
   ```

All options:

- `-h, --help`

  Help screen.

- `-D, --demo DEMO`

  Run demonstration, DEMO is one of (case ignored): Android, Flutter (default), iOS, Linux, macOS, Web, Windows. If you run demo, the application will create directory `~/Projects/my_app`. It will place the output images there (you can safely remove it later). Demo, and possibly, your future runs, require `resvg` to be installed. Specifically for the Android demo, `cwebp` should be installed too. And specifically for the Windows demo, install `ImageMagick` (to convert multiple `.png`s to a single `.ico`). Demo will read configuration files from `examples/config` as well as env files from `examples/env` under the package installation directory. The sample input SVG file will be copied to the demo output directory too, under `assets/images`.

- `-c, --config CONFIG`

  A file in JSON format that holds rules of conversion. Supports comma-separated glob masks to process multiple config files. If this setting is omitted, the application will expect configuration (just the content) in its `<stdin>`.

- `-d, --delete`

  Delete all generated files, but not directories.

- `-e, --env ENV`

  Directory containing env files. Env files are text files with lines in the `name = value` format with any number of spaces around `=`. This format allows you to define extra environment variables to use in configuration files. If the non-empty beginning of the file content represents line comment (`#` for POSIX, `::` for Windows, `!` for OpenVMS, `|` for RiscOS), it defines that platform's rules for the environment variables' expansion. Please note that when running on Windows, the escape character will still be defined as `^` rather than `\` in order to avoid possible issues with paths. So, if you wish to use POSIX rules of expansion, do that in the env files that do not contain escaped characters (you can define those via variables in the platform-specific env files). The application will load the content from `.env`, then from files containing `posix` and `env` in their name on POSIX-compatible OSes (Linux, BSD, macOS, AIX), then from files containing `bsd` and `env` in their name (for FreeBSD, NetBSD, macOS, and similar), then from files containing `<plat>` and `env` in their name (\<plat\> is what Python's `platform.system()` call returns, as well as from files containing `macos` and `env` on macOS). Every pattern should appear in the beginning or in the end of the filename, or should be separated by `.` or `-` or `_`. For instance, on Windows, it could be, `.env`, `windows.env` as well as something exotic like `abc-env_def.windows--ghi`. The last file to load will be `svg2many.env` if present. Please note that there was no way for the author to test the application in OpenVMS or RiscOS, so expect issues there. You are welcome to report those in the GitHub repository.

- `-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`.

- `ARGUMENTS`

  Anything that you can refer to in the configuration file(s) like `$1`, `$2` (POSIX) or `%1`, `%2`, etc. For example, it could represent the name of a project which will appear as part of a path: `~/Projects/$1`.

The SVG-to-raster-image conversion is done via an arbitrary external command defined in the config (`export` or `after`). You can use any rasterizer: `resvg`, `ImageMagick`, `Inkscape`, headless `Chrome`. The command receives the modified SVG content via pipe (stdin) or via a temporary file (if `{i}` is present in the command).

The preferred exporter is `resvg` (you can install that using `apt`, `yum`, `brew` or `scoop`), as it is faster than any headless browser or tools like `ImageMagick` or `Inkscape`, and produces images of good quality.

Another good option for Linux is `rsvg-convert`. It has issues with the text alignment when running on Windows though. Also the project does not support the Windows executable, so you need to look for a third-party build.

## JSON Configuration File Format

### Nodes

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

  Default command to run upon completion of all exports in a target (like `magick` 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.

- `$.inpFile`

  Input SVG file. Read from `<stdin>` if not specified, null, empty, or `"-"`.

- `$.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). Optionally 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

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

- `{i}`

  Input (SVG) file path. If this placeholder is not present in the export command, the scaled and/or shifted content of the original input file will be fed into the respective application via its `<stdin>`. Otherwise, the scaled and/or shifted content will be saved to a temporary SVG file in the output directory, and that file's path will be inserted into the export command.

- `{n}`

  Input filename without type (extension). With multiple extensions, all of those will be stripped.

- `{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).

- `{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 -->
