oiiotool man page


oiiotool -- simple image processing operations


Usage:  oiiotool [filename,option,action]...


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


Options (general):


Print help message


Verbose status messages


Quiet mode (turn verbose off)


No saved output (dry run)


Do operations on all subimages/miplevels


Debug mode


Print runtime statistics


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


%s               Echo message to console (options: newline=0)

--metamatch %s

Regex: which metadata is printed with -info -v

--no-metamatch %s

Regex: which metadata is excluded with -info -v


Print pixel statistics on all inputs


Print all pixel data values (options: empty=0)


Print SHA-1 hash of each input image


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


%s %s      Count of how many pixels are outside the low and high color arguments (each is a comma-separated color value list)


Do not overwrite existing files


%d            Number of threads (default 0 == #cores)

--frames %s

Frame range for '#' or printf-style wildcards

--framepadding %d

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

--views %s

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


Disable numeric wildcard expansion for subsequent command line arguments


Enable numeric wildcard expansion for subsequent command line arguments


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


Turn off automatic color conversion


Keep native pixel data type (bypass cache if necessary)


%d              ImageCache size (in MB: default=4096)


%d           Autotile size for cached images (default=4096)

Commands that read images:


%s                   Input file (argument: filename) (options: now=, printinfo=, autocc=, type=, ch=)


%s %s         Sets input config attribute (name, value) (options: type=...)

Commands that write images:


%s                   Output the current image to the named file


%s                Output the current image as a texture


%s                Output the current image as a latlong env map

Options that affect subsequent image output:


%s                   '-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


%d %d            Output tiled images (tilewidth, tileheight)

--compression %s

Set the compression method

--quality %d

Set the compression quality, 1-100


Add dither to 8-bit output

--planarconfig %s

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 change current image metadata (but not pixel values):


%s %s          Sets metadata attribute (name, value) (options: type=...)


%s %s         Sets string metadata attribute (name, value)


%s        Erase attributes matching regex


%s            Sets caption (ImageDescription metadata)


%s            Add a keyword


Clear all keywords


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


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


%d        Set the assumed orientation


Rotate orientation metadata 90 deg clockwise


Rotate orientation metadata 90 deg counter-clockwise


Rotate orientation metadata 180 deg


%s             Set the pixel data window origin (e.g. +20+10)


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


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


%s            Set the channel names (comma-separated)

Options that affect subsequent actions:

--fail %g

Failure threshold difference (0.000001)

--failpercent %g

Allow this percentage of failures in diff (0)

--hardfail %g

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

--warn %g

Warning threshold difference (0.00001)

--warnpercent %g

Allow this percentage of warnings in diff (0)

--hardwarn %g

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



%s %d          Create a blank image (args: geom, channels)


%s %s %d      Create a patterned image (args: pattern, geom, channels). Patterns: black, fill, checker, noise


%s %s          Create a centered convolution kernel (args: name, geom)


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 perceptual difference of two images (modified by --fail, --failpercent, --hardfail, --warn, --warnpercent --hardwarn)


Add two images

--addc %s

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


Subtract two images

--subc %s

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


Multiply two images

--mulc %s

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

--divc %s

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)


Take the absolute value of the image pixels


Absolute difference between two images

--absdiffc %s

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

--powc %s

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,...)

--colormap %s

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


%s               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


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


%s              Paste fg over bg at the given position (e.g., +100+50)


%s             Assemble images into a mosaic (arg: WxH; options: pad=0)


’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


%s %d       Histogram one channel (options: cumulative=0)


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


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


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


%s             Resize (640x480, 50%) (options: filter=%s)


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


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


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


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


Convolve with a kernel


%s               Blur the image (arg: WxH; options: kernel=name)


%s             Median filter the image (arg: WxH)


%s             Dilate (area maximum) the image (arg: WxH)


%s              Erode (area minimum) the image (arg: WxH)


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


Laplacian filter the image


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)


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


Fill in holes (where alpha is not 1)


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


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)


%s               Render a poly-line (args: x1,y1,x2,y2... ; options: color=)


%s                Render a box (args: x1,y1,x2,y2 ; options: color=)


%s               Fill a region (options: color=)


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

Manipulating channels or subimages:


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


Append the channels of the last two images


Discard all but the top level of a MIPmap


%d          Select just one MIP level (0 = highest res)


%s           Select just one subimage (by index or name)


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


Deepen normal 2D image to deep


Flatten deep image to non-deep

Image stack manipulation:


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


Swap the top two images on the stack.


Throw away the current image


%s              Label the top image

Color management:


%s        Explicitly specify an OCIO configuration file


%s       Set the assumed color space (without altering pixels)


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


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


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


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


%s  Apply the named OCIO filetransform (options: inverse=)


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

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

Output formats supported: bmp, dpx, field3d, fits, gif, hdr, ico, iff, jpeg, jpeg2000, openexr, png, pnm, rla, sgi, socket, targa, tiff, webp, zfile

Known color spaces: "linear", "sRGB", "Rec709"

Dependent libraries: dcmtk 3.6.2, Field3d 1.7.2, gif_lib 5.1.4, jpeg-turbo 1.5.90, OpenJpeg 2.3.0, OpenEXR 2.2.0, libpng 1.6.34, libraw 0.18.8-Release, LIBTIFF, Version 4.0.9, Webp 0.6.1


02 April 2018 OpenImageIO