Scroll to navigation

oiiotool(1) OpenImageIO oiiotool(1)

NAME

oiiotool -- simple image processing operations

SYNOPSIS

Usage: oiiotool [filename|command]...

DESCRIPTION

This program is part of the OpenImageIO (http://www.openimageio.org) tool suite. Detailed documentation is available in pdf format with the OpenImageIO distribution.

Important usage tips:
  • The oiiotool command line is processed in order, LEFT to RIGHT.
  • The command line consists of image NAMES ('image.tif') and COMMANDS ('--over'). Commands start with dashes (one or two dashes are equivalent). Some commands have required arguments which must follow on the command line. For example, the '-o' command is followed by a filename.
  • oiiotool is STACK-based: naming an image pushes it on the stack, and most commands pop the top image (or sometimes more than one image), perform a calculation, and push the result image back on the stack. For example, the '--over' command pops the top two images off the stack, composites them, then pushes the result back onto the stack.
  • Some commands allow one or more optional MODIFIERS in the form 'name=value', which are appended directly to the command itself (no spaces), separated by colons ':'. For example, oiiotool in.tif --text:x=100:y=200:color=1,0,0 "Hello" -o out.tif
  • Using numerical wildcards will run the whole command line on each of several sequentially-named files, for example: oiiotool fg.#.tif bg.#.tif -over -o comp.#.tif See the manual for info about subranges, number of digits, etc.
  • Command line arguments containing substrings enclosed in braces {} are replaced by evaluating their contents as expressions. Simple math is allowed as well as retrieving metadata such as {TOP.'foo:bar'}, {IMG[0].filename}, or {FRAME_NUMBER/24.0}.

OPTIONS

Options (general flags):

Print help message
Print version
Verbose status messages
Quiet mode (turn verbose off and reduce printed output)
No saved output (dry run)
Do not exit upon error, try to process additional commands (danger!)
Do operations on all subimages/miplevels
Debug mode
Print runtime statistics
Print OIIO build information
Print resolution and basic info on all inputs, detailed metadata if -v is also used (options: format=xml:verbose=1)
List all supported file formats and their filename extensions
Which metadata is printed with -info -v
Which metadata is excluded with -info -v
Print pixel statistics of all inputs files
Print all pixel data values of input files (options: empty=1, C=arrayname)
Print SHA-1 hash of each input image
Update mode: skip outputs when the file exists and is newer than all inputs
Do not overwrite existing files
Create output directories if it doesn't exists
Number of threads (default 0 == #cores)
[EXPERIMENTAL] Use GPU if available (options: device=...)
Turn off automatic premultiplication of images with unassociated alpha
Turn on automatic premultiplication of images with unassociated alpha
Automatically --reorient all images upon input
Automatically color convert based on filename (options: unpremult=)
Turn off automatic color conversion
Keep native pixel data type (bypass cache if necessary)
ImageCache size (in MB: default=4096)
Autotile enable for cached images (the argument is the tile size, default 0 means no autotile)
Always merge metadata of all inputs into output
Sets global OpenImageIO attribute (options: type=...)
Allow experimental features

Control flow and scripting:

Set a user variable (options: type=...)
If VALUE is not 0 or empty, execute commands until --endif
Else clause of the current 'if' block
End the current 'if' block
If VALUE is not 0 or empty, execute commands until --endwhile and loop
End the current 'while' block
Iterate over a range the commands between here and --endfor. The range may be END (implied begin 0 and step 1), START,END (implied step 1) or START,END,STEP
End the current 'for' block
Frame range for '#' or printf-style wildcards
Frame number padding digits (ignored when using printf-style wildcards)
Views for %V/%v wildcards (comma-separated, defaults to "left,right")
Skip to next frame in range if there's an error, rather than exiting
Parallelize evaluation of frame range
Disable numeric wildcard expansion for subsequent command line arguments
Enable numeric wildcard expansion for subsequent command line arguments
Disable {expression} evaluation for subsequent command line arguments
Enable {expression} evaluation for subsequent command line arguments

Commands that read images:

Input file (options: autocc=, ch=, get_thumbnail=, info=, infoformat=, native=, now=, type=, unpremult=)
Sets input config attribute (options: type=...)
Set policy for missing input files: 'error' (default), 'black', 'checker'
Test file read (do not keep image; used for debugging)

Commands that write images:

Output the current image to the named file (options: all=, autocc=, autocrop=, autotrim=, bits=, contig=, datatype=, dither=, fileformatname=, scanline=, separate=, tile=, unpremult=)
Output the current image as a texture
Output the current image as a latlong env map
Output the current bump texture map as a 6 channels texture including the first and second moment of the bump slopes (options: bumpformat=height|normal|auto, uvslopes_scale=val>=0, bumpscale=%f, bumpinverts=false, bumpinvertt=false, slopefilter=sobel|centraldiff, bumprange=centered|positive|auto)

Options that affect subsequent image output:

’-d TYPE' sets the output data format of all channels, '-d CHAN=TYPE' overrides a single named channel (multiple -d args are allowed). Data types include: uint8, sint8, uint10, uint12, uint16, sint16, uint32, sint32, half, float, double
Output scanline images
Output tiled images with this tile size
Set the compression method (in the form "name" or "name:quality")
Add dither when writing <= 8-bit output from > 8 bit input
Force planarconfig (contig, separate, default)
Adjust file times to match DateTime metadata
Do not automatically crop images whose formats don't support separate pixel data and full/display windows
Automatically trim black borders upon output to file formats that support separate pixel data and full/display windows

Options that print data (usually about the current image):

Echo message to console (options: newline=0)
Print info and metadata of the current top image (options: allsubimages=, native=1, stats=1, verbose=0)
Print pixel statistics of the current top image (options: allsubimages=, window=<geom>)
Count of how many pixels have the given color (argument: color;color;...) (options: eps=color)
Count of how many pixels are outside the min/max color range (each is a comma-separated color value list)

Options that change current image metadata (but not pixel values):

Sets metadata attribute (options: type=...)
Sets string metadata attribute
Erase attributes matching regex (options: fromfile=1 filename-containing-patterns
Sets caption (ImageDescription metadata)
Add a keyword
Clear all keywords
Write full command line into Exif:ImageHistory, Software metadata attributes
Do not write full command line into Exif:ImageHistory, Software metadata attributes
Do not write any Exif:ImageHistory or Software metadata attributes
Write command line into Software & ImageHistory but remove --sattrib and --attrib options
Set the assumed orientation
Rotate orientation metadata 90 deg clockwise
Rotate orientation metadata 90 deg counter-clockwise
Rotate orientation metadata 180 deg
Set the pixel data window origin (e.g. +20+10, -16-16)
Offset the pixel data window origin from its current position (e.g. +20+10, -16-16)
Set the display window (e.g., 1920x1080, 1024x768+100+0, -20-30)
Set the 'full' image range to be the pixel data window
Set the channel names (comma-separated)

Options that affect subsequent actions:

Failure threshold difference (0.000001)
Allow this percentage of failures in diff (0)
Fail diff if any one pixel exceeds this error (infinity)
Warning threshold difference (0.00001)
Allow this percentage of warnings in diff (0)
Warn if any one pixel difference exceeds this error (infinity)

Actions:

Create a blank image
Create a patterned image. Pattern name choices: black, constant, fill, checker, noise
Create a centered convolution kernel
Capture an image (options: camera=%d)
Print report on the difference of two images (modified by --fail, --failpercent, --hardfail, --warn, --warnpercent --hardwarn)
Print report on the Yee perceptual difference of two images (modified by --fail, --failpercent, --hardfail, --warn, --warnpercent --hardwarn)
Compute FLIP perceptual difference of two images (options: hdr=1, colormap=NAME, ppd=67.02, maxluminance=2.0)
Add two images
Add to all channels a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)
Subtract two images
Subtract from all channels a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)
Scale all channels of one image by the single channel of another image
Multiply two images
Multiply the image values by a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)
Divide first image by second image
Divide the image values by a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)
Multiply two images, add a third
Take the color inverse (subtract from 1) (options: chbegin=0, chend=3
Take the absolute value of the image pixels
Absolute difference between two images
Absolute difference versus a scalar or per-channel constant (e.g.: 0.5 or 1,1.25,0.5)
Raise the image values to a scalar or per-channel power (e.g.: 2.2 or 2.2,2.2,2.2,1.0)
Add noise to an image (options: type=gaussian:mean=0:stddev=0.1, type=uniform:min=0:max=0.1, type=salt:value=0:portion=0.1, seed=0
Turn into 1-channel image by summing channels (options: weight=r,g,...)
Color map based on channel 0 (arg: "inferno", "viridis", "magma", "turbo", "plasma", "blue-red", "spectrum", "heat", or comma-separated list of RGB triples)
Convert the named cryptomatte channels into a color matte image
Set pixel data resolution and offset, cropping or padding if necessary (WxH+X+Y or xmin,ymin,xmax,ymax)
Crop or pad to make pixel data region match the "full" region
Crop to the minimal ROI containing nonzero pixel values
Cut out the ROI and reposition to the origin (WxH+X+Y or xmin,ymin,xmax,ymax)
Paste fg over bg at the given position (e.g., +100+50; '-' or 'auto' indicates using the data window position as-is; options: all=%d, mergeroi=%d)
Paste the metadata from the first image into the second image (options: merge=%d, pattern=REGEX)
Assemble images into a mosaic (arg: WxH; options: pad=0, fit=WxH)
’Over' composite of two images
Depth composite two images with Z channels (options: zeroisinf=%d)
Merge/composite two deep images
Hold out one deep image by another
Rotate the image 90 degrees clockwise
Rotate the image 180 degrees
Rotate the image 270 degrees clockwise (or 90 degrees CCW)
Flip the image vertically (top<->bottom)
Flop the image horizontally (left<->right)
Rotate and/or flop the image to transform the pixels to match the Orientation metadata
Transpose the image
Circular shift the image (e.g.: +20-10)
Resample (640x480, 50%) (options: interp=0)
Resize (640x480, 50%) (options: from=<geom>, to=<geom>, filter=%s, highlightcomp=%d, edgeclamp=%d)
Resize to fit within a window size (options: filter=%s, pad=%d, fillmode=%s, exact=%d, highlightcomp=%d)
Scale up the image's width or height to match the given pixel aspect ratio (options: filter=%s, highlightcomp=%d)
Rotate pixels (degrees clockwise) around the center of the display window (options: filter=%s, center=%f,%f, recompute_roi=%d, highlightcomp=%d
Warp pixels (argument is a 3x3 matrix, separated by commas) (options: filter=%s, recompute_roi=%d, highlightcomp=%d)
Warp the first image using normalized "st" coordinates from the second image (options: filter=%s, chan_s=0, chan_t=1, flip_s=0, flip_t=0)
Convolve with a kernel
Blur the image (options: kernel=name)
Median filter the image
Dilate (area maximum) the image
Erode (area minimum) the image
Unsharp mask (options: kernel=gaussian, width=3, contrast=1, threshold=0)
Laplacian filter the image
Normalize the image (options: incenter=0.5, outcenter=0.5, scale=0.5)
Take the FFT of the image
Take the inverse FFT of the image
Convert complex (real,imag) to polar (amplitude,phase)
Convert polar (amplitude,phase) to complex (real,imag)
Fix NaN/Inf values in the image (choices: none, black, box3, error)
Fill in holes (where alpha is not 1)
Pixel-by-pixel max of two images
Max all values with a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)
Maximum of all channels of the image
Pixel-by-pixel min of two images
Min all values with a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)
Minimum of all channels of the image
Clamp values (options: min=..., max=..., clampalpha=0)
Remap values (options: black=0..., white=1..., sthresh=0.5..., scontrast=1.0..., gamma=1, clamp=0|1)
Scale saturation of the color channels
Decorrelation stretch, exaggerating subtle color variation (options: firstchannel=0, nchannels=, scale=1.0, sigma=, mean=, percentile=, mode=covariance|correlation)
Compress the range of pixel values with a log scale (options: luma=0|1)
Un-rangecompress pixel values back to a linear scale (options: luma=0|1)
Render a poly-line (options: color=)
Render points (options: color=)
Render a box (options: color=)
Fill a region (options: color=)
Render text into the current image (options: x=, y=, size=, color=)
Demosaic (options: pattern=%s, algorithm=%s, layout=%s, white_balance=%f:R,G1,G2,B)

Manipulating channels or subimages:

Select or shuffle channels (e.g., "R,G,B", "B,G,R", "2,3,4")
Force the current image to have N channels (padding with 0.0 as needed)
Append the channels of the last two images
Discard all but the top level of a MIPmap
Select just one MIP level (0 = highest res)
Select just one subimage by index or name (options: delete=1)
Split the top image's subimges into separate images
Append the last two images into one multi-subimage image
Append all images on the stack into a single multi-subimage image
Split the top image's channel-name-based layers into separate images on the stack
Deepen normal 2D image to deep
Flatten deep image to non-deep
Extract an embedded thumbnail (options: fail=, index=)
Attach the top image as the thumbnail of the image below it

Image stack manipulation:

Label the top image
Duplicate the current image (push a copy onto the stack)
Swap the top two images on the stack.
Throw away the current image
Throw away the image on the bottom of the stack
Throw away the image on the bottom of the stack
Move an indexed stack item to the top of the stack
Remove all images from the stack, leaving it empty

Color management:

Print extensive details about the color management configuration
Explicitly specify an OCIO configuration file
Set the assumed color space (without altering pixels)
Convert the current image's pixels to a named color space
Convert pixels from 'src' to 'dst' color space (options: key=, value=, unpremult=, strict=)
Color convert pixels with a 3x3 or 4x4 matrix (options: unpremult=,transpose=)
Apply the named OCIO look (options: from=, to=, inverse=, key=, value=, unpremult=)
Apply the named OCIO display and view (options: from=, looks=, key=, value=, unpremult=, inverse=)
Apply the named OCIO filetransform (options: inverse=, unpremult=)
Apply the named OCIO namedtransform (options: inverse=, key=, value=, unpremult=)
Divide all color channels of the current image by the alpha to "un-premultiply"
Multiply all color channels of the current image by the alpha
Multiply all color channels of the current image by the alpha, but don't crush alpha=0 pixels to black.
Output the current image's ICC profile as a separate file
Add the contents of the file to the top image as its ICC profile
Set or modifiy CICP metadata for supporting output formats (e.g., "12,16,0,1")

Input formats supported: bmp, cineon, dds, dicom, dpx, ffmpeg, fits, gif, hdr, heif, ico, iff, jpeg, jpeg2000, jpegxl, null, openexr, openvdb, png, pnm, psd, raw, rla, sgi, softimage, targa, tiff, webp, zfile

Output formats supported: bmp, dpx, fits, gif, hdr, heif, ico, iff, jpeg, jpeg2000, jpegxl, null, openexr, png, pnm, rla, sgi, targa, term, tiff, webp, zfile

OpenColorIO 2.6.0 Color config: ocio://default Run `oiiotool --colorconfiginfo` for a full color management inventory.

Filters available: box, triangle, gaussian, sharp-gaussian, catmull-rom, blackman-harris, sinc, lanczos3, radial-lanczos3, nuke-lanczos6, mitchell, bspline, disk, cubic, keys, simon, rifman

OIIO 3.2.2.0 | Linux/x86_64 Build compiler: gcc 16.2 | C++17/201703 HW features enabled at build: sse2,sse3,ssse3,sse41,sse42 No CUDA support (disabled / unavailable at build time)

Dependencies: BZip2 1.0.8, DCMTK 3.7.0, FFmpeg 8.1.3, fmt 12.1.0, Freetype 2.15.0, GIF 5.2.2, Imath 3.2.3, JXL 0.12.0, libdeflate 1.25, Libheif 1.23.6, libjpeg-turbo 3.2.0, LibRaw 0.22.2, libuhdr NONE, nanobind 3.1.0, OpenColorIO 2.6.0, OpenCV 4.13.0, OpenEXR 3.5.2, OpenGL, OpenJPEG 2.5.4, openjph 0.32.0, OpenVDB 13.1.0, PNG 1.6.59, pugixml 1.16, Python3 3.13.16, Qt6 6.12.0, Robinmap 1.4.1, TBB 2023.0.0, TIFF 4.7.2, WebP 1.6.0, ZLIB 1.3.1, zstd 1.5.7

Running on 4 cores 15.6GB sse2,sse3,ssse3,sse41,sse42,avx,avx2,fma,f16c,popcnt,rdrand No compute specific hardware enabled.

Full OIIO documentation can be found at https://docs.openimageio.org

30 October 2026