.. _gs3_general_provisions:

Общие положения
===============

:term:`Application Server` предоставляет следующие способы работы с изображениями, используемыми в прикладных приложениях:

1. :term:`Коллекции изображений <Коллекция изображений>` - наборы изображений, объединённых в виде :term:`спрайта изображений <Спрайт изображений>` и хранящихся в ресурсах :term:`Application Server` или в базе данных прикладного проекта.
   Используются для быстрого и централизованного доступа к большому количеству однотипных изображений по индексу.

2. :term:`Изображения ресурсов прикладного проекта <Изображение ресурсов прикладного проекта>` - отдельные файлы изображений, хранящиеся в каталоге ``КореньПроекта/Модуль/src/main/resources`` прикладного проекта.
   Используются для хранения уникальных или редко используемых изображений, которые нецелесообразно добавлять в :term:`коллекции изображений <Коллекция изображений>`, так как они предназначены исключительно для конкретного прикладного проекта.

.. seealso::

    - :ref:`Спецификация сервиса изображений - Изображения ресурсов прикладного проекта <gs3_images_scala_images>`
    - :ref:`Спецификация сервиса изображений - Коллекции изображений <gs3_images_image_collections>`

    .. dropdown:: Pascal API

        - :pas:class:`TbtkScriptBitMapImageObject`
        - :pas:class:`TbtkScriptJpegImageObject`

Сравнение способов
------------------

.. list-table::
    :header-rows: 1

    * - Характеристика
      - Коллекции изображений
      - Изображения ресурсов прикладного проекта
    * - Место хранения
      - ``${G3_HOME}/server/resources/imagecollection/`` или таблица ``BTK_COMPONENT`` базы данных прикладного проекта
      - ``КореньПроекта/Модуль/src/main/resources``
    * - Поддерживаемые форматы
      - ``.png``, ``.svg``
      - ``.jpeg``, ``.jpg``, ``.png``, ``.ico``, ``.svg``
    * - Доступ к данным
      - 1. :ref:`EngineEndpoint.get_image <uri_endpoint_reference_get_image>`
        2. :ref:`Сервис загрузки коллекций изображений <gs3_rest_image_collections>`
      - 1. :ref:`EngineEndpoint.get_resource_image <uri_endpoint_reference_get_resource_image>`
        2. :ref:`Сервис загрузки ресурсных файлов <gs3_rest_resources>`
    * - Назначение
      - Набор однотипных изображений
      - Единичные или уникальные изображения
    * - Требования к размеру
      - Единый размер для всех изображений коллекции
      - Нет
    * - Производительность при массовом доступе
      - Высокая (все изображения передаются в составе одного спрайта)
      - Низкая (каждое изображение запрашивается отдельно)

Рекомендации по выбору
-----------------------

Используйте :term:`коллекции изображений <Коллекция изображений>`, если:

- Требуется быстрый доступ к большому набору изображений.
- Важно уменьшить количество сетевых запросов.
- Все изображения имеют одинаковый размер.
- Все изображения схожи по смыслу и назначению. Например: коллекция изображений, используемых в кнопках редактора - ``editbuttons``, коллекция изображений панели инструментов - ``toolbarprimary``.

Используйте :term:`изображения ресурсов прикладного проекта <Изображение ресурсов прикладного проекта>`, если:

- Графика уникальна для конкретного прикладного проекта.
- Изображений мало, нет смысла собирать их в коллекцию.
- Необходимо гибко обновлять отдельные файлы без обновления коллекции изображений.