LibRaw — это программный продукт для работы с RAW-файлами на низком уровне: чтение данных сенсора, извлечение технических метаданных, доступ к встроенным превью, распаковка RAW-данных и базовая RAW-конвертация. Это не фоторедактор в духе Lightroom, RawTherapee или darktable, а библиотека и набор консольных утилит, на которых можно строить RAW viewer, RAW converter, анализатор данных матрицы, модуль импорта в фоторедактор, пакетный конвертер или внутренний компонент DAM-системы. LibRaw решает именно ту часть задачи, которую сложнее всего писать самостоятельно: распознавание множества камерных RAW-форматов, чтение служебных полей, обработка особенностей сжатия, извлечение Bayer/CFA-структуры, черного уровня, баланса белого, геометрии кадра и встроенных миниатюр.

Главная особенность LibRaw в том, что программа выглядит не как окно с кнопками, а как интерфейс для разработчика. Ее панели управления — это класс LibRaw, структура imgdata, параметры imgdata.params, методы open_file(), unpack(), unpack_thumb(), dcraw_process(), dcraw_ppm_tiff_writer(), функции C API и консольные примеры вроде raw-identify, simple_dcraw, dcraw_half, dcraw_emu. Через них приложение получает доступ к исходным RAW-данным и решает, что делать дальше: показать превью, построить собственный демозаик, сохранить TIFF, извлечь JPEG-миниатюру, проверить поддержку камеры или передать массив пикселей в собственный image processing pipeline.

В прикладных программах LibRaw может быть почти незаметной для обычного пользователя. Например, в digiKam она проявляется как модуль Import Raw Using Libraw: справа находятся вкладки Raw Decoding, Post Processing, Info, гистограмма, блоки Demosaicing, White Balance, Corrections, кнопки Import, Update, Reset, Use Default. Это не собственный графический интерфейс LibRaw, а пример того, как программа-хост выводит наружу параметры библиотеки. Такой подход хорошо показывает реальное назначение LibRaw: она отвечает за чтение и первичную интерпретацию RAW, а визуальная оболочка, история правок, каталог, рейтинги, маски и экспорт — уже задача приложения, которое ее использует.

Назначение LibRaw

LibRaw нужна там, где программа должна понимать RAW-файлы цифровых камер не на уровне открыть картинку, а на уровне получить данные, с которыми можно работать дальше. RAW — это не готовое изображение вроде JPEG или PNG. Внутри находится массив значений с сенсора, служебные области, черные поля, данные о цветофильтровой решетке, баланс белого, ориентация, сведения о камере, иногда несколько встроенных превью и дополнительная производительская информация. Без такого слоя, как LibRaw, разработчику пришлось бы отдельно разбираться с CR2, CR3, NEF, NRW, ARW, RAF, RW2, ORF, PEF, DNG, MOS, KDC, DCR и другими форматами, а также учитывать различия между моделями камер и поколениями их RAW-кодеков.

LibRaw закрывает несколько конкретных задач:

• открывает RAW-файл и определяет его тип;

• читает EXIF и технические метаданные, необходимые для RAW processing;

• извлекает геометрию кадра: размеры исходного RAW, видимую область, ориентацию, итоговую ширину и высоту;

• определяет CFA/Bayer pattern или другую структуру сенсора;

• извлекает black level, white level, коэффициенты баланса белого и цветовые матрицы;

• распаковывает RAW-данные в память;

• извлекает embedded preview / thumbnail;

• выполняет базовую постобработку в стиле dcraw;

• записывает простой результат в PPM или TIFF;

• отдает обработанное изображение в память для дальнейшей работы в приложении.

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

Чем LibRaw отличается от обычного RAW-редактора

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

Сильная сторона LibRaw — не финальная цветокоррекция, а декодирование. Она берет на себя слой, который находится до творческой обработки:

Задача	Как это делает LibRaw
Определить камеру и формат	Читает структуру файла и заполняет imgdata.idata
Получить размеры RAW	Заполняет imgdata.sizes
Получить цветовые данные	Заполняет imgdata.color
Получить технические сведения	Заполняет imgdata.other, imgdata.makernotes, другие служебные блоки
Распаковать сенсорные данные	Выполняет unpack()
Извлечь превью	Выполняет unpack_thumb() или unpack_thumb_ex()
Сделать простую проявку	Выполняет dcraw_process()
Сохранить результат	Использует dcraw_ppm_tiff_writer() или возвращает буфер через dcraw_make_mem_image()

Это важное различие. Если нужна программа для ручной обработки фотографий, LibRaw сама по себе не подойдет. Если нужна библиотека RAW image decoder для собственного приложения, LibRaw как раз попадает в задачу.

Поддерживаемые RAW-файлы и типы данных

LibRaw работает с RAW-файлами цифровых камер: CRW/CR2/CR3 у Canon, NEF/NRW у Nikon, ARW/SR2/SRF у Sony, RAF у Fujifilm, RW2 у Panasonic, ORF у Olympus/OM System, PEF у Pentax, DNG, MOS, KDC, DCR и рядом других форматов. Важна не только поддержка расширения, но и поддержка конкретной модели камеры, потому что внутри одного расширения могут отличаться кодек, расположение метаданных, сжатие, цветовая информация и служебные области.

LibRaw извлекает не только пиксели. Для RAW-конвертера важны данные, которые определяют дальнейшую интерпретацию изображения:

• геометрия кадра — фактический размер RAW, видимая область, поворот, итоговый размер изображения;

• CFA/Bayer pattern — порядок цветовых фильтров на матрице;

• black level — уровень черного, который нужно вычитать перед нормализацией;

• white level — верхняя граница полезного сигнала;

• white balance — коэффициенты камеры, авто-ББ или пользовательские множители;

• цветовые матрицы — данные для перехода в рабочее цветовое пространство;

• thumbnail / preview — встроенное JPEG-превью или другая миниатюра;

