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

LibRaw C++ API

Содержание

  1. Объект LibRaw
  2. Возвращаемые значения
  3. Методы, загружающие данные из файла
  4. Вспомогательные функции
  5. Постобработка данных, эмуляция поведения dcraw
  6. Запись данных в файлы, эмуляция поведения dcraw

Объект LibRaw

Основной объект (класс) LibRaw, создается либо без параметров, либо передаются флаги, определяющие поведение объекта.

#include "libraw/libraw.h"
...

   LibRaw ImageProcessor(unsigned int flags=0);
...
    

Флаги (несколько флагов задаются через | - оператор bitwise-OR):

Для обработки изображения используются три группы методов

Результаты обработки размещаются в поле imgdata, которое имеет тип libraw_data_t, в этом же наборе данных содержатся поля, управляющие постобработкой и выводом.

Возвращаемые значения

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

Методы, загружающие данные из файла

int LibRaw::open_file(const char *rawfile)

Открывает RAW-файл, считывает оттуда метаданные (EXIF), заполняет структуры:

Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.

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

int LibRaw::unpack(void)

Производит распаковку RAW-данных изображения, вычисление уровня черного (не для всех форматов), вычитание черного (не для всех форматов). Результаты работы помещаются в imgdata.image.

На чтение данных в ряде (редких) случаев влияют настройки, сделанные в imgdata.params (libraw_output_params_t), подробнее см. в API notes.

Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.

int LibRaw::unpack_thumb(void)

Производит чтение (либо распаковку) preview (thumbnail) изображения, помещая результат в буфер imgdata.thumbnail.thumb.
JPEG-preview помещаются в данный буфер без каких-либо изменений (с заголовком и т.п.), Другие форматы preview помещаются в буфер в виде распакованого image bitmap (3 компонента, 8 бит на компонент).
Формат thumbnail записывается в поле imgdata.thumbnail.tformat, возможные значения описаны в описании констант и структур данных.

Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.

Вспомогательные функции

void LibRaw::recycle(void)

Освобождает аллоцированные данные экземпляра LibRaw, делая возможным обработку следующего файла тем же процессором. Повторные вызовы recycle() вполне возможны и ничему не противоречат.

LibRaw::~LibRaw()

Деструктор, сводится к вызову recycle()

const char* libraw_strerror(int errorcode)

Аналог функции strerror(3) - выдает текстовую расшифровку (на английском языке) для кодов ошибок LibRaw

Установка функций нотификации об ошибках

При работе библиотеки возможны два типа исключительных ситуаций, которые могут требовать уведомления вызывающего приложения:

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

Уведомитель о нехватке памяти

        typedef void (* memory_callback)(const char *file, const char *where);
        void LibRaw::set_memerror_handler(memory_callback func);
    

Пользователь может определить свою функцию, вызываемую по нехватке памяти. Это void-функция, получающая два строковых параметра:

Задача callback - информационная (уведомление пользователя или кода программы о невозможности выполнить обработку).

Если не установить свой обработчик, то будет использован стандартный (печать сообщения об ошибке в stderr).

Можно установить нулевой обработчик, передав NULL в set_memerror_handler, тогда функция уведомления вызываться не будет. Того же эффекта можно добиться, если создать объект LibRaw с флагом конструктора LIBRAW_OPTIONS_NO_MEMERR_CALLBACK.

В случае нехватки памяти, обработка текущего файла прекращается, вызывается уведомитель, все аллоцированные ресурсы освобождаются, делается recycle(). Текущий вызов вернет ошибку LIBRAW_UNSUFFICIENT_MEMORY.
При попытке продолжить обработку данных, все вызовы последущие будут возвращать LIBRAW_OUT_OF_ORDER_CALL. Обработку нового файла можно начать обычным образом: вызвав LibRaw::open_file().

Уведомитель об ошибке чтения файла

        typedef void (*data_callback)(const char *file, const int offset);
        void LibRaw::set_dataerror_handler(data_callback func); 
    

Пользователь может определить свою функцию, вызываемую по ошибке входных данных. Это void-функция, получающая два параметра:

Задача callback - информационная (уведомление пользователя или кода программы о невозможности выполнить обработку).

Если не установить свой обработчик, то будет использован стандартный (печать сообщения об ошибке в stderr).

Можно установить нулевой обработчик, передав NULL в set_dataerror_handler, тогда функция уведомления вызываться не будет. Того же эффекта можно добиться, если создать объект LibRaw с флагом конструктора LIBRAW_OPTIONS_NO_DATAERR_CALLBACK.

В случае ошибки во входных данных, обработка текущего файла прекращается, вызывается уведомитель, все аллоцированные ресурсы освобождаются, делается recycle(). Текущий вызов вернет ошибку LIBRAW_IO_ERROR.
При попытке продолжить обработку данных, все вызовы последущие будут возвращать LIBRAW_OUT_OF_ORDER_CALL. Обработку нового файла можно начать обычным образом: вызвав LibRaw::open_file().

Постобработка данных, эмуляция поведения dcraw

Вместо написания своей пост-обработки Bayer Pattern, можно воспользоваться вызовами dcraw (которые вызываются после вызова open_file() + unpack() /+ unpack_thumb()/).

Задание параметров

Практически все параметры, которые можно задать через командную строку dcraw, задаются путем присваивания значений полям структуры LibRaw::imgdata.params, структура имеет тип libraw_output_params_t, все поля перечислены и достаточно подробно описаны в описании структур данных.

int LibRaw::adjust_sizes_info_only(void)

Функция рассчитывает правильные размеры выходного изображения (imgdata.sizes.iwidth и imgdata.sizes.iheight) для следующих случаев:

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

Функция должна использоваться в информационных целях, она несовместима с вызовами dcraw_document_mode_processing() и dcraw_process().

int LibRaw::dcraw_document_mode_processing(void)

Функция эмулирует dcraw -D - отключение интерполяции, баланса белого и преобразования цветов.
Вызывается после вызова LibRaw::unpack();

Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.

int LibRaw::dcraw_process(void)

Функция эмулирует возможности постобработки, имеющиеся в dcraw
Вызывается после вызова LibRaw::unpack();

Поддерживается вся функциональность dcraw (задаваемая через значение полей в imgdata.params) за исключением:

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

Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.

Запись данных в файлы, эмуляция поведения dcraw

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

int LibRaw::dcraw_ppm_tiff_writer(const char *outfile)

Записывает результаты постобработки в файл в формате PPM/PGM или TIFF (формат задается через imgdata.params.output_tiff). Производит результаты, бинарно идентичные с dcraw.

Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.

int LibRaw::dcraw_thumb_writer(const char *thumbfile)

Записывает thumbnail в файл в формате PPM для bitmap-thumbnails и JPEG для JPEG-thumbnails, в формате полностью идентичном результатам работы dcraw.

Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.

[вернуться к оглавлению]
Alex Tutubalin
Last modified: Sun Mar 23 19:21:53 MSK 2008