🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › Oiiotool
🦀 ClawHub

Oiiotool

by @oumad

Image processing with oiiotool CLI — format conversion (EXR, TIFF, DPX, PNG, JPEG, HDR), OCIO/ACES color management and display transforms, exposure adjustme...

Versionv0.1.1
Downloads534
#advertising#legal#productivity
TERMINAL
clawhub install oiiotool

📖 About This Skill

name: oiiotool description: > Image processing with oiiotool CLI — format conversion (EXR, TIFF, DPX, PNG, JPEG, HDR), OCIO/ACES color management and display transforms, exposure adjustment, resize/crop, compositing, EXR sequence to video, texture baking, image comparison, and batch/sequence operations. Use when working with image files, EXR sequences, color spaces, or HDR content. compatibility: Requires oiiotool (pip install openimageio). ffmpeg needed for video encoding. metadata: author: oumad version: "1.0" clawdbot: '{"requires":{"bins":["oiiotool","python3"]}}'

oiiotool Skill

Command-line image processing with OpenImageIO's oiiotool. Industry-standard tool used across VFX, CGI, game dev, and photography for format conversion, color management, compositing, and batch image operations.

Setup

pip install openimageio

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

Verify: 

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:

# 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: 

    export OCIO=/path/to/studio_config.ocio

    Check what's available: 

    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

    • # 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

    # 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.

    # 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:

    # 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

    # 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:

    # 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

    # 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:

    # 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:

    # 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):

    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:

    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:

    python scripts/seq_to_video.py /path/to/sequence/
python scripts/seq_to_video.py /path/to/sequence/ --fps 24 --crf 18
python scripts/seq_to_video.py /path/to/sequence/ --display "sRGB - Display" --view "ACES 1.0 - SDR Video"
python scripts/seq_to_video.py /path/to/sequence/ --exposure -4 --output comp.mp4

    Requires ffmpeg in PATH.

    Image Operations

    Resize & Fit

    # Resize to exact dimensions
oiiotool input.exr --resize 1920x1080 -o output.exr
    Resize by percentage
    
oiiotool input.exr --resize 50% -o output.exr
    Resize width only, preserve aspect (height=0 means auto)
    
oiiotool input.exr --resize 1024x0 -o output.exr
    Fit within dimensions (preserves aspect ratio, no stretching)
    
oiiotool input.exr --fit 1920x1080 -o output.exr
    Fit and pad to exact dimensions
    
oiiotool input.exr --fit:pad=1 1920x1080 -o output.exr
    Choose resize filter
    
oiiotool input.exr --resize:filter=lanczos3 1920x1080 -o output.exr
    Fix pixel aspect ratio
    
oiiotool input.exr --pixelaspect 2.0 -o output.exr

    Available filters: box, triangle, gaussian, catmull-rom, blackman-harris, sinc, lanczos3, mitchell, bspline, cubic. Default lanczos3 is good for most uses.

    Crop & Cut

    # Crop to region (WxH+X+Y — adjusts data window, keeps display window)
oiiotool input.exr --crop 1920x1080+100+50 -o output.exr
    Cut (crop + reposition to origin)
    
oiiotool input.exr --cut 1920x1080+100+50 -o output.exr
    Crop to full/display window
    
oiiotool input.exr --croptofull -o output.exr
    Auto-trim black borders
    
oiiotool input.exr --trim -o output.exr

    Rotate & Flip

    oiiotool input.exr --rotate90 -o output.exr      # 90 CW
oiiotool input.exr --rotate180 -o output.exr
oiiotool input.exr --rotate270 -o output.exr      # 90 CCW
oiiotool input.exr --flip -o output.exr           # vertical mirror
oiiotool input.exr --flop -o output.exr           # horizontal mirror
oiiotool input.exr --transpose -o output.exr
oiiotool input.exr --rotate 45 -o output.exr      # arbitrary angle
    Auto-orient based on EXIF
    
oiiotool --autoorient input.jpg -o output.jpg

    Blur & Sharpen

    # Gaussian blur
oiiotool input.exr --blur 5x5 -o output.exr
oiiotool input.exr --blur:kernel=gaussian 10x10 -o output.exr
    Median filter (salt-and-pepper noise removal)
    
oiiotool input.exr --median 3x3 -o output.exr
    Unsharp mask (sharpen)
    
oiiotool input.exr --unsharp:kernel=gaussian:width=3:contrast=1.5 -o output.exr
    Morphological ops
    
oiiotool input.exr --dilate 3x3 -o output.exr
oiiotool input.exr --erode 3x3 -o output.exr

    Channel Operations

    # Select/reorder channels
