oiiotool命令行比c++ api更稳更快，适用于缩放、格式转换、通道提取等批量处理；c++ api仅适合深度集成场景，且需避免imagebufalgo::resize，改用imagebuf流程并显式管理spec与错误。
oiiotool 命令行用法比 C++ API 更直接
绝大多数图像批量处理需求，根本不需要写 C++ 代码调用 OpenImageIO 的 API。直接用 oiiotool 命令行工具更稳、更快、更少出错——它本身就是 OpenImageIO 官方提供的主力工具，底层就是调的同一套库，但避开了编译链接、内存管理、异常传播这些 C++ 接口容易卡壳的环节。
常见错误现象：写了一堆 OIIO::ImageInput::open() 和循环读写逻辑，结果路径含空格时崩溃、多线程下 get_image_spec() 返回空指针、或 PNG 写入后颜色通道错位。这些问题在命令行里一条 oiiotool --resize 512x512 *.exr -o resized/ 就绕过去了。
- 使用场景优先选命令行：缩放、格式转换、通道提取（
--ch R,G,B）、LUT 应用（--colorconfig）、批量重命名、HDR 转 LDR（--tocolorspace sRGB） - 只有当你需要和已有 C++ 工程深度集成（比如在渲染器里实时预览中间帧），才考虑调 API；否则纯属给自己加调度复杂度
-
oiiotool支持 glob 和通配符，Windows 下用双引号包路径（"input/*.png"），Linux/macOS 注意 shell 展开顺序
真要用 C++ API 时，别碰 ImageBufAlgo::resize —— 用 ImageBuf 合成流程
ImageBufAlgo::resize() 看似方便，但默认不处理 alpha 预乘、不校验色彩空间、对非幂等操作（如多次 resize）累积误差明显。实际批量处理中，更可靠的是走 ImageBuf 构造 → 修改 spec → copy_pixels() 或 set_pixels() 流程。
典型坑：直接 ib.resize(512, 512) 后保存，EXR 文件的 displaywindow 和 pixelaspect 没同步更新，下游软件读出来变形；或者 JPEG 读入时 spec.format 是 UINT8，但没显式设置 spec.attribute("oiio:ColorSpace", "sRGB")，导致 gamma 处理错乱。
- 必须显式拷贝原始
ImageSpec并修改关键字段：spec.width/spec.height、spec.full_x/spec.full_y、spec.full_width/spec.full_height - 写入前检查
ib.has_error()，别只靠ib.write()返回值——很多错误（如磁盘满、权限不足）只存在ib.geterror()字符串里 - 批量处理时复用同一个
ImageBuf实例（调ib.reset()），避免反复 new/delete 带来的分配抖动
Windows 下 oiiotool 找不到 DLL 或报错 “Unable to open file”
不是路径问题，是 OpenImageIO 运行时依赖的第三方 DLL（如 libpng16.dll、zlib.dll）没进 PATH，或者版本冲突。错误信息里如果出现 0xc000007b 或 MSVCP140.dll missing，基本锁定是 VC++ 运行时环境缺失。
常见错误现象：oiiotool input.jpg -o out.png 报 Unable to open file "input.jpg"，但文件明明存在；或者执行一半突然弹窗提示 DLL 加载失败。
- 下载官方预编译包（不是 GitHub Release 里的源码 zip），解压后把
bin/目录加到系统 PATH，确保oiiotool.exe能直接调用同目录下的所有 DLL - 用
Dependency Walker（或lddon WSL）查oiiotool.exe缺少哪些 DLL；重点补vcruntime140.dll、msvcp140.dll（对应 VS2015+ 运行时） - 避免混用不同版本 OpenImageIO：CMake 项目里
find_package(OpenImageIO)找到的头文件和你 PATH 里的oiiotool不一定兼容，尤其跨 2.x / 3.x 大版本时
批量处理时输出文件名控制不牢，导致覆盖或乱序
oiiotool 默认按输入顺序处理，但输出名不自动带序号或原名前缀。用 -o out.exr 会把所有输入塞进一个文件；用 -o out.%04d.exr 又可能因 glob 展开顺序和文件系统排序不一致导致错位。
最稳妥的方式是用 shell 循环（Linux/macOS）或 forfiles（Windows），把文件名控制权交还给脚本层，而不是依赖 oiiotool 的内部计数。
- Linux/macOS 示例：
for f in *.tif; do oiiotool "$f" --resize 1024x --colorconfig ocio_config.ocio --ociocolor linear sRGB -o "resized/$(basename "$f" .tif)_1024_srgb.png"; done - Windows 示例：
forfiles /s /m *.exr /c "cmd /c oiiotool @path --resize 2048x -o \"out\@fname_2k.@ext\"" - 绝对不要用
oiiotool *.exr -o %04d.png——shell 展开顺序不可控，z.exr可能排第一，a.exr排最后，但编号却是 0001/0002…
真正麻烦的从来不是 resize 或 format 转换本身，而是路径拼接时的编码差异（Windows 中文路径、macOS UTF-8 正规化）、临时文件残留、以及多进程同时写同一目录引发的竞态——这些在命令行里得靠脚本兜底，在 C++ 里得自己上 flock 或原子 rename，一不留神就漏掉。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
