第6章：LibRaw：RAW 解码实战

工欲善其事，必先利其器：从 git clone 源码、绕开 dcraw.c 下载的坑，到 open_file → unpack → dcraw_process 三步把底片读成位图

6.1 工欲善其事：为什么是 LibRaw

还记得第 3 章那张 RAW 解剖图吗？文件头是"门牌号"，IFD 是"目录"，tag 是"条目"，传感器图像数据是"正文"，而拜耳马赛克让每个像素只记录一种颜色。图纸画得再清楚，真到了服务端要处理 dng、CR2 的时候，总不能自己写解析器——几十家厂商、几十种方言，光"非标准文件头 + 私有 tag + 数据加密"这三样就够写三年。这正是LibRaw 存在的理由：把"读懂各种 RAW"这件事封装成一个库，让你的程序只跟一种接口打交道。

LibRaw 是什么？官网（libraw.org）的定义很直白：一个从数码相机 RAW 文件里提取数据的库，支持 CRW/CR2、NEF、RAF、DNG、MOS、KDC、DCR 等几乎所有 RAW 格式。它的血统值得一提：LibRaw 2008 年立项，基础是 David Coffin 写的经典命令行工具 dcraw.c；dcraw 本身在 2018 年停止维护，此后新机型的支持全靠 LibRaw 团队自己维护，现行稳定版是 0.22.x。许可证是双许可：LGPL 2.1 或 CDDL 1.0，二选一，对服务端商用都友好。第 5 章选型全景里它被定位为"RAW 解码专用"，这一章就把它从源码装起来、用起来。

# 先验明正身：素材里的真实需求——服务端拿到的就是这类"底片"
$ file IMG_0001.CR2 test.dng
# IMG_0001.CR2: Canon CR2 RAW image data, 6000x4000, little-endian
# test.dng:    TIFF image data, little-endian, direntries=13, height=4000 ...

# 体积对比：同一画面，底片通常比 JPEG 大一个数量级
$ ls -lh IMG_0001.JPG IMG_0001.CR2
# -rw-r--r-- 482K IMG_0001.JPG
# -rw-r--r-- 5.8M IMG_0001.CR2

# LibRaw 与 dcraw 的血缘（官网 Project history）：
dcraw.c（Dave Coffin，1997-2018 维护）
   └── 2008 年 LibRaw 立项：把 dcraw.c 改造成可被程序调用的库
        ├── 去掉全局变量、做成线程安全
        ├── 大幅增强元数据提取
        └── 2018 年 dcraw 停更后，新机型支持全部由 LibRaw 团队接手
            （现行稳定版 0.22.x，双许可 LGPL 2.1 / CDDL 1.0）

6.2 磨刀：源码下载与编译环境

决定自己编译 LibRaw 的原因很实际：官方发布页提供 0.22.2 的源码包，但很多发行版的包管理器里版本偏旧，而且我们后面要写程序、想直接读源码排错，源码树最合适。第一步是克隆官方仓库：git clone https://github.com/LibRaw/LibRaw.git。注意素材笔记里是 2020 年的操作（LibRaw 0.19/0.20 时代），那时克隆下来目录里就有 DEVELOPER-NOTES 文件——它提示你：先执行 mkdist.sh 脚本来生成编译所需的东西。为什么？因为仓库里没有直接放 configure 脚本，它要靠 autoconf/automake 现场生成；mkdist.sh 就是干这个的，顺带还会拉一个特殊文件（下一节的主角 dcraw.c）。

编译环境按素材里的真实流程准备依赖。素材跑在 CentOS/RHEL 系，用 yum 装：autoconf、automake（生成 configure 与 Makefile）、libtool（构建共享库）、gcc / gcc-c++（C/C++ 编译器）、make（构建驱动）、pkgconfig（生成 libraw.pc）、freetype-devel（字体/文本相关，可选模块需要）、lcms2 与 lcms2-devel（色彩管理库 Little CMS，处理 ICC 色彩配置文件）、jasper 与 jasper-devel（JPEG-2000 编解码，部分格式需要）。Debian/Ubuntu 系把 yum 换成 apt、包名去掉 -devel 后缀（如 liblcms2-dev）即可，思路完全一样。

