oiiotool - Man Page

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

--help

Print help message

--version

Print version

-v

Verbose status messages

-q

Quiet mode (turn verbose off and reduce printed output)

-n

No saved output (dry run)

--no-error-exit

Do not exit upon error, try to process additional commands (danger!)

-a

Do operations on all subimages/miplevels

--debug

Debug mode

--runstats

Print runtime statistics

--buildinfo

Print OIIO build information

--info

Print resolution and basic info on all inputs, detailed metadata if -v is also used (options: format=xml:verbose=1)

--list-formats

List all supported file formats and their filename extensions

--metamatch REGEX

Which metadata is printed with -info -v

--no-metamatch REGEX

Which metadata is excluded with -info -v

--stats

Print pixel statistics of all inputs files

--dumpdata

Print all pixel data values of input files (options: empty=1, C=arrayname)

--hash

Print SHA-1 hash of each input image

-u

Update mode: skip outputs when the file exists and is newer than all inputs

--no-clobber

Do not overwrite existing files

--create-dir

Create output directories if it doesn't exists

--threads N

Number of threads (default 0 == #cores)

--gpu

[EXPERIMENTAL] Use GPU if available (options: device=...)

--no-autopremult

Turn off automatic premultiplication of images with unassociated alpha

--autopremult

Turn on automatic premultiplication of images with unassociated alpha

--autoorient

Automatically --reorient all images upon input

--autocc

Automatically color convert based on filename (options: unpremult=)

--noautocc

Turn off automatic color conversion

--native

Keep native pixel data type (bypass cache if necessary)

--cache MB

ImageCache size (in MB: default=4096)

--autotile TILESIZE

Autotile enable for cached images (the argument is the tile size, default 0 means no autotile)

--metamerge

Always merge metadata of all inputs into output

--oiioattrib NAME VALUE

Sets global OpenImageIO attribute (options: type=...)

--experimental

Allow experimental features

Control flow and scripting:

--set NAME VALUE

Set a user variable (options: type=...)

--if VALUE

If VALUE is not 0 or empty, execute commands until --endif

--else

Else clause of the current 'if' block

--endif

End the current 'if' block

--while VALUE

If VALUE is not 0 or empty, execute commands until --endwhile and loop

--endwhile

End the current 'while' block

--for VARIABLE RANGE

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

--endfor

End the current 'for' block

--frames FRAMERANGE

Frame range for '#' or printf-style wildcards

--framepadding NDIGITS

Frame number padding digits (ignored when using printf-style wildcards)

--views VIEWNAMES

Views for %V/%v wildcards (comma-separated, defaults to "left,right")

--skip-bad-frames

Skip to next frame in range if there's an error, rather than exiting

--parallel-frames

Parallelize evaluation of frame range

--wildcardoff

Disable numeric wildcard expansion for subsequent command line arguments

--wildcardon

Enable numeric wildcard expansion for subsequent command line arguments

--evaloff

Disable {expression} evaluation for subsequent command line arguments

--evalon

Enable {expression} evaluation for subsequent command line arguments

Commands that read images:

-i FILENAME

Input file (options: autocc=, ch=, get_thumbnail=, info=, infoformat=, native=, now=, type=, unpremult=)

--iconfig NAME VALUE

Sets input config attribute (options: type=...)

--missingfile OPTION

Set policy for missing input files: 'error' (default), 'black', 'checker'

--testread FILENAME

Test file read (do not keep image; used for debugging)

Commands that write images:

-o FILENAME

Output the current image to the named file (options: all=, autocc=, autocrop=, autotrim=, bits=, contig=, datatype=, dither=, fileformatname=, scanline=, separate=, tile=, unpremult=)

-otex FILENAME

Output the current image as a texture

-oenv FILENAME

Output the current image as a latlong env map

-obump FILENAME

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

’-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

--scanline

Output scanline images

--tile WIDTH HEIGHT

Output tiled images with this tile size

--compression NAME

Set the compression method (in the form "name" or "name:quality")

--dither

Add dither when writing <= 8-bit output from > 8 bit input

--planarconfig CONFIG

Force planarconfig (contig, separate, default)

--adjust-time

Adjust file times to match DateTime metadata

--noautocrop

Do not automatically crop images whose formats don't support separate pixel data and full/display windows

--autotrim

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 TEXT

Echo message to console (options: newline=0)

--printinfo

Print info and metadata of the current top image (options: allsubimages=, native=1, stats=1, verbose=0)

--printstats

Print pixel statistics of the current top image (options: allsubimages=, window=<geom>)

--colorcount COLORLIST

Count of how many pixels have the given color (argument: color;color;...) (options: eps=color)

--rangecheck MIN MAX

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

--attrib NAME VALUE

Sets metadata attribute (options: type=...)

--sattrib NAME VALUE

Sets string metadata attribute

--eraseattrib REGEX

Erase attributes matching regex (options: fromfile=1 filename-containing-patterns

--caption TEXT

Sets caption (ImageDescription metadata)

--keyword KEYWORD

Add a keyword

--clear-keywords

Clear all keywords

--history

Write full command line into Exif:ImageHistory, Software metadata attributes

--no-history

Do not write full command line into Exif:ImageHistory, Software metadata attributes

--nosoftwareattrib

Do not write any Exif:ImageHistory or Software metadata attributes

--sansattrib

Write command line into Software & ImageHistory but remove --sattrib and --attrib options

--orientation ORIENT

Set the assumed orientation

--orientcw

Rotate orientation metadata 90 deg clockwise

--orientccw

Rotate orientation metadata 90 deg counter-clockwise

--orient180

Rotate orientation metadata 180 deg

--origin +X+Y

Set the pixel data window origin (e.g. +20+10, -16-16)

--originoffset +X+Y

Offset the pixel data window origin from its current position (e.g. +20+10, -16-16)

--fullsize GEOM

Set the display window (e.g., 1920x1080, 1024x768+100+0, -20-30)

--fullpixels

Set the 'full' image range to be the pixel data window

--chnames NAMELIST

Set the channel names (comma-separated)

Options that affect subsequent actions:

--fail THRESH

Failure threshold difference (0.000001)

--failpercent PCNT

Allow this percentage of failures in diff (0)

--hardfail THRESH

Fail diff if any one pixel exceeds this error (infinity)

--warn THRESH

Warning threshold difference (0.00001)

--warnpercent PCNT

Allow this percentage of warnings in diff (0)

--hardwarn THRESH

Warn if any one pixel difference exceeds this error (infinity)

Actions:

--create GEOM NCHANS

Create a blank image

--pattern NAME GEOM NCHANS

Create a patterned image. Pattern name choices: black, constant, fill, checker, noise

--kernel NAME GEOM

Create a centered convolution kernel

--capture

Capture an image (options: camera=%d)

--diff

Print report on the difference of two images (modified by --fail, --failpercent, --hardfail, --warn, --warnpercent --hardwarn)

--pdiff

Print report on the Yee perceptual difference of two images (modified by --fail, --failpercent, --hardfail, --warn, --warnpercent --hardwarn)

--flipdiff

[EXPERIMENTAL] Compute FLIP perceptual difference of two images (options: hdr=1, colormap=NAME, ppd=67.02, maxluminance=2.0)

--add

Add two images

--addc VAL

Add to all channels a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)

--sub

Subtract two images

--subc VAL

Subtract from all channels a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)

