vfx-oiio

name	vfx-oiio
description	VFX-grade image processing with OpenImageIO: oiiotool (stack-based Swiss Army knife - load/save, resize/crop/rotate/blur, metadata, compositing, color management via OCIO, deep images), iconvert (format conversion), iinfo (metadata dump), igrep (search metadata), idiff (perceptual diff), maketx (build tiled MIP-map textures for renderers), iv (GUI viewer). Handles OpenEXR, TIFF, DPX, Cineon, JPEG, JPEG 2000, JPEG XL, HEIC/HEIF/AVIF, PNG, BMP, RAW (LibRaw), FITS, PSD, WebP, PNM, Targa, IFF, SGI, Radiance HDR, GIF, DDS, Field3D, OpenVDB, Ptex. Direct OCIO integration (--colorconvert, --ociolook, --ociodisplay, --ociofiletransform). Docs at openimageio.readthedocs.io. Use when the user asks to convert image formats at VFX scale, apply color management, build MIP-map textures, read DPX/Cineon/EXR/OpenVDB, do deep compositing, or batch-process imagery with oiiotool.
argument-hint	[action]

Vfx Oiio

Context: $ARGUMENTS

Quick start

• Inspect an image: -> Step 1 (oiio.py info)
• Convert formats: -> Step 2 (oiio.py convert)
• Perceptual diff: -> Step 3 (oiio.py diff)
• Search metadata: -> Step 4 (oiio.py grep)
• Build .tx / .exr tiled texture (maketx): -> Step 5 (oiio.py maketx)
• Color-space transform: -> Step 6 (oiio.py color)
• Resize / crop / rotate: -> Steps 7-9 (oiio.py resize|crop|rotate)
• Arbitrary oiiotool recipe: -> Step 10 (oiio.py tool -- args...)

When to use

• Converting between 30+ VFX image formats (EXR, DPX, Cineon, TIFF, HDR, JPEG XL, PSD, ...).
• OCIO color management with --colorconvert, --ociodisplay, --ociolook, --ociofiletransform.
• Building MIP-mapped tiled textures for Arnold, RenderMan, V-Ray, Cycles.
• Deep compositing (--deepen, --deepmerge, --deepholdout).
• Pixel-level perceptual diff (idiff).
• Pair with vfx-openexr for EXR-specific authoring; with vfx-usd for USD texture paths.

---

Step 1 — Info

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py info plate.exr

Expands to iinfo -v plate.exr. Use --stats for per-channel pixel stats (min/max/avg/stddev) which is invaluable for "is this actually black?" and "did my tonemap clip?".

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py info --stats plate.exr

---

Step 2 — Convert

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py convert --in in.dpx --out out.exr

Expands to iconvert in.dpx out.exr. Format inferred from the output extension.

Set compression explicitly (EXR output):

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py convert --in in.dpx --out out.exr --compression dwaa

---

Step 3 — Perceptual diff

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py diff a.exr b.exr

Expands to idiff a.exr b.exr. Exit 0 = identical within default tolerance. Tune tolerance with --fail 0.01 --warn 0.001.

Save a difference image:

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py diff a.exr b.exr --out diff.exr
# -> idiff -o diff.exr a.exr b.exr

---

Step 4 — Grep metadata

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py grep --pattern "smpte:TimeCode" plate.exr

Expands to igrep smpte:TimeCode plate.exr. Case-insensitive by default.

---

Step 5 — maketx (tiled MIP-map texture)

Build a .tx texture from a source image:

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py maketx --in source.exr --out texture.tx

Expands to maketx -o texture.tx source.exr.

Common flags:

• --hdri — preserve HDR range, use box downsampling for lighting IBLs.
• --unpremult — unpremultiply alpha before downscaling (for color maps with alpha).
• --monochrome-detect — single out R=G=B files as 1-channel to save memory.
• --filter lanczos3 — specify downsample filter.
• --colorconvert sRGB ACEScg — bake in a color transform during maketx.

---

Step 6 — Color-space transform

Convert between OCIO-managed color spaces:

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py color --in srgb.png --out acescg.exr \
  --from sRGB --to ACEScg

Expands to oiiotool --colorconfig $OCIO srgb.png --colorconvert sRGB ACEScg -o acescg.exr.

Requires an active OCIO config (set $OCIO to a config.ocio path, e.g. the ACES 1.3 studio config).

Apply a view transform (display-referred output):

# View an ACEScg EXR through the Rec.709 ACES ODT:
uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py tool -- \
  in_acescg.exr --ociodisplay "sRGB" "Rec.709" -o preview.png

---

Step 7 — Resize

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py resize --in big.exr --out small.exr --size 1920x1080

Expands to oiiotool big.exr --resize 1920x1080 -o small.exr.

