LibRaw: декодирование RAW и интеграция в приложения

LibRaw решает задачу чтения файлов цифровых камер на уровне приложения: распознаёт контейнер RAW, извлекает несжатые или декомпрессированные значения сенсора, геометрию кадра, схему цветных фильтров, уровни чёрного и насыщения, баланс белого, сведения о камере и объективе, а также встроенные превью. Библиотека полезна разработчикам просмотрщиков, конвертеров, каталогизаторов, научных анализаторов, панорамных и стековых программ, которым нужен единый C или C++ API вместо собственного набора декодеров для CR2, CR3, NEF, ARW, RAF, ORF, DNG и других семейств. Она умеет выполнить базовую dcraw-совместимую проявку, но её основное назначение — надёжно доставить данные из RAW в код вызывающей программы, а не заменить законченный фоторедактор.

Что представляет собой LibRaw

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

Слово RAW не обозначает единый формат. Производители камер используют разные контейнеры, варианты сжатия, таблицы тегов, способы хранения миниатюр, геометрию активной области и правила интерпретации цветных каналов. Даже одинаковое расширение может содержать данные разных поколений камер и режимов съёмки. LibRaw скрывает большую часть этой неоднородности: после успешного open_file() вызывающая программа получает унифицированные поля размеров, модели камеры, числа кадров, ориентации, паттерна CFA, коэффициентов баланса белого и цветовых матриц. После unpack() один из указателей в imgdata.rawdata ведёт к распакованным значениям пикселей.

При этом унификация не означает, что все RAW становятся обычной матрицей Bayer RGGB. Библиотека встречается с X-Trans, многоканальными и полноцветными массивами, плавающими DNG, небольшими sRAW/mRAW, многокадровыми режимами, пиксель-шифтом и форматами со специфическими преобразованиями. Код, который без проверки предполагает один 16-битный канал и период 2×2, будет корректен лишь для части камер. Практическая ценность LibRaw состоит не только в декомпрессии, но и в том, что она сообщает вызывающей стороне, с каким расположением и типом данных та имеет дело.

Граница между декодированием и проявкой

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

Разработчики LibRaw прямо отделяют такую базовую проявку от production-процессинга. Алгоритмы рендера унаследованы от dcraw и сохраняются прежде всего для совместимости, проверки декодеров и быстрого построения изображения. В полноценном RAW-конвертере обычно требуются собственные профили камер, современные методы демозаики и подавления шума, коррекция объектива, локальные маски, управляемая тональная кривая, точное восстановление светов и стабильный цветовой движок. LibRaw даёт для этого исходные данные, но не навязывает готовую художественную интерпретацию.

Кому библиотека подходит

• Разработчику просмотрщика, которому нужны метаданные и встроенное JPEG-превью без полной проявки.
• Создателю конвертера, который строит собственную линейную обработку поверх распакованных значений сенсора.
• Автору каталогизатора, анализатора экспозиции, стека, панорамы или астрономического приложения.
• Инженеру компьютерного зрения, которому важно получить CFA, активную область, чёрный и белый уровни до обычной RGB-обработки.
• Разработчику плагина или серверного модуля, где RAW должен стать одним из поддерживаемых входов.

Фотографу, которому нужно открыть кадр, подвигать экспозицию, стереть объект и сохранить JPEG, сама LibRaw почти ничего не даёт: понадобится готовое приложение, использующее библиотеку, либо отдельный редактор. Такая граница особенно важна при установке. Архив с LibRaw может содержать DLL, заголовки, библиотеки и консольные образцы, но после запуска не появляется привычное окно «Открыть фотографию».

Установка и начало работы

Способ установки зависит от роли LibRaw в проекте. Для знакомства удобен готовый двоичный пакет: в нём обычно есть каталог bin с образцами, include/libraw с заголовками и библиотеки для линковки. Для выпуска собственного продукта предпочтительнее воспроизводимая сборка из исходного кода с явно зафиксированными опциями, компилятором, разрядностью и дополнительными зависимостями. Пакет из репозитория операционной системы подходит, когда его ветка и набор функций соответствуют требованиям проекта; для поддержки новой камеры иногда нужна более свежая стабильная ветка.

Сборка в Unix-подобной системе

Классическая последовательность состоит из подготовки configure, запуска конфигуратора, компиляции и установки. В официальном архиве конфигуратор уже подготовлен; в снимке репозитория сначала может потребоваться autoreconf --install. Параметр --enable-examples включает сборку образцов, поддержка OpenMP управляется опциями --enable-openmp и --disable-openmp, а подключение LCMS — соответствующими ключами --enable-lcms или --disable-lcms. Перед выпуском приложения полезно сохранить полный вывод конфигурации: по нему видно, включены ли цветовой движок, JPEG-декодирование и многопоточность.

После установки компилятор должен находить заголовок libraw/libraw.h, а линкер — подходящую библиотеку raw или raw_r в зависимости от пакета и схемы сборки. Ошибка «undefined reference» не всегда означает, что LibRaw не установлена. При статической линковке приходится добавить транзитивные зависимости, а сборка с OpenMP требует совместимого рантайма и флагов в конечном приложении. Если библиотека собрана с OpenMP, а программа линкуется без него, сообщения часто указывают на GOMP_* или функции omp_*.

Сборка в Windows

В исходниках предусмотрены готовые make-файлы для Visual Studio и другие проекты сборки. Важнее всего не смешивать архитектуры: 64-битное приложение должно линковаться с 64-битной библиотекой, а конфигурации Debug и Release желательно держать раздельно. Несовпадение CRT, настроек исключений и модели времени выполнения может проявиться не при линковке, а при освобождении памяти на границе модулей. Особенно осторожно нужно обращаться с буферами, которые создаёт LibRaw: освобождать их следует штатными методами библиотеки, а не произвольным free() из другого модуля.

Для путей с национальными символами в Windows проверяют наличие возможности Unicode paths через libraw_capabilities() и используют open_wfile() или соответствующую C-функцию. Передача UTF-8-строки в обычный open_file() не гарантирует одинакового поведения во всех сочетаниях компилятора и системной кодовой страницы.

Первый практический тест

Сначала полезно запустить не конвертер, а raw-identify. Без полной распаковки он показывает, распознаны ли камера и режим, сколько изображений находится в контейнере, каковы размеры, поля обрезки, ориентация и основные параметры съёмки. Ключ -v разворачивает подробный дамп, -u сообщает имя выбранного декодера, сочетание -u -f добавляет сведения о маскированных областях, а -w выводит таблицы баланса белого, если они присутствуют.

Следующий тест — simple_dcraw или dcraw_emu на копии файла. Он подтверждает, что после распаковки работает базовая постобработка и запись результата. Не стоит начинать с целой папки: один известный кадр проще сравнить с камерным JPEG, проверить поворот, границы активной области и отсутствие грубых цветовых ошибок. Только после этого имеет смысл собирать собственный минимальный пример и подключать его к приложению.

Состав пакета и консольные примеры

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

Пример 4channels особенно нагляден, потому что не пытается выдать сырой массив за готовую цветную фотографию. Он создаёт отдельные серые изображения для компонентов сенсора, умеет выбрать кадр из многокадрового контейнера, применить грубую гамму для визуальной проверки, выполнить целочисленное автомасштабирование и включить или отключить вычитание чёрного. Такой результат помогает увидеть виньетирование, маскированные поля, различие двух зелёных каналов и дефекты отдельных участков матрицы.

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

Параметры dcraw_emu

dcraw_emu связывает знакомые ключи dcraw с полями libraw_output_params_t. Например, -w запрашивает камерный баланс белого, -a — автоматический, -r задаёт четыре пользовательских множителя, -H выбирает режим работы со светами, -q — алгоритм интерполяции, -o — выходное пространство, -4 — линейный 16-битный результат, -T — TIFF. Дополнительные ключи демонстрации управляют обрезкой, экспокоррекцией до демозаики, использованием памяти вместо файлового потока и подробным измерением стадий.

Полный список на конкретном скриншоте относится к определённой сборке и не должен служить единственной документацией. Часть экспериментальных демозаик может отсутствовать, переместиться в отдельный пакет или требовать особой лицензии; дополнительные декодеры доступны только при соответствующей компиляции. Надёжный подход — вызвать утилиту без аргументов, сохранить её текущую справку и сопоставить каждый нужный ключ с полем структуры в заголовках установленной версии.

Жизненный цикл объекта и правильный порядок вызовов

