LibRaw: структуры данных и константы

Структуры данных LibRaw определены в заголовочном файле libraw/libraw_types.h
Используемые константы определены в файле libraw/libraw_const.h

Содержание:

1. Структуры данных
   1. libraw_data_t - основная структура данных LibRaw
   2. Структура libraw_iparams_t - основные параметры изображения
   3. Структура libraw_image_sizes_t - размеры изображения
   4. Структура libraw_colordata_t - информация о цвете
   5. Структура color_data_state_t - описание источника цветовых данных
   6. Структура libraw_imgother_t - прочие параметры изображения
   7. Структура libraw_thumbnail_t - описание Thumbnail
   8. Структура libraw_output_params_t - управление постобработкой в стиле dcraw
   9. Структура libraw_masked_t - сохраненные значения пикселов черной рамки (маскированных пикселов)
   10. Структура libraw_processed_image_t - данные, выводимые функциями dcraw_make_mem_image()/dcraw_make_mem_thumb()
2. Объекты абстракции ввода данных
   • Поля данных
3. Константы
   1. enum LibRaw_errors - коды ошибок
   2. Нештатные ситуации (warnings) возникающие при обработке RAW-данных
   3. enum LibRaw_progress - текущее состояние объекта LibRaw
   4. enum LibRaw_thumbnail_formats - форматы данных Thumbnails
   5. enum LibRaw_colorstate - описание источника данных о цветовой информации
   6. enum LibRaw_filtering - настройки фильтрации данных на этапе распаковки и постобработки
   7. enum LibRaw_image_formats - описание типов данных, содержащихся в структуре libraw_processed_image_t

Структуры данных

libraw_data_t - основная структура данных LibRaw

Структура libraw_data_t - это "обертка" для структур данных, доступных пользователю библиотеки.
При использовании C++ API она доступна как LibRaw::imgdata (экземпляр_класса.imgdata). Данные в этой структуре появляются после открытия файла через open_file, за исключением собственно изображения (заполняется по unpack()) и данных содержащих preview-данные (заполняются по вызову unpack_thumb())
Поля данных:

unsigned int progress_flags;

В этом поле фиксируются проведенные фазы обработки изображения.

unsigned int progress_flags;

В этом поле фиксируются подозрительные ситуации (warnings), возникшие при обработке изображения.

libraw_iparams_t idata;

В этой структуре описаны извлеченные из RAW-файла основные параметры изображения. Детально поля структуры описаны ниже.

libraw_image_sizes_t sizes;

В этой структуре описаны геометрические параметры изображения. Детально поля структуры описаны ниже.

libraw_colordata_t color;

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

libraw_imgother_t other;

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

libraw_thumbnail_t thumbnail;

Структура данных, содержащая информацию о preview и сами данные preview. Все поля структуры кроме собственно данных preview заполняются в open_file() или других вызовах открытия потока (open_buffer(),open_datastream()), само изображение-preview считывается отдельным вызовом unpack_thumb(). Детально поля структуры описаны ниже.

libraw_masked_t masked_pixels;

Структура данных, содержащая пикселы "темной рамки" (маскированных пикселов). Поля структуры детально описаны ниже. Структура заполняется на этапе чтения данных unpack().

ushort (*image)[4];

Регион памяти, содержащий собственно пиксели изображения, заполняется при вызове unpack();

libraw_output_params_t params;

Структура данных, предназначенная для управления пост-обработкой изображения (при использовании эмулятора dcraw). Детально поля структуры описаны ниже.

Структура libraw_iparams_t - основные параметры изображения

char make[64];

Изготовитель камеры.

char model[64];

Модель камеры.

unsigned raw_count;

Количество RAW-изображений в файле (0 - означает что файл не распознан).

unsigned dng_version;

Версия DNG (для DNG-формата).

unsigned is_foveon;

1 для матриц Foveon, 0 - для остальных.
Матрицы Foveon поддерживаются в LibRaw-demosaic-pack-GPL2

int colors;

Количество цветов в файле.

unsigned filters;

Битовая маска, описывающая порядок цветовых пикселей в матрице (0 - для полноцветных RAW). 32 бита поля описывают 16 пикселов (8 строк по 2 пиксела, слева направа и сверху вниз), каждые два бита имеют значения от 0 до 3, соответствующие 4-м возможным цветам. Для удобной работы с этим полем предназначена функция COLOR(row,column) возвращающая номер активного цвета для данного пиксела.

char cdesc[5];

Описание цветов с номерами 0-3 (RGBG,RGBE,GMCY или GBTG).

Структура libraw_image_sizes_t - размеры изображения