oiiotool input.exr --ch R,G,B -o output.exr         # drop alpha
oiiotool input.exr --ch B,G,R -o output.exr         # BGR swap
oiiotool input.exr --ch R,G,B,A=1.0 -o output.exr   # add solid alpha
oiiotool input.exr --ch 0 -o output.exr             # first channel only
    Rename channels
    
oiiotool input.exr --chnames R,G,B -o output.exr
    Combine channels from multiple files
    
oiiotool rgb.exr alpha.exr --chappend -o rgba.exr
    Luminance (sum weighted channels)
    
oiiotool input.exr --chsum:weight=0.2126,0.7152,0.0722 -o luminance.exr
    Split layer-named channels into separate images
    
oiiotool multilayer.exr --layersplit -o layer.exr

    Compositing

    # Alpha-over composite
oiiotool fg.exr bg.exr --over -o comp.exr
    Paste fg at position
    
oiiotool bg.exr fg.exr --paste +100+50 -o comp.exr
    Depth-based composite (Z channel)
    
oiiotool a.exr b.exr --zover -o comp.exr
    Mosaic/contact sheet
    
oiiotool img1.exr img2.exr img3.exr img4.exr --mosaic 2x2 -o grid.exr
oiiotool img*.exr --mosaic:pad=4 3x3 -o contact.exr
    Math operations between two images
    
oiiotool a.exr b.exr --add -o sum.exr
oiiotool a.exr b.exr --mul -o product.exr
oiiotool a.exr b.exr --absdiff -o diff.exr
oiiotool a.exr b.exr --max -o max.exr
oiiotool a.exr b.exr --min -o min.exr

    Color & Value Adjustments

    # Multiply (exposure, tint)
oiiotool input.exr --mulc 2.0 -o output.exr              # all channels
oiiotool input.exr --mulc 1.1,1.0,0.9 -o output.exr      # per-channel warm tint
    Add offset
    
oiiotool input.exr --addc 0.1 -o output.exr
    Power/gamma
    
oiiotool input.exr --powc 2.2 -o output.exr              # apply gamma
oiiotool input.exr --powc 0.4545 -o output.exr            # remove gamma
    Invert colors
    
oiiotool input.exr --invert -o output.exr
    Clamp values
    
oiiotool input.exr --clamp:min=0:max=1 -o output.exr
    Contrast (S-curve)
    
oiiotool input.exr --contrast:black=0.1:white=0.9:scontrast=2.0 -o output.exr
    Saturation
    
oiiotool input.exr --saturate 1.5 -o output.exr          # boost
oiiotool input.exr --saturate 0 -o output.exr             # desaturate
    Range compress (HDR -> log preview)
    
oiiotool input.exr --rangecompress -o output.exr
    Fix NaN/Inf values
    
oiiotool input.exr --fixnan black -o output.exr
oiiotool input.exr --fixnan box3 -o output.exr            # interpolate neighbors
    False color visualization
    
oiiotool depth.exr --colormap inferno -o heatmap.png
oiiotool depth.exr --colormap viridis -o heatmap.png
oiiotool depth.exr --colormap turbo -o heatmap.png

    Drawing & Annotation

    # Text overlay
oiiotool input.exr --text:x=20:y=40:size=24:color=1,1,1 "Frame 001" -o output.exr
    Draw box outline
    
oiiotool input.exr --box:color=1,0,0 100,100,500,400 -o output.exr
    Draw lines
    
oiiotool input.exr --line:color=0,1,0 0,0,100,100 -o output.exr
    Fill region with solid color
    
oiiotool input.exr --fill:color=0,0,1 100x100+50+50 -o output.exr
    Create solid color image from scratch
    
oiiotool --create 1920x1080 3 --fill:color=0.18,0.18,0.18 1920x1080+0+0 -o gray18.exr

    Sequence Processing

    oiiotool supports frame number wildcards for batch operations:

    # '#' expands to frame numbers (padded to match # count)
oiiotool --frames 1001-1100 input.####.exr --resize 50% -o output.####.exr
    printf-style patterns
    
oiiotool --frames 1001-1100 input.%04d.exr -o output.%04d.png
    Frame step (every other frame)
    
oiiotool --frames 1-100x2 input.####.exr -o output.####.exr
    Skip missing frames
    
oiiotool --frames 1001-1100 --skip-bad-frames input.####.exr -o output.####.png
    Parallel frame processing (use all cores)
    
oiiotool --frames 1001-1100 --parallel-frames input.####.exr --resize 1920x1080 -o output.####.exr
    ACES display transform on entire sequence
    
oiiotool --frames 1001-1100 input.####.exr --ociodisplay "sRGB - Display" "ACES 1.0 - SDR Video" -d uint8 -o output.####.png
    Exposure + display transform on sequence
    