LibRaw хранит состояние обработки внутри экземпляра. Сразу после создания объект пуст; после open_file(), open_buffer() или open_datastream() заполнены метаданные и описание контейнера; после unpack() доступен распакованный сенсорный буфер; после dcraw_process() сформировано RGB-изображение для записи или копирования. Поле progress_flags отмечает уже пройденные стадии. Этот автомат состояний защищает от части ошибок, но требует соблюдать последовательность.

1. Создать отдельный объект LibRaw или получить дескриптор через libraw_init().
2. Задать параметры, которые влияют на открытие и распаковку: выбор кадра, ограничения памяти, специальные RAW-флаги.
3. Открыть файл, буфер или пользовательский поток и немедленно проверить код возврата.
4. Прочитать метаданные, список кадров и превью; при необходимости уточнить shot_select.
5. Вызвать unpack() для сенсорных данных и проверить, какой указатель rawdata стал ненулевым.
6. Либо обработать RAW собственным кодом, либо заполнить параметры вывода и вызвать dcraw_process().
7. Скопировать результат в свой буфер, записать TIFF/PPM или извлечь превью.
8. Освободить возвращённые буферы штатной функцией и вызвать recycle() перед повторным использованием объекта.

Ошибка LIBRAW_OUT_OF_ORDER_CALL обычно говорит не о повреждённом файле, а о нарушении этой схемы. Типичные причины: unpack() вызван до открытия; dcraw_process() — до распаковки; после фатальной ошибки код продолжает обращаться к прежнему состоянию; приложение освободило входной буфер раньше завершения чтения. После успешного открытия нового файла объект сам очищает прежние ресурсы, но явный recycle() делает границы операции понятнее и упрощает диагностику утечек.

recycle, recycle_datastream и деструктор

recycle() возвращает объект почти в состояние сразу после создания: освобождает внутренние изображения, метаданные текущего файла и поток. В C++ деструктор выполнит такую очистку автоматически, однако в длительном пакетном процессе ждать уничтожения объекта невыгодно. recycle_datastream() закрывает или отпускает только входной поток, сохраняя уже извлечённые данные, если это допустимо для дальнейшего этапа. Такой вызов полезен, когда после полной распаковки нужно рано освободить файловый дескриптор, но применять его следует только после понимания, не понадобится ли библиотеке повторное чтение.

Буферы, созданные dcraw_make_mem_image() и dcraw_make_mem_thumb(), освобождают через dcraw_clear_mem() или C-аналог libraw_dcraw_clear_mem(). Указатели внутри imgdata принадлежат объекту и становятся недействительными после recycle(), нового open_* или разрушения экземпляра. Поэтому кэш приложения должен копировать нужные данные, а не хранить сырой адрес на внутреннюю память LibRaw.

Открытие файла, памяти и пользовательского потока

open_file и open_wfile

open_file() — самый простой вариант для локального пути. Метод не декодирует весь кадр: он разбирает заголовки, находит изображения и превью, выбирает декодер и заполняет доступные структуры. Для очень больших контейнеров существует форма с параметром bigfile_size, а в Windows — функции с широкими строками. Приложению не следует определять RAW только по расширению и пропускать открытие: настоящая проверка выполняется парсером.

Путь к файлу должен оставаться доступным, пока активен поток. Если каталог удаляется сразу после open_file(), а unpack() запускается позже, результат зависит от поведения файловой системы. В серверном приложении безопаснее переместить загрузку в неизменяемый рабочий каталог, открыть её внутри изолированного процесса, закончить распаковку и лишь затем удалять.

open_buffer

open_buffer(void*, size_t) позволяет читать RAW из памяти: это удобно для архивов, ресурсов, сетевого кэша и языковых обёрток. Метод не копирует весь предоставленный массив автоматически во владение вызывающей стороны; исходный буфер должен сохраняться до завершения всех операций, которым может понадобиться поток. Если его выделил сборщик мусора, обёртка обязана закрепить объект или создать стабильную нативную копию.

Не нужно загружать любой пользовательский файл целиком без ограничений только ради open_buffer(). Для крупных снимков двойное хранение контейнера и распакованной матрицы резко увеличивает пик памяти. Когда данные уже находятся на диске, файловый поток часто экономнее. Буфер имеет смысл при наличии собственного кэша, mmap или когда стоимость случайного доступа к внешнему хранилищу выше стоимости одной загрузки.

open_datastream

C++ API принимает наследника LibRaw_abstract_datastream. Пользовательская реализация предоставляет чтение, позиционирование, получение размера и дополнительные сведения. Так можно подключить контейнер внутри собственного формата, виртуальную файловую систему, шифрованное хранилище или объектный кэш. Критически важно реализовать семантику случайного доступа: RAW-парсер не ограничивается последовательным чтением от начала к концу, а переходит между IFD, MakerNotes, превью и сегментами изображения.

Поток должен корректно сообщать конец файла и ошибки, поддерживать большие смещения и не возвращать успешное чтение при неполном результате. Неверная реализация часто выглядит как «случайный» LIBRAW_IO_ERROR на отдельных камерах, потому что разные форматы используют разные схемы размещения данных. Тестировать собственный datastream нужно на наборе TIFF-подобных RAW, DNG с тайлами, контейнерах с несколькими превью и больших файлах.

open_bayer

open_bayer() предназначен не для обычного файла камеры, а для уже имеющегося массива Bayer без стандартного контейнера. Вызывающая сторона передаёт размеры, поля, паттерн, число неиспользуемых битов и чёрный уровень. Метод полезен при работе с промышленным сенсором, научной камерой или собственным транспортным форматом, но ответственность за правильное описание данных лежит на приложении. Ошибка в ширине строки, порядке байтов, CFA или полях не может быть исправлена по метаданным, которых нет.

Структура imgdata и чтение метаданных

libraw_data_t, доступная в C++ как RawProcessor.imgdata, объединяет публичные структуры. Большинство полей появляется уже после открытия, тогда как сенсорные данные заполняются после unpack(), а содержимое выбранного превью — после unpack_thumb(). Публичные заголовки libraw_types.h и libraw_const.h являются точным источником имён и типов для установленной ветки.

idata: тип изображения и CFA

В imgdata.idata находятся производитель и модель, нормализованные варианты названий, количество цветов, строка обозначений каналов, число RAW-изображений в контейнере, код фильтров и таблица X-Trans. По этим данным решают, применим ли обычный Bayer-конвейер. Функция COLOR(row, col) возвращает индекс компонента для координаты и надёжнее жёсткого вычисления RGGB, особенно при четырёх компонентах, CMYG и иных схемах.

Поле с количеством кадров важно для DNG и многокадровых режимов. Нулевой shot_select означает первый выбранный RAW, но «первый» не всегда равен самому большому или основному изображению. Для DNG доступны флаги, меняющие порядок или добавляющие enhanced-кадры и превью. Каталогизатору лучше показать пользователю список, а автоматическому конвертеру — явно зафиксировать правило выбора и записывать его в журнал.

sizes: геометрия сенсора и результата

imgdata.sizes различает полный RAW-массив, активную область и предполагаемый выход. Поля raw_width и raw_height относятся к хранимому сенсорному буферу; width и height — к видимой области до некоторых преобразований; iwidth и iheight используются постобработкой. Отступы left_margin и top_margin показывают начало активной области внутри полного массива. Именно путаница этих величин приводит к зелёным или чёрным полосам по краям и смещённому CFA.

Ориентация хранится отдельно. Поворот нельзя применять к сенсорным координатам до операций, зависящих от CFA и маскированных пикселей. В готовом просмотрщике удобно оставить декодирование в исходной геометрии, завершить демозаику и только затем повернуть RGB. Для расчёта конечных размеров без полного рендера служит adjust_sizes_info_only(); повторный вызов после уже изменённых размеров может дать неверный результат, поэтому его место в конвейере фиксируют однозначно.

Некоторые файлы содержат рекомендуемые inset crops. Метод adjust_to_raw_inset_crop() может перенести выбранную рамку в основные поля размеров, но документация советует делать это после unpack(), иначе изменение маскированной области способно нарушить расчёт чёрного. Приложение должно хранить исходную и применённую рамку отдельно, чтобы пользователь мог переключить «полный сенсор» и «рекомендованный кадр» без повторной догадки.

color: уровни, баланс и матрицы

imgdata.color содержит общий и поканальный чёрный уровень, максимумы, множители камеры cam_mul, предварительные множители pre_mul, матрицы преобразования и DNG-данные для источников света. Нулевые, отрицательные или явно невозможные коэффициенты нельзя слепо использовать: библиотека выставляет предупреждение о плохом камерном балансе, а вызывающая сторона выбирает резервный режим.

