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

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

Creating images for testing can be a challenging task. The goal of this
library is to help you out with basic tasks. You can easily generate very
basic graphic images (no custom shapes).

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, 7 image formats are supported:

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

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

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_images/png_bytes_1.py
        :name: test_creating_images_png_bytes_1
        :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 colour of a
size 100x100 px.

----

If you want an image of a different size or colour, provide ``size``
(width, height: ``Tuple[int, int]``)
or ``color`` (RGB tuple: ``Tuple[int, int, int]``) arguments.
See the example below:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_images/png_bytes_2.py
        :name: test_creating_images_png_bytes_2
        :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
        :name: test_creating_images_png_file_1
        :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
        :name: test_creating_images_png_file_2
        :language: python
        :lines: 3-

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

----

All other image formats (``SVG``, ``BMP``, ``GIF``, ``TIF``, ``PPM`` and
``JPG``) work in exactly the 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,
based on a chosen 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 a 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))

----

.. raw:: html

    &nbsp;