# 素材真实流程：克隆源码（现行主分支即 0.22 系）
$ git clone https://github.com/LibRaw/LibRaw.git
$ cd LibRaw

# 听 DEVELOPER-NOTES 的话：先看它说了什么
$ head -30 DEVELOPER-NOTES
# 大意：仓库需要先跑 mkdist.sh 生成 configure 等构建文件

$ ls
# Changelog.txt  COPYRIGHT  Makefile.am  configure.ac  internal/
# lib/  mkdist.sh  samples/  src/  ...

# 素材真实流程（CentOS/RHEL 系，yum 装依赖）：
$ yum install autoconf automake freetype-devel gcc gcc-c++ libtool make pkgconfig -y
$ yum install wget -y
$ yum install lcms2 lcms2-devel -y
$ yum install jasper jasper-devel -y

# 检查关键工具是否就位：
$ autoconf --version | head -1
$ g++ --version | head -1

6.3 排障：dcraw.c 下载失败的坑

磨刀总会碰到硌手的石头。素材笔记里记录了一个真实坑：执行 mkdist.sh 时，它尝试从网上下载 dcraw.c，结果失败了。dcraw.c 是 Dave Coffin 的经典工具源码，LibRaw 的历史代码直接继承自它，mkdist.sh 会在生成构建文件时把它拉下来（现行版本里这份源码对应关系已经重构进 src/，但这个"脚本要联网拉东西"的思路保留了下来）。下载失败的原因通常是网络不通或站点临时不可达——服务端环境尤其常见。

素材的解决方法是教科书式的"看脚本、改脚本、手动补"：先打开 mkdist.sh 找到下载 dcraw.c 的那一行，把自动下载的步骤注释或绕过去，然后手动用 wget 从 dcraw 的官方站点下载：https://www.dechifro.org/dcraw/dcraw.c（dechifro.org 就是 Dave Coffin 的站点，LibRaw README 里也指向它），把文件放到脚本期望的位置，再重新执行 mkdist.sh。这条排障链的价值不在命令本身，而在思路：构建脚本失败时，先读脚本，再决定是修网络、修脚本还是手动补文件。

# 1) 打开 mkdist.sh，找到与 dcraw 相关的下载步骤
$ grep -n dcraw mkdist.sh
# ... 某一行：wget 某处/dcraw.c（素材里这一行下载失败）

# 2) 手动下载官方 dcraw.c，放到脚本期望的路径
$ wget https://www.dechifro.org/dcraw/dcraw.c
# --2026-08-08 ... 'dcraw.c' saved [198K]

# 3) 修改 mkdist.sh：把失败的自动下载步骤注释掉（前面加 #）
#    （示意，具体行号以你克隆的版本为准）
# wget http://example.invalid/dcraw/dcraw.c   <- 注释掉

# 4) 重新执行 mkdist.sh，这次它直接用本地文件
$ ./mkdist.sh

# 下载完验证文件不是 HTML 错误页：
$ file dcraw.c
# dcraw.c: C source, ASCII text, with very long lines
$ wc -l dcraw.c
# 15000 左右（dcraw.c 是著名的"单文件怪物"）

# mkdist.sh 跑完后，configure 脚本就生成了：
$ ls configure
# configure

6.4 开刃：configure、make、make install

构建文件齐了，接下来是经典的 autotools 三连：configure → make → make install。素材里的 configure 命令是 ./configure --prefix=/usr/local/helios CXX=/usr/local/bin/g++——两个参数各有用意：--prefix 指定安装目录（装到 /usr/local/helios 而不是系统目录，便于管理、卸载干净）；CXX=/usr/local/bin/g++ 是指定 C++ 编译器路径（素材机器上系统自带的是老版本 g++，他们另外装了新的，用 CXX 变量指过去）。注意素材那台机器的 g++ 是 4.8.5——这个数字先记下，6.7 节会引出一个大坑。