Поле maximum — не просто максимальное значение типа unsigned short. Оно отражает уровень насыщения после особенностей конкретного декодера и может корректироваться по данным кадра. Поканальные уровни важны для DNG, где насыщение каналов различается. Нормализация «значение / 65535» без вычитания чёрного и учёта реального максимума искажает экспозицию, баланс и запас в светах.

Матрица камеры не является готовым ICC-профилем для всех условий. Она даёт основу для перехода из пространства сенсора, но точная колориметрия может требовать интерполяции между источниками света, тональной кривой, профиля объектива и калибровки конкретной камеры. Для технического предпросмотра встроенных данных достаточно; для цветокритичного конвертера их объединяют с собственной системой профилей.

other, lens и MakerNotes

В imgdata.other находятся ISO, выдержка, диафрагма, фокусное расстояние, время съёмки, порядковый номер, описание, автор, компенсация вспышки и GPS. Структура lens собирает доступные сведения об объективе, креплении, фокусном диапазоне и идентификаторах из EXIF и MakerNotes. Отсутствующее значение часто равно нулю, поэтому ноль нельзя всегда интерпретировать как реальное измерение.

Vendor-specific MakerNotes представлены отдельными структурами, но LibRaw не заменяет специализированный редактор метаданных. Её цель — извлечь сведения, нужные для RAW-процессинга и идентификации. Она не предоставляет универсальный интерфейс записи EXIF, IPTC и XMP обратно в исходный RAW. Если приложение должно менять подписи, авторские поля или рейтинги, обычно применяют отдельную библиотеку и записывают sidecar либо метаданные выходного формата.

Для нестандартного тега можно установить set_exifparser_handler(). Обратный вызов получает номер, TIFF-тип, длину, порядок байтов и поток, установленный на данные тега. Это низкоуровневый механизм: обработчик обязан проверять длину, не выходить за границы и не нарушать позицию потока. Его используют точечно, когда штатной структуры недостаточно, а не для повторного разбора всего файла.

Распаковка сенсорных данных

unpack() запускает декодер, выбранный на этапе открытия, и помещает результат в imgdata.rawdata. В зависимости от формата ненулевым становится ровно один из указателей: raw_image для однокомпонентных 16-битных данных, color3_image или color4_image для трёх- и четырёхкомпонентных пикселей, либо соответствующий float*-буфер для плавающего DNG. Универсальный код сначала проверяет тип, затем выбирает ветку обработки; обращение к raw_image без проверки приводит к падению на форматах с другим представлением.

Распакованный массив — не копия байтов контейнера. Потоковое или блочное сжатие уже снято, данные могут быть приведены к удобному расположению, а отдельные форматы требуют обязательных декодерных преобразований. Поэтому результат обычно больше исходного RAW. Камерный файл мог хранить 12 или 14 бит на пиксель со сжатием, тогда как выгруженный TIFF занимает 16 бит без сопоставимой упаковки. Это нормальное следствие декомпрессии, а не скрытая ретушь.

Вычитание чёрного

Для собственной проявки предусмотрен subtract_black(). Метод учитывает общий и поканальный чёрный, обновляет максимумы и корректирует связанные поля. Обычный визуальный конвейер выполняет эту стадию до баланса белого и демозаики. Если вычитать одно число вручную, игнорируя таблицы и маскированные области, в тенях появляются цветовой сдвиг, полосы или разный уровень зелёных каналов.

В научной задаче решение зависит от методики. Иногда нужны значения до вычитания чёрного вместе с калибровочными полями, иногда — уже скорректированный сигнал. В обоих случаях сохраняют оригинальные уровни и точно документируют, какие флаги декодера применялись. Термин «необработанный» не гарантирует абсолютную неизменность: сама камера могла выполнить коррекцию дефектных пикселей или нелинейное кодирование, а декодер — обязательное разворачивание формата.

CFA и края активной области

При чтении Bayer-массива координаты цвета вычисляют в системе полного RAW-буфера. Если алгоритм начинает цикл с видимого (0,0), но забывает прибавить top_margin и left_margin, паттерн сдвигается. Симптом — сильная зелёно-пурпурная сетка даже при правильных коэффициентах. Метод COLOR() и поля отступов снимают эту неоднозначность.

Маскированные пиксели вокруг активной области могут участвовать в расчёте чёрного, но не входят в итоговый кадр. Утилита unprocessed_raw на поддерживаемых камерах умеет сохранить их вместе с данными; raw-identify -u -f помогает увидеть размеры. Для пользовательского изображения такие поля обрезают после калибровки, а для анализа сенсора сохраняют в отдельном канале или описании.

Плавающий DNG и многоканальные форматы

Float DNG хранится в float_image, float3_image или float4_image. Флаг LIBRAW_RAWOPTIONS_CONVERTFLOAT_TO_INT просит преобразовать значения в 16-битное целое, но такой шаг необратимо ограничивает диапазон и требует осознанной нормализации. Если дальнейший алгоритм поддерживает float, лучше не делать промежуточное квантование только ради привычного типа.

Полноцветные и малые YCC-форматы нельзя обрабатывать тем же кодом, что классический Bayer. Для sRAW существуют специальные флаги, способные отключить YCbCr-to-RGB и интерполяцию недостающих компонент, но они предназначены для эксперимента и собственного процессора. Базовый просмотрщик обычно оставляет штатное преобразование, иначе получает буфер, смысл которого должен интерпретировать самостоятельно.

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

Многие камеры записывают в RAW один или несколько предварительно проявленных кадров. После open_file() структура списка показывает количество, размеры, смещения, предполагаемый формат и поворот. unpack_thumb() извлекает выбранное по умолчанию превью, а unpack_thumb_ex(index) — элемент по индексу. Результат описан в imgdata.thumbnail: формат, ширина, высота, длина, число компонентов и указатель на данные.

Формат LIBRAW_THUMBNAIL_JPEG обычно означает готовый JPEG-поток, который можно без перекодирования передать JPEG-декодеру или записать как файл. Bitmap-превью представлено RGB-данными и при необходимости записывается как PPM. Встречаются 16-битные bitmap, а также контейнеры с H.265-кадром, который LibRaw извлекает без превращения в RGB. Приложение должно ветвиться по tformat, а не назначать расширение по привычке.

Отсутствие превью возвращает LIBRAW_NO_THUMBNAIL и не означает, что основной RAW неисправен. Неподдерживаемый тип даёт отдельную ошибку. Правильный просмотрщик в таком случае запускает половинную проявку или строит небольшой RGB сам. Размеры элемента в списке могут быть неизвестны до распаковки, поэтому выбор «самого большого» только по нулевым полям требует запасного правила.

Камерное превью не является эталоном сенсорных данных. Оно отражает Picture Style, контраст, шумоподавление, коррекцию объектива, баланс и кадрирование камеры. Оно подходит для мгновенной ленты и проверки композиции, но гистограмму RAW, запас светов и цвет пользовательской проявки по нему оценивать нельзя. Хорошая программа помечает источник изображения: «встроенное превью» или «проявка из RAW».

Быстрый сценарий для фотокаталога

1. Открыть файл и проверить код возврата, не вызывая unpack().
2. Прочитать модель, дату, выдержку, ISO, ориентацию и список превью.
3. Выбрать подходящий элемент по формату и размеру, затем вызвать unpack_thumb_ex().
4. Декодировать JPEG или bitmap, применить отдельный поворот превью и создать уменьшенную копию кэша.
5. Скопировать нужные метаданные, вызвать recycle() и перейти к следующему файлу.
6. Полную распаковку выполнять только для открытого пользователем кадра или фонового построения качественного превью.

Такой путь существенно экономит процессор и память по сравнению с полной демозаикой каждого файла. Ускорение зависит от камеры и размера превью, поэтому не стоит публиковать универсальные цифры. Принцип остаётся верным: сначала дешёвый разбор контейнера, затем готовое превью, и только по запросу — декодирование сенсора.

Базовая dcraw-совместимая проявка

Параметры imgdata.params типа libraw_output_params_t управляют dcraw_process(), файловыми writer-функциями и результатом в памяти. Большинство полей соответствует ключам dcraw. Их задают до постобработки; некоторые, влияющие на чтение и размер, — ещё до unpack(). Смешивание этапов затрудняет воспроизводимость: лучше сформировать отдельный объект настроек приложения, проверить диапазоны и одним блоком перенести их в LibRaw.

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

use_camera_wb выбирает коэффициенты, записанные камерой, если они пригодны. use_auto_wb вычисляет средний баланс по изображению. greybox[4] задаёт прямоугольник для расчёта, а user_mul[4] — явные множители R, G, B и второго G. Эти режимы не следует включать одновременно без понимания приоритета. Для интерфейса удобно сделать взаимоисключающий выбор: «камера», «авто», «область», «пользовательские коэффициенты».