• поля производителя — дополнительные сведения, которые могут понадобиться отдельным приложениям.

Для просмотра это означает, что программа может быстро показать embedded preview, не прогоняя полный демозаик. Для технического анализа это означает, что приложение может читать исходные сенсорные значения и сравнивать их с калибровочными данными. Для RAW-конвертера это означает, что можно построить собственный pipeline поверх уже распакованных данных.

Архитектура программы

Центральная сущность в C++ API — объект LibRaw. Он создается как процессор изображения, работает с одним источником данных за раз и хранит результат в поле imgdata. Последовательно можно обработать любое количество файлов: открыть один RAW, прочитать метаданные, распаковать данные, выполнить нужные операции, очистить состояние через recycle() и перейти к следующему файлу. При необходимости приложение может создавать несколько объектов LibRaw и использовать их в разных потоках, учитывая расход памяти на каждый процессор.

Внутри imgdata собраны основные блоки данных:

Блок	Назначение
imgdata.idata	Основные идентификационные параметры изображения и камеры
imgdata.sizes	Размеры RAW, итогового изображения, служебные размеры, ориентация
imgdata.color	Цветовые коэффициенты, матрицы, баланс белого, black/white level
imgdata.other	Дополнительные сведения об изображении
imgdata.thumbnail	Данные встроенной миниатюры после чтения
imgdata.rawdata	Низкоуровневые RAW-данные
imgdata.image	Буфер после преобразования в формат, совместимый с dcraw-стилем обработки
imgdata.params	Параметры постобработки и вывода

Эта структура делает LibRaw удобной для программ, которым нужно не просто получить RGB, а контролировать этапы. Например, один разработчик может использовать unpack() и дальше строить собственный демозаик, другой — вызвать dcraw_process() и получить базовый TIFF, третий — вообще не трогать полное изображение и извлечь только миниатюру через unpack_thumb().

Основной рабочий сценарий

Типичный рабочий сценарий LibRaw состоит из нескольких этапов. Он достаточно строгий: сначала открытие, потом распаковка, потом постобработка или копирование данных.

1. Создание процессора

В C++ создается объект:

#include "libraw/libraw.h"LibRaw processor;

Этот объект хранит состояние обработки, параметры, указатели на данные, сведения о файле и буферы.

2. Открытие RAW-файла

Файл открывается методом:

processor.open_file("photo.NEF");

На этом этапе LibRaw читает заголовки и метаданные. Изображение еще не распаковано полностью, но уже заполнены важные поля: imgdata.idata, imgdata.sizes, imgdata.color, imgdata.other, imgdata.thumbnail. Именно после open_file() приложение может узнать модель камеры, размеры, ориентацию, цветовую информацию, наличие превью и многие технические параметры.

Также существуют другие варианты открытия:

• open_buffer() — открыть RAW из буфера памяти;

• open_datastream() — открыть через абстрактный поток данных;

• open_bayer() — открыть вручную заданный Bayer-массив;

• open_file() — стандартный путь для обычного файла на диске.

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

3. Распаковка RAW

После открытия вызывается:

processor.unpack();

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

4. Настройка параметров

Параметры задаются через processor.imgdata.params. Например:

processor.imgdata.params.output_tiff = 1;processor.imgdata.params.output_bps = 16;processor.imgdata.params.use_camera_wb = 1;processor.imgdata.params.user_qual = 3;processor.imgdata.params.output_color = 1;

Эти поля соответствуют dcraw-стилю управления обработкой: формат вывода, битность, баланс белого, алгоритм интерполяции, цветовое пространство, яркость, highlight recovery, поворот, шумоподавление, dark frame, bad pixels map и другие параметры.

5. Постобработка

Для базовой RAW-конвертации вызывается:

processor.dcraw_process();

dcraw_process() выполняет постобработку в стиле dcraw: масштабирование, баланс белого, демозаик, преобразование в RGB, применение части параметров imgdata.params. Это удобный путь для простого конвертера, просмотрщика или тестовой утилиты, но для профессионального фоторедактора обычно строят собственный pipeline поверх распакованных RAW-данных.

6. Вывод результата

Результат можно записать в файл:

processor.dcraw_ppm_tiff_writer("photo.tiff");

Или получить в память:

int err = 0;libraw_processed_image_t *image = processor.dcraw_make_mem_image(&err);

Вариант с памятью важен для приложений с собственным UI, GPU-пайплайном, системой кэша или экспортом в нестандартный формат. Программа может получить готовый RGB-буфер и дальше передать его в OpenGL, Qt, OpenCV, собственный рендерер, серверную обработку или внутренний модуль сохранения.

7. Очистка состояния

После обработки вызывается:

processor.recycle();

Это освобождает внутренние данные и готовит объект к следующему файлу.

Консольные утилиты LibRaw

Вместе с библиотекой поставляются примеры и утилиты, которые показывают, как пользоваться API на практике. Они полезны не только как демонстрационный код, но и как диагностический инструмент. Особенно часто используются raw-identify, simple_dcraw, dcraw_half, dcraw_emu.

raw-identify

raw-identify — диагностическая утилита для чтения RAW-метаданных. Она использует open_file() и печатает поля из imgdata. В обычной работе это первый инструмент для проверки: распознается ли файл, какая камера определена, какие размеры прочитаны, есть ли превью, какие таблицы баланса белого доступны.

Примеры команд:

raw-identify photo.NEF

Выводит базовую информацию о RAW-файле.

raw-identify -v photo.NEF

Показывает расширенный дамп метаданных.

raw-identify -u photo.CR3

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

raw-identify -u -f photo.CR3

Дополнительно выводит информацию по masked areas.

raw-identify -w photo.ARW

Печатает таблицы баланса белого, сохраненные в RAW-файле.

Для разработчика это быстрый способ понять, что LibRaw видит внутри файла. Если приложение получает странный цвет, неверный размер или некорректный поворот, raw-identify -v помогает отделить проблему чтения метаданных от проблемы дальнейшей обработки.