В структуру libraw_image_sizes_t собраны все данные из файла, описывающие размеры изображения.
Поля данных:

ushort raw_height, raw_width;

Полный размер RAW-изображения (включая рамку) в пикселах.

ushort height, width;

Размер видимой (содержательной) части изображения (без рамки).

ushort top_margin, left_margin;

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

ushort bottom_margin, right_margin;

Ширина в пикселах нижней и правой части черной рамки (маскированных пикселов).

ushort iheight, iwidth;

Размер выходного изображения (может отличаться от height/width для камер, где требуется поворот изображения, либо где пиксели неквадратные).

double pixel_aspect;

Отношение ширины пикселя к высоте. Если оно отличается от единицы, то при выводе требуется масштабирование изображения по одной из осей.

int flip;

Ориентация изображения (0 - не требует поворота, 3 - требуется поворот на 180, 5 - 90 градусов против часовой стрелки, 6 - 90 градусов по часовой).

Структура libraw_colordata_t - информация о цвете

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

color_data_state_t color_flags;

Структура данных, описывающая источники получения цветовых данных. Подробнее описана ниже

ushort white[8][8];

Блок белых пикселей, извлекаемый из файлов CIFF/CRW. Для других форматов не извлекается, используется для расчетов коэффициентов баланса белого.

float cam_mul[4];

Коэффициенты баланса белого (as shot). Либо считывается из файла, либо рассчитывается.

float pre_mul[4];

Коэффициенты баланса белого для дневного света (Daylight balance). Либо считывается из файла, либо рассчитывается из данных файла, либо берутся hardcoded-константы.

float cam_xyz[4][3];

Матрица преобразования из камерного RGB в XYZ. Константная таблица, разная для разных камер, полный аналог ColorMatrix формата DNG. Последняя строка для RGB-камер как правило нулевая, для CMYG и подобных - не нулевая.

float cmatrix[3][4];

Матрица баланса белого, для части камер считывается из файла, из остальных рассчитывается.

float rgb_cam[3][4];

Еще одна матрица баланса белого, считывается из файла для камер Leaf и Kodak.

ushort curve[0x4001];

Camera tone curve, считывается для камер Nikon, Sony и некоторых других.

unsigned black;

Уровень черного. Для некоторых камер будет равен нулю (что означает, что вычитание черного проведено на этапе распаковки или самой камерой), для некоторых камер рассчитывается на этапе распаковки, для некоторых - считывается из RAW-файла, для некоторых - hardcoded.

unsigned cblack[8];

Поканальные данные об уровне черного. Элементы массива с номерами 0-3 - сами поканальные данные (суммы на этапе распаковки, усредненные данные после распаковки), элементы с номерами 4-7 - поканальные счетчики черных пикселов для усреднения.

unsigned maximum;

Максимальное значение пикселя. Для ряда камер рассчитывается из данных, для ряда - hardcoded. Значение maximum может меняться на стадии постпроцессинга (после вычитания черного) и автоустановкой максимума на основании поканальных максимумов в реальных данных (регулируется параметром params.adjust_maximum_thr).

unsigned channel_maximum[4];

Максимальное значение пикселей по цветовым каналам, рассчитывается на этапе распаковки данных.

ph1_t phase_one_data;

Блок цветовых данных, считываемый для камер Phase One.

float flash_used;

float canon_ev;

Поля используются для расчета баланса белого (для некоторых P&S камер Canon).

char model2[64];

Для некоторых камер - версия Firmware.

void *profile;

Указатель на извлеченный ICC-профиль (если он есть в RAW-файле).

unsigned profile_length;

Длина ICC-профиля в байтах.

Структура color_data_state_t - описание источника цветовых данных

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

        unsigned curve_state        : 3;
        unsigned rgb_cam_state      : 3;
        unsigned cmatrix_state      : 3;
        unsigned pre_mul_state      : 3;
        unsigned cam_mul_state      : 3;
    

Каждое из полей принимает одно из значений, возможных для enum LibRaw_colorstate.

Структура libraw_imgother_t - прочие параметры изображения

В структуру libraw_imgother_t собраны данные, считанные из RAW-файла и не нужные для пост-обработки изображения.
Поля данных:

float iso_speed;

Чувствительность ISO.

float shutter;

Выдержка.

float aperture;

Диафрагма.

float focal_len;

Фокусное расстояние.

time_t timestamp;

Дата съемки.

unsigned shot_order;

Серийный номер изображения.

unsigned gpsdata[32];

GPS-данные.

char desc[512];

Описание изображения.

char artist[64];

Автор изображения.

Структура libraw_thumbnail_t - описание Thumbnail