Камерный баланс иногда отсутствует или помечен как плохой. Поведение fallback зависит от RAW-флага: можно перейти к авто или дневному свету. Программа должна показать пользователю, что применён резервный вариант, а не молча подписать его «As Shot». В пакетном конвертере этот факт записывают в журнал рядом с предупреждениями process_warnings.

Гамма, яркость и экспокоррекция

gamm[0] и gamm[1] описывают показатель и линейный участок выходной кривой. По умолчанию используются dcraw-совместимые параметры; для линейного результата оба значения ставят в 1. bright задаёт общий множитель. no_auto_bright отключает автоматическое поднятие яркости по гистограмме, а auto_bright_thr определяет долю допускаемого клиппинга.

Для технической передачи в другой процессор обычно выбирают 16 бит, линейную гамму, no_auto_bright=1 и документированный баланс. Иначе библиотека может визуально «улучшить» кадр, что удобно для просмотра, но мешает повторяемому анализу. Поля exp_correc, exp_shift и exp_preser выполняют сдвиг экспозиции до демозаики с управлением сохранением светов; это не заменяет полноценную тональную кривую.

Света и максимумы

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

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

Демозаика и подавление шума

user_qual выбирает доступный алгоритм: линейный, VNG, PPG, AHD, DCB и дополнительные варианты, если они включены в сборку. Неподдержанное значение может привести к fallback на AHD и соответствующему предупреждению. Поэтому список в пользовательском интерфейсе формируют по возможностям конкретной версии, а не копируют из старой справки.

half_size создаёт изображение половинного размера без обычной полной интерполяции и полезен для быстрых превью. four_color_rgb сохраняет два зелёных канала раздельно дольше обычного. threshold включает wavelet denoise, fbdd_noiserd — FBDD до демозаики, med_passes — медианные проходы. Эти методы базовые и не знают профилей шума конкретной камеры; для финального качества специализированный алгоритм обычно эффективнее.

Цветовое пространство и профили

output_color выбирает raw, sRGB, Adobe RGB, Wide Gamut, ProPhoto, XYZ, ACES, DCI-P3 или Rec. 2020 согласно поддерживаемым кодам ветки. Значение raw сохраняет пространство камеры и требует последующей интерпретации. use_camera_matrix управляет применением встроенных цветовых данных. При сборке с LCMS можно указать входной и выходной ICC-профили через camera_profile и output_profile.

Выбор широкого пространства сам по себе не увеличивает информацию, если до него уже произошло клиппирование или неверное преобразование. Для 8-битного файла sRGB обычно безопаснее для массового просмотра; для промежуточного 16-битного TIFF выбирают пространство всего конвейера и встраивают профиль на этапе записи, если writer и приложение это поддерживают. PPM не несёт полноценной системы цветового управления, поэтому его используют прежде всего как технический формат.

Разрядность, формат и поворот

output_bps выбирает 8 или 16 бит, output_tiff — TIFF вместо PPM/PGM. user_flip может отключить поворот или задать одно из поддерживаемых направлений; значение по умолчанию использует ориентацию RAW. cropbox задаёт прямоугольник до поворота, что важно для координат интерфейса. Если пользователь рисует рамку на уже повёрнутом превью, приложение должно пересчитать её обратно.

dcraw_process() вызывают только после успешного unpack(). Затем dcraw_ppm_tiff_writer() пишет файл, а dcraw_make_mem_image() возвращает структуру в памяти. Встроенный writer не создаёт JPEG, PNG или WebP. Для них обработанный bitmap передают соответствующему кодеку и отдельно решают вопросы профиля, EXIF, качества и субдискретизации.

Собственный процессинг поверх RAW

Если приложение строит свою проявку, после unpack() оно работает с rawdata, размерами, CFA, уровнями и матрицами, не вызывая dcraw_process(). Такой путь сложнее, зато позволяет контролировать каждую стадию: коррекцию дефектов, вычитание чёрного, линеаризацию, баланс, демозаику, шумоподавление, highlight recovery, цветовое преобразование, тональную кривую и коррекцию геометрии. LibRaw остаётся декодером и поставщиком метаданных.

Рекомендуемая последовательность

1. Проверить тип распакованного буфера, число компонентов и паттерн, а не предполагать Bayer.
2. Скопировать в журнал исходные чёрные уровни, максимумы, коэффициенты и выбранный кадр.
3. Определить активную область с учётом полей и inset crop, не разрушая данные калибровочных пикселей раньше времени.
4. Выполнить коррекцию дефектных пикселей и dark-frame, если она предусмотрена методикой.
5. Вычесть чёрный штатным методом или собственной реализацией, учитывающей поканальные таблицы.
6. Нормализовать каналы по реальным максимумам, не клиппируя отрицательные промежуточные значения без причины.
7. Применить баланс белого в линейном пространстве.
8. Выполнить демозаику, подходящую конкретному CFA; отдельно обработать монохромные и полноцветные массивы.
9. Перевести данные из пространства камеры в рабочее, затем выполнить шумоподавление и тональную обработку в выбранном порядке.
10. Применить ориентацию, геометрию объектива, кадрирование и масштабирование, после чего закодировать выход.

Порядок не универсален: часть процессоров подавляет шум до демозаики, часть после, а коррекция хроматических аберраций может работать на CFA. Важно другое — каждая стадия должна быть осознанной. Вызвать subtract_black(), а затем ещё раз вычесть сохранённый color.black — типичная двойная коррекция. Аналогично нельзя одновременно применить камерный баланс в LibRaw и повторить те же множители в своём коде.

Линейность и измерительные задачи

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

Сохраняйте версию LibRaw, имя декодера, raw_count, индекс кадра, режимы DNG, размеры, чёрные уровни, максимумы и предупреждения рядом с результатом. Тогда изменение данных после обновления можно объяснить, а не списать на «другую камеру». Для воспроизводимого исследования библиотеку и настройки фиксируют в окружении проекта.

Получение результата в памяти

Для GUI, плагина или сервиса промежуточный TIFF часто не нужен. После dcraw_process() метод get_mem_image_format() сообщает ширину, высоту, число каналов и бит на компонент, а copy_mem_image() копирует строки в предоставленный буфер с заданным stride и порядком RGB/BGR. Этот путь удобен, когда приложение уже владеет поверхностью рендера или объектом изображения.

dcraw_make_mem_image() выделяет libraw_processed_image_t, где указаны тип, ширина, высота, число цветов, битность, размер и массив байтов. Для превью действует dcraw_make_mem_thumb(). Возвращаемая структура может содержать bitmap или JPEG, поэтому поле type проверяют до интерпретации. После использования вызывают dcraw_clear_mem(); удалять указатель оператором delete нельзя.

Stride может быть больше width × channels × bytes_per_component из-за выравнивания поверхности. Копирование одной непрерывной операцией корректно только при плотной укладке. При 16 битах дополнительно учитывают порядок байтов конечного графического API. LibRaw сообщает битность, но не превращает произвольную структуру пикселя пользовательской библиотеки в свою.

Планирование памяти

Полный RAW, распакованный CFA, временный четырёхканальный imgdata.image, демозаичный RGB и выходной буфер могут одновременно находиться в памяти. Для камеры с десятками мегапикселей это намного больше размера файла на карте. Пиковую оценку строят по ширине, высоте, числу каналов, типу и временным копиям, а не по размеру RAW на диске.

Поле max_raw_memory_mb ограничивает размер RAW-буфера; при превышении возвращается LIBRAW_TOO_BIG. Это защита от чрезмерного выделения, но не полный лимит процесса: собственный RGB, кэш превью и кодеки тоже потребляют память. На сервере используют общий лимит контейнера или изолированного worker-процесса. На рабочей станции ограничивают число одновременно декодируемых кадров, а не запускают по задаче на каждое логическое ядро.

C API и языковые обёртки

C API повторяет основную схему C++: libraw_init(), libraw_open_file() или libraw_open_buffer(), libraw_unpack(), libraw_dcraw_process(), вывод, libraw_recycle() и libraw_close(). Первый аргумент почти всех функций — указатель libraw_data_t. Нулевой указатель возвращает EINVAL; остальные коды соответствуют правилам C++ API.

Для части полей есть getter/setter-функции: размеры, множители, матрицы, уровень насыщения, демозаика, цветовое пространство, битность, гамма, яркость и света. Они уменьшают зависимость от layout структуры при использовании динамической библиотеки другой совместимой минорной версии. Однако новый код всё равно должен проверять заголовки и ABI ветки, а не считать любой libraw.so взаимозаменяемым.