simple_dcraw

simple_dcraw — упрощенная эмуляция поведения dcraw для нескольких базовых сценариев. Она показывает, как открыть файл, распаковать RAW, обработать его и записать результат. В ней удобно проверять простую конвертацию в TIFF или извлечение embedded thumbnail.

Примеры:

simple_dcraw -v photo.NEF

Запускает обработку с подробным выводом.

simple_dcraw -T photo.NEF

Создает TIFF-результат вместо PPM.

simple_dcraw -e photo.NEF

Извлекает встроенную миниатюру, если она есть в RAW-файле.

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

dcraw_half

dcraw_half демонстрирует C API и поведение в стиле dcraw -h, то есть получение half-size color image. Такой режим полезен, когда нужна скорость, а не максимальное качество: быстрые превью, индексирование больших каталогов, технический просмотр, предварительный анализ серии файлов.

dcraw_emu

dcraw_emu — более полный эмулятор dcraw, который принимает множество ключей командной строки. Через него можно протестировать white balance, TIFF-вывод, 16-bit output, алгоритм демозаики, цветовое пространство, яркость, gamma curve, highlight mode, dark frame, bad pixels, half-size mode и другие параметры.

Пример простой конвертации:

dcraw_emu -v -T -w -q 3 -o 1 photo.NEF

Что делает команда:

Ключ	Смысл
-v	подробный режим вывода
-T	запись TIFF вместо PPM
-w	использование баланса белого камеры
-q 3	выбор AHD-интерполяции
-o 1	вывод в sRGB

Пример 16-битного вывода:

dcraw_emu -v -T -4 -w photo.CR2

Здесь -4 включает 16-bit linear output, что полезно для дальнейшей обработки в другой программе.

Пример извлечения встроенного превью:

dcraw_emu -e photo.ARW

Этот сценарий нужен просмотрщикам и каталогизаторам: часто камера уже записала внутрь RAW полноценный JPEG-preview, который можно показать мгновенно без полного RAW development.

Параметры обработки: что реально можно настроить

LibRaw управляется не кнопками, а полями libraw_output_params_t, доступными как imgdata.params. Это один из главных рабочих блоков программы. Через него задается поведение dcraw_process(), dcraw_ppm_tiff_writer() и dcraw_thumb_writer().

Формат и битность вывода

За формат отвечает:

processor.imgdata.params.output_tiff = 1;

Значение 1 включает TIFF-вывод, 0 оставляет PPM/PGM-стиль вывода.

За битность отвечает:

processor.imgdata.params.output_bps = 16;

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

Баланс белого

В LibRaw есть несколько способов управлять white balance:

processor.imgdata.params.use_camera_wb = 1;

Используется баланс белого, записанный камерой.

processor.imgdata.params.use_auto_wb = 1;

Включается автоматический баланс белого.

processor.imgdata.params.user_mul[0] = 2.0;processor.imgdata.params.user_mul[1] = 1.0;processor.imgdata.params.user_mul[2] = 1.5;processor.imgdata.params.user_mul[3] = 1.0;

Задаются пользовательские множители каналов.

Есть и прямоугольник для расчета баланса белого:

processor.imgdata.params.greybox[0] = 100;processor.imgdata.params.greybox[1] = 100;processor.imgdata.params.greybox[2] = 200;processor.imgdata.params.greybox[3] = 200;

greybox соответствует логике -A x y w h: берется область кадра, по которой рассчитывается баланс белого. Это полезно в программах, где пользователь пипеткой выбирает серую область, а приложение передает координаты в RAW processing.

В графической оболочке, построенной поверх LibRaw, это превращается в понятные элементы: Method, T(K), Green, Highlights, Exposure Correction (E.V). В API тем же задачам соответствуют поля use_camera_wb, use_auto_wb, user_mul, greybox, highlight, exp_correc, exp_shift, exp_preser.

Дебайеризация и качество интерполяции

Параметр:

processor.imgdata.params.user_qual = 3;

выбирает алгоритм интерполяции. В dcraw-совместимой логике используются значения для linear interpolation, VNG, PPG, AHD, DCB, DHT и других режимов. Для быстрых превью можно использовать более простой метод, для финального вывода — более качественный.

Дополнительные параметры:

processor.imgdata.params.half_size = 1;processor.imgdata.params.four_color_rgb = 1;processor.imgdata.params.median_filter_passes = 1;

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

Цветовое пространство

Параметр:

processor.imgdata.params.output_color = 1;

задает выходное цветовое пространство. В dcraw-совместимой схеме поддерживаются варианты вроде raw, sRGB, Adobe RGB, Wide Gamut, ProPhoto, XYZ, ACES, DCI-P3, Rec. 2020.

Для приложений с color management важны также:

processor.imgdata.params.camera_profile = "camera.icc";processor.imgdata.params.output_profile = "output.icc";

Эти поля используются, когда LibRaw собрана с поддержкой LCMS. Они позволяют применять входной профиль камеры и выходной ICC-профиль.

Яркость, экспозиция и highlights

В LibRaw есть параметры, которые влияют на светлоту и работу с пересветами:

processor.imgdata.params.no_auto_bright = 1;processor.imgdata.params.bright = 1.0;processor.imgdata.params.highlight = 0;processor.imgdata.params.exp_correc = 1;processor.imgdata.params.exp_shift = 1.5;processor.imgdata.params.exp_preser = 0.5;

no_auto_bright отключает автоматическую подстройку яркости. bright задает множитель яркости. highlight управляет обработкой пересвеченных областей. exp_correc, exp_shift, exp_preser включают коррекцию экспозиции до демозаики, задают линейный сдвиг и сохранение светов.

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

Коррекции и технические параметры

Для технической обработки доступны:

