@realsee/hdr-toolbox

用 TypeScript 合成、分解和转换 Android Ultra HDR JPEG。工具遵循 Android Ultra HDR Image Format v1.1 的 JPEG/R 封装：

• 主图是普通 SDR JPEG，旧版查看器可直接显示。
• 主图携带 GContainer XMP，声明 Primary 和 GainMap 两个资源。
• gain map JPEG 携带 Adobe HDR Gain Map XMP。
• MPF APP2 索引主图与第二张 JPEG；两张 JPEG 紧密拼接。

当前写入 Ultra HDR v1 XMP + MPF。v1.1 中提到的 ISO 21496-1 双重元数据属于增强的跨平台兼容建议，本工具暂不写入 ISO 21496-1 APP2。

环境与构建

需要 Node.js 20 或 22。@realsee/equirect-toolbox 使用原生 WebGL 依赖，因此不要使用 Node 24 运行全景命令。

npm install
npm run build
node dist/cli.js --help
# 安装为包后也可直接运行：hdr-toolbox --help

配置

输入配置可以是示例中的 JSON，也可以是标准 HDR gain map XMP。JSON 数值使用线性 boost：

{
  "max_content_boost": 813.30419921875,
  "min_content_boost": 1,
  "gamma": 1,
  "offset_sdr": 0,
  "offset_hdr": 0,
  "hdr_capacity_min": 1,
  "hdr_capacity_max": 1000,
  "use_base_color_space": true
}

写入 JSON 时使用下划线（snake_case）key，数值和布尔值都写成原生 JSON 类型。读取时同时兼容下划线和驼峰（camelCase，如 maxContentBoost）两种写法，方便兼容旧文件；数值也接受字符串形式（如 "1"、"1.0"），会按数字解析。写入 XMP 时，max_content_boost、min_content_boost、hdr_capacity_min 和 hdr_capacity_max 会自动转换为标准要求的 log2 值。分解时，.json 输出线性值（下划线 key），.xmp 输出标准 XMP。

CLI

1. SDR + gain map + cfg → Ultra HDR

hdr-toolbox compose \
  --sdr examples/cube/0_f.jpg \
  --gainmap examples/cube/0_f_gainmap.jpg \
  --config examples/cube/0_gainmap_cfg.json \
  --output output/0_f.uhdr.jpg

合成只改写 JPEG metadata marker，不会重编码 SDR 或 gain map 像素。若 SDR 未携带规范要求的 ICC profile，会无重编码地补入 sRGB ICC marker。

2. Ultra HDR → SDR + gain map + cfg

hdr-toolbox extract \
  --input output/0_f.uhdr.jpg \
  --sdr output/0_f.jpg \
  --gainmap output/0_f_gainmap.jpg \
  --config output/0_gainmap_cfg.json

将 --config 改成 .xmp 后缀即可输出原生 XMP 表达。

3. cubemap → equirect Ultra HDR

hdr-toolbox cube-to-equirect \
  --input-dir examples/cube \
  --prefix 0 \
  --output output/0_equirect.uhdr.jpg

六面映射如下：

| 文件面名 | cubemap key | 方向 | | -------- | ----------- | ------- | | r | px | 右 / +X | | l | nx | 左 / -X | | u | py | 上 / +Y | | d | ny | 下 / -Y | | f | pz | 前 / +Z | | b | nz | 后 / -Z |

SDR 文件名为 <prefix>_[r,l,u,d,f,b].jpg。gain map 同时兼容 <prefix>_<face>_gainmap.jpg 和示例里的 <prefix>_<face>.gainmap.jpg。配置自动读取输入目录下的 <prefix>_gainmap_cfg.json（找不到时回退 <prefix>_gainmap_cfg.xmp）。六面必须是同尺寸、正方形且边长为 2 的幂。输出尺寸是面宽的 4×2 倍。

4. equirect Ultra HDR → cubemap

hdr-toolbox equirect-to-cube \
  --input output/0_equirect.uhdr.jpg \
  --output-dir output/cube \
  --prefix 0

输出 6 张 <prefix>_<face>.jpg、6 张 <prefix>_<face>_gainmap.jpg 和 <prefix>_gainmap_cfg.json。

TypeScript API

import { composeUltraHdr, extractUltraHdr } from "@realsee/hdr-toolbox";

await composeUltraHdr({
  sdr: "sdr.jpg",
  gainMap: "gainmap.jpg",
  config: "gainmap_cfg.json",
  output: "image.uhdr.jpg",
});

await extractUltraHdr({
  input: "image.uhdr.jpg",
  sdr: "sdr.jpg",
  gainMap: "gainmap.jpg",
  config: "gainmap_cfg.xmp",
});

校验

npm run typecheck
npm test
npm run lint
npm run format:check
npm run build

规范参考：Android Ultra HDR Image Format v1.1。