Python-разработчики часто используют rawpy — отдельную обёртку над LibRaw, возвращающую массивы NumPy и высокоуровневый postprocess(). Это удобный способ прототипирования, но сообщения, версии и значения enum принадлежат обёртке, а не обязательно напрямую совпадают с C++ API. При отладке полезно узнать, с какой LibRaw собран установленный пакет, и воспроизвести спорный файл официальным raw-identify.

Для .NET, Java, Rust и других языков действуют те же правила FFI: нативный объект не переносится между несовместимыми рантаймами без явного владения; callback не должен исчезнуть у сборщика мусора; входной буфер закрепляется; строки кодируются ожидаемым способом; освобождение выполняется той же библиотекой, которая выделила память. Обёртка должна превращать отрицательные коды LibRaw и положительные errno в понятные исключения, сохраняя исходное число для диагностики.

Многопоточность и производительность

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

OpenMP способен распараллелить некоторые стадии базовой постобработки. Если приложение одновременно запускает много внешних worker-ов, каждый из которых создаёт команду OpenMP, возникает oversubscription: число активных потоков многократно превышает число ядер, растут переключения и память. Обычно выбирают один уровень параллелизма: либо несколько файлов с ограниченным числом внутренних потоков, либо меньше файлов с OpenMP внутри. Настройку проверяют на реальной смеси камер, а не на одном маленьком кадре.

Progress callback при OpenMP может приходить не по строго возрастающим итерациям. Интерфейс не должен трактовать каждое значение как монотонный процент без нормализации. Удобнее отображать название стадии через strprogress(), хранить максимум полученной доли и считать callback сигналом состояния, а не точным секундомером.

Что ускоряет работу без потери корректности

• Для ленты сначала извлекать встроенное превью, а полную проявку запускать по требованию.
• Для метаданных ограничиваться open_file(); unpack() не нужен.
• Использовать half_size для быстрого качественного предпросмотра, когда камерного JPEG нет.
• Держать разумную очередь, чтобы диск читал последовательно, а память не заполнялась десятками CFA.
• Повторно рендерить открытый RAW с разными параметрами только там, где сохранённое состояние действительно допускает это; ориентироваться на multirender_test.
• Кэшировать результат по хэшу файла, версии декодера, индексу кадра и параметрам, иначе старое превью переживёт обновление.
• Не писать промежуточный TIFF, если следующий модуль принимает bitmap в памяти.

postprocessing_benchmark помогает увидеть время распаковки, демозаики и других стадий в конкретной среде. Его вывод нельзя превращать в обещание «LibRaw обрабатывает кадр за N секунд»: результат зависит от формата, сжатия, мегапикселей, диска, компилятора, OpenMP и выбранного алгоритма. Полезный вывод — какая стадия доминирует именно в вашем конвейере и изменилось ли это после обновления.

Callbacks, отмена и журналирование

set_progress_handler() принимает callback со стадией, номером итерации и ожидаемым числом. Возврат ненулевого значения прекращает обработку и даёт LIBRAW_CANCELLED_BY_CALLBACK. Кроме того, setCancelFlag() позволяет быстро запросить остановку декодера, а clearCancelFlag() — снять флаг перед следующей задачей. Отмена должна приводить к понятному состоянию UI и очистке временного файла, но не маскироваться как «повреждённый RAW».

set_dataerror_handler() сообщает об ошибке чтения: имя может быть NULL, а смещение равно позиции проблемы или -1 при неожиданном конце файла. Callback информационный; после фатальной ошибки библиотека очищает состояние и возвращает LIBRAW_IO_ERROR. Последующие операции над тем же состоянием дадут LIBRAW_OUT_OF_ORDER_CALL, поэтому обработчик не должен пытаться продолжить демозаику.

error_count() возвращает число нефатальных проблем диапазона, обнаруженных при распаковке. Поле process_warnings дополняет код возврата: плохой камерный баланс, отсутствие профиля, неправильный dark frame, fallback декодера, переход на AHD и другие ситуации могут оставить пригодный результат. В журнале полезно хранить три слоя: код функции, текст strerror() и битовую маску предупреждений.

Практические рабочие сценарии

Просмотрщик с мгновенной лентой

Поток сканирования открывает файл, читает метаданные и извлекает лучшее доступное превью. UI получает маленькую копию и сразу показывает карточку. Когда пользователь открывает кадр, отдельная задача вызывает unpack(), строит половинный либо полный RGB и заменяет камерный JPEG. В кэше хранят оба варианта с признаком источника, потому что их цвет и кадрирование могут различаться.

При переходе на другой кадр callback отменяет ненужную полную проявку. Worker освобождает результат, вызывает recycle() и берёт следующую задачу. Такая архитектура не блокирует интерфейс и не расходует память на полную демозаику всей папки.

Извлечение метаданных для каталога

Для каждой записи достаточно open_file(). Каталог сохраняет нормализованную модель, серийные и объективные данные, ISO, выдержку, диафрагму, фокусное, время, GPS, ориентацию, размеры и число RAW-кадров. Значения проверяются на ноль и диапазон. MakerNotes, которые не нужны поиску, не сериализуются целиком: это уменьшает схему и зависимость от внутренней структуры версии.

Перед импортом приложение вычисляет идентификатор файла и запоминает версию LibRaw. После обновления можно переиндексировать только кадры, для которых изменился парсер или появились поля. Если open_file() вернул unsupported, файл не удаляют: он остаётся в каталоге с причиной и может стать поддерживаемым после обновления.

Техническая конвертация в 16-битный TIFF

Сначала выбирают баланс и рабочее пространство, устанавливают output_bps=16, output_tiff=1, нужную гамму и состояние no_auto_bright. Затем выполняют open, unpack и dcraw_process(). Перед записью проверяют предупреждения, размеры и цветовое пространство. Имя выхода строят так, чтобы не перезаписать оригинал и не столкнуться двумя кадрами одного многокадрового DNG.

Если TIFF предназначен для дальнейшей цветокоррекции, обычно отключают автоматическую яркость и избегают агрессивного восстановления светов. Если это конечное превью, можно применить sRGB и визуальные параметры. Один и тот же пресет не должен одновременно называться «линейный мастер» и «готовое изображение».

Анализ CFA и качества сенсора

Инструмент открывает RAW, сохраняет все исходные размеры и уровни, распаковывает данные, определяет тип буфера и использует COLOR(). Маскированные области не отбрасываются до оценки чёрного. Программа строит статистику отдельно для каждого компонента, помечает насыщенные и дефектные пиксели и не применяет автояркость, гамму или художественное восстановление.

Для сравнения камер методика использует одинаковую физическую экспозицию и учитывает усиление, а не сравнивает значения JPEG. Результат сопровождается версией декодера и флагами. Если формат камеры выполняет внутри обязательную нелинейную операцию, это указывается как ограничение измерения.

Пакетная обработка папки

Сканер отделяет обнаружение файлов от декодирования. Очередь ограничена, например, несколькими задачами, а каждый worker имеет свой объект. После каждой функции проверяется код; фатальная ошибка завершает только текущий файл. Путь выхода создаётся атомарно во временном имени, а после успешной записи переименовывается. Это предотвращает появление «готового» обрезанного TIFF при остановке процесса.

Итоговый отчёт содержит успешные кадры, unsupported, no thumbnail, отменённые, повреждённые и превышающие лимит. Такие категории намного полезнее одного сообщения «не удалось обработать 12 файлов».

Сервис, принимающий чужие загрузки

RAW-парсер работает в отдельном непривилегированном процессе или контейнере с лимитом памяти, времени, размера файла и числа пикселей. Используется стабильный исправительный релиз, а не случайный snapshot. До декодирования проверяется общий размер, после открытия — заявленная геометрия, после распаковки — фактический объём. Сетевые запросы и доступ к произвольным путям из worker-а запрещены.

Timeout инициирует setCancelFlag(), затем при необходимости процесс завершается целиком. Один worker обрабатывает ограниченное число файлов и перезапускается, чтобы локализовать утечки сторонних кодеков. Такой дизайн важнее попытки «санитизировать» сложный бинарный RAW регулярными выражениями.

Ошибки и способы устранения

Новая камера не открывается

Поддержка определяется не расширением, а моделью, режимом и версией. Сначала запускают raw-identify -v на оригинальном файле, не прошедшем через мессенджер или облачную оптимизацию. Затем сверяют LibRaw::version(), список cameraList() и release notes. Минорное исправление стабильной ветки обычно не добавляет камеры, тогда как новая основная ветка или snapshot может содержать свежий декодер. Для публичного сервиса snapshot оценивают отдельно по риску.