make 开始编译：LibRaw 会同时产出两个库——libraw（单线程版，一般程序链接它）和 libraw_r（reentrant 可重入版，编译时带 -pthread，多线程程序用）；头文件装到 include/libraw/；示例程序装到 bin/（raw-identify、simple_dcraw、dcraw_emu 等，下一节的主角）；另外还有 pkg-config 用的 libraw.pc / libraw_r.pc。make install 之后，用 pkg-config --modversion libraw 验证安装，用 ls 看看三个目录的产物——"工欲善其事"的第三步：验收工具真的装好了。

# 素材真实流程：configure（指定安装前缀 + C++ 编译器）
$ ./configure --prefix=/usr/local/helios CXX=/usr/local/bin/g++
# checking for g++... /usr/local/bin/g++
# checking for gcc... gcc
# ...
# config.status: creating Makefile

# 编译 + 安装
$ make
# g++ ... -c src/libraw_c_api.cpp ...
$ make install
# /usr/local/helios/bin/raw-identify
# /usr/local/helios/bin/simple_dcraw
# /usr/local/helios/bin/dcraw_emu
# /usr/local/helios/lib/libraw.a  /usr/local/helios/lib/libraw_r.a
# /usr/local/helios/include/libraw/libraw.h

# 验收：三个视角各看一眼
$ ls /usr/local/helios/lib /usr/local/helios/include/libraw /usr/local/helios/bin
$ pkg-config --modversion libraw
# 0.22.2（素材时代是 0.19/0.20，现行版本号以实际编译为准）
$ /usr/local/helios/bin/raw-identify IMG_0001.CR2
# Canon EOS R5 6000x4000 ...  <- 能读出底片信息，说明库装好了

# 写程序时怎么找到库？链接参数：
$ pkg-config --cflags --libs libraw
# -I/usr/local/helios/include/libraw -L/usr/local/helios/lib -lraw

6.5 试刀：dcraw_emu 命令行

刀开了刃，先劈两根柴试试手。素材笔记里提到的命令行工具是 libraw_dcraw——那是当时对"dcraw 模拟器"的叫法；现行 0.22 源码树里对应的示例程序叫 dcraw_emu（samples/dcraw_emu.cpp，编译产物 bin/dcraw_emu），官网的说明是"almost complete dcraw emulator"（几乎完整的 dcraw 模拟器）。它把 dcraw 的命令行参数几乎全部继承了下来，是验证"库能不能读某个文件"最快的工具——也是素材里服务端转码脚本的骨干。

常用参数挑几个说人话：-v 详细模式（打印解码过程）；-w 用相机白平衡、-a 用整幅图像平均做白平衡；-q N 选去马赛克算法（0=线性、1=VNG、2=PPG、3=AHD、4=DCB——第 3 章讲过，去马赛克就是把缺的颜色从邻居"借"出来，算法质量决定锐度）；-6 输出 16 位、-T 输出 TIFF（默认 PPM）；-o sRGB 指定输出色彩空间；-t N 旋转翻转；-h 输出半尺寸图（快一倍）。记住这些，是因为第 3 章那条"dcraw -e 提取缩略图 / dcraw -v 完整解码 + ffmpeg 转 JPEG"的流程，现在换汤不换药。

# 试刀 1：完整解码成 PPM（-v 看过程，-w 用相机白平衡）
$ dcraw_emu -v -w IMG_0001.CR2
# Loading Canon EOS R5 image from IMG_0001.CR2 ...
# Scaling against darkness ...
# AHD interpolation ...        <- 默认去马赛克算法
# IMG_0001.ppm 写入完成

# 试刀 2：直接输出 TIFF，并指定 16 位 + sRGB 色彩空间
$ dcraw_emu -T -6 -o sRGB -q 3 IMG_0001.CR2
# 输出 IMG_0001.tiff（-q 3 = AHD 去马赛克）

# 试刀 3：半尺寸 + 全图平均白平衡，快速出预览图
$ dcraw_emu -h -a -T IMG_0001.CR2

