oiiotool(1)

TITLE
oiiotool -- simple image processing operations

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

DESCRIPTION
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
Options (general):

    --help
        Print help message

    -v  Verbose status messages

    -q  Quiet mode (turn verbose off)

    -n  No saved output (dry run)

    -a  Do operations on all subimages/miplevels

    --debug
        Debug mode

    --runstats
        Print runtime statistics

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

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

    --stats
        Print pixel statistics on all inputs

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

    --hash
        Print SHA-1 hash of each input image

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

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

    --no-clobber
        Do not overwrite existing files

    --threads
        %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)

    --wildcardoff
        Disable numeric wildcard expansion for subsequent command line arguments

    --wildcardon
        Enable numeric wildcard expansion for subsequent command line arguments

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

    --noautocc
        Turn off automatic color conversion

    --native
        Keep native pixel data type (bypass cache if necessary)

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

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

Commands that read images:

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

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

Commands that write images:

    -o  %s Output the current image to the named file

    -otex
        %s Output the current image as a texture

    -oenv
        %s Output the current image as a latlong env map

Options that affect subsequent image output:

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

    --scanline
        Output scanline images

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

    --compression %s
        Set the compression method

    --quality %d
        Set the compression quality, 1-100

    --dither
        Add dither to 8-bit output

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

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

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

    --eraseattrib
        %s Erase attributes matching regex

    --caption
        %s Sets caption (ImageDescription metadata)

    --keyword
        %s Add a keyword

    --clear-keywords
        Clear all keywords

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

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

    --orientation
        %d 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
        %s Set the pixel data window origin (e.g. +20+10)

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

Actions:

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

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

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

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

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

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

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

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

    --mad
        Multiply two images, add a third

    --invert
        Take the color inverse (subtract from 1)

    --abs
        Take the absolute value of the image pixels

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

    --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 %s
        Color map based on channel 0 (arg: "blue-red", "spectrum", "heat", or comma-separated list of RGB triples)

    --crop
        %s 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
        %s Cut out the ROI and reposition to the origin (WxH+X+Y or xmin,ymin,xmax,ymax)

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

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

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

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

    --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
        %s Circular shift the image (e.g.: +20-10)

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

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

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

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

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

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

    --convolve
        Convolve with a kernel

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

    --median
        %s Median filter the image (arg: WxH)

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

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

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

    --laplacian
        Laplacian filter the image

    --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
        %s Fix NaN/Inf values in the image (options: none, black, box3, error)

    --fillholes
        Fill in holes (where alpha is not 1)

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

    --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
        %s Render a poly-line (args: x1,y1,x2,y2... ; options: color=)

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

    --fill
        %s Fill a region (options: color=)

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

Manipulating channels or subimages:

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

    --chappend
        Append the channels of the last two images

    --unmip
        Discard all but the top level of a MIPmap

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

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

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

    --deepen
        Deepen normal 2D image to deep

    --flatten
        Flatten deep image to non-deep

Image stack manipulation:

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

    --label
        %s Label the top image

Color management:

    --colorconfig
        %s Explicitly specify an OCIO configuration file

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

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

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

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

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

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

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

    Input formats supported: bmp, cineon, dds, dpx, ffmpeg, 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, 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: FFMpeg Lavf58.45.100, gif_lib 5.1.6, jpeg-turbo 2.0.5, OpenJpeg 1.5.2, OpenEXR 2.5.3, libpng 1.6.37, libraw 0.20.0-Release, LIBTIFF, Version 4.1.0, Webp 1.1.0