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)
Debug mode
Print runtime statistics
Do operations on all subimages/miplevels
Print resolution and metadata on all inputs
--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=0:printinfo=0:autocc=0)
%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 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,...)
%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
%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%)
%s Resize (640x480, 50%) (options: filter=%s)
%s Resize to fit within a window size (options: filter=%s, pad=%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 (without regard to its previous interpretation)
%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

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

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

Dependent libraries: Field3d 1.7.2, gif_lib unknown version, jpeg-turbo 1.5.0, OpenEXR 2.2.0, libpng 1.6.25, libraw 0.17.2-Release, LIBTIFF, Version 4.0.6, Webp 0.5.1


OpenImageIO 03 October 2016