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``.

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`` and ``PPM``) work in
exact same way.
