.. _cli:

*******************************************************************************
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
