C++ API | LibRaw

Содержание

Объект LibRaw
Возвращаемые значения
Методы, загружающие данные из файла
Вспомогательные функции
- Информация о версии библиотеки
- Список поддерживаемых форматов (камер)
  - int LibRaw::cameraCount()
  - const char** LibRaw::cameraList()
- int LibRaw::set_rawspeed_camerafile(char *path_to_cameras_xml)
- int LibRaw::get_decoder_info(libraw_decoder_info_t *)
- const char* LibRaw::unpack_function_name()
- int LibRaw::subtract_black()
- void LibRaw::recycle_datastream(void)
- void LibRaw::recycle(void)
- LibRaw::~LibRaw()
- const char* LibRaw::strprogress(enum LibRaw_progress code)
- const char* LibRaw::strerror(int errorcode)
- Установка функций нотификации об ошибках
Постобработка данных, эмуляция поведения dcraw
Запись данных в файлы, эмуляция поведения dcraw
- int LibRaw::dcraw_ppm_tiff_writer(const char *outfile)
- int LibRaw::dcraw_thumb_writer(const char *thumbfile)
Запись распакованых данных в буфер в памяти
Абстракция ввода

Объект LibRaw

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

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

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

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

LIBRAW_OPTIONS_NO_MEMERR_CALLBACK не устанавливать стандартный обработчик ошибки нехватки памяти (стандартный обработчик печатает сообщение об ошибке в stderr).
LIBRAW_OPTIONS_NO_DATAERR_CALLBACK не устанавливать стандартный обработчик ошибки чтения файла (стандартный обработчик печатает сообщение об ошибке в stderr).

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

Загрузка данных из RAW-файла
Функции пост-обработки, эмулирующие поведение dcraw
Функции записи в файл, эмулирующие поведение dcraw

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

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

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

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

int LibRaw::open_datastream(LibRaw_abstract_datastream *stream)

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

imgdata.idata (libraw_iparams_t),
imgdata.sizes (libraw_image_sizes_t),
imgdata.color (libraw_colordata_t),
imgdata.other (libraw_imgother_t) и
imgdata.thumbnail (libraw_thumbnail_t).

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

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

Входной параметр: Объект класса, производного от LibRaw_abstract_datastream. Объект должен быть проиницализирован и готов к чтению. Деинициализация объекта производится в вызвавшем приложении.

int LibRaw::open_file(const char *filename[,INT64 bigfile_size])

Win32 only: int LibRaw::open_file(const wchar_t *filename[,INT64 bigfile_size])

Создает объект LibRaw_file_datastream или LibRaw_bigfile_datastream, вызывает open_datastream(), при успехе выставляет внутренний флаг, сигнализирующий о том, что созданный объект должен быть уничтожен при recycle(), при неуспехе открытия - уничтожает только что созданный объект.

Необязательный Параметр bigfle_size задает размер входного файла, начиная с которого происходит использование LibRaw_bigfile_datastream. По-умолчанию, этот размер равен 250 Мб.

int LibRaw::open_buffer(void *buffer, size_t bufsize)

Создает объект LibRaw_buffer_datastream, вызывает open_datastream(), при успехе выставляет внутренний флаг, сигнализирующий о том, что созданный объект должен быть уничтожен при recycle(), при неуспехе открытия - уничтожает только что созданный объект.

int LibRaw::unpack(void)

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

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

int LibRaw::unpack_thumb(void)

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

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

Информация о версии библиотеки

const char* LibRaw::version()

Возвращает строковое представление версии библиотеки в формате MAJOR.MINOR.PATCH-Status (например, 0.6.0-Alpha2 или 0.6.1-Release).

int LibRaw::versionNumber()

Возвращает целочисленное представление версии библиотеки. При выходе новых версий библиотеки версия всегда не убывает.

bool LIBRAW_CHECK_VERSION(major,minor,patch)

Макрос для проверки версии в прикладных программах. Возвращает true если текущая версия библиотеки больше или равна переданной в параметрах. Макрос выполняется динамически и может использоваться для проверки версии библиотеки, загружаемой из shared library/DLL.

Список поддерживаемых форматов (камер)

int LibRaw::cameraCount()

Возвращает количество камер, поддерживаемых текущей версией библиотеки.

const char** LibRaw::cameraList()

Возвращает cписок камер, поддерживаемых библиотекой. Список на 1 элемент длиннее, чем количество камер, в последнем элементе списка содержится NULL.

Прочие вспомогательные функции

int LibRaw::set_rawspeed_camerafile(char *path_to_cameras_xml)

(Только для LibRaw, скомпилированной с поддержкой библиотеки RawSpeed)

Получает имя файла, содержащего Читает XML-описание камер (cameras.xml)

int LibRaw::get_decoder_info(libraw_decoder_info_t *)

Функция заполняет структуру libraw_decoder_info_t по переданному указателю данными о текущем декодере.