--scale

Scale all channels of one image by the single channel of another image

--mul

Multiply two images

--mulc VAL

Multiply the image values by a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)

--div

Divide first image by second image

--divc VAL

Divide the image values by a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)

--mad

Multiply two images, add a third

--invert

Take the color inverse (subtract from 1) (options: chbegin=0, chend=3

--abs

Take the absolute value of the image pixels

--absdiff

Absolute difference between two images

--absdiffc VAL

Absolute difference versus a scalar or per-channel constant (e.g.: 0.5 or 1,1.25,0.5)

--powc VAL

Raise the image values to a scalar or per-channel power (e.g.: 2.2 or 2.2,2.2,2.2,1.0)

--noise

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

--chsum

Turn into 1-channel image by summing channels (options: weight=r,g,...)

--colormap MAPNAME

Color map based on channel 0 (arg: "inferno", "viridis", "magma", "turbo", "plasma", "blue-red", "spectrum", "heat", or comma-separated list of RGB triples)

--cryptomatte-colors NAME

Convert the named cryptomatte channels into a color matte image

--crop GEOM

Set pixel data resolution and offset, cropping or padding if necessary (WxH+X+Y or xmin,ymin,xmax,ymax)

--croptofull

Crop or pad to make pixel data region match the "full" region

--trim

Crop to the minimal ROI containing nonzero pixel values

--cut GEOM

Cut out the ROI and reposition to the origin (WxH+X+Y or xmin,ymin,xmax,ymax)

--paste +X+Y

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)