# 素材服务端思路的"库版"：批量 CR2 -> JPEG
# dcraw_emu 输出 PPM/TIFF，再用 ffmpeg 压成 JPEG（第 3 章同款组合）
$ for f in *.CR2; do
    dcraw_emu -w -T "$f"
    ffmpeg -y -i "${f%.CR2}.tiff" "${f%.CR2}.jpg"
done

# 先看底片里有没有内嵌缩略图：simple_dcraw 模拟 dcraw -e 的行为
# （samples 里的另一个示例，专门提取内嵌预览图）
$ simple_dcraw -e test.dng
# test.thumb.jpg 提取完成（毫秒级，不需要完整解码）

6.6 核心 API：open_file → unpack → dcraw_process

命令行只是试刀，真正的活要写进程序。LibRaw 的 C++ API 极简，核心就三步，而且每一步都对应第 3 章的五层结构：① open_file() 打开文件、解析文件头与各层元数据（IFD/tag 全读进 imgdata 结构：idata 里是厂商型号，sizes 里是尺寸，color 里是色彩信息，thumbnail 里是缩略图描述）；② unpack() 真正解压"传感器图像数据"层——把压缩的拜耳马赛克解成原始像素；③ dcraw_process() 做后处理：去马赛克、白平衡、缩放、色彩空间转换，产出可显示的 RGB 图像。官方原话：一个 LibRaw 对象同时只能处理一个文件，但可以串行处理任意多个文件。

两个细节必须知道：错误码约定——所有 API 返回 int，LIBRAW_SUCCESS（值为 0）表示成功，出错时用 libraw_strerror(返回值) 转成人话，写程序务必逐级检查（素材里 open_file 就崩过一次，见 6.7）；内存管理——如果用 dcraw_make_mem_image() 把结果拷进内存缓冲，用完必须 dcraw_clear_mem() 释放；处理完一张调用 recycle() 复位对象，好处理下一张。下面是完整的"CR2 → PPM"最小程序，照着官网 API 示例写，直接可编译。

// raw2ppm.cpp：LibRaw 三步走最小示例（照官网 API 示例组织）
#include <cstdio>
#include "libraw/libraw.h"

int main(int argc, char **argv) {
    if (argc < 2) {
        fprintf(stderr, "usage: %s <rawfile>\n", argv[0]);
        return 1;
    }
    LibRaw processor;                          // ① 创建图像处理器对象

    int ret = processor.open_file(argv[1]);     // ② 打开文件，读元数据
    if (ret != LIBRAW_SUCCESS) {
        fprintf(stderr, "open_file: %s\n",
                libraw_strerror(ret));
        return 1;
    }
    // 元数据此刻已在 imgdata 里：厂商/型号/尺寸/色彩信息
    printf("make=%s model=%s size=%dx%d\n",
           processor.imgdata.idata.make,
           processor.imgdata.idata.model,
           processor.imgdata.sizes.width,
           processor.imgdata.sizes.height);

    ret = processor.unpack();                  // ③ 解压传感器像素（拜耳马赛克）
    if (ret != LIBRAW_SUCCESS) {
        fprintf(stderr, "unpack: %s\n", libraw_strerror(ret));
        return 1;
    }

    ret = processor.dcraw_process();             // ④ 后处理：去马赛克/白平衡/色彩空间
    if (ret != LIBRAW_SUCCESS) {
        fprintf(stderr, "dcraw_process: %s\n", libraw_strerror(ret));
        return 1;
    }

    // ⑤ 写文件：dcraw_ppm_tiff_writer 自动按后缀决定 PPM/TIFF
    ret = processor.dcraw_ppm_tiff_writer("out.ppm");
    if (ret != LIBRAW_SUCCESS) {
        fprintf(stderr, "write: %s\n", libraw_strerror(ret));
        return 1;
    }
    processor.recycle();                       // ⑥ 复位，准备处理下一张
    return 0;
}

# 编译链接（-lraw 是单线程版；多线程程序用 -lraw_r）
$ g++ -o raw2ppm raw2ppm.cpp $(pkg-config --cflags --libs libraw)