processor.imgdata.params.bad_pixels = "badpixels.txt";processor.imgdata.params.dark_frame = "darkframe.pgm";processor.imgdata.params.threshold = 100.0;processor.imgdata.params.fbdd_noiserd = 1;

bad_pixels задает карту битых пикселей. dark_frame указывает dark frame для вычитания. threshold связан с шумоподавлением. fbdd_noiserd включает FBDD noise reduction.

В графических программах эти настройки часто отображаются как Noise Reduction, Threshold, Chromatic Aberration Correction, Black Point, White Point, Exposure Correction. В LibRaw это конкретные поля структуры параметров, которые приложение может заполнить перед вызовом dcraw_process().

Работа с метаданными RAW

Один из самых сильных сценариев LibRaw — чтение метаданных без обязательной полной проявки. После open_file() уже доступны многие поля imgdata. Это экономит время при каталогизации, индексации и анализе больших архивов.

Через C API можно получать ключевые значения функциями:

libraw_get_raw_height(lr);libraw_get_raw_width(lr);libraw_get_iheight(lr);libraw_get_iwidth(lr);libraw_get_cam_mul(lr, index);libraw_get_pre_mul(lr, index);libraw_get_rgb_cam(lr, index1, index2);libraw_get_iparams(lr);libraw_get_lensinfo(lr);libraw_get_imgother(lr);

Эти функции удобны, когда приложение написано на C или использует биндинги, где прямой доступ к C++-структурам нежелателен.

Практически это дает такие задачи:

• вывести список камер в архиве;

• отсортировать RAW-файлы по модели камеры;

• найти файлы с определенной ориентацией;

• проверить размеры и кроп-области;

• получить коэффициенты баланса белого;

• извлечь данные объектива;

• проверить наличие embedded thumbnail;

• сравнить black level у серии кадров;

• построить технический отчет по RAW-съемке;

• подготовить данные для собственного RAW converter.

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

Извлечение встроенных превью и миниатюр

Многие RAW-файлы содержат встроенный JPEG-preview. Камера записывает его для быстрого просмотра на экране камеры, в системных файловых менеджерах и в программах каталогизации. LibRaw умеет извлекать такое превью отдельно от полного RAW-декодирования.

Основные методы:

processor.unpack_thumb();

Читает или распаковывает основное превью.

processor.unpack_thumb_ex(index);

Читает конкретную миниатюру из списка, если в файле несколько preview-изображений.

После этого данные находятся в imgdata.thumbnail.thumb, а формат — в imgdata.thumbnail.tformat. JPEG-превью обычно помещается в буфер без изменений, а другие форматы могут быть распакованы как bitmap.

Типичные задачи:

Задача	Почему используется thumbnail
Быстрый просмотр папки	Не нужно демозаицировать каждый RAW
DAM-каталог	Миниатюры строятся быстрее
Web-превью	Можно извлечь JPEG из RAW
Проверка фокуса на серии	Быстрый предварительный просмотр
Архивный анализ	Можно получить картинку без полной обработки

При этом важно понимать ограничение: embedded preview — это уже обработанное камерой изображение. Оно может отличаться от результата LibRaw dcraw_process() и от результата в Lightroom, Capture One, RawTherapee или darktable. Превью отражает камерный JPEG-рендеринг, а RAW-конвертация строится заново из сенсорных данных.

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

C++ API — основной способ работы с LibRaw. Минимальный пример выглядит так:

#include "libraw/libraw.h"#include <iostream>int main() {    LibRaw processor;    int ret = processor.open_file("photo.NEF");    if (ret != LIBRAW_SUCCESS) {        std::cerr << "open_file failed: " << libraw_strerror(ret) << "\n";        return 1;    }    std::cout << "Camera: " << processor.imgdata.idata.make              << " " << processor.imgdata.idata.model << "\n";    std::cout << "Image size: "              << processor.imgdata.sizes.width              << " x "              << processor.imgdata.sizes.height              << "\n";    ret = processor.unpack();    if (ret != LIBRAW_SUCCESS) {        std::cerr << "unpack failed: " << libraw_strerror(ret) << "\n";        processor.recycle();        return 1;    }    processor.imgdata.params.output_tiff = 1;    processor.imgdata.params.output_bps = 16;    processor.imgdata.params.use_camera_wb = 1;    processor.imgdata.params.user_qual = 3;    ret = processor.dcraw_process();    if (ret != LIBRAW_SUCCESS) {        std::cerr << "dcraw_process failed: " << libraw_strerror(ret) << "\n";        processor.recycle();        return 1;    }    ret = processor.dcraw_ppm_tiff_writer("photo.tiff");    if (ret != LIBRAW_SUCCESS) {        std::cerr << "writer failed: " << libraw_strerror(ret) << "\n";        processor.recycle();        return 1;    }    processor.recycle();    return 0;}

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

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

C API — это обертка вокруг C++ API. Он нужен для программ на C, для FFI-биндингов и для языков, которым удобнее подключать C-интерфейс.

Пример:

#include <stdio.h>#include "libraw/libraw.h"int main() {    libraw_data_t *lr = libraw_init(0);    if (!lr) {        return 1;    }    int ret = libraw_open_file(lr, "photo.CR2");    if (ret != LIBRAW_SUCCESS) {        printf("open error: %s\n", libraw_strerror(ret));        libraw_close(lr);        return 1;    }    printf("Raw size: %d x %d\n",           libraw_get_raw_width(lr),           libraw_get_raw_height(lr));    ret = libraw_unpack(lr);    if (ret != LIBRAW_SUCCESS) {        printf("unpack error: %s\n", libraw_strerror(ret));        libraw_close(lr);        return 1;    }    lr->params.output_tiff = 1;    lr->params.output_bps = 16;    lr->params.use_camera_wb = 1;    ret = libraw_dcraw_process(lr);    if (ret == LIBRAW_SUCCESS) {        libraw_dcraw_ppm_tiff_writer(lr, "photo.tiff");    }    libraw_close(lr);    return 0;}