Если модель заявлена, но конкретный режим не читается, приложите полный RAW, точное сообщение, имя декодера и параметры съёмки к отчёту. JPEG или DNG, созданный сторонним конвертером, не заменяет исходник для диагностики.

Цвет не похож на камерный JPEG

Это ожидаемо: камера использует собственный Picture Style, профиль, локальный контраст, шумоподавление, коррекцию оптики и тональную кривую. LibRaw не пытается воспроизвести каждый фирменный движок. Сначала проверьте, что выбран камерный баланс, правильная матрица, чёрный и максимум; затем сравнивайте линейные этапы. Точное совпадение требует отдельного профилирования и собственной обработки.

Приложение падает после нескольких файлов

Проверьте владение памятью: внутренние указатели нельзя использовать после нового open_file(); структуры dcraw_make_mem_image() освобождаются dcraw_clear_mem(); входной буфер для open_buffer() живёт до окончания чтения; callback остаётся действительным. В пакетном цикле логируйте память до и после recycle(). Если рост остаётся, разделите тест на декодирование, собственный RGB и выходной кодек.

Линкер не находит символы

Сверьте разрядность, имя библиотеки, порядок аргументов линкера и зависимости. Для статической GNU-сборки библиотеки обычно указываются после объектных файлов. Если LibRaw собрана с OpenMP, добавьте подходящий runtime или пересоберите без OpenMP. При LCMS, JPEG и других опциях статическая библиотека может требовать явных зависимостей. Ошибка с украшенными C++-именами нередко означает несовместимый компилятор или попытку вызвать C++ API как C.

Форматы, камеры и особые режимы

Список расширений полезен только как предварительный фильтр. CR2 и CR3 принадлежат разным поколениям контейнеров Canon, NEF менялся вместе с камерами Nikon, RAF охватывает Bayer и X-Trans, а DNG допускает мозаичные, линейные, плавающие, многокадровые и сжатые варианты. Поэтому формулировка «поддерживается DNG» слишком общая. Поддержка означает конкретное сочетание контейнера, схемы хранения, камеры и режима.

cameraList() возвращает модели, известные сборке, но наличие имени ещё не гарантирует одинаковую обработку всех размеров RAW, электронных затворов, high-resolution, pixel-shift и специальных сжатий. Обратная ситуация тоже возможна: совместимый DNG открывается без отдельной строки камеры. Автоматический тест должен работать с образцами каждого используемого режима, а не только проверять присутствие модели в списке.

Многокадровые RAW

Поле raw_count сообщает количество изображений. shot_select выбирает индекс до распаковки. Для Pentax Pixel Shift существуют флаги объединения кадров и порядок p4shot_order; для DNG — правила добавления и приоритета subimage. Если приложение всегда берёт нулевой кадр, оно может получить компонент многокадровой серии вместо ожидаемого объединённого результата.

Универсальный интерфейс показывает число кадров и позволяет выбрать. Автоматический pipeline сначала определяет известный режим, затем применяет явно заданную политику. При неизвестном контейнере безопаснее обработать первый стандартный RAW и записать предупреждение, чем бесшумно объединять данные по догадке.

Дополнительные декодеры

Сборка LibRaw может включать RawSpeed, Adobe DNG SDK или другие дополнительные компоненты. libraw_capabilities() сообщает доступные возможности, а параметры use_rawspeed и use_dng_sdk выбирают путь там, где он применим. Нельзя показывать переключатель RawSpeed, не проверив capability: в обычной сборке он ничего не даст.

Если RawSpeed не поддержал файл или сообщил проблему, LibRaw способна перейти на собственный декодер и выставить warning. Это не всегда ошибка результата, но важно для воспроизводимости. DNG SDK может обработать специальные Float, Linear или deflate-варианты, если библиотека собрана с ним. Такой выбор влияет на буфер, стадии DNG и лицензирование конечной поставки, поэтому фиксируется в конфигурации.

Превью новых типов

Современный RAW может хранить не только JPEG. Встречаются HEVC/H.265 и другие внутренние форматы, которые LibRaw извлекает как поток, но не обязательно декодирует в RGB. Просмотрщик должен иметь соответствующий мультимедийный декодер либо перейти к проявке сенсорных данных. Нельзя записать H.265-буфер с расширением JPG только потому, что старые камеры использовали JPEG.

Безопасная обработка недоверенных файлов

RAW — сложный бинарный контейнер с таблицами смещений, вложенными IFD, сжатыми сегментами и MakerNotes. Ошибочный размер способен привести к огромному выделению, а обрыв — к чтению за ожидаемым концом. Исправительные выпуски LibRaw нередко содержат проверки границ, поэтому обновление библиотеки является частью безопасности, а не только добавлением камер.

Публичные snapshots предназначены прежде всего для свежей поддержки и могут иметь незамороженный API/ABI. Для сервиса анонимных загрузок выбирают протестированный стабильный релиз с актуальными исправлениями. Если новая камера вынуждает использовать snapshot, его прогоняют через собственный corpus, fuzz-набор и изоляцию, а не просто заменяют библиотеку в production.

• Ограничьте размер входа, заявленные размеры изображения, raw_count и max_raw_memory_mb.
• Декодируйте без сетевого доступа и прав записи вне временного каталога.
• Установите таймаут и обрабатывайте отмену; после жёсткого превышения завершайте worker.
• Не доверяйте строкам Make, Model, Artist и Description: экранируйте их в HTML, JSON и логах.
• Проверяйте арифметику размера выходного буфера на переполнение до выделения.
• Не разрешайте входному имени формировать путь вывода без нормализации.
• Сохраняйте проблемный файл отдельно только по политике конфиденциальности и с ограниченным доступом.

Флаг проверки смещений превью помогает выявлять элементы, чьи offset и size выходят за контейнер. Однако ни один флаг не заменяет sandbox. Дополнительный JPEG, LCMS, DNG или видео-декодер расширяет поверхность атаки и должен обновляться вместе с LibRaw.

Тестирование интеграции

Один удачный NEF не доказывает готовность продукта. Нужен corpus, разбитый по производителю, модели и режиму: обычный сжатый RAW, lossless и lossy варианты, малый RAW, высокое разрешение, многокадровый файл, DNG с несколькими IFD, кадр без превью, повреждённая копия и файл с Unicode-путём. Образцы хранятся законно и не публикуются без разрешения автора.

Что проверять автоматически

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

Проверка цвета

Цветовую цепочку тестируют на нейтральных мишенях, насыщенных цветах, светах возле клиппинга и глубоких тенях. Отдельно сравнивают режимы камерного и автоматического WB, применение матрицы и выходное пространство. Камерный JPEG служит визуальной ссылкой на намерение производителя, но не абсолютным эталоном линейных данных.

При обновлении библиотеки сначала сравнивают black/maximum, матрицы и выбранный кадр. Если они изменились, разница во всём RGB закономерна. Попытка компенсировать её случайным коэффициентом яркости скрывает источник. Приложение должно уметь вывести диагностический отчёт до демозаики.

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

Измеряют отдельно open, thumbnail, unpack, process и output. Corpus содержит маленькие и большие файлы, разные виды сжатия и диск, похожий на пользовательский. В отчёте указывают процессор, число внешних и OpenMP-потоков, build flags и температуру кэша. Сравнение имеет смысл только при одинаковых параметрах качества и output.

Следят не только за средним временем, но и за пиком памяти, 95-м процентилем, отменой и поведением повреждённого файла. Просмотрщик может предпочесть быстрый preview даже при более медленной полной проявке; серверу важнее предсказуемый лимит, чем рекорд одного кадра.

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

Открытая LibRaw распространяется по двойной схеме LGPL 2.1 и CDDL 1.0: разработчик выбирает подходящую лицензию для использования библиотеки. Это не означает, что весь продукт обязан стать открытым при любом способе подключения, но конкретные обязанности зависят от выбранной лицензии, линковки, модификаций и способа распространения. Перед коммерческим выпуском их проверяет юрист или специалист по open-source compliance.

В дистрибутив включают тексты лицензий и уведомления, сохраняют сведения об изменениях библиотеки и обеспечивают требуемый выбранной лицензией способ замены или получения исходников. Если исходный код LibRaw изменён, условия к патчам отличаются от простого использования неизменённой DLL. Дополнительные DNG SDK, RawSpeed, LCMS, JPEG-кодеки и демозаичные пакеты имеют собственные условия, которые анализируются отдельно.