oiiotool --frames 1001-1100 input.####.exr --mulc 0.0625 --ociodisplay "sRGB - Display" "ACES 1.0 - SDR Video" -d uint8 -o output.####.png
    Read only RGB channels for efficiency on multichannel sequences
    
oiiotool --frames 1001-1100 -i:ch=R,G,B input.####.exr --ociodisplay "sRGB - Display" "ACES 1.0 - SDR Video" -d uint8 -o output.####.png

    Sequence to Video (with ffmpeg)

    Two-step process:

    # Step 1: Convert EXR sequence to PNG
oiiotool --frames 1001-1100 --parallel-frames input.####.exr --ociodisplay "sRGB - Display" "ACES 1.0 - SDR Video" -d uint8 -o _tmp/output.####.png
    Step 2: Encode with ffmpeg
    
ffmpeg -framerate 24 -start_number 1001 -i _tmp/output.%04d.png -c:v libx264 -pix_fmt yuv420p -crf 18 output.mp4

    Or use the helper script: python scripts/seq_to_video.py /path/to/sequence/

    Texture Baking

    # Tiled, mipmapped texture for rendering engines
oiiotool input.exr -otex output.tx
    Environment map (lat-long to cube)
    
oiiotool latlong.hdr -oenv environment.tx
    Bump map processing
    
oiiotool bump.exr -obump normals.tx

    Image Comparison

    # Difference report
oiiotool a.exr b.exr --diff
    Perceptual difference
    
oiiotool a.exr b.exr --pdiff
    With thresholds
    
oiiotool a.exr b.exr --fail 0.001 --failpercent 1 --diff
    Visual difference (amplified)
    
oiiotool a.exr b.exr --absdiff --mulc 10 -o diff_amplified.exr
    Count pixels matching a color
    
oiiotool input.exr --colorcount "0,0,0"
    Count pixels outside a range
    
oiiotool input.exr --rangecheck 0,0,0 1,1,1

    Patterns & Test Images

    # Black
oiiotool --create 1920x1080 3 -o black.exr
    Constant color
    
oiiotool --pattern constant:color=0.5,0.5,0.5 1920x1080 3 -o gray50.exr
    Checker
    
oiiotool --pattern checker:color1=0.2,0.2,0.2:color2=0.8,0.8,0.8:width=64:height=64 1920x1080 3 -o checker.exr
    Noise
    
oiiotool --pattern noise:type=gaussian:mean=0.5:stddev=0.1 1920x1080 3 -o noise.exr

    Metadata Manipulation

    # Set metadata
oiiotool input.exr --attrib "Artist" "John Doe" -o output.exr
oiiotool input.exr --attrib:type=float "exposure" 1.5 -o output.exr
    Remove metadata by pattern
    
oiiotool input.exr --eraseattrib "camera.*" -o output.exr
    Copy metadata from one image to another
    
oiiotool source.exr target.exr --pastemeta -o output.exr
    Set caption
    
oiiotool input.exr --caption "Final comp v3" -o output.exr

    Deep Image Operations

    # Flatten deep image to regular 2D
oiiotool deep.exr --flatten -o flat.exr
    Convert regular image to deep
    
oiiotool input.exr --deepen -o deep.exr
    Merge two deep images
    
oiiotool a_deep.exr b_deep.exr --deepmerge -o merged.exr
    Deep holdout
    
oiiotool fg_deep.exr holdout_deep.exr --deepholdout -o result.exr

    Cryptomatte Visualization

    # Built-in cryptomatte to color matte
oiiotool input.exr --cryptomatte-colors crypto_material -o material_colors.exr

    > For advanced cryptomatte extraction with custom palettes and batch processing, see the exr skill.

    Performance Tips

  • --threads N — control parallelism (default: all cores)
  • --parallel-frames — parallelize sequence processing
  • -i:ch=R,G,B — read only needed channels from multichannel EXRs
  • --cache MB — increase image cache for large files
  • --native — bypass cache for one-shot operations
  • --autotile 64 — better cache performance with large scanline images
  • -u — update mode: skip outputs newer than inputs

    • Related Skills

  • exr — Python-level EXR internals: channel inspection, cryptomatte extraction with custom palettes, beauty pass extraction with ACEScg matrix. Use when you need fine-grained channel access or cryptomatte decoding beyond what --cryptomatte-colors provides.

    • ⚙️ Configuration

    pip install openimageio

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

    Verify: 

    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:

    # 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: 

    export OCIO=/path/to/studio_config.ocio

    Check what's available: 

    oiiotool --colorconfiginfo