Use --filter lanczos3 for high quality, --filter box for IBL/HDRI. Default is a good general-purpose filter (blackman-harris).

---

Step 8 — Crop

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py crop --in in.exr --out out.exr --box 100,100,1820,980

Expands to oiiotool in.exr --crop 1720x880+100+100 -o out.exr.

---

Step 9 — Rotate

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py rotate --in in.exr --out out.exr --degrees 90

Expands to oiiotool in.exr --rotate 90 -o out.exr. 90 / 180 / 270 are lossless; other angles resample pixels.

---

Step 10 — Raw oiiotool wrapper

For anything not wrapped above, pass arbitrary args through. The stack-based grammar is oiiotool's superpower:

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py tool -- \
  bg.exr fg.exr --over -o composite.exr

Expands to oiiotool bg.exr fg.exr --over -o composite.exr.

Read [references/oiiotool-cheatsheet.md] for 15 copy-paste recipes covering the common ops.

---

Gotchas

• oiiotool is a stack machine, not a linear pipeline. Order matters: every positional input pushes an image on the stack; every operator consumes the top N and pushes a result. a.exr b.exr --over works, but a.exr --over b.exr does NOT (no second operand for --over yet).
• --over requires premultiplied alpha. If bg.exr has straight alpha, add --unpremult before and --premult after, or use --Aover (straight-alpha over).
• iinfo vs iinfo -v: without -v you get one-line-per-file summary. With -v you get full metadata dump. --stats is a third level: actually scans pixels.
• maketx bakes in color transforms if you pass --colorconvert. Once baked in, the renderer cannot reinterpret. Usually you want --colorconvert only when producing linear working-space .tx from an sRGB texture.
• OCIO configs are environment-driven. Most tools honor $OCIO pointing at config.ocio. If your color-convert complains "colorspace not found", check echo $OCIO and ociocheck $OCIO.
• maketx default tile size is 64. Override with --tile 128 for large-area sampling; for small filters 64 is optimal.
• idiff is PSNR/SSIM-based by default, not a strict byte-compare. For bit-exact use cmp or openssl dgst.
• Format auto-detection uses the extension, not magic bytes. A .dpx written with a wrong header will be mis-read. Use iinfo to sanity-check.
• --ociodisplay vs --colorconvert: --colorconvert is scene-referred roundtrip; --ociodisplay applies a display transform (ACES RRT+ODT, Filmic view, etc.) and produces display-referred output.
• OIIO's Ptex / OpenVDB / Field3D support is optional — require build-time linking. Some distributions don't ship those format plugins; check "Supported input formats".

---

Examples

Example 1: "Convert a 16-bit TIFF to linear EXR"

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py convert --in photo.tif --out photo.exr \
  --compression zip

Example 2: "Make an IBL .tx for Arnold, preserving HDR"

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py maketx --in studio.exr --out studio.tx --hdri

Example 3: "Transform sRGB PNG to ACEScg EXR"

export OCIO=/path/to/studio-config-v1.0.0/config.ocio
uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py color --in logo.png --out logo_acescg.exr \
  --from sRGB --to ACEScg

Example 4: "Composite fg over bg and crop"

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py tool -- \
  bg.exr fg.exr --over --crop 1920x1080+0+0 -o comp.exr

Example 5: "Diff two renders and save a heat map"

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py diff render_v1.exr render_v2.exr --out diff.exr

Example 6: "Find all EXRs with a given AOV name"

uv run ${CLAUDE_SKILL_DIR}/scripts/oiio.py grep --pattern "specular.R" *.exr

---

Troubleshooting

Error: oiiotool: command not found

Cause: OIIO binaries not installed. Solution: brew install openimageio, apt install openimageio-tools, or build from source (github.com/AcademySoftwareFoundation/OpenImageIO).

Error: ColorSpace 'X' not found

Cause: OCIO config doesn't define that color space. Solution: echo $OCIO to verify config path; ociocheck $OCIO to list defined spaces; use an ACES studio config if unsure.

--over gives dark halos

Cause: Straight-alpha input treated as premultiplied. Solution: Add --unpremult before --over; or use --Aover.

maketx produces huge output file

Cause: --monochrome-detect not set and source is grayscale but stored as RGB. Solution: Add --monochrome-detect. Also check compression: --compression dwaa or --compression zip.

iinfo crashes on a DPX

Cause: Non-standard DPX header (Kodak legacy, early camera logs). Solution: Try oiiotool --info -v in.dpx; if it also crashes, the file needs a header fix (use the dpx DCC or re-export from source).

---

Reference docs

• oiiotool recipe cheat-sheet (15 most-used pipelines: alpha ops, compositing, color, deep, resize, denoise) -> [references/oiiotool-cheatsheet.md]