Структура libraw_thumbnail_t описывает все параметры, связанные с сохраненным в RAW-файле preview.
Поля данных:

LibRaw_thumbnail_formats tformat;

Формат данных thumbnail. Одно из значений enum LibRaw_thumbnail_formats.

ushort twidth, theight;

Размер preview-изображения в пикселах.

unsigned tlength;

Длина thumbnail в байтах.

int tcolors;

Количество цветов preview.

char *thumb;

Указатель на thumbmail, извлеченный из файла данных.

Структура libraw_output_params_t - управление постобработкой в стиле dcraw

Структура libraw_output_params_t используется для управления dcraw-совместимыми вызовами dcraw_process(), dcraw_ppm_tiff_writer(), dcraw_thumb_writer(), dcraw_document_mode_processing(). Поля этой структуры соответствуют ключам командной строки программы dcraw.
Поля данных:

unsigned greybox[4];

Ключи dcraw: -A x1 y1 width height
4 числа, отвечающие координатам (в пикселах) прямоугольника по которому рассчитывается баланс белого: верхний левый угол, ширина и высота. Координаты задаются для неповернутого изображения.

unsigned cropbox[4];

Ключи dcraw:нет
4 числа, отвечающие координатам (в пикселах) прямоугольника, до которого будет обрезано результирующее изображение: верхний левый угол, ширина и высота. Координаты задаются для неповернутого изображения. Результат обрезания затем может быть повернут в соответствии со значениями flip и user_flip.

double aber[4];

Ключи dcraw: -C
Исправление хроматических аббераций, задаются только
aber[0] - множитель красного
aber[2] - множитель зеленого. Для ряда форматов влияет на чтение RAW-данных т.к. при коррекции аберраций выходной размер меняется.

double gamm[6];

Ключи dcraw: -g
Задание пользовательской гамма-кривой. Должны быть установлены первые два поля в массиве:
gamm[0] - инвертированный (1.0/g) показатель степени
gamm[1] - наклон для начальной линейной части. Для получения чистой степенной функции должно быть установлено в 0.
Остальные 4 значения в этом поле заполняются автоматически.

По-умолчанию используются настройки спецификации BT.709: степень 2.222, наклон 4.5. Для задания sRGB-кривой нужно ставить значения gamm[0]=1/2.4 и gamm[1]=12.92. Для простой степенной функции без линейного участка наклон линейной части задается нулевым, для линейной кривой нужно устанавливать gamm[0]=gamm[1]=1.

float user_mul[4];

Ключи dcraw: -r mul0 mul1 mul2 mul3
4 множителя (r,g,b,g) пользовательского баланса белого

unsigned shot_select, multi_out;

Ключи dcraw: -s
выбор номера изображения для обработки (для форматов, содержащих несколько RAW-изображений в одном файле) Режим multi_out ( -s all) нужно программировать самостоятельно, dcraw_process() его не поддерживает.

float bright;

Ключи dcraw: -b
Яркость (умолчание 1.0)

float threshold;

Ключи dcraw: -n
Параметр для подавления шума через wavelet denoising.

int half_size;

Ключи dcraw: -h
Выводить изображение в половинном размере. Для ряда форматов влияет на чтение RAW-данных.

int four_color_rgb;

Ключи dcraw: -f
Включает отдельную интерполяцию для двух зеленых компонент.

int document_mode;

Ключи dcraw: -d/-D
0 - стандартная обработка (с балансом белого)
1 - соответствует -d (без цветовой обработки и без дебайеризации)
2 - соответствует -D (-d без баланса белого)

int highlight;

Ключи dcraw: -H
0-9 - Highlight mode (0=clip, 1=unclip, 2=blend, 3+=rebuild)

int use_auto_wb;

Ключи dcraw: -a
Использовать автобаланс белого, полученный после усреднения всего изображения.

int use_camera_wb;

Ключи dcraw: -w
Использовать баланс белого полученный из камеры, если это возможно.

int use_camera_matrix;

Ключи dcraw: +M/-M
Использовать (1)/не использовать(0) camera color matrix.

int output_color;

Ключи dcraw: -o число
[0-5] Output colorspace (raw,sRGB,Adobe,Wide,ProPhoto,XYZ)

char* output_profile;

Ключи dcraw: -o имя файла
Путь к ICC-файлу выходного профиля (используется только если библиотека собрана с поддержкой LCMS)

char* camera_profile;

Ключи dcraw: -o имя файла
Путь к ICC-файлу профиля камеры (используется только если библиотека собрана с поддержкой LCMS)

char* bad_pixels;