const char* LibRaw::unpack_function_name()

Возвращает имя функции-распаковщика файла. Интересна только разработчикам тестов для LibRaw, чтобы проверить test coverage.

void LibRaw::subtract_black()

Вызов производит вычитание уровня черного из RAW-данных, если вычитание не произведено самой камерой. При этом соответствующим образом исправляются поля colordata.data_maximum, colordata.data_maximum и даные об уровне черного (colordata.black и colordata.cblack).

Данный вызов надлежит использовать в случае, когда вы хотите делать постпроцессинг RAW-данных самостоятельно. Встроенные в LibRaw функции постпроцессинга вызовут subtract_black() самостоятельно.

void LibRaw::recycle_datastream(void)

Этот вызов позволяет освободить file handle (и ассоциированные буферы), если ваше приложение больше не собирается вызывать unpack() или unpack_thumb() и, следовательно, может разблокировать файл и освободить память, которая использовалась для чтения RAW-файла.

void LibRaw::recycle(void)

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

LibRaw::~LibRaw()

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

const char* LibRaw::strprogress(enum LibRaw_progress code)

Выдает текстовую расшифровку (на английском языке) для кодов текущей стадии обработки LibRaw

const char* LibRaw::strerror(int errorcode)

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

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

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

Динамическая отрисовка статуса обработки изображения.
Досрочное прекращение процесса обработки (например, по запросу пользователя)

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

нехватка памяти
ошибка чтения данных

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

Индикация стадий обработки/досрочное ее прекращение

        typedef int (*progress_callback)(void *callback_data,enum LibRaw_progress stage, int iteration, int expected);
        void LibRaw::set_progress_handler(progress_callback func,void *callback_data);

Пользователь может определить свою функцию, которая будет многократно (10-50 раз) вызываться в процессе обработки данных RAW-файла вызовами dcraw_process().

Этот callback может сигнализировать о необходимости прекратить обработку путем возврата ненулевого значения. В этом случае обработка будет завершена, память освобождена вызовом recycle() и объект LibRaw будет готов к обработке следующего файла. Текущий вызов dcraw_process() вернет код ошибки LIBRAW_CANCELLED_BY_CALLBACK.

Параметры вызова:

void *callback_data: void*-указатель, переданный при установке callback через set_memerror_handler. Используется для передачи в callback дополнительных данных
enum LibRaw_progress stage: Текущая стадия обработки. Код может быть превращен в строку путем вызова функции LibRaw::strprogress. Callback вызывается не на всех стадиях обработки, а только на тех, которые могут занять большое время.
int iteration: Номер итерации обработки (от 0 до expected-1). Внутри стадии обработки callback вызывается более одного раза, номер итерации внутри одной стадии всегда возрастает.
int expected: Ожидаемое количество итераций на этой стадии обработки

Возвращаемые значения: 0 если обработку можно продолжить, ненулевое число - если обработку следует немедленно прекратить.

При использовании OpenMP порядок следования iteration неопределен, они не обязаны строго возрастать.

Пример кода callback:

int my_progress_callback(void *data,enum LibRaw_progress p,int iteration, int expected)
{
    char *passed_string = (char *data);
    printf("Callback: %s  pass %d of %d, data passed: %s\n",libraw_strprogress(p),iteration,expected,passed_string);
    if(timeout || key_pressed )
        return 1; // cancel processing immediately
    else
        return 0; // can continue
}

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

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

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

callback_data - void*-указатель, переданный при установке callback через set_memerror_handler. Используется для передачи в callback дополнительных данных
file - имя RAW-файла при обработке которого произошла ошибка нехватки памяти. Это имя файла может быть нулевым - в случае, когда оно неизвестно модулю получения данных. Callback должен правильно обрабатывать случай нулевого имени.
where - имя функции в которой не хватило памяти;

Задача 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)(void *callback_data,const char *file, const int offset);
        void LibRaw::set_dataerror_handler(data_callback func,void *callback_data);

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

callback_data - void*-указатель, переданный при установке callback через set_memerror_handler. Используется для передачи в callback дополнительных данных
file: имя RAW-файла при обработке которого произошла ошибка нехватки памяти, этот параметр может быть нулевым (NULL), вызываемый callback должен корректно обрабатывать этот случай.
offset: -1 если файл закончился (тогда как LibRaw ожидает там еще данные), положительное число - позиция в файле (в байтах от начала), где возникла ошибка распаковки.

