oiiotool

What this skill does

# oiiotool Skill

Command-line image processing with [OpenImageIO's oiiotool](https://docs.openimageio.org). Industry-standard tool used across VFX, CGI, game dev, and photography for format conversion, color management, compositing, and batch image operations.

## Setup

```bash
pip install openimageio
```

This installs both the `oiiotool` CLI and the `OpenImageIO` Python module.

Verify:
```bash
oiiotool --version
oiiotool --list-formats
```

### OCIO / ACES Configuration

oiiotool uses OpenColorIO for color management. **Since OCIO 2.2+, built-in ACES configs are available — no file download needed:**

```bash
# Use built-in ACES CG config (recommended for most users)
export OCIO=ocio://cg-config-latest

# Or specify per-command
oiiotool --colorconfig ocio://cg-config-latest input.exr ...
```

Available built-in configs:
- `ocio://cg-config-latest` — CG-focused config (no camera color spaces, lean). Recommended.
- `ocio://studio-config-latest` — Full studio config (includes camera color spaces).
- `ocio://cg-config-v4.0.0_aces-v2.0_ocio-v2.5` — Pin to a specific version.

For production studios with a custom config:
```bash
export OCIO=/path/to/studio_config.ocio
```

Check what's available:
```bash
oiiotool --colorconfiginfo
```

## Core Concept: Stack-Based Processing

oiiotool processes commands **left to right** on a stack:
- Naming a file **pushes** it onto the stack
- Commands **pop** inputs, process, and **push** results
- `-o` writes the top of stack to a file

```bash
# Read -> process -> write
oiiotool input.exr --resize 1920x1080 -o output.png

# Two images -> composite -> write
oiiotool fg.exr bg.exr --over -o comp.exr
```

## File Info & Metadata

```bash
# Basic info (resolution, channels, format)
oiiotool --info input.exr

# Verbose info (all metadata)
oiiotool --info -v input.exr

# Pixel statistics (min, max, mean, stddev per channel)
oiiotool --stats input.exr

# Filter metadata with regex
oiiotool --info -v --metamatch "camera|lens" input.exr
```

## Format Conversion

Supported formats: EXR, TIFF, PNG, JPEG, DPX, HDR (Radiance), BMP, TGA, GIF, WebP, JPEG2000, PSD, ICO, FITS, and more.

```bash
# Simple conversion (format inferred from extension)
oiiotool input.exr -o output.png
oiiotool input.dpx -o output.tiff
oiiotool input.hdr -o output.exr

# Control output bit depth
oiiotool input.exr -d uint8 -o output.png       # 8-bit
oiiotool input.exr -d uint16 -o output.png       # 16-bit
oiiotool input.exr -d half -o output.exr         # 16-bit float (half)
oiiotool input.exr -d float -o output.tiff       # 32-bit float

# JPEG quality
oiiotool input.exr -d uint8 --compression jpeg:95 -o output.jpg

# EXR compression types
oiiotool input.exr --compression zip -o output.exr        # lossless, good general
oiiotool input.exr --compression piz -o output.exr        # lossless, best for noisy/CG
oiiotool input.exr --compression zips -o output.exr       # lossless, scanline
oiiotool input.exr --compression dwaa:45 -o output.exr    # lossy, very small files

# Tiled vs scanline EXR
oiiotool input.exr --tile 64 64 -o output.exr
oiiotool input.exr --scanline -o output.exr

# Add dither when going from high bit depth to 8-bit (reduces banding)
oiiotool input.exr -d uint8 --dither -o output.png
```

### Production Tip: Selective Channel Reading

For large multichannel EXRs (beauty + depth + normals + crypto), read only what you need to save memory and time:

```bash
# Read only R,G,B channels (skip depth, normals, cryptomatte, etc.)
oiiotool -i:ch=R,G,B input.exr -o output.png

# Combined with conversion and color management
oiiotool -i:ch=R,G,B input.exr --resize 1024x0 --colorconvert "ACES2065-1" "Rec.1886 Rec.709 - Display" --compression "jpeg:90" -o output.jpg
```

This is critical in production where EXRs can have 50+ channels and be hundreds of MB each.

## Color Management (OCIO)

### Color Space Conversion

```bash
# Convert between named color spaces
oiiotool input.exr --colorconvert ACEScg "sRGB - Texture" -o output.png
oiiotool input.exr --colorconvert linear srgb -o output.png
oiiotool input.exr --tocolorspace "sRGB - Texture" -o output.png

# Set the assumed input color space (without changing pixels)
oiiotool input.png --iscolorspace srgb --tocolorspace linear -o linear.exr
```

### ACES Display Transforms (Tone Mapping)

The proper way to view HDR content. Applies the ACES Reference Rendering Transform (RRT) + Output Device Transform (ODT) for correct highlight rolloff:

```bash
# sRGB monitor (most common for web/review)
oiiotool input.exr --ociodisplay "sRGB - Display" "ACES 1.0 - SDR Video" -d uint8 -o output.png

# Rec.709 broadcast
oiiotool input.exr --ociodisplay "Rec.1886 Rec.709 - Display" "ACES 1.0 - SDR Video" -d uint8 -o output.png

# DCI-P3 cinema
oiiotool input.exr --ociodisplay "P3-D65 - Display" "ACES 1.0 - SDR Cinema" -d uint8 -o output.png

# HDR (1000 nits, PQ)
oiiotool input.exr --ociodisplay "Rec.2100-PQ - Display" "ACES 1.1 - HDR Video (1000 nits & Rec.2020 lim)" -d uint16 -o output.png

# Un-tone-mapped (linear to display, no RRT — useful for comparing raw values)
oiiotool input.exr --ociodisplay "sRGB - Display" "Un-tone-mapped" -d uint8 -o output.png
```

> **When to use display transforms vs colorconvert:** Use `--ociodisplay` when converting HDR scene-referred data to a display for viewing (applies tone mapping). Use `--colorconvert` when converting between working color spaces (no tone mapping, preserves linearity).

### OCIO Looks & File Transforms

```bash
# Apply an OCIO look (e.g., ACES gamut compression)
oiiotool input.exr --ociolook "ACES 1.3 Reference Gamut Compression" -o output.exr

# Apply a file-based transform (3D LUT, CDL, CLF)
oiiotool input.exr --ociofiletransform my_grade.cube -o output.exr

# Inverse
oiiotool input.exr --ociofiletransform:inverse=1 my_grade.cube -o output.exr
```

### Manual Matrix Color Conversion

When you don't have OCIO or need a specific 3x3 matrix:

```bash
# ACEScg to linear sRGB (comma-separated, row-major)
oiiotool input.exr --ccmatrix "1.70505,-0.62179,-0.08326,-0.13026,1.14080,-0.01055,-0.02400,-0.12897,1.15297" -o output.exr
```

## Exposure Adjustment

EXR stores linear light values. Exposure in stops is powers of 2:

```bash
# Lower exposure (darken) — reveal HDR highlights
oiiotool input.exr --mulc 0.0625 -o output.exr        # -4 stops
oiiotool input.exr --mulc 0.0078125 -o output.exr      # -7 stops

# Raise exposure (brighten) — reveal shadow detail
oiiotool input.exr --mulc 4 -o output.exr              # +2 stops
oiiotool input.exr --mulc 16 -o output.exr             # +4 stops

# Fractional stops
oiiotool input.exr --mulc 0.00407 -o output.exr        # -7.6 stops
```

**Exposure + ACES display transform** (most useful combo for HDR review):

```bash
oiiotool input.exr --mulc 0.0078125 --ociodisplay "sRGB - Display" "ACES 1.0 - SDR Video" -d uint8 -o output_exp-7.png
```

### Exposure Reference Table

| Stops | Multiplier | Formula | Use Case |
|-------|-----------|---------|----------|
| +8    | 256       | 2^8     | Deep shadow recovery |
| +6    | 64        | 2^6     | Dark shadow detail |
| +4    | 16        | 2^4     | Shadow detail |
| +2    | 4         | 2^2     | Slight brighten |
| 0     | 1         | 2^0     | Native exposure |
| -2    | 0.25      | 2^-2    | Slight darken |
| -4    | 0.0625    | 2^-4    | Highlight recovery |
| -6    | 0.015625  | 2^-6    | Bright highlight detail |
| -8    | 0.00390625| 2^-8    | Extreme highlight recovery |

## Ready-Made Scripts

### Exposure Sweep

Generate a composite contact sheet of multiple exposures from an HDR EXR:

```bash
python scripts/exposure_sweep.py input.exr
python scripts/exposure_sweep.py input.exr --stops -8,-6,-4,-2,0,2,4,6,8
python scripts/exposure_sweep.py input.exr --display "sRGB - Display" --view "ACES 1.0 - SDR Video"
python scripts/exposure_sweep.py input.exr --cols 4 --output sweep.jpg
```

### EXR Sequence to Video

Convert an EXR image sequence to MP4:

```bash
python sc