Metadata-Version: 2.4
Name: svg2many
Version: 0.4.6
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.6
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 produces 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. 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` (environment variable expansion)

### Usage

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

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 style or as an attribute).

2. Install `svg2many` from _PyPI_.

3. 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)

4. Create configuration file or take that from the sources mentioned above.

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

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

7. Run:

   ```
   svg2many -c (your-config-file) [-e (env-file)] [-d] [-q] [-v]
   ```

All options:

- `-h, --help`

   Help screen.

- `-c, --config CONFIG`

   A file in JSON format that holds rules of conversion, or `<stdin>` (if omitted). Supports comma-separated glob masks to process multiple config files. 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. It allows you to define extra environment variables to use in different configuration files. You can put comments there 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 are scanned 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.

- `-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 SVG-to-raster 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.

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 third-party builds.

## 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 pipe. 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 file directory path.

- `{O}`

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

## Good Luck!
