******************************************************************************* Command-line interface ******************************************************************************* :mod:`emblematic` is usually invoked as a command-line tool. ============ Installation ============ To install :mod:`emblematic` for command-line usage: .. code-block:: console $ pipx install emblematic :mod:`pipx` should automatically add ``emblematic`` to your :envvar:`PATH`, allowing you to call it like this: .. code-block:: console $ emblematic --version If that for some reason does not work, you should still be able to use emblematic by calling it via :mod:`pipx`: .. code-block:: console $ 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: .. code-block:: console $ 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. .. code-block:: console $ 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: .. code-block:: console $ emblematic --version emblematic, version 4.0.0 .. _basic: ---------- Basic mode ---------- .. todo:: Add sample image. The simplest operation :mod:`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: .. code-block:: console $ 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: .. code-block:: console $ 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, :mod:`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 :mod:`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: .. code-block:: console $ tree icons icons ├── a │   ├── d.svg │   └── e.svg ├── b │   ├── f.svg │   └── g.svg └── c ├── h.svg └── j.svg And you tried running :mod:`emblematic` like this: .. code-block:: console $ emblematic basic --background-file='background.svg' --output-dir='out' -- 'icons/' The resulting directory structure would be: .. code-block:: console $ 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, :mod:`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: .. code-block:: console $ 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, :mod:`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. .. code-block:: console $ 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 :ref:`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. .. code-block:: console $ 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: ---------- Solid mode ---------- .. todo:: Add sample image. If the foreground image you're using does not have a specific color, as is the case for many icon packs like `Font Awesome`_, :mod:`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: .. code-block:: console $ 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 :ref:`basic`, but it requires the additional ``--foreground-color COLOR`` parameter, which specifies the color to use to fill the foreground as a `CSS color`: .. code-block:: console $ 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 .. _Font Awesome: https://fontawesome.com/ .. _CSS color: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value .. _shadow: ----------- Shadow mode ----------- .. todo:: Add sample image. :mod:`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 :ref:`solid`, 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: .. code-block:: console $ 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 .. _sigma parameter: https://en.wikipedia.org/wiki/Gaussian_blur#Mathematics .. _Gaussian blur: https://en.wikipedia.org/wiki/Gaussian_blur .. _duotone: ------------ Duotone mode ------------ .. todo:: Add sample image. If the foreground image you're using specifies two different color regions, as is the case for the `Font Awesome Duotone`_ icon pack, :mod:`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 :ref:`solid`, 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: .. code-block:: console $ 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 .. _Font Awesome Duotone: https://docs.fontawesome.com/web/style/duotone