Если не установить свой обработчик, то будет использован стандартный (печать сообщения об ошибке в 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::raw2image

Функция аллоцирует буфер для постобработки imgdata.image, предварительно освобождая его, если он уже был аллоцирован, и заполняет его данными в формате, совместимыми с версиями LibRaw 0.13 и старше.

Эту функцию следует вызывать самостоятельно только если вы собираетесь самостоятельно обрабатывать RAW-данные и ваш код рассчитан на LibRaw 0.13 и более старые версии. Функции постпроцессинга (см. ниже) вызывают raw2image() самостоятельно.

void LibRaw::free_image

Этот вызов освобождает буфер imgdata.image, аллоцированный вызовом raw2image();

Эту функцию следует вызывать, если текущий результат постпроцессинга уже не нужен (например, скопирован куда-то), но возможны повторные вызовы постпроцессинга тех же данных (например, с другими параметрами), поэтому вызывать recycle() еще рано.

int LibRaw::adjust_sizes_info_only(void)

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

файлы от камер Fuji (повернутые на 45 градусов);
файлы от камер с неквадратными пикселами;
изображения, снятые повернутой камерой.

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

int LibRaw::dcraw_process(void)

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

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

вычитания dark frame
работы с bad pixels

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

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

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

int LibRaw::dcraw_ppm_tiff_writer(const char *outfile)

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

int LibRaw::dcraw_thumb_writer(const char *thumbfile)

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

Запись распакованых данных в буфер в памяти

Помимо записи в файл, библиотека предоставляет возможности записи извлеченных и обработанных функциями dcraw_* данных в буфер в памяти. Для этого имеются такие вызовы:

get_mem_image_format - возвращает размер битмепа и его битность
copy_mem_image - копирует постпроцессированное изображение в произвольный буфер с заданным шагом (stride) строк и с заданным порядком данных в пикселе (RGB/BGR)
dcraw_make_mem_image - преобразование извлеченных данных в RGB-битмэп нужного размера.
dcraw_make_mem_thumb - извлечение thumbnail в виде образа JPEG-файла в памяти, либо (для тех камер, где preview - не JPEG) в виде RGB-bitmap.

Пример использования этих функций - mem_image (см. каталог samples/ дистрибутива).

void get_mem_image_format(int widthp, int heightp, int colorsp, int bpp) const - возвращает размеры обработанного изображения

Значения (размеры изображения) возвращаются в переменных, заданных указателями:

Ширина изображения в пикселах - в *widthp;
Высота - в *heightp;
Количество цветов изображения - в *colorsp;
Битность изображения (8 или 16) в *bpp;

int LibRaw::copy_mem_image(void* scan0, int stride, int bgr) - копирует постпроцессированное изображение в виде битмепа в произвольный буфер

Параметры функции:

void *scan0 - указатель на буфер. Буфер аллоцируется вызывающим приложением и должен быть не меньше чем stride*image_height
int stride - шаг (stride) строки изображения в байтах. Обычно должен быть равен image_width*(bits_per_pixel/8*image_colors, но может быть больше, если, например, строки изображения хочется выровнять на 8 (16, 32) байта.
int bgr - порядок следования цветов пиксела. RGB для bgr==0 и BGR в остальных случаях.

The function returns an integer number in accordance with the error code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

libraw_processed_image_t dcraw_make_mem_image(int errorcode=NULL) - запись распакованного изображения в буфер в памяти

Аллоцирует буфер необходимого размера и записывает в него распакованное и обработанное изображение. Возвращает аллоцированную структуру libraw_processed_image_t с заполненными полями. Всегда возвращает распакованый bitmap (т.е. поле type возвращаемой структуры равно LIBRAW_IMAGE_BITMAP).

Перед вызовом этой функции должна быть вызвана dcraw_process().

В случае ошибки возвращается NULL. Если в качестве аргумента errorcode передан ненулевой указатель, то по адресу указателя записывается код ошибки в соответствии с соглашением о кодах возврата.

Внимание! Память, аллоцированная функцией, не освобождается при вызове деструктора или LibRaw::recycle и должна быть освобождена вызвавшим приложением путем вызова LibRaw::dcraw_clear_mem().

libraw_processed_image_t dcraw_make_mem_thumb(int errorcode=NULL) - запись распакованного thumbnail в буфер в памяти

Аллоцирует буфер необходимого размера и записывает в него thumbnail. Возвращает аллоцированную структуру libraw_processed_image_t с заполненными полями. Для большинства типов RAW-файлов в структуре будет содержаться JPEG, (т.е. поле type возвращаемой структуры равно LIBRAW_IMAGE_JPEG), для некоторых типов камер - RGB-bitmap.

Перед вызовом этой функции должна быть вызвана unpack_thumb();

void LibRaw::dcraw_clear_mem(libraw_processed_image_t *)

Освобождает память, аллоцированную dcraw_make_mem_image и dcraw_make_mem_thumb.

Это статический член класса, вызывать его нужно как LibRaw::dcraw_clear_mem(...).

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

Абстракция ввода

class LibRaw_abstract_datastream - абстрактный интерфейс чтения RAW-файлов

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

Методы класса LibRaw_abstract_datastream

Верификация объекта

virtual int valid(): Проверка валидности потока. Метод возвращает 1 если поток сконструирован правильно и 0 если из данного потока нельзя читать (передали несуществующее имя файла для файлового потока и т.п.).