--pastemeta

Paste the metadata from the first image into the second image (options: merge=%d, pattern=REGEX)

--mosaic WxH

Assemble images into a mosaic (arg: WxH; options: pad=0, fit=WxH)

--over

’Over' composite of two images

--zover

Depth composite two images with Z channels (options: zeroisinf=%d)

--deepmerge

Merge/composite two deep images

--deepholdout

Hold out one deep image by another

--rotate90

Rotate the image 90 degrees clockwise

--rotate180

Rotate the image 180 degrees

--rotate270

Rotate the image 270 degrees clockwise (or 90 degrees CCW)

--flip

Flip the image vertically (top<->bottom)

--flop

Flop the image horizontally (left<->right)

--reorient

Rotate and/or flop the image to transform the pixels to match the Orientation metadata

--transpose

Transpose the image

--cshift +X+Y

Circular shift the image (e.g.: +20-10)

--resample GEOM

Resample (640x480, 50%) (options: interp=0)

--resize GEOM

Resize (640x480, 50%) (options: from=<geom>, to=<geom>, filter=%s, highlightcomp=%d, edgeclamp=%d)

--fit GEOM

Resize to fit within a window size (options: filter=%s, pad=%d, fillmode=%s, exact=%d, highlightcomp=%d)

--pixelaspect ASPECT

Scale up the image's width or height to match the given pixel aspect ratio (options: filter=%s, highlightcomp=%d)

--rotate DEGREES

Rotate pixels (degrees clockwise) around the center of the display window (options: filter=%s, center=%f,%f, recompute_roi=%d, highlightcomp=%d

--warp MATRIX

Warp pixels (argument is a 3x3 matrix, separated by commas) (options: filter=%s, recompute_roi=%d, highlightcomp=%d)

--st_warp

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

Convolve with a kernel

--blur WxH

Blur the image (options: kernel=name)

--median WxH

Median filter the image

--dilate WxH

Dilate (area maximum) the image

--erode WxH

Erode (area minimum) the image

--unsharp

Unsharp mask (options: kernel=gaussian, width=3, contrast=1, threshold=0)

--laplacian

Laplacian filter the image

--normalize

Normalize the image (options: incenter=0.5, outcenter=0.5, scale=0.5)

--fft

Take the FFT of the image

--ifft

Take the inverse FFT of the image

--polar

Convert complex (real,imag) to polar (amplitude,phase)

--unpolar

Convert polar (amplitude,phase) to complex (real,imag)

--fixnan STRATEGY

Fix NaN/Inf values in the image (choices: none, black, box3, error)

--fillholes

Fill in holes (where alpha is not 1)

--max

Pixel-by-pixel max of two images

--maxc VAL

Max all values with a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)

--maxchan

Maximum of all channels of the image

--min

Pixel-by-pixel min of two images

--minc VAL

Min all values with a scalar or per-channel constants (e.g.: 0.5 or 1,1.25,0.5)

--minchan

Minimum of all channels of the image

--clamp

Clamp values (options: min=..., max=..., clampalpha=0)

--contrast

Remap values (options: black=0..., white=1..., sthresh=0.5..., scontrast=1.0..., gamma=1, clamp=0|1)

--saturate SCALE

Scale saturation of the color channels

--rangecompress

Compress the range of pixel values with a log scale (options: luma=0|1)

--rangeexpand

Un-rangecompress pixel values back to a linear scale (options: luma=0|1)

--line X1,Y1,X2,Y2,...

Render a poly-line (options: color=)

--point X1,Y1,X2,Y2,...

Render points (options: color=)

--box X1,Y1,X2,Y2

Render a box (options: color=)

--fill GEOM

Fill a region (options: color=)

--text TEXT

Render text into the current image (options: x=, y=, size=, color=)

--demosaic

Demosaic (options: pattern=%s, algorithm=%s, layout=%s, white_balance=%f:R,G1,G2,B)

Manipulating channels or subimages:

--ch CHANLIST

Select or shuffle channels (e.g., "R,G,B", "B,G,R", "2,3,4")

--nchannels N

Force the current image to have N channels (padding with 0.0 as needed)

