Command-line interface

emblematic is usually invoked as a command-line tool.

Installation

To install emblematic for command-line usage:

$ pipx install emblematic

pipx should automatically add emblematic to your PATH, allowing you to call it like this:

$ emblematic --version

If that for some reason does not work, you should still be able to use emblematic by calling it via pipx:

$ pipx run emblematic --version

Usage

Show help message

To display a message explaining how to use a certain command, append the --help option to it:

$ emblematic --help
Usage: emblematic [OPTIONS] COMMAND [ARGS]...

  Generate an emblem, an easily recognizable yet consistently styled icon.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  basic    Create a simple emblem.
  duotone  Create an emblem with two separate colors as foreground.
  shadow   Create an emblem with a solid color foreground with a shadow.
  solid    Create an emblem with a solid color foreground.

$ emblematic basic --help
Usage: emblematic basic [OPTIONS] [FOREGROUND_FILENAME]...

  Create a simple emblem.

Options:
  -b, --background-file FILE      SVG file to use as background.  [required]
  -o, --output-dir DIRECTORY      Base directory where created emblems should be stored in. Must already exist.  [required]
  -s, --save-svg / -S, --ignore-svg
                                  Whether an emblem in SVG format should be generated or not.  [default: s]
  -p, --save-png / -P, --ignore-png
                                  Whether an emblem in PNG format should be generated or not.  [default: p]
  -w, --width-px FLOAT            Width in pixels of the output.  [default: 512.0]
  -h, --height-px FLOAT           Height in pixels of the output.  [default: 512.0]
  --help                          Show this message and exit.

Show version number

To find the version number of the version of emblematic you have installed, pass the --version option to the main command:

$ emblematic --version
emblematic, version 4.0.0

Basic mode

Basic emblem — An emblem generated in basic mode.

The simplest operation emblematic can perform is to load a SVG image as a background, then repeatedly overlay other SVG images onto it, generating a separate file for each.

This mode of operation is called basic, and can be selected with the basic command:

$ emblematic basic
Usage: emblematic basic [OPTIONS] [FOREGROUND_FILENAME]...
Try 'emblematic basic --help' for help.

Error: Missing option '-b' / '--background-file'.

From there, to generate emblems, you’ll need to: - specify the background SVG file you want to use with the --background-file FILE option; - select the directory where files should be output to with the --output-dir DIRECTORY option; - pass all the different foreground images you want to generate an emblem with as arguments (denoted in the help message as [FOREGROUND_FILENAME]...).

For example, to overlay icon_a.svg and icon_b.svg to background.svg, creating the out/icon_a.png and out/icon_b.png files, you can enter the following console command:

$ emblematic basic --background-file='background.svg' --output-dir='out' -- 'icon_a.svg' 'icon_b.svg'
out/icon_a.png
out/icon_b.png

As a response and as a way to show progress, emblematic will output the names of the created files, each on a separate line.

Keep input directory structure on generation

If you’re generating emblems for a lot of icons, you might want to have them organized in subdirectories.

If you pass emblematic a directory as a foreground image, it will find all files ending with .svg inside and will try to generate an emblem from each of them, placing them in the output directory in the same directory structure it found them in.

For example, if you had the following directory structure:

$ tree icons
icons
├── a
│   ├── d.svg
│   └── e.svg
├── b
│   ├── f.svg
│   └── g.svg
└── c
    ├── h.svg
    └── j.svg

And you tried running emblematic like this:

$ emblematic basic --background-file='background.svg' --output-dir='out' -- 'icons/'

The resulting directory structure would be:

$ tree out
out
├── a
│   ├── d.png
│   └── e.png
├── b
│   ├── f.png
│   └── g.png
└── c
    ├── h.png
    └── j.png

Specifying the size of the output images

By default, emblematic will output images large 512x512 pixels.

You can change this behavior with the --width-px and --height-px options.

As an example, see this command:

$ emblematic basic --background-file='background.svg' --output-dir='out' --width-px=1000 --height-px=1000 -- 'icon_a.svg' 'icon_b.svg'
out/icon_a.png
out/icon_b.png