Ключи dcraw: -P имя файла
Путь к файлу с картой плохих пикселов (в формате "столбец строка дата-появления в unix-формате", по одной записи на строку).

char* dark_frame;

Ключи dcraw: -K имя файла
Путь к файлу с темновым кадром (16-битный PGM-файл, полученный, например, запуском dcraw -D).

int output_bps;

Ключи dcraw: -4
8 bit (default)/ 16 bit (ключ -4)

int output_tiff;

Ключи dcraw: -T
0/1 - выводить PPM/TIFF

int user_flip;

Ключи dcraw: -t
[0-7] Flip image (0=none, 3=180, 5=90CCW, 6=90CW) Умолчание -1, означает брать из RAW.
Для ряда форматов влияет на чтение RAW-данных, в частности на распаковку thumbnails от камер Kodak.

int user_qual;

Ключи dcraw: -q
0-10: качество и вид интерполяции (дебайеризации):

• 0 - линейная интерполяция
• 1 - VNG-интерполяция
• 2 - PPG-интерполяция
• 3 - AHD-интерполяция
• 4 - DCB-интерполяция
• 5 - Модифицированная AHD-интерполяция
• 6 - AFD-интерполяция (5-проходов)
• 7 - VCD-интерполяция
• 8 - Смешанная VCD/измененная AHD
• 9 - LMMSE-интерполяция
• 10 - AMaZE-интерполяция

Значения 5-9 имеют смысл только если LibRaw скомпилирована с "LibRaw demosaic pack GPL2" (файл README.demosaic-packs в вашем дистрибутиве LibRaw описывает это в подробностях). Значение 10 (AMaZe-интерполяция) имеет смысл только если LibRaw скомпилирована с "LibRaw demosaic pack GPL3".
Если задан неподдерживаемый LibRaw вариант (например, demosaic pack не вкомпилирован), будет выполнена AHD-интерполяция.

int user_black;

Ключи dcraw: -k
Пользовательский уровень черного.

int user_sat;

Ключи dcraw: -S
Регулировка насыщенности.

int med_passes;

Ключи dcraw: -m
Количество проходов median filter

int no_auto_bright;

Ключи dcraw: -W
Не использовать автоматическое повышение яркости по гистограмме.

float auto_bright_thr;

Ключи dcraw:нет
Доля пикселов, которые будут насыщены при использовании автоматического повышения яркости. Значение по-умолчанию 0.01 (для совместимости с dcraw), рекомендованное стартовое значение для современных многомегапиксельных малошумных камер 0.001-0.00003.

float adjust_maximum_thr;

Ключи dcraw:нет
Этот параметр управляет авто-установкой значения maximum, используемого на стадии постпроцессинга. Если поканальный максимум (channel_maximum[]) больше чем maximum*adjust_maximum_thr, то поле maximum будет установлено в значение, рассчитанное по данным конкретного снимка.
Стандартное значение поля: 0.75. Если вы установите его больше чем 0.99999, то будет использовано стандартное значение. Если вы установите adjust_maximum_thr меньше чем 0.00001, то корректировка максимума будет выключена.
Автокорректировка максимума не должна повреждать снимки (особенно если используется стандартное значение), но очень полезна при обработке снимков с выбитыми (пересвеченными) участками и позволяет автоматически бороться с "розовыми облаками" (для дневного света) и с "сине-зелеными светами" (для освещения лампами накаливания).

int use_fuji_rotate;

Ключи dcraw: -j
Умолчание - 1 (использовать), 0 - отключает поворот для камер на сенсоре Fuji.

char *bpfile;

Ключи dcraw: -P
Имя файла с картой плохих пикселов.

char *dark_frame;

Ключи dcraw: -K
Имя файла с dark frame.

enum LibRaw_filtering filtering_mode;

Ключи dcraw: нет
Задает режим фильтрации RAW-данных (вычитание уровня черного, сглаживание нулевых пикселов, наложение тоновой кривой). Подробнее см. в описании режимов фильтрации и в перечислении этих режимов ниже.

int green_matching;

Включает подавление разбаланса чувствительности зеленых каналов. Ключи dcraw: нет
Умолчание - 0 (не использовать), 1 - включает этот этап обработки. Включение этого режима требует удвоенного количества памяти под bitmap.

int dcb_iterations

Ключи dcraw: нет
Количество циклов коррекции после DCB-алгоритма. Умолчание - нет коррекции.

int dcb_enhance_fl

Ключи dcraw: нет
ненулевое значение: усиливать цвета после DCB-интерполяции.

int fbdd_noiserd

Ключи dcraw: нет
Управляет алгоритмом подавления шума FBDD перед демозаикой (интерполяцией)