--chappend

Append the channels of the last two images

--unmip

Discard all but the top level of a MIPmap

--selectmip MIPLEVEL

Select just one MIP level (0 = highest res)

--subimage SUBIMAGEINDEX

Select just one subimage by index or name (options: delete=1)

--sisplit

Split the top image's subimges into separate images

--siappend

Append the last two images into one multi-subimage image

--siappendall

Append all images on the stack into a single multi-subimage image

--layersplit

Split the top image's channel-name-based layers into separate images on the stack

--deepen

Deepen normal 2D image to deep

--flatten

Flatten deep image to non-deep

--thumbnail-get

Extract an embedded thumbnail (options: fail=, index=)

--thumbnail-set

Attach the top image as the thumbnail of the image below it

Image stack manipulation:

--label %s

Label the top image

--dup

Duplicate the current image (push a copy onto the stack)

--swap

Swap the top two images on the stack.

--pop

Throw away the current image

--popbottom

Throw away the image on the bottom of the stack

--stackreverse

Throw away the image on the bottom of the stack

--stackextract INDEX

Move an indexed stack item to the top of the stack

--stackclear

Remove all images from the stack, leaving it empty

Color management:

--colorconfiginfo

Print extensive details about the color management configuration

--colorconfig FILENAME

Explicitly specify an OCIO configuration file

--iscolorspace COLORSPACE

Set the assumed color space (without altering pixels)

--tocolorspace COLORSPACE

Convert the current image's pixels to a named color space

--colorconvert SRC DST

Convert pixels from 'src' to 'dst' color space (options: key=, value=, unpremult=, strict=)

--ccmatrix MATRIXVALS

Color convert pixels with a 3x3 or 4x4 matrix (options: unpremult=,transpose=)

--ociolook LOOK

Apply the named OCIO look (options: from=, to=, inverse=, key=, value=, unpremult=)

--ociodisplay DISPLAY VIEW

Apply the named OCIO display and view (options: from=, looks=, key=, value=, unpremult=, inverse=)

--ociofiletransform FILENAME

Apply the named OCIO filetransform (options: inverse=, unpremult=)

--ocionamedtransform NAME

Apply the named OCIO namedtransform (options: inverse=, key=, value=, unpremult=)

--unpremult

Divide all color channels of the current image by the alpha to "un-premultiply"

--premult

Multiply all color channels of the current image by the alpha

--repremult

Multiply all color channels of the current image by the alpha, but don't crush alpha=0 pixels to black.

--iccwrite FILENAME

Output the current image's ICC profile as a separate file

--iccread FILENAME

Add the contents of the file to the top image as its ICC profile

--cicp CICP

Set or modifiy CICP metadata for supporting output formats (e.g., "12,16,0,1")

Input formats supported: bmp, cineon, dds, dicom, dpx, fits, gif, hdr, heif, ico, iff, jpeg, jpeg2000, jpegxl, null, openexr, openvdb, png, pnm, psd, ptex, 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.1.18.1 | Linux/x86_64 Build compiler: gcc 16.2 | C++17/201703 HW features enabled at build: sse2 No CUDA support (disabled / unavailable at build time)

Dependencies: BZip2 1.0.8, DCMTK 3.6.9, FFmpeg NONE, fmt 12.1.0, Freetype 2.14.3, GIF 6.1.3, Imath 3.1.12, JXL 0.11.2, libdeflate 1.26, Libheif 1.23.5, libjpeg-turbo 3.1.4.1, LibRaw 0.22.2, libuhdr 1.4.0, OpenColorIO 2.6.0, OpenCV 4.13.0, OpenEXR 3.4.13, OpenGL, OpenJPEG 2.5.4, openjph 0.31.0, OpenVDB 13.1.0, PNG 1.6.58, Ptex 2.5, pugixml 1.16, pybind11 3.0.4, Python3 3.15.0, Qt6 6.11.2, Robinmap, TBB 2020.3, TIFF 4.7.2, WebP 1.6.0, ZLIB 1.3.1

Running on 8 cores 29.3GB sse2,sse3,ssse3,sse41,sse42,avx,avx2,avx512f,avx512dq,avx512ifma,avx512cd,avx512bw,avx512vl,fma,f16c,popcnt,rdrand No compute specific hardware enabled.

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

Info

06 October 2026 OpenImageIO