Ключевые функции C API:

Функция	Назначение
libraw_init()	Создает экземпляр libraw_data_t
libraw_open_file()	Открывает RAW-файл
libraw_unpack()	Распаковывает RAW-данные
libraw_unpack_thumb()	Извлекает миниатюру
libraw_dcraw_process()	Выполняет dcraw-совместимую постобработку
libraw_dcraw_ppm_tiff_writer()	Записывает PPM/TIFF
libraw_dcraw_make_mem_image()	Возвращает обработанное изображение в памяти
libraw_close()	Освобождает ресурсы

C API сохраняет ту же логику: открыть, прочитать, распаковать, обработать, вывести, закрыть.

Практическая инструкция: проверка RAW-файла через LibRaw

Шаг 1. Проверить, распознается ли файл

raw-identify sample.NEF

Если файл поддерживается, утилита выведет основные данные. Если формат не распознан или файл поврежден, это будет видно сразу. Такой тест полезен перед тем, как искать ошибку в собственном коде.

Шаг 2. Получить расширенную информацию

raw-identify -v sample.NEF

Расширенный вывод показывает больше полей imgdata: размеры, модель камеры, цветовые данные, служебные параметры. Это главный режим диагностики.

Шаг 3. Узнать функцию распаковки

raw-identify -u sample.CR3

Если нужно понять, какой decoder path использует LibRaw, применяется -u. Для анализа masked areas можно добавить -f:

raw-identify -u -f sample.CR3

Шаг 4. Проверить таблицы баланса белого

raw-identify -w sample.ARW

Этот режим полезен, если приложение неправильно интерпретирует white balance или если нужно сравнить камерные коэффициенты с собственными расчетами.

Шаг 5. Сделать простую TIFF-конвертацию

simple_dcraw -T sample.NEF

Эта команда проверяет не только чтение метаданных, но и полный путь: распаковка, обработка, запись результата.

Шаг 6. Сделать TIFF через dcraw_emu с параметрами

dcraw_emu -v -T -4 -w -q 3 -o 1 sample.NEF

Такой вариант удобен для воспроизводимого теста:

• -v показывает подробности;

• -T задает TIFF;

• -4 включает 16-bit linear output;

• -w использует camera white balance;

• -q 3 выбирает AHD;

• -o 1 задает sRGB.

Шаг 7. Извлечь превью

simple_dcraw -e sample.NEF

или:

dcraw_emu -e sample.NEF

Если внутри RAW есть embedded preview, его можно получить без полной RAW-конвертации.

Практическая инструкция: встроить LibRaw в приложение

Интеграция LibRaw в приложение обычно строится вокруг одного из трех сценариев.

Сценарий 1. Быстрый просмотр RAW

Задача: показать пользователю превью как можно быстрее.

Пайплайн:

1. Создать объект LibRaw.

2. Вызвать open_file().

3. Проверить наличие thumbnail.

4. Вызвать unpack_thumb().

5. Получить буфер imgdata.thumbnail.thumb.

6. Передать JPEG/bitmap в UI.

7. Освободить ресурсы через recycle().

Преимущество такого подхода — скорость. Недостаток — изображение будет соответствовать встроенному камерному превью, а не полной проявке RAW.

Сценарий 2. Базовая конвертация RAW в TIFF

Задача: получить нейтральный 16-битный TIFF для дальнейшей обработки.

Пайплайн:

1. open_file();

2. unpack();

3. задать output_tiff = 1;

4. задать output_bps = 16;

5. включить use_camera_wb = 1;

6. выбрать user_qual;

7. вызвать dcraw_process();

8. записать через dcraw_ppm_tiff_writer().

Такой сценарий подходит для пакетных конвертеров, технических утилит и программ, где RAW-проявка не является основной функцией.

Сценарий 3. Собственный RAW pipeline

Задача: использовать LibRaw только как RAW decoder, а цвет, демозаик, шумоподавление и тональную обработку делать самостоятельно.

Пайплайн:

1. open_file();

2. прочитать imgdata.sizes, imgdata.color, imgdata.idata;

3. unpack();

4. получить RAW-данные;

5. применить собственный black level correction;

6. выполнить собственную нормализацию;

7. построить собственный demosaicing;

8. применить собственный color management;

9. выполнить tone mapping, exposure, noise reduction;

10. вывести результат через собственный код.

Именно этот сценарий важен для серьезных RAW-конвертеров, исследовательского ПО, астрофотографии, машинного зрения и нестандартных камерных пайплайнов.

Использование LibRaw в графических программах

LibRaw часто работает как невидимый слой внутри графических приложений. В digiKam она используется для RAW-импорта: пользователь видит панель Import Raw Using Libraw, а внутри приложение передает параметры в LibRaw и получает результат для дальнейшего редактирования. В меню digiKam RAW-поддержка также связана с пунктом Help → Supported RAW Camera, где можно проверить список поддерживаемых камер в конкретной сборке программы.

На уровне интерфейса это выглядит как обычные настройки RAW-редактора: 16 bits color depth, Interpolate RGB as four colors, Do not stretch or rotate pixels, Quality, Pass, Refine interpolation. На уровне LibRaw это соответствует параметрам битности, интерполяции, поворота, геометрии, медианной фильтрации и режимов обработки CFA. Именно поэтому LibRaw удобно встраивать: программа-хост может дать пользователю понятные элементы управления, а библиотека выполнит низкоуровневую часть.

Производительность и память

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

Для быстрого просмотра можно извлечь embedded preview. Для промежуточного результата можно использовать half-size mode. Для технического анализа можно не выполнять dcraw_process(), а читать только метаданные или распакованные RAW-значения. Для финального вывода можно включать 16-bit output, качественную интерполяцию, correction-параметры и профильный вывод.

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