Поставка динамической библиотеки упрощает обновление безопасности, но требует контролировать ABI и поиск DLL/so. Статическая сборка делает пакет автономнее, однако увеличивает ответственность за зависимости и обновление. В обоих случаях программа при диагностике должна показывать runtime-версию через LibRaw::version(), а не только версию заголовков, с которыми она компилировалась.

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

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

LibRaw и ФотоМАСТЕР

ФотоМАСТЕР — готовый фоторедактор с графическим интерфейсом. Он открывает фотографию и предоставляет коррекцию света и цвета, шумоподавление и резкость, кадрирование, эффекты, портретную ретушь, удаление объектов, замену или размытие фона, замену неба и сохранение результата. Пользователь управляет изображением мышью и видит итог, не пишет код. Это подходящий выбор для обработки отдельных снимков и понятного визуального workflow.

LibRaw не предоставляет ни кистей, ни выделения, ни замены фона. Её преимущество в другом: приложение получает C/C++ API, сенсорный массив, CFA, уровни, матрицы, несколько RAW-кадров и превью. Разработчик решает, как представить их пользователю или обработать автоматически. ФотоМАСТЕР нельзя использовать как замену библиотеке внутри собственного конвертера, а LibRaw нельзя предложить фотографу вместо редактора без разработки оболочки.

Для автоматизации массового нестандартного анализа LibRaw гибче: можно читать только заголовки, сохранять четыре канала, строить собственный алгоритм и не создавать видимый документ. Для ретуши и композиционного монтажа ФотоМАСТЕР существенно практичнее, потому что нужные функции уже собраны в интерфейсе. Выбор определяется не «мощностью», а тем, кто выполняет работу — конечный пользователь или код приложения.

LibRaw и dcraw

dcraw — консольный декодер и конвертер, чьи ключи стали основой базовой обработки LibRaw. Он удобен как небольшая самостоятельная команда: получил RAW, применил параметры, записал PPM или TIFF. Для shell-сценария этого может быть достаточно. Встраивание же исполняемого файла требует запускать процесс, разбирать текстовый вывод, управлять временными файлами и связывать ошибки с конкретной стадией.

LibRaw превращает ту же область в библиотечный интерфейс: метаданные доступны структурами, сенсорный буфер остаётся в памяти, callbacks позволяют отменять работу, а один процесс может обслуживать очередь. Кроме того, архитектура без глобальных переменных рассчитана на многопоточную интеграцию. dcraw_emu помогает перенести знакомые параметры, но production-приложение постепенно заменяет командные ключи типизированной конфигурацией.

dcraw остаётся полезным эталоном поведения старой цепочки и простым инструментом, но LibRaw лучше подходит как компонент. Это сравнение не опирается на дату проекта: различие функциональное — standalone-команда против API с доступом к промежуточным данным.

LibRaw и RawSpeed

RawSpeed — C++-библиотека, сфокусированная на быстром декодировании RAW и выдаче немодифицированных данных, CFA и уровней. Она широко используется там, где приложение строит весь последующий процесс самостоятельно. Камерные определения связаны с конкретной версией cameras.xml, поэтому файл данных и код обновляют согласованно.

LibRaw предоставляет более широкий dcraw-подобный слой: помимо распаковки и метаданных, у неё есть превью, C API, готовая базовая постобработка, writers и многочисленные диагностические образцы. С другой стороны, если проекту нужен только быстрый декодер внутри уже развитого RAW-движка, RawSpeed может лучше соответствовать архитектуре. LibRaw также может быть собрана с поддержкой RawSpeed и использовать его для подходящих файлов, сохраняя собственный внешний API и fallback.

Сравнивать скорость абстрактно нельзя. Она зависит от формата, ветки, compiler flags и того, включён ли в замер постпроцессинг LibRaw, которого у прямого декодера может не быть. Сначала выравнивают объём работы: только unpack против только decode, одинаковый файл и число потоков.

LibRaw и Adobe DNG SDK

Adobe DNG SDK предоставляет инструменты для DNG, включая разбор и операции, специфичные для этого стандарта. Он полезен, когда приложение создаёт, проверяет или глубоко обрабатывает DNG и должно следовать его модели стадий. Но множество камер пишет собственные CR3, NEF, ARW, RAF и другие контейнеры; DNG SDK сам по себе не является универсальным декодером всех этих файлов.

LibRaw выбирают для единого входа от большого набора производителей. При сборке с DNG SDK она способна делегировать ему специальные варианты DNG, оставляя вызывающему приложению один API. Цена — более сложная сборка и необходимость учитывать лицензии и версии двух компонентов. Для DNG-центричного продукта прямое использование SDK может дать больше контроля; для универсального просмотрщика LibRaw обычно проще как фасад.

Как выбрать архитектуру проекта

LibRaw подходит, если приложение должно принимать фирменные RAW, быстро получать превью и метаданные, иметь доступ к CFA или строить собственную проявку. Библиотека особенно уместна, когда обработка автоматическая или интерфейс уже существует. Она снимает трудоёмкую часть разбора десятков контейнеров, но оставляет творческую и продуктовую логику разработчику.

Не стоит строить на одной базовой dcraw_process() обещание профессионального конвертера. Для такого продукта понадобятся отдельные модули: современная демозаика, профильное шумоподавление, база объективов, управление цветом, тональная модель, локальные корректировки, output codecs и metadata writer. LibRaw будет входным слоем, а не всем движком.

Если задача ограничена ручным улучшением фотографий, выбирают готовый редактор. Если нужен shell-конвертер без программирования — командную утилиту. Если RAW уже приведён к DNG и важны DNG-специфичные стадии — оценивают профильный SDK. Правильная архитектура часто комбинирует компоненты: LibRaw декодирует, собственный pipeline обрабатывает, отдельная библиотека кодирует JPEG/TIFF/PNG и ещё одна пишет XMP.

Частые вопросы

Можно ли открыть LibRaw и редактировать фотографию?

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

Может ли LibRaw сохранить JPEG?

Встроенная dcraw-цепочка записывает PPM/PGM или TIFF и возвращает bitmap/JPEG-превью в памяти. Полностью проявленный JPEG кодируют внешней библиотекой из полученного RGB. При этом отдельно задают качество, профиль, EXIF и ориентацию.

Можно ли изменить и записать исходный RAW?

LibRaw — читатель и декодер. Она не предназначена для пересборки фирменного RAW с изменёнными пикселями или MakerNotes. Изменения сохраняют в sidecar, базе приложения или новом TIFF, DNG, JPEG и другом выходном формате с подходящим writer-ом.

Даёт ли unpack абсолютно исходные значения сенсора?

Он даёт распакованные данные в представлении LibRaw, но контейнерное сжатие уже снято, а формат мог требовать обязательного преобразования. Камера также могла выполнить внутреннюю коррекцию. Для измерений изучают decoder flags, сохраняют чёрный и максимум и проверяют линейность экспериментально.

Нужно ли вызывать subtract_black?

Для собственной обычной проявки — как правило, да; dcraw_process() делает это сам. Для научной задачи решение зависит от методики. Нельзя вызывать штатное вычитание и затем повторять его вручную.

Почему preview и проявка отличаются?

Preview создан камерой с её стилем, контрастом, балансом, коррекцией объектива и шумоподавлением. Проявка LibRaw использует другую базовую цепочку. Отличие само по себе не указывает на ошибку; грубый оттенок или сетка требуют проверки CFA, WB и уровней.

Можно ли использовать LibRaw из Python?

Да, обычно через отдельную обёртку rawpy. Она предоставляет массивы и удобный postprocess, но версия встроенной LibRaw может отличаться от системной. Для сложной диагностики сравнивают результат с официальными примерами той же нативной версии.

Потокобезопасна ли библиотека?

Архитектура рассчитана на многопоточную работу, но каждый параллельный файл должен иметь свой экземпляр. Один LibRaw нельзя одновременно менять из нескольких потоков. Нужно также учитывать OpenMP и потокобезопасность собственных callbacks и output codecs.

Как узнать, поддерживается ли камера?

Проверить оригинальный файл через raw-identify, runtime-версию и cameraList(). Имя в списке — хороший признак, но специальные режимы тестируют отдельно. Расширение файла не является достаточным доказательством.

Что делать, если превью отсутствует?

Обработать LIBRAW_NO_THUMBNAIL как штатную ветку и построить half-size либо полный RGB. Не следует объявлять файл повреждённым или показывать пустую карточку, если основной RAW успешно распаковывается.

Зачем нужны raw_width и width одновременно?

raw_width описывает хранимый массив, включая служебные области; width — видимую часть. Отступы связывают их. Для CFA и чёрного нужен полный массив, для конечной фотографии — активная область.

