[вернуться к оглавлению]

# LibRaw: общие комментарии к API

## Содержание

1. Варианты LibRaw
2. Соглашения о кодах ошибок и действиях при ошибках
3. Нештатные ситуации, не являющиеся ошибкой
4. Абстракция ввода данных
5. Thread safety
6. Использование C++
7. Параметры структуры LibRaw::imgdata.params, влияющие на поведение open_file/unpack/unpack_thumb
8. Фильтрация RAW-данных
9. Хранение данных маскированных пикселов
10. Использование памяти
    1. Использование стека
    2. Управление динамической памятью
    3. Использование динамической памяти
       1. Память для раскодированного изображения
       2. Память для раскодированного thumbnail
       3. Память для раскодированного ICC-profile
       4. Память для распаковки RAW
       5. Память для постобработки
       6. Память для записи файла
       7. Память для распаковки в буфер в памяти
11. Несовместимости с dcraw
    1. Обработка Thumbnails от камер Kodak

## Варианты LibRaw

Начиная с версии 0.9, библиотека LibRaw существует в единственном варианте. Более старые версии существовали в трех редакциях (основная, облегченная и коммерческая).

## Соглашения о кодах ошибок и действиях при ошибках

Приняты следующие соглашения о возвращаемых ошибках

1. Все функции, которые могут вернуть код ошибки имеют целый тип возвращаемых данных.
2. При отсутствии ошибки возвращается 0 (LIBRAW_SUCCESS).
3. Если случилась ошибка в системном вызове, то возвращается значение errno (это положительное число), которое может быть проанализировано с помощью strerror() или подобных средств.
4. Все собственные коды ошибок LibRaw - отрицательные, при этом ошибки делятся на два типа:
   Нефатальные ошибки
     Нефатальные ошибки не запрещают исполнение других функций в последовательности обработки (например, unpack_thumb() вполне может вернуть код, означающий "preview отсутствует" и это не мешает затем вызвать unpack()).
   Фатальные ошибки
     В случае возникновения фатальной ошибки (нехватка памяти, ошибка во входных данных, невозможность распаковки данных) текущая стадия обработки завершается, все аллоцированные ресурсы освобождаются.
     В случае попытки продолжения обработки - все последущие вызовы API вернут ошибку LIBRAW_OUT_OF_ORDER_CALL.
     Вместе с тем, экземпляр LibRaw, в котором возникла фатальная ошибка, может обрабатывать следущие RAW-файлы обычным образом (вызов open_file() (либо open_datastream(), open_buffer()) затем unpack() и так далее).
5. Проверка фатальности ошибки осуществляется макросом LIBAW_FATAL_ERROR(код ошибки)
6. Коды ошибок перечислены и расшифрованы здесь.

## Нештатные ситуации, не являющиеся ошибкой

В случае возникновения нештатной ситуации, не мешающей получить из файла какие-то данные, о ней будет просигнализировано путем взведения соответствующего бита в imgdata.process_warnings. Возможные типы предупреждений перечислены и расшифрованы здесь.

## Абстракция ввода данных

LibRaw использует для чтения файла объект, производный от класса LibRaw_abstract_datastream. Cемантика этого класса схожа с семантикой объектов типа "файл с произвольным позиционированием", объект реализующий ввод должен поддерживать операции позиционирования и чтения.

Для работы с некоторыми форматами, содержащими зашифрованые куски TIFF-каталогов, требуется временное переключение ввода на временный поток, привязанный к созданному LibRaw буферу в памяти. Эта функциональность реализуется в базовом классе LibRaw_abstract_datastream через имеющеется там поле substream, которое является указателем на объект класса LibRaw_buffer_datastream.
При использовании собственных реализаций потоков данных, необходимо в методах чтения и позиционирования проверять инициализированность этого поля и если оно не нулевое - передавать управление туда. Подробнее см. реализацию класса LibRaw_file_datastream в заголовочном файле libraw/libraw_datastream.h.