Режим	Что выполняется	Скорость	Качество/полнота
Только open_file()	Чтение метаданных	Очень высокая	Без изображения
unpack_thumb()	Извлечение превью	Высокая	Камерный JPEG/preview
unpack()	Распаковка RAW	Средняя	Исходные данные
dcraw_process()	Базовая RAW-конвертация	Ниже	RGB-результат
Собственный pipeline	Зависит от приложения	Зависит от кода	Максимальный контроль

Качество RAW-конвертации

LibRaw умеет выполнять базовую dcraw-совместимую RAW-конвертацию, но ее сильная сторона — не замена профессиональному редактору. Это особенно важно понимать при сравнении вывода dcraw_emu с результатом камерного JPEG, Lightroom, Capture One, RawTherapee, darktable или DxO PhotoLab. Разные программы используют разные цветовые профили, tone mapping, шумоподавление, highlight recovery, локальную контрастность, кривые, lens correction, дефолтные профили камеры и собственные rendering-модели.

LibRaw дает контролируемую основу:

• корректно открыть и распаковать файл;

• получить технические параметры;

• применить базовые dcraw-style настройки;

• вывести TIFF/PPM или буфер;

• передать данные в другой модуль.

Если нужна выразительная картинка из коробки, LibRaw не обязана давать такой же результат, как камерный JPEG. Камерный JPEG уже прошел закрытый ISP производителя: шумоподавление, резкость, кривые, saturation, contrast, picture style, lens correction, локальные улучшения. LibRaw работает ближе к исходным данным и не имитирует полностью фирменный JPEG-процессор камеры.

Лицензирование и использование в проектах

LibRaw распространяется как открытая библиотека с вариантами лицензирования LGPL 2.1 и CDDL 1.0. Это важно для разработчиков: библиотеку можно использовать в разных типах программных продуктов, но условия выбранной лицензии нужно соблюдать.

Практически при интеграции нужно учитывать:

• как именно библиотека подключается — статически или динамически;

• изменяется ли исходный код LibRaw;

• распространяется ли приложение вместе с библиотекой;

• требуется ли публиковать изменения в самой библиотеке;

• какие сторонние компоненты включены в сборку;

• какие форматы и возможности зависят от дополнительных библиотек.

Для коммерческого приложения это не техническая мелочь, а часть архитектурного решения. LibRaw закрывает сложную задачу RAW decoding, но разработчик должен заранее выбрать юридически корректную модель использования.

Сильные стороны LibRaw

Широкая поддержка RAW-форматов

LibRaw ориентирована на большое количество камерных RAW-форматов. Это ее основная ценность: разработчик получает единый интерфейс вместо набора отдельных декодеров для Canon, Nikon, Sony, Fujifilm, Panasonic, Olympus, Pentax, DNG и других файлов.

Доступ к техническим данным

Библиотека достает не только RGB-картинку, а именно RAW-сущности: CFA, black level, white balance, color matrices, размеры, ориентацию, thumbnail, поля камеры. Для профессионального пайплайна это важнее, чем простая конвертация в JPEG.

C и C++ API

Наличие C++ API и C API делает LibRaw удобной для разных проектов. C++ API дает прямую объектную модель через LibRaw. C API проще подключать из других языков, через FFI, плагины и обертки.

Возможность использовать только нужный слой

LibRaw не навязывает полный pipeline. Можно ограничиться open_file() для метаданных, unpack_thumb() для превью, unpack() для RAW-данных или dcraw_process() для простого RGB-результата. Это делает библиотеку гибкой.

Наличие консольных примеров

raw-identify, simple_dcraw, dcraw_half, dcraw_emu позволяют быстро проверить работу библиотеки без написания собственного приложения. Это ценно при диагностике поддержки камеры, проблем с цветом, ошибками распаковки и различиями между RAW-файлами.

Подходит для встраивания

LibRaw хорошо ложится в архитектуру приложений, где RAW — только один из поддерживаемых форматов. Просмотрщик изображений может использовать ее для RAW, а JPEG/PNG/TIFF открывать другими декодерами. DAM-система может использовать ее для thumbnails и метаданных. Конвертер может использовать ее как первый этап собственного процесса.

Недостатки и ограничения

Нет собственного полноценного GUI

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

Базовая проявка не равна профессиональному RAW-редактору

dcraw_process() удобен, но это не то же самое, что сложный современный pipeline RawTherapee, darktable, Lightroom или Capture One. Для нейтральной технической конвертации он полезен. Для художественной обработки и максимального качества финального изображения лучше строить отдельный pipeline.

Результат зависит от сборки и окружения

Некоторые возможности зависят от того, с какими опциями и сторонними библиотеками собрана LibRaw. Например, color management через ICC-профили связан с поддержкой LCMS, а отдельные декодеры или ускоренные пути могут зависеть от дополнительных компонентов.

Новые камеры могут требовать обновленной поддержки

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

Нужно понимать RAW-процессинг

LibRaw не скрывает полностью сложность RAW. Разработчику все равно нужно понимать black level, CFA, white balance, demosaicing, color space, linear data, gamma, tone mapping, highlight clipping. Библиотека снимает большой пласт работы, но не заменяет знание image processing.

Сравнение с аналогами

LibRaw и dcraw

dcraw — исторически важная утилита для чтения и конвертации RAW-файлов. LibRaw выросла из идеи превратить код dcraw в библиотеку, пригодную для встраивания в другие программы, убрать зависимость от глобального состояния и улучшить работу с метаданными. Для разработчика разница принципиальна: dcraw — прежде всего отдельная command-line utility, а LibRaw — библиотека с C/C++ API, структурами данных и встраиваемым workflow.

Критерий	LibRaw	dcraw
Основной формат	Библиотека + примеры	Консольная утилита
Встраивание в приложения	Да	Неудобно
API	C/C++	Нет полноценного библиотечного API
Метаданные	Расширенный доступ через структуры	Ограниченный сценарий вывода
Постобработка	dcraw-style emulation	Собственный основной режим
Подход	Компонент для программ	Утилита-конвертер

