[вернуться к оглавлению]
LibRaw: структуры данных и константы
Структуры данных LibRaw определены в заголовочном файле libraw/libraw_types.h
Используемые константы определены в файле libraw/libraw_const.h
Содержание:
- Структуры данных
- libraw_data_t - основная структура данных LibRaw
- Структура libraw_iparams_t - основные параметры изображения
- Структура libraw_image_sizes_t - размеры изображения
- Структура libraw_colordata_t - информация о цвете
- Структура color_data_state_t - описание источника цветовых данных
- Структура libraw_imgother_t - прочие параметры изображения
- Структура libraw_thumbnail_t - описание Thumbnail
- Структура libraw_output_params_t - управление постобработкой в стиле
dcraw
- Константы
- enum LibRaw_errors - коды ошибок
- Нештатные ситуации (warnings) возникающие при обработке RAW-данных
- enum LibRaw_progress - текущее состояние объекта LibRaw
- enum LibRaw_thumbnail_formats - форматы данных Thumbnails
- enum LibRaw_colorstate - описание источника данных о цветовой
информации
Структуры данных
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 заполняются
Детально поля структуры описаны ниже.
- 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 - для остальных.
- int colors;
-
Количество цветов в файле.
- unsigned filters;
-
Битовая маска, описывающая порядок цветовых пикселей в матрице (0 - для Foveon). 32 бита поля описывают 16
пикселов (8 строк по 2 пиксела, слева направа и сверху вниз), каждые два бита имеют значения от 0 до 3,
соответствующие 4-м возможным цветам. Для удобной работы с этим полем предназначена функция FC(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 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 cmatrix[3][4];
-
Матрица баланса белого, для части камер считывается из файла, из остальных рассчитывается.
- float rgb_cam[3][4];
-
Еще одна матрица баланса белого, считывается из файла для камер Leaf и Kodak.
- ushort curve[0x4001];
-
Camera tone curve, считывается для камер Nikon, Sony и некоторых других.
- unsigned black;
-
Уровень черного. Для некоторых камер будет равен нулю (что означает, что вычитание черного проведено на этапе
распаковки или самой камерой), для некоторых камер рассчитывается на этапе распаковки, для некоторых -
считывается из RAW-файла, для некоторых - hardcoded.
- unsigned maximum;
-
Максимальное значение пикселя. Для ряда камер рассчитывается из данных, для ряда - hardcoded.
- ph1_t phase_one_data;
-
Блок цветовых данных, считываемый для камер Phase One.
- float flash_used;
- float canon_ev;
-
Поля используются для расчета баланса белого (для некоторых P&S камер Canon).
- char model2[64];
-
Описание баланса белого для камер Foveon.
- 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 x2 y2
4 числа, отвечающие координатам (в пикселах) прямоугольника по которому рассчитывается баланс белого.
- double aber[4];
-
Ключи dcraw: -C
Исправление хроматических аббераций, задаются только
aber[0] - множитель красного
aber[2] - множитель зеленого.
Для ряда форматов влияет на чтение RAW-данных т.к. при коррекции аберраций
выходной размер меняется.
- 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)
- 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-3 - качество интерполяции (0 - linear, 1- VNG, 2 - PPG, 3 - AHD).
- int user_black;
-
Ключи dcraw: -k
Пользовательский уровень черного.
- int user_sat;
-
Ключи dcraw: -S
Регулировка насыщенности.
- int med_passes;
-
Ключи dcraw: -m
Количество проходов median filter
- int no_auto_bright;
-
Ключи dcraw: -W
Не использовать автоматическое повышение яркости по гистограмме.
- int use_fuji_rotate;
-
Ключи dcraw: -j
Умолчание - 1 (использовать), 0 - отключает поворот для камер на сенсоре Fuji.
- char *bpfile;
-
Ключи dcraw: -P
Имя файла с картой плохих пикселов.
- char *dark_frame;
-
Ключи dcraw: -K
Имя файла с dark frame.
Константы
enum LibRaw_errors - коды ошибок
Все функции, возвращающие целые числа, возвращают либо errno, либо один из следующих кодов ошибок (см. также соглашения о кодах ошибок)
Фатальные ошибки (получение такого кода ошибки означает безусловное прекращение обработки файла, ибо
структуры данных находятся в неизвестном состоянии).
- LIBRAW_UNSUFFICIENT_MEMORY
- Попытка получения памяти от системы закончилась неудачей.
Все аллоцированные ресурсы будут освобождены, вызвана функция recycle(), объект LibRaw приведен в состояние "сразу после создания".
- LIBRAW_DATA_ERROR
- При распаковке данных возникла фатальная ошибка.
Все аллоцированные ресурсы будут освобождены, вызвана функция recycle(), объект LibRaw приведен в состояние "сразу после создания".
- LIBRAW_IO_ERROR
- При чтении файла возникла фатальная ошибка (файл закончился раньше времени, либо поврежден).
Все аллоцированные ресурсы будут освобождены, вызвана функция recycle(), объект LibRaw приведен в состояние "сразу после создания".
Нефатальные ошибки
- LIBRAW_SUCCESS=0
- Нет ошибки, функция завершилась успешно.
- LIBRAW_UNSPECIFIED_ERROR
- Произошла неизвестная ошибка. Этот код не должен выдаваться никогда.
- LIBRAW_FILE_UNSUPPORTED
- Не поддерживаемый формат файла (попытка открыть RAW-файл неизвестного программе формата).
- LIBRAW_REQUEST_FOR_NONEXISTENT_IMAGE
- Попытка извлечь RAW-изображение с номером, не существующим в файле данных (только для форматов,
поддерживающих хранение нескольких изображений в одном файле).
- LIBRAW_OUT_OF_ORDER_CALL
- Функции API вызывались в неправильном порядке (например, unpack() до
open_file()), либо предыдущая стадия
завершилась с ошибкой (например, вызываем unpack() если open_file() вернула ошибку).
- LIBRAW_NO_THUMBNAIL
- Возвращается при попытке получить thumbnail из файла, не содержащего preview.
- LIBRAW_UNSUPPORTED_THUMBNAIL
- RAW-файл содержит preview неподдерживаемого формата.
enum LibRaw_progress - текущее состояние объекта LibRaw
В LibRaw::imgdata.progress_flags содержится битовая маска, описывающая все стадии обработки, уже проведенные
над файлом.
Фаза открытия файла и извлечения RAW-данных.
- LIBRAW_PROGRESS_START=0
-
Объект только создан, никакой обработки не проводилось.
- LIBRAW_PROGRESS_OPEN
-
Обрабатываемый файл открыт
- LIBRAW_PROGRESS_IDENTIFY
-
Проведена идентификация данных, формат опознан, извлечены метаданные.
- LIBRAW_PROGRESS_SIZE_ADJUST
-
Проведено выравнивание размеров данных (для тех файлов, которым это нужно, а это некоторые файлы с камер
Kodak).
- LIBRAW_PROGRESS_LOAD_RAW
-
Загружены RAW-данные.
Следующие флаги выставляются при использовании обработки изображений, позаимствованной у dcraw.
- LIBRAW_PROGRESS_REMOVE_ZEROES
-
Удалены нулевые значения для тех камер, для которых это нужно (камеры Panasonic).
- LIBRAW_PROGRESS_RESERVED_PRE1-LIBRAW_PROGRESS_RESERVED_PRE2
-
Зарезервированы под возможные будущие стадии обработки "до дебайеризации".
- LIBRAW_PROGRESS_FOVEON_INTERPOLATE
-
Проведена интерполяция для камер с сенсором Foveon.
- LIBRAW_PROGRESS_SCALE_COLORS
-
Произведена балансировка белого.
- LIBRAW_PROGRESS_PRE_INTERPOLATE
-
Проведено уменьшение изображения (для режима half_size) и копирование 2-го канала зеленого в первый
в тех точках, где 2-й канал есть, а первого - нет.
- LIBRAW_PROGRESS_INTERPOLATE
-
Проведена интерполяция (де-байеризация).
- LIBRAW_PROGRESS_MIX_GREEN
-
Проведено усреднение каналов зеленого.
- LIBRAW_PROGRESS_MEDIAN_FILTER
-
Проведена медианная фильтрация.
- LIBRAW_PROGRESS_HIGHLIGHTS
-
Проведена работа со светами.
- LIBRAW_PROGRESS_FUJI_ROTATE
-
Для изображений с камер Fuji проведен поворот (либо вызвана adjust_sizes_info_only()).
- LIBRAW_PROGRESS_FLIP
-
Для изображений, снятых повернутой камерой, произведен пересчет размеров (sizes.iwidth/sizes.iheight поменяли местами).
- LIBRAW_PROGRESS_CONVERT_RGB
-
Проведена конверсия в выходное RGB-пространство.
- LIBRAW_PROGRESS_STRETCH
-
Произведено изменение размеров изображения для камер с неквадратными пикселами.
- LIBRAW_PROGRESS_STAGE17 - LIBRAW_PROGRESS_STAGE27
-
Зарезервировано на случай появления других стадий обработки.
Следующие флаги выставляются при загрузке thumbnails.
LIBRAW_PROGRESS_THUMB_LOAD
Произведена загрузка данных Thumbnail (для камер Kodak - еще сделаны необходимые преобразования).
LIBRAW_PROGRESS_TRESERVED1 - LIBRAW_PROGRESS_TRESERVED3
Зарезервировано на случай появления других стадий обработки.
enum LibRaw_thumbnail_formats - форматы данных Thumbnails
Формат данных thumbnail записывается в поле данных imgdata.thumbnail.tformat.
На сегодняшний день LibRaw знает о четырех форматах thumbnail из которых распаковываются два:
- LIBRAW_THUMBNAIL_UNKNOWN
- Формат неизвестен или thumbnail еще не читался.
- LIBRAW_THUMBNAIL_JPEG
- В буфере thumbnail лежит JPEG-файл (считанный as-is из RAW-файла, каких-либо манипуляций над ним не
проводится).
- LIBRAW_THUMBNAIL_BITMAP
-
В буфере для thumbnaill лежит гамма-скорректированный RGB-bitmaip (для камер Kodak гамма-коррекция проводится
с учетом максимальных значений, а баланс белого выставляется в соответствии с настройками камеры)
В этом формате каждый пиксель изображения представлен 8-битным RGB-триплетом.
- LIBRAW_THUMBNAIL_LAYER
-
Формат данных в настоящее время распознается при открытии RAW-файла, но не поддерживается: не распаковывается
в LibRaw::unpack_thumb.
- LIBRAW_THUMBNAIL_ROLLEI
-
Формат данных в настоящее время распознается при открытии RAW-файла, но не поддерживается: не распаковывается
в LibRaw::unpack_thumb.
Нештатные ситуации (warnings) возникающие при обработке RAW-данных
При обработке изображений могут возникнуть сомнительные ситуации, не являющиеся фатальными, но возможно
влияющие на результат извлечения данных или их постобработки. Индикация таких состояний производится путем
установки бита в поле imgdata.process_warnings
- LIBRAW_WARN_FOVEON_NOMATRIX
- Только для камер на Foveon: не удалось извлечь одну из матриц данных.
- LIBRAW_WARN_FOVEON_INVALIDWB
-
Только для камер на Foveon: не удалось извлечь данные о балансе белого.
- LIBRAW_WARN_BAD_CAMERA_WB
-
При постобработке задано использовать баланс белого камеры, а он непригоден для использования.
- LIBRAW_WARN_NO_METADATA
-
Только для камер, где метаданные берутся из внешнего jpeg: не удалось извлечь метаданные.
- LIBRAW_WARN_NO_JPEGLIB
-
Только для P&S камер Kodak: данные в формате JPEG. Одновременно open_file() вернет LIBRAW_FILE_UNSUPPORTED.
enum LibRaw_colorstate - описание источника данных о цветовой информации
Для каждого типа извлекаемой цветовой информации (см. выше описание структуры imgdata.color.color_flags)
записывается источник получения данных. Возможные значения перечислены ниже.
- LIBRAW_COLORSTATE_UNKNOWN
-
Источник данных неизвестен.
- LIBRAW_COLORSTATE_INIT
-
Поле данных инициализировано в умолчание (общее для всех
камер) перед открытием RAW-файла.
- LIBRAW_COLORSTATE_CONST
-
Источник данных - константа, забитая в код.
- LIBRAW_COLORSTATE_LOADED
-
Данные загружены из RAW-файла.
- LIBRAW_COLORSTATE_CALCULATED
-
Данные рассчитаны на основании RAW-данных.
- LIBRAW_COLORSTATE_RESERVED1-LIBRAW_COLORSTATE_RESERVED3
-
Зарезервировано.
[вернуться к оглавлению]
Alex Tutubalin
Last modified: Sat Apr 19 17:10:19 MSD 2008