• 0 - не использовать FBDD
• 1 - легкое подавление шума
• 2 - полное подавление шума

int eeci_refine

Ключи dcraw: нет
ненулевое значение - Использовать алгоритм EECI refine после VCD+AHD-интерполяции.

int es_med_passes

Ключи dcraw: нет
Количество проходов медианного фильтра, чувствительного к границам для подавления артефактов VCD+AHD интерполяции. Значения больше 1 не рекомендуются.

int ca_correc

Ключи dcraw: нет
положительное значение - подавлять хроматическую аберрацию перед интерполяцией.

float cared,cablue

Ключи dcraw: нет
Если одно из этих полей имеет отличное от нуля значение, то автоматическая подборка параметров коррекции аберрации производиться не будет. Диапазон значений обеих полей: +-0.1..+-4.

int cfaline; float linenoise;

Подавление полосатости (banding).
cfaline - положительное значение включает подавление.
linenoise - степень подавления, разумный диапазон параметра от 0.001 до 0.02.

int cfa_clean; float lclean,cclean;

Подавляет импульсный (высокочастотный) шум.
cfa_clean: положительное значение включает подавление.
lclean,cclean - Степень подавления для яркостного (lclean) и цветового (cclean) шумов. Разумное значение от 0.005 до 0.05.

int cfa_green; float green_thresh;

Подавление "лабиринтных" артефактов, возникающих из-за неравенства каналов зеленого.
cfa_green - положительное значение включает подавление.
green_thresh - максимальное различие междк каналами при котором происходит выравнивание. Разумные значения от 0.01 до 0.1.

int exp_correc; float exp_shift,exp_preser;

Экспокоррекция перед байеровской интерполяцией.

• exp_correc: положительное значение включает экспокоррекцию (умолчание: выключено).
• exp_shift: экспозиционный сдвиг в линейной шкале. Нормально обрабатываются значения от 0.25 (затемнение на 2 ступени экспозиции) до 8.0 (осветление на 3 ступени). Умолчание: 1.0 (нет экспокоррекции).
• exp_preser: степень сохранения деталей в светах при осветлении изображения. Диапазон значений от 0.0 (линейный сдвиг экспозиции с вылетом светов) до 1.0 (максимальное сохранение деталей в светах). Умолчание: 0.0.

Структура libraw_masked_t - сохраненные значения пикселов черной рамки (маскированных пикселов)

Структура данных libraw_masked_t предназначена для хранения пикселов "черной рамки" - не входящих в видимое изображение, но используемых для расчета уровня черного, уровня темнового шума и прочих подобных вычислений. В отличие от буфера изображения, где для каждого пиксела аллоцировано 4 ushort-значения (одно из них заполняется при чтении RAW, а остальные используются при постпроцессинге), в буфере для маскированных пикселов нет избыточной аллокации и каждому пикселу соответствует одно 16-битное значение. Разные участки рамки хранятся в отдельных буферах внутри данной структуры, как показано на рисунке:

Поля данных:

ushort *buffer;

Буфер для хранения всех данных, имеет размер (raw_width*raw_height - width*height).

ushort *tl;

Указатель на участок буфера, предназначенный для хранения верхнего левого угла рамки. Размер этого участка буфера равен (top_margin*left_margin).

ushort *top;

Указатель на участок буфера, предназначенный для хранения верхней части раммки, над активной областью изображения. Размер равен (top_margin*width).

ushort *tr;

Указатель на участок буфера, предназначенный для хранения верхнего правого угла рамки. Размер этого участка буфера равен (top_margin*right_margin).

ushort *left;

Указатель на участок буфера, предназначенный для хранения части раммки, расположенной слева активной области изображения. Размер равен (left_margin*height).

ushort *right;

Указатель на участок буфера, предназначенный для хранения части раммки, расположенной справа активной области изображения. Размер равен (right_margin*height).

ushort *bl;

Указатель на участок буфера, предназначенный для хранения нижнего левого угла рамки. Размер этого участка буфера равен (bottom_margin*left_margin).

ushort *bottom;

Указатель на участок буфера, предназначенный для хранения нижней части раммки, под активной областью изображения. Размер равен (bottom_margin*width).

ushort *br;

Указатель на участок буфера, предназначенный для хранения нижнего правого угла рамки. Размер этого участка буфера равен (bottom_margin*right_margin).

ushort (*ph1_black)[2];

В этот буфер считываются данные об уровне черного для задников PhaseOne (количество элементов равно числу строк в данных, первое число в элементе относится к левой полустроке, второе - к правой.

class LibRaw_abstract_datastream {
...
protected:
    LibRaw_abstract_datastream *substream;
}