LibRaw логичнее выбирать для новых приложений, где нужно встроить RAW image decoder. dcraw полезен как историческая база и точка сравнения, но как архитектурный компонент он уступает LibRaw.

LibRaw и RawSpeed

RawSpeed — библиотека, ориентированная на быстрый первый этап декодирования RAW. Она выдает RAW-данные и CFA-информацию, но не является полноценной библиотекой отображения RAW: не делает демозаик, не выполняет цветокоррекцию и не отдает viewable image или thumbnail как цельный RAW processing layer.

Критерий	LibRaw	RawSpeed
Основной фокус	Универсальное чтение RAW, метаданные, thumbnail, базовая обработка	Быстрая распаковка RAW
Метаданные	Широкий набор данных для обработки	Ограниченный набор
Thumbnail	Есть	Не является целью библиотеки
Дебайеризация	Есть dcraw-style обработка	Нет
Применение	RAW viewers, converters, analyzers	Быстрый decoder stage
Гибкость для конечного приложения	Выше	Уже по назначению

RawSpeed хорош там, где нужна скорость распаковки и дальше все делает собственный pipeline. LibRaw шире: она больше подходит как универсальный RAW layer для приложений, где важны и метаданные, и embedded preview, и простой вывод.

LibRaw и Adobe DNG SDK

Adobe DNG SDK работает вокруг DNG: чтение, запись DNG и преобразование DNG-данных в форму, пригодную для отображения или дальнейшей обработки. DNG сам по себе является публично документированным форматом для camera raw data.

Критерий	LibRaw	Adobe DNG SDK
Основной фокус	Множество камерных RAW-форматов	DNG
Форматы	CR2, CR3, NEF, ARW, RAF, RW2, ORF, DNG и другие	DNG
Тип продукта	Универсальный RAW decoder	SDK для DNG
Сценарий	Открыть разные RAW-файлы камер	Работать с DNG-форматом
Подходит для собственного RAW viewer	Да	Только если ставка на DNG
Сильная сторона	Универсальность	Стандартизованный DNG-workflow

Если приложение должно работать почти со всеми RAW-файлами камер, LibRaw практичнее. Если задача строго связана с DNG-пайплайном, DNG SDK может быть более специализированным инструментом.

LibRaw и OpenImageIO

OpenImageIO — универсальный фреймворк для чтения и записи изображений через абстракцию ImageInput и плагины форматов. Он удобен как общий слой image I/O: открыть файл, получить ImageSpec, прочитать пиксели, работать с разными форматами через единый интерфейс.

Критерий	LibRaw	OpenImageIO
Основной фокус	RAW-файлы цифровых камер	Универсальный image I/O
Глубина RAW-метаданных	Высокая	Зависит от backend/плагина
RAW processing	Специализированный	Не основной фокус
Форматы изображений	RAW	Много форматов
Подходит для DAM/рендера	Как RAW-компонент	Как общий I/O-слой
Лучший сценарий	Нужен контроль RAW	Нужна единая система чтения разных изображений

В сложном приложении они могут не конкурировать, а дополнять друг друга: LibRaw отвечает за RAW, OpenImageIO — за общий ввод-вывод остальных форматов.

LibRaw и RawTherapee

RawTherapee — полноценная программа для RAW processing с графическим интерфейсом, неразрушающим редактированием, 32-bit floating point pipeline, продвинутыми алгоритмами демозаики, цветокоррекцией, шумоподавлением, кривыми, пакетной обработкой и инструментами для фотографов.

Критерий	LibRaw	RawTherapee
Тип	Библиотека	Пользовательская программа
Пользовательский интерфейс	Нет собственного полноценного GUI	Есть
Назначение	Встроить RAW-декодер	Обрабатывать фотографии
Целевая аудитория	Разработчики	Фотографы и ретушеры
Гибкость для программирования	Высокая	Не основной сценарий
Готовый результат для фотографа	Нет	Да

Сравнивать их напрямую нужно аккуратно. LibRaw — компонент, RawTherapee — готовое приложение. Если нужно проявлять фотографии руками, выбирают RawTherapee. Если нужно написать свой просмотрщик или конвертер, выбирают LibRaw.

LibRaw и darktable

darktable — open source photography workflow application и RAW developer с виртуальным lighttable/darkroom, каталогизацией, неразрушающей обработкой и большим набором модулей.

Критерий	LibRaw	darktable
Тип	Библиотека/SDK	RAW-редактор и workflow-приложение
Каталог	Нет	Да
Модули обработки	Базовая dcraw-style обработка	Развитый модульный pipeline
Встраивание	Да	Нет как простая библиотека LibRaw-типа
Основной пользователь	Разработчик	Фотограф
Задача	Получить RAW-данные	Организовать и обработать съемку

darktable подходит фотографу, которому нужен рабочий процесс от импорта до экспорта. LibRaw подходит разработчику, которому нужен RAW decoding layer внутри собственной программы.

Для кого подходит LibRaw

LibRaw стоит выбирать, если задача связана с разработкой ПО, а не с ручной обработкой фотографий.

Разработчики RAW-просмотрщиков

Просмотрщик может использовать LibRaw для определения модели камеры, чтения размеров, извлечения embedded preview и построения быстрых миниатюр. Для открытия файла пользователю не обязательно ждать полной демозаики: достаточно unpack_thumb().

Разработчики RAW-конвертеров

Конвертер может использовать open_file(), unpack(), imgdata.color, imgdata.sizes, а дальше строить собственный pipeline. Если нужен простой результат, можно использовать dcraw_process() и TIFF-вывод.

Разработчики DAM-систем

Digital asset management software должен быстро индексировать большие архивы. LibRaw помогает извлекать метаданные, определять камеры, получать миниатюры и строить превью.

Разработчики научного и технического ПО