Можно ли применять dcraw_process в коммерческом продукте?

Технически его можно использовать в рамках лицензии, но разработчики позиционируют этот рендер как базовый, демонстрационный и совместимый с dcraw, а не как современную production-проявку. Для простого viewer этого достаточно; для продукта, продающего качество RAW, нужен собственный процессор.

Почему после обновления меняется результат?

Могли измениться декодер, black level, матрица, выбор подкадра, обработка DNG или исправление ошибки. Сравните диагностические поля и warnings до RGB. Версию библиотеки и параметры всегда включают в ключ кэша и отчёт.

Как корректно завершить обработку после ошибки?

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

Переход с dcraw на LibRaw

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

Соответствие ключей и полей

Ключ -4 часто понимают слишком упрощённо. В dcraw-совместимой логике он означает 16-битный линейный выход вместе с определёнными настройками гаммы и автояркости, а простое присваивание output_bps=16 меняет только глубину. При переносе пресета нужно воспроизвести всю комбинацию, иначе новый TIFF будет 16-битным, но тонально отличаться.

Текстовый stderr старой утилиты заменяют структурированным результатом. Например, unsupported, no thumbnail и bad crop — разные классы, которые UI может объяснить отдельно. Имя выходного файла больше не обязано строиться внутри decoder-а: приложение может выбрать собственный формат, атомарную запись и политику конфликтов.

От процесса к объекту

Shell-запуск естественно изолировал каждый файл отдельным процессом. После перехода на библиотеку состояние живёт дольше, поэтому ошибки владения становятся заметнее. Сначала стоит сохранить модель «один объект — один файл», уничтожая экземпляр после операции. Когда тесты стабильны, объект можно переиспользовать через recycle() и добавить pool. Оптимизация до корректной очистки затрудняет поиск проблемы.

Если прежний скрипт передавал stdout следующей команде, аналогом служит copy_mem_image() или dcraw_make_mem_image(). Это исключает сериализацию PPM, но соседний модуль должен понимать битность, stride, порядок каналов и цветовое пространство. Неявные свойства pipe теперь становятся частью контракта функций.

Разбор предупреждений process_warnings

Успешный код возврата не гарантирует идеальные входные данные. Маска process_warnings сообщает о ситуациях, в которых библиотека смогла продолжить. Приложение должно расшифровать известные биты и сохранить неизвестные числом: после обновления могут появиться новые предупреждения, которые старая оболочка ещё не умеет подписывать.

• LIBRAW_WARN_BAD_CAMERA_WB означает, что запрошенный камерный баланс непригоден; показывайте фактически использованный fallback.
• LIBRAW_WARN_NO_EMBEDDED_PROFILE и профильные ошибки требуют проверить LCMS, путь и наличие данных, а не повторять рендер с теми же параметрами.
• LIBRAW_WARN_NO_BADPIXELMAP сообщает, что внешний список дефектов не прочитан; результат возможен, но заявленная коррекция не выполнена.
• LIBRAW_WARN_BAD_DARKFRAME_FILE и LIBRAW_WARN_BAD_DARKFRAME_DIM указывают на формат или размеры dark frame; применять его частично нельзя.
• Флаги RawSpeed различают успешное использование, unsupported и problem с fallback на внутренний декодер.
• LIBRAW_WARN_FALLBACK_TO_AHD показывает, что выбранная демозаика недоступна и результат создан другим алгоритмом.

Предупреждение не обязательно показывать модальным окном. В просмотрщике достаточно значка в диагностике; в пакетном конвертере — строки отчёта; в научном pipeline некоторые биты повышаются до ошибки, потому что меняют методику. Политика задаётся приложением, но игнорировать маску полностью нельзя.

Повторный рендер одного файла

Интерактивный интерфейс часто меняет баланс, гамму или алгоритм без повторного чтения RAW. LibRaw хранит резервные данные, необходимые для повторной dcraw-постобработки, а multirender_test показывает принцип. Это экономит I/O и распаковку, но не любой параметр можно менять на поздней стадии. shot_select, некоторые специальные флаги, коррекция аберраций и параметры, влияющие на размеры или unpack, требуют открыть либо распаковать заново.

Практично разделить настройки на три группы. Первая действует до открытия: ограничения и выбор потока. Вторая действует до unpack(): кадр, RAW-опции и форматные особенности. Третья меняется перед dcraw_process(): WB, gamma, output color, demosaic, highlights и brightness. UI помечает изменение первой или второй группы как «нужна перезагрузка RAW», а третью применяет к сохранённому распакованному буферу.

После каждого рендера старый imgdata.image заменяется внутренней логикой, поэтому внешние указатели на него не сохраняют. Если кадр передан GPU, создают собственную копию или синхронизируют жизнь ресурса. Кэш результата включает весь набор параметров; иначе смена highlights может вернуть старый bitmap.

Контрольный список перед выпуском

Сборка и зависимости

• Runtime и compile-time версия выводятся в диагностике; несовместимость ABI обнаруживается при запуске тестов.
• Разрядность, CRT и тип линковки единообразны для приложения и нативных модулей.
• Фактические capabilities для LCMS, Unicode paths, RawSpeed и DNG SDK проверяются кодом.
• Лицензии LibRaw и опциональных компонентов входят в поставку.
• Процесс обновления библиотеки и security-исправлений документирован.

Корректность данных

• Проверяются все коды каждой стадии, process_warnings и error_count().
• Тип rawdata, thumbnail и processed image определяется по enum, а не по расширению.
• Размеры и умножения проверены на переполнение до выделения.
• Margins, ориентация, crop и CFA протестированы на камерах с разной геометрией.
• Камерный, автоматический и ручной WB не включаются одновременно.
• Технические пресеты отключают нежелательные auto-bright, gamma и highlight reconstruction.

Ресурсы и UX

• Входной буфер живёт достаточно долго, а внутренние указатели не переживают recycle().
• Каждый memory image освобождается штатной функцией; cancel не оставляет временный файл.
• Параллелизм ограничен, OpenMP не создаёт oversubscription, пиковая память измерена.
• No thumbnail имеет fallback, unsupported не приводит к удалению оригинала, warnings доступны пользователю.
• Кэш зависит от версии, индекса кадра и всех влияющих параметров.
• Оригинал никогда не перезаписывается writer-ом без отдельного подтверждённого решения приложения.

Такой список полезнее общего теста «открывается у меня». Он охватывает поведение на другой машине, обновление DLL, необычную камеру, отмену и нехватку памяти — именно там проявляются ошибки интеграции, которые не видны на одном демонстрационном кадре.

Минимальный диагностический отчёт

Когда пользователь присылает проблемный файл, полезно запросить не скриншот сообщения, а компактный отчёт: runtime-версию LibRaw, код и текст ошибки, Make/Model, размеры, raw_count, выбранный shot_select, имя декодера, тип ненулевого rawdata-буфера, маску process_warnings, error_count() и параметры, отличающиеся от значений по умолчанию. Для сбоя после постобработки добавляют WB-режим, user_qual, highlight, гамму, output color и bit depth. Такой набор позволяет отличить неподдержанную камеру от неверного порядка вызовов, повреждения, отсутствующего профиля и ошибки собственной оболочки, не раскрывая содержимое фотографии.

Если нужен исходный RAW, передача согласуется отдельно: файл может содержать GPS, серийный номер камеры, имя автора и изображение высокого разрешения. В публичный баг-трекер не помещают его автоматически. Сначала воспроизводят проблему на обезличенном или разрешённом образце, а метаданные отчёта экранируют перед выводом в HTML.

Практический итог

LibRaw оправдана там, где RAW должен стать частью программного продукта, а не разовой фотографией в редакторе. Она унифицирует открытие контейнеров, предоставляет метаданные, геометрию, CFA, калибровочные уровни, превью и распакованные данные, поддерживает C и C++, работу с файлами, памятью и собственными потоками, callbacks, ограничения ресурсов и базовый dcraw-совместимый рендер. Максимальную пользу библиотека даёт при строгом порядке вызовов, проверке типов буфера и предупреждений, отдельном объекте на поток, контроле памяти и тестовом corpus по режимам камер. Её ограничения столь же важны: нет пользовательского интерфейса, каталога, ретуши, универсальной записи метаданных и современного готового RAW-движка. Если принять эту границу, LibRaw становится надёжным входным слоем, поверх которого можно строить просмотрщик, конвертер, анализатор или специализированный фотопроцессор без повторной реализации множества закрытых форматов.

Читайте также: ФотоМАСТЕР и Excire Foto.