Keeping intermediate SVGs

By default, emblematic avoids saving to disk the intermediate SVG files from which the PNGs are generated, as many programs will have trouble displaying them correctly.

If you want to keep them, pass the --save-svg option, or if you want to make explicit that you do not want them, in case the default behavior changes in the future, pass the --ignore-svg option.

This command will save out/icon_a.svg and out/icon_b.svg in addition to the two PNG files from before.

$ emblematic basic --background-file='background.svg' --output-dir='out' --save-svg -- 'icon_a.svg' 'icon_b.svg'
out/icon_a.svg
out/icon_a.png
out/icon_b.svg
out/icon_b.png

Skipping PNG generation

If you do not have Inkscape installed (see Prerequisites), you might want to only generate SVG files, and ignore generating PNGs entirely.

To do so, you can use the --ignore-png option, combined with the --save-svg option.

$ emblematic basic --background-file='background.svg' --output-dir='out' --save-svg --ignore-png -- 'icon_a.svg' 'icon_b.svg'
out/icon_a.svg
out/icon_b.svg

Note

Passing --ignore-png without also specifying --save-svg will result in a no-operation.

Solid mode

Solid emblem — An emblem generated in solid mode.

If the foreground image you’re using does not have a specific color, as is the case for many icon packs like Font Awesome, emblematic supports filling it with a color specified in the command line.

This mode of operation is called solid, and can be selected via the solid command:

$ emblematic solid --help
Usage: emblematic solid [OPTIONS] [FOREGROUND_FILENAME]...
Try 'emblematic solid --help' for help.

Error: Missing option '-b' / '--background-file'.

It functions mostly in the same way as Basic mode, but it requires the additional --foreground-color COLOR parameter, which specifies the color to use to fill the foreground as a CSS color:

$ emblematic basic --background-file='background.svg' --output-dir='out' --foreground-color='#00ff00' -- 'icon_a.svg' 'icon_b.svg'
out/icon_a.png
out/icon_b.png

Shadow mode

Shadow emblem — An emblem generated in shadow mode.

emblematic supports adding a shadow or glow to a single-color foreground image.

This mode of operation is called shadow, and can be selected via the shadow command.

It functions similarly to Solid mode, but in addition to those parameters, it requires four additional options, describing the parameters of the shadow:

--shadow-offset-x-px NUMBER specifies the horizontal offset of the shadow from its initial position, with positive values moving it towards the right and negative values moving to towards the left;
--shadow-offset-y-px NUMBER specifies the vertical offset of the shadow from its initial position, with positive values moving it down and negative values moving it up;
--shadow-stddev NUMBER specifies the sigma parameter of the applied Gaussian blur, with higher values increasing the radius of the shadow;
--shadow-color COLOR specifies the color of the shadow, as a CSS color.

For example:

$ emblematic shadow --background-file='background.svg' --output-dir='out' --foreground-color='#009900' --shadow-offset-x-px='16' --shaodw-offset-y-px='16' --shadow-stddev='1.0' --shadow-color='#00ff00' -- 'icon_a.svg' 'icon_b.svg'
out/icon_a.png
out/icon_b.png

Duotone mode

Duotone emblem — An emblem generated in duotone mode.

If the foreground image you’re using specifies two different color regions, as is the case for the Font Awesome Duotone icon pack, emblematic supports specifying in the command line two different colors to fill them with.

This mode of operation is called duotone, and can be selected via the duotone command.

It’s just like Solid mode, but requires specifying both colors instead of just one:

--primary-color COLOR specifies the CSS color of the first region;
--secondary-color COLOR specifies the CSS color of the second region.

Note

For this to work, the two color regions in the input foreground file need to be marked respectively with the fa-primary and fa-secondary classes.

For example, to color the primary region green and the secondary red:

$ emblematic duotone --background-file='background.svg' --output-dir='out' --primary-color='#00ff00' --secondary-color='#ff0000' -- 'icon_a.svg' 'icon_b.svg'
out/icon_a.png
out/icon_b.png