Если поток данных знает имя обрабатываемого файла в файловой системе, он должен уметь сообщить его всем, кто в нем нуждается вызовом fname(). Это имя будет использовано при вызове callbacks (уведомителях об ошибках) и может быть использовано для генерации имени файла с метаданными, если это нужно для распаковываемого формата.

Для некоторых форматов данных метаданные (экспозиционные параметры, баланс белого) не хранятся в RAW-файле, но могут быть считаны из JPEG-версии того же снимка. Если реализация надстройки над LibRaw_abstract_datastream умеет вернуть имя обрабатываемого файла при вызове fname(), то предполагается, что для такой реализации возможно временное переключение потока ввода на другой файл. Чтобы это было действительно так, реализация потока данных должна реализовать методы subfile_open()/subfile_close(). Стандартные реализации, унаследованные от базового класса, просто возврашают код ошибки.
Пример реализации методов открытия дополнительного потока данных можно подсмотреть в реализации класса LibRaw_file_datastream в заголовочном файле libraw/libraw_datastream.h.

## Thread safety

Thread safety обеспечивается, если объект LibRaw создается и иcпользуется внутри одного thread. При этом количество threads (каждая со своим объектом LibRaw) ничем не ограничено (кроме потребностей в памяти).

В случае создания объекта LibRaw в одном потоке исполнения, а использования в другом - необходима внешняя синхронизация, не дающая произвести одновременный доступ к одному объекту.

В Unix (Linux/FreeBSD/MacOS) собираются две версии библиотеки: thread-safe версия libraw_r.a и более быстрая не thread-safe libraw.a.

Thread-safe версия использует для хранения локальных данных поля в классе LibRaw, что позволяет иметь несколько экземпляров класса LibRaw, работающих одновременно.

Не thread-safe версия хранит промежуточные данные в глобальных переменных, что несколько быстрее. Не thread-safe версия может использоваться и в multithreaded-приложениях, но только если экземпляр класса LibRaw гарантированно один.

Под Windows собирается только thread-safe версия.

## Использование C++

При обработке исключительных ситуаций внутри LibRaw используется механизм C++ exceptions. Все исключения перехватываются внутри функций библиотеки и проникать наружу не должны.

Для аллокации/освобождения памяти используются функции malloc(calloc)/free, а не new/delete.

Какие-либо специфические библиотеки (STL, Boost, smart pointers) - не используются.

При использовании С API ссылки на C++-вызовы new/delete остаются, поэтому линковаться надо с libstdc++(Unix)/....(Windows).

## Параметры структуры LibRaw::imgdata.params, влияющие на поведение open_file/unpack/unpack_thumb

Большинство полей данных структуры LibRaw::imgdata.params влияют только на постобработку данных, но есть ряд исключений, унаследованных текущей версией LibRaw от особенностей исходных текстов dcraw (постепенно эти зависимости будут удаляться).

imgdata.params.use_camera_matrix и imgdata.params.use_camera_wb
  Влияют на загрузку RAW-данных для камер у которых есть colormatrix.
  Внимание! Если параметр imgdata.params.use_camera_matrix не установлен пользователем, то он копируется из imgdata.params.use_camera_wb на этапе открытия файла.
imgdata.params.user_flip
  Если этот параметр больше или равен нулю, то на этапе открытия файла (open_file() и остальные подобные вызовы) производится присваивание `imgdata.sizes.flip = imgdata.params.user_flip`.
imgdata.params.shot_select
  Позволяет выбрать номер извлекаемого изображения для тех форматов данных, где возможно хранение нескольких RAW-изображений в одном файле данных.
imgdata.params.half_size
  Влияет на загрузку RAW-данных для задников Phase One и Sinar. Кроме того, если установлен этот параметр, то считывание данных будет производиться в битмэп половинного размера в котором будут заполняться 4 компонента.
imgdata.params.threshold, imgdata.params.aber
  Использование этих параметров (т.е. указание, что будет использоваться, соответственно, wavelet denoising и исправление аберраций) то чтение данных будет производиться в битмэп половинного размера, у каждого пиксела будут заполнены вче 4 компонента (для байеровских матриц).
