Creating images
===============
.. Internal references

.. _faker-file: https://pypi.org/project/faker-file/

Creating images for testing could be a challenging job. The goal of this
library is to help you out with basic tasks. You can easily generate very
basic graphic images, but no custom shapes. Paper size is A4.

If you don't like how image files are generated by this library, you can
check the `faker-file`_ package, which can produce complex images.

Supported image formats
-----------------------
Currently, 6 image formats are supported:

- ``PNG``
- ``SVG``
- ``BMP``
- ``GIF``
- ``TIF``
- ``PPM``
- ``JPG``

Generating images as bytes
--------------------------
See the following full functional snippet for generating a ``PNG`` image.

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_images/png_bytes_1.py
        :language: python
        :lines: 1-3

    *See the full example*
    :download:`here <_static/examples/creating_images/png_bytes_1.py>`

The generated ``PNG`` image will be an image filled with a given color of a
size 100x100 px.

----

If you want image of a different size or color, provide ``size``
(``Tuple[int, int]``) and color (``Tuple[int, int, int]``) arguments along.
See the example below:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_images/png_bytes_2.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_images/png_bytes_2.py>`

Generating files
----------------
Generate a ``PNG`` image.

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_images/png_file_1.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_images/png_file_1.py>`

----

With ``size`` and ``color`` tweaks:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_images/png_file_2.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_images/png_file_2.py>`

----

All other formats (``SVG``, ``BMP``, ``GIF``, ``TIF``, ``PPM`` and ``JPG``)
work in exact same way.

The only format that slightly deviates from others is ``JPG``. Produced
``JPG`` images are still rectangles, but unlike all others, instead of being
filled with a single solid colour, they are filled with a mixture of colours,
around a picked base colour. Also, colours on the ``JPG`` image are not
precise, but a closest match to the colour given.

The following code will generate a 10x10 px square filled with solid yellow
colour.

.. container:: jsphinx-toggle-emphasis

    .. code-block:: python
        :name: test_jpg_file_10x10_yellow
        :emphasize-lines: 3

        from fake import FAKER

        FAKER.jpg_file(size=(10, 10), color=(182, 232, 90))

While the following code, will generate a 640x480 px square filled with yellow
and other colours.

.. container:: jsphinx-toggle-emphasis

    .. code-block:: python
        :name: test_jpg_file_640x480_yellow_mix
        :emphasize-lines: 3

        from fake import FAKER

        FAKER.jpg_file(size=(640, 480), color=(18, 52, 185))

The only colour that always stays solid is the default colour - gray
``(128, 128, 128)``.

.. container:: jsphinx-toggle-emphasis

    .. code-block:: python
        :name: test_jpg_file_300x200_solid_gray
        :emphasize-lines: 3

        from fake import FAKER

        FAKER.jpg_file(size=(720, 540))

----