=====
Image
=====

:superscript:`*Config object requires the 'library-image' addon to use`

This page contains the different ways of defining how an image should
be loaded for use in other configurations requiring the ``Image`` type.


Types
=====

Different types of ``Image`` provide different behaviours and may have additional parameters for configuring that behavior.

The type is specified by setting the :bdg-primary:`type` parameter to the name of the type. If the same name is used by two different addons, you can prefix the name with ``ADDON_NAME:`` to specify which one to use.

A list of available types for ``Image`` are listed below:

---------

BITMAP
------

Loads a singular image. For very large images that you may have issues loading, 
try the `STITCHED_BITMAP`_ type instead.


.. _object-image-template-library-image-bitmap-parameter-columns:

:bdg-ref-primary:`columns <object-image-template-library-image-bitmap-parameter-columns>` :doc:`/config/documentation/objects/Integer` 

.. _object-image-template-library-image-bitmap-parameter-path-format:

:bdg-ref-primary:`path-format <object-image-template-library-image-bitmap-parameter-path-format>` :doc:`/config/documentation/objects/String` - Path to the image relative to the config pack directory. (For Windows users: Use the ``/`` directory separator instead of ``\``)

.. _object-image-template-library-image-bitmap-parameter-rows:

:bdg-ref-primary:`rows <object-image-template-library-image-bitmap-parameter-rows>` :doc:`/config/documentation/objects/Integer` 

.. _object-image-template-library-image-bitmap-parameter-zero-indexed:

:bdg-ref-success:`zero-indexed <object-image-template-library-image-bitmap-parameter-zero-indexed>` :doc:`/config/documentation/objects/Boolean` 

Default: ``false``

---------

STITCHED_BITMAP
---------------

An alternate way of loading ``Image`` s via a set of smaller images
arranged in a grid that are 'stitched' together during generation.
This type is primarily used when singular images are too large to be
loaded into memory (a limit imposed Java's ``BufferedImage`` class implementation).


.. _object-image-template-library-image-stitched_bitmap-parameter-columns:

:bdg-ref-primary:`columns <object-image-template-library-image-stitched_bitmap-parameter-columns>` :doc:`/config/documentation/objects/Integer` - How many columns of images to stitch together.

.. _object-image-template-library-image-stitched_bitmap-parameter-path:

:bdg-ref-primary:`path <object-image-template-library-image-stitched_bitmap-parameter-path>` :doc:`/config/documentation/objects/String` - The format string for the path to the images relative to the config pack directory. (For Windows users: Use the ``/`` directory separator instead of ``\``)

The file name section of the path format must contain the text ``{row}`` and ``{column}``
indicating the sections of the file names that indicate which rows and columns the files belong to.

Given the following example image files in the pack directory to be stitched into one image:

.. code-block::

    my-config-pack/
    ├── pack.yml
    ├── images
    ┆   └── stitched-image/
            ├ my-image-0-0.png
            ├ my-image-0-1.png
            ├ my-image-1-0.png
            └ my-image-1-1.png

The ``path-format`` to stitch together the images would be: 

.. code-block:: yaml

    path-format: images/stitched-image/my-image-{row}-{column}.png


.. _object-image-template-library-image-stitched_bitmap-parameter-rows:

:bdg-ref-primary:`rows <object-image-template-library-image-stitched_bitmap-parameter-rows>` :doc:`/config/documentation/objects/Integer` - How many rows of images to stitch together.

.. _object-image-template-library-image-stitched_bitmap-parameter-zero-indexed:

:bdg-ref-success:`zero-indexed <object-image-template-library-image-stitched_bitmap-parameter-zero-indexed>` :doc:`/config/documentation/objects/Boolean` 

Default: ``false``

Should be set to true if the image row and column indexes begin at 0.


Uses
====

Used by 3 parameters:

- :ref:`In DISTANCE_TRANSFORM in NoiseSampler <object-noisesampler-template-library-image-distance_transform-parameter-image>`:

  :bdg-ref-primary:`image <object-noisesampler-template-library-image-distance_transform-parameter-image>` :doc:`/config/documentation/objects/Image` 

- :ref:`In SINGLE_IMAGE in ColorSampler <object-colorsampler-template-library-image-single_image-parameter-image>`:

  :bdg-ref-primary:`image <object-colorsampler-template-library-image-single_image-parameter-image>` :doc:`/config/documentation/objects/Image` - The image to be sampled

- :ref:`In TILED_IMAGE in ColorSampler <object-colorsampler-template-library-image-tiled_image-parameter-image>`:

  :bdg-ref-primary:`image <object-colorsampler-template-library-image-tiled_image-parameter-image>` :doc:`/config/documentation/objects/Image` - The image to be sampled