Для анализа RAW важны линейные данные, black level, CFA, white level, коэффициенты каналов. LibRaw дает доступ к таким данным без необходимости писать парсеры для каждого камерного формата.

Разработчики программ для астрофото, панорам и стекинга

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

Разработчики серверных конвертеров

Серверная система может принимать RAW-файлы, извлекать превью, создавать технический TIFF, проверять совместимость, формировать метаданные и отдавать результат в web-интерфейс.

Для кого LibRaw не подходит

LibRaw не стоит выбирать как основную программу, если пользователь ожидает готовый визуальный RAW-редактор. Здесь нет привычных инструментов фотографа: ползунков Exposure, Contrast, Highlights, Shadows, Texture, Clarity, масок, локальных правок, пресетов, пакетной очереди с визуальным контролем, каталога и экспорта в социальные форматы.

Если задача — обработать отпускные фотографии, сделать цветокоррекцию, подготовить серию для печати или создать единый стиль съемки, удобнее использовать RawTherapee, darktable, Lightroom, Capture One, DxO PhotoLab или другой RAW developer. LibRaw будет полезна косвенно — как компонент внутри таких программ или как база для разработчика.

Типичные ошибки при понимании LibRaw

Ошибка 1. Ждать от LibRaw готовый интерфейс редактора

LibRaw — это не приложение с панелями редактирования. Ее интерфейс — API и command line samples. Если нужен GUI, его пишет программа-хост.

Ошибка 2. Сравнивать результат с камерным JPEG без учета обработки

Камерный JPEG уже содержит picture style, contrast, saturation, sharpening, denoise, lens correction и tone curve. LibRaw при базовой обработке не обязана повторять закрытый ISP камеры.

Ошибка 3. Думать, что RAW — это просто большой JPEG

RAW-файл содержит данные сенсора и метаданные, а не финальную картинку. Чтобы получить изображение, нужны black level correction, white balance, demosaicing, color transform, gamma/tone mapping и другие этапы.

Ошибка 4. Использовать dcraw_process() как единственный путь

dcraw_process() удобен, но LibRaw ценна не только им. Во многих серьезных проектах важнее open_file(), unpack(), доступ к imgdata и собственная обработка.

Ошибка 5. Игнорировать параметры сборки

Поддержка отдельных возможностей может зависеть от того, как собрана библиотека. Для приложения важно контролировать окружение, особенно если оно должно одинаково работать на Windows, macOS и Linux.

Пример реального workflow для разработчика

Представим приложение: быстрый RAW viewer с технической панелью.

Что нужно пользователю

• открыть папку с RAW;

• увидеть миниатюры;

• быстро переключаться между файлами;

• видеть модель камеры, объектив, размеры, ISO, выдержку;

• при необходимости открыть полный демозаик;

• экспортировать технический TIFF.

Как LibRaw закрывает задачу

Функция приложения	Что используется в LibRaw
Сканирование папки	open_file()
Получение модели камеры	imgdata.idata
Получение размеров	imgdata.sizes
Получение миниатюры	unpack_thumb()
Полная обработка	unpack() + dcraw_process()
TIFF-экспорт	dcraw_ppm_tiff_writer()
Техническая панель	imgdata.color, imgdata.other, C API getters

Такой viewer может быть очень быстрым, если в ленте использовать embedded preview, а полную обработку запускать только при открытии кадра.

Пример workflow для RAW-конвертера

Другой пример — пакетный конвертер RAW в 16-битный TIFF.

Параметры

• использовать баланс белого камеры;

• выводить TIFF;

• сохранять 16 бит;

• использовать AHD;

• не применять агрессивную автояркость;

• писать лог по каждому файлу.

Командная логика

dcraw_emu -v -T -4 -w -q 3 input.NEF

API-логика

processor.open_file(path);processor.unpack();processor.imgdata.params.output_tiff = 1;processor.imgdata.params.output_bps = 16;processor.imgdata.params.use_camera_wb = 1;processor.imgdata.params.user_qual = 3;processor.imgdata.params.no_auto_bright = 1;processor.dcraw_process();processor.dcraw_ppm_tiff_writer(output_path);processor.recycle();

Такой конвертер не будет заменой художественному редактору, но он решает техническую задачу: получить предсказуемый TIFF из набора RAW-файлов.

Пример workflow для анализа сенсора

Для анализа сенсора часто не нужен готовый RGB. Нужны значения до демозаики.

Задачи

• прочитать RAW;

• определить CFA pattern;

• получить black level;

• извлечь массив значений;

• посчитать шум по каналам;

• сравнить dark frame;

• построить статистику насыщения.

Почему LibRaw подходит

Библиотека дает доступ к техническим данным RAW и позволяет не тратить время на поддержку десятков камерных форматов. Приложение может использовать LibRaw только как этап распаковки, а всю математику выполнять самостоятельно.

Итоговая оценка

LibRaw — сильная программа не для конечной ретуши, а для разработки RAW-инструментов. Ее ценность в том, что она превращает хаотичный мир камерных RAW-форматов в единый C/C++ интерфейс: открыть файл, прочитать метаданные, распаковать RAW, извлечь thumbnail, получить параметры камеры, выполнить базовую обработку или передать данные в собственный pipeline.

Это хороший выбор для RAW viewer, RAW converter, анализатора данных сенсора, DAM-системы, серверного конвертера, инструмента астрофото, программы для стекинга, панорамного софта и любого приложения, где RAW-файл — исходный материал. LibRaw не надо оценивать как замену Lightroom или RawTherapee: это другой слой. Она находится ниже пользовательского интерфейса и отвечает за то, чтобы программа вообще могла надежно читать RAW-файлы разных камер.

Главное преимущество LibRaw — универсальность и контроль. Главный недостаток — отсутствие готового пользовательского workflow. Для разработчика это нормальная цена: библиотека делает сложную низкоуровневую работу и оставляет архитектуру обработки на стороне приложения.