imgdata.params.filtering_mode
  Влияет на загрузку RAW-данных для тех камер, у которых вычитание уровня черного (возможно, частичное) производится на этапе чтения RAW: Canon A600, A5, CRW/CR2; камеры с LJPEG-сжатием (некоторые камеры Nikon, Kodak и Hasselblad).
imgdata.params.use_camera_wb
  Влияет на загрузку матрицы баланса белого для задников Leaf.
imgdata.params.document_mode
  В текущей версии LibRaw не влияет на чтение данных. В dcraw - влияет на данные thumbnails для некоторых камер Kodak.

## Фильтрация RAW-данных

На этапе обработки RAW-данных LibRaw может осуществлять такие стадии обработки:

- Вычитание уровня черного, рассчитанного по черной рамке.
- Удаление нулевых значений (усреднение значений соседних пикселов).
- Применение к данным кривой, считанных из метаданных изображения

В текущей версии LibRaw возможны следующие настройки фильтрации (настройка производится через задание параметра imgdata.params.filtering_mode в одно из значений enum LibRaw_filtering:

- Совместимая с dcraw фильтрация (умолчание). Этот режим оставлен как умолчание для совместимости с предыдущими версиями LibRaw, его использование не рекомендуется.
- Отключение одного или нескольких видов фильтрации. Эти режимы предназначены для ситуации, когда фильтрация не нужна (анализаторы RAW и подобные программы), либо когда вызывающая программа выполняет фильтрацию самостоятельно (например, базируясь на данных, считанных с черной рамки.
- Автоматический выбор наилучшей фильтрации, доступной в LibRaw: улучшенных режимов для отдельных камер, поддержанных специализированными процедурами фильтрации; фильтрация кодом dcraw для всех остальных камер. Этот режим рекомендуется к использованию для всех приложений, перекладывающих все тонкости обработки RAW на LibRaw.

## Хранение данных маскированных пикселов

Для части форматов RAW LibRaw извлекает данные неактивных сенсоров матрицы ("маскированные пикселы" или "черная рамка") и сохраняет их в структуре данных imgdata.masked_pixels. Эти данные затем могут быть использованы для:

- Расчета уровня черного (в том числе, по столбцам, соответствующим разным каналам АЦП для подавления banding).
- Расчет уровня шумов, в том числе по цветовым каналам, что актуально для камер у которых разное поканальное усиление сигнала.

Данные черной рамки доступны только RAW-данных с байеровскими данными (один компонент на пиксель) и только для тех камер, где эта рамка доступна. Извлечение данных для многоцветных RAW (Canon sRAW, Kodak YRGB, Sinar 4-shot) возможно будет добавлено в следующих версиях.

Маскированные пикселы и активные пикселы изображения можно объединить в общий 4-компонентный битмэп вызовом add_masked_borders_to_bitmap().

## Использование памяти

### Использование стека

Экземпляр класса LibRaw имеет собственный размер около 100 килобайт, при использовании конструкций вида `LibRaw imageProcessor;` эта память аллоцируется на стеке.

Методы класса LibRaw (и вызовы С API) при работе могут аллоцировать до 130-140 килобайт данных на стеке под автоматические переменные.

Таким образом, для работы одного экземпляра LibRaw может требоваться около 250 килобайт стека. В большинстве современных архитектур это не является проблемой, но при использовании LibRaw в multi-threaded-окружении необходимо не забывать аллоцировать достаточно памяти для стека thread.

При динамической аллокации (`LibRaw *iProcessor = new LibRaw;`) требования к памяти на стеке снижаются (на 100 килобайт - размер экземпляра класса). При использовании C API экземпляр LibRaw аллоцируется динамически.

### Управление динамической памятью

LibRaw ведет учет всех блоков аллоцированной динамической памяти, при возникновении исключительной ситуации (фатальной ошибки) все они освобождаются. Код учета довольно примитивный и не расчитан на аллокацию большого числа блоков (в обычной ситуации при обработке файла аллокация происходи 2-6 раз), при расширении LibRaw собственными методами это надлежит учитывать.

### Использование динамической памяти

LibRaw использует динамическую память:

- для раскодированного изображения;
- для раскодированного thumbnail;
- для извлеченного из RAW-файла ICC-профиля (если он там есть);
- для временных данных на этапе распаковки RAW-файла;
- для временных данных на этапе постобработки и записи результата;
- для чтения исходного RAW-файла (только на Win32)

#### Память для раскодированного изображения

С целью упрощения дальнейшей обработки, память под извлекаемые RAW-данные аллоцируется с 4-кратным (для байеровских камер) запасом: для каждого пикселя отводится 4 16-битных компонента (три из которых будут нулевыми после распаковки RAW). Это позволяет проводить дебайеризацию и прочие действия по постобработке прямо в том же буфере, куда были извлечены данные, но повышает требования к памяти вчетверо.
Таким образом, размер памяти под буфер изображения в 6-10 раз превышает размер исходного RAW-файла.
Вполне вероятно, что в следующих версиях LibRaw аллокация этого буфера будет более экономной, при условии неиспользования вызовов постобработки, унаследованных от dcraw..

Буфер для раскодированного изображения аллоцируется при вызове unpack() и освобождается при recycle().

#### Память для раскодированного thumbnail

Память для thumbnail аллоцируется при вызове unpack_thumb() и освобождается при recycle(). Аллоцируется буфер размером ровно под thumbnail т.е. до нескольких мегабайт.

#### Память для раскодированного ICC-profile

Память для ICC-профиля аллоцируется при вызове unpack_profile() и освобождается при recycle(). Аллоцируется буфер размером ровно под размер ICC-профиля т.е. до нескольких сотен килобайт.

#### Память для распаковки RAW

Память для временных буферов, нужных при распаковке RAW-данных может быт аллоцирована во время работы unpack() и освобождается до завершения этой функции. Размеры аллоцированных буферов невелики, в пределах нескольких десятков килобайт.

#### Память для постобработки

При постобработке изображений (унаследованной от dcraw) выделяется память под гистограмму (128 килобайт). Эта память выделяется при вызове dcraw_document_mode_processing() и dcraw_process(), а освобождается при вызове recycle().

Помимо этого, при работе dcraw_process() и использовании ряда имеющихся возможностей:

- ротации изображений с камер FUJI;
- коррекции хроматических аберраций;
- изменении размеров изображения (включая случаи коррекции неквадратного пиксела);
- highlight recovery;

будет аллоцирован временный буфер, размер которого равен размеру результирующего изображения (из расчета 6-8 байт на пиксел для разных стадий обработки). При завершении промежуточной подстадии обработки, буфер с предыдущей копией изображения будет освобожден.
Если постобработка не используется, то временные буферы не аллоцируются.

#### Память для записи файла

Вызов dcraw_ppm_tiff_writer() аллоцирует память под одну строку выходного изображения. Аллоцированная память освобождается перед выходом из вызова.

#### Память для распаковки в буфер в памяти

Вызовы dcraw_make_mem_image() и dcraw_make_mem_thumb() (и их аналоги в C-API) аллоцируют дополнительную память в объеме, необходимом для хранения выводимых данных (изображения и thumbnail, соответственно).Освобождение этой памяти - задача вызывающей функции.

## Несовместимости с dcraw

### Обработка Thumbnails от камер Kodak

В ряде камер Kodak preview (thumbnail) хранится в виде нескорректированного изображения. При извлечении его с помощью dcraw -e используются те же настройки баланса белого, коррекции цветов и так далее, что и для извлечения основных RAW-данных (включая удаление дефектов и вычитание dark frame, что ошибочно т.к. размер изображения другой).
В вызове LibRaw::unpack_thumb() всегда используется баланс белого, взятый из камеры (as shot), какие-либо настроки из imgdata.params не используются.

Для Всех остальных камер thumbnails извлекаются as-is, без каких-либо цветовых преобразований, как в dcraw, так и в LibRaw.

[вернуться к оглавлению]

Last modified: Sun Mar 28 22:08:27 MSD 2010