# 运行：先看元数据，再产出 out.ppm
$ ./raw2ppm IMG_0001.CR2
# make=Canon model=Canon EOS R5 size=6000x4000
$ file out.ppm
# out.ppm: PPM image data, 6000x4000, 8-bit, RGB

# 不用 pkg-config 也可以直接写：
$ g++ -o raw2ppm raw2ppm.cpp \
    -I/usr/local/helios/include/libraw -L/usr/local/helios/lib -lraw

6.7 实战复盘：从 CR2 到 JPEG，与那个版本之坑

最后复盘素材里的完整实战。需求一句话：服务端拿到 dng/CR2，转成 JPEG 供预览。最优策略和第 3 章 dcraw 时代一模一样，只是工具换成 LibRaw：能提缩略图就提缩略图（unpack_thumb / simple_dcraw -e，毫秒级），没有内嵌预览或需要全尺寸才走完整解码（unpack + dcraw_process）。完整解码要走"传感器元数据 + 传感器图像数据"两层，做去马赛克、白平衡，代价比提缩略图高一个数量级——把这条判断写进服务端，QPS 能差出几倍。

但素材里藏着一个真正的坑，也是这一章必须记住的现象：程序里调用 open_file 打开 CR2 时直接崩溃。不是文件坏了，不是代码写错——素材排查到最后发现，问题出在编译器版本：那台机器的 g++ 是 4.8.5，把编译器升到 4.9.2 之后再编译同样的代码，open_file 就正常了。为什么换个 g++ 小版本程序就从"一打开 CR2 就崩"变正常？这背后是 ABI 兼容性、标准库实现差异这些"看不见的版本"问题——这一章只把这个现象钉在这里，完整的原因分析和排查方法论（core dump、gdb、strace）留给第 14 章《调试实战：版本与崩溃》。这也是本教程的节奏：先记住"有这种事"，再学会"怎么查这种事"。

# 素材真实现象：同一份代码、同一个 CR2，编译环境不同结果不同
$ g++ --version | head -1
# g++ (GCC) 4.8.5            <- 素材最初的系统编译器
$ ./raw2ppm IMG_0001.CR2
# Segmentation fault (core dumped)   <- open_file 阶段直接崩溃

# 换编译器版本（4.8.5 -> 4.9.2）后重编译，同样的代码正常：
$ g++ --version | head -1
# g++ (GCC) 4.9.2
$ ./raw2ppm IMG_0001.CR2
# make=Canon model=Canon EOS R5 size=6000x4000   <- 一切正常
# （原因分析与排查方法见第 14 章：ABI 兼容性、core dump、gdb）

# 服务端完整流程（素材思路 + LibRaw API）：
# 1) 优先提缩略图：unpack_thumb() + dcraw_make_mem_thumb()
#    或直接 simple_dcraw -e（命令行版），毫秒级出预览
$ simple_dcraw -e test.dng        # 输出 test.thumb.jpg

# 2) 没有缩略图/需要全尺寸：完整解码再压 JPEG
$ dcraw_emu -T -w test.dng
$ ffmpeg -y -i test.tiff preview.jpg

# 3) 批量循环（先试缩略图，失败再完整解码）：
$ for f in *.dng; do
    simple_dcraw -e "$f"
    test -f "${f%.dng}.thumb.jpg" || dcraw_emu -T -w "$f"
done

走完这一章，回头看第 3 章那张解剖图：open_file 读的是"文件头 + 元数据"，unpack 解的是"传感器图像数据"，dcraw_process 把"单通道马赛克"变成"RGB 三通道"——每一步都有图纸对应。这就是"工欲善其事"的完整闭环：先懂结构（第 3 章），再选对工具（第 5 章），然后亲手把工具打磨好（本章），最后带着"版本之坑"的意识进第 14 章补排错能力。下一章主角是 libvips——它甚至内置了 LibRaw 的 loader，能把"读底片"和"高性能处理"串成一条流水线，到时候你会发现，这一章的功底直接能搬过去用。