\chapter{{\kw oiiotool}: the OIIO Swiss Army Knife}
\label{chap:oiiotool}
\indexapi{oiiotool}

\section{Overview}


The \oiiotool program will read images (from any file format for which
an \ImageInput plugin can be found), perform various operations on them,
and write images (in any format for which an \ImageOutput plugin can be
found).

The \oiiotool utility is invoked as follows:

\medskip

\hspace{0.25in} \oiiotool \emph{args}

\medskip

\oiiotool maintains an \emph{image stack}, with the top image in the
stack also called the \emph{current image}.  The stack begins containing
no images.

\oiiotool arguments consist of image names, or commands.  When an
image name is encountered, that image is pushed on the stack and becomes
the new \emph{current image}.

Most other commands either alter the current image (replacing it with
the alteration), or in some cases will pull more than one image off the
stack (such as the current image and the next item on the stack) and
then push a new image.

\subsubsection*{Optional arguments}

Some commands stand completely on their own (like {\cf --flip}), others
take one or more arguments (like {\cf --resize} or {\cf -o}):

\smallskip
\hspace{0.25in} {\cf oiiotool foo.jpg --flip --resize 640x480 -o out.tif}
\smallskip

A few commands take optional modifiers for options that are so
rarely-used or confusing that they should not be required arguments.
In these cases, they are appended to the command name, after a colon
(``{\cf :}''), and with a \emph{name}{\cf =}\emph{value} format.  As
an example:

\smallskip
\hspace{0.25in} {\cf oiiotool --capture:camera=1 -o out.tif}
\smallskip

\subsubsection*{Frame sequences}
\index{frame sequences}\index{wildcard}
\index{numeric frame sequence wildcards}

It is also possible to have \oiiotool operate on numbered sequences of
images.  In effect, this will execute the \oiiotool command several
times, making substitutions to the sequence arguments in turn.

Image sequences are specified by having filename arguments to
oiiotool use either a numeric range wildcard (designated such as
``{\cf 1-10\#}'' or a {\cf printf}-like notation ``{\cf 1-10\%d}''),
or spelling out a more complex pattern with
{\cf --frames}.  For example:

\begin{code}
    oiiotool big.1-3#.tif --resize 100x100 -o small.1-3#.tif

    oiiotool big.1-3%04d.tif --resize 100x100 -o small.1-3%04d.tif

    oiiotool --frames 1-3 big.#.tif --resize 100x100 -o small.#.tif

    oiiotool --frames 1-3 big.%04d.tif --resize 100x100 -o small.%04d.tif
\end{code}

\noindent Any of those will be the equivalent of having issued the following
sequence of commands:

\begin{code}
    oiiotool big.0001.tif --resize 100x100 -o small.0001.tif
    oiiotool big.0002.tif --resize 100x100 -o small.0002.tif
    oiiotool big.0003.tif --resize 100x100 -o small.0003.tif
\end{code}

The frame range may be forwards ({\cf 1-5}) or backwards ({\cf 5-1}),
and may give a step size to skip frames ({\cf 1-5x2} means 1, 3, 5) or
take the complement of the step size set ({\cf 1-5y2} means 2, 4) and
may combine subsequences with a comma.

If you are using the {\cf \#} or {\cf @} wildcards, then
the wildcard characters themselves specify how many digits to pad
with leading zeroes, with {\cf \#} indicating 4 digits and {\cf @}
indicating one digit (these may be combined: {\cf \#@@} means 6 digits).
An optional {\cf --framepadding} can also be used to override the number
of padding digits.
For example,
\begin{code}
    oiiotool --framepadding 3 --frames 3,4,10-20x2 blah.#.tif
\end{code}
\noindent would match {\cf blah.003.tif}, {\cf blah.004.tif},
{\cf blah.010.tif}, {\cf blah.012.tif}, 
{\cf blah.014.tif}, {\cf blah.016.tif}, {\cf blah.018.tif}, 
{\cf blah.020.tif}.

Alternately, you can use the {\cf printf} notation, such as
\begin{code}
    oiiotool --frames 3,4,10-20x2 blah.%03d.tif
\end{code}

\NEW % 1.5
Two special command line arguments can be used to disable numeric wildcard
expansion: {\cf --wildcardoff} disables numeric wildcard expansion for
subsequent command line arguments, until {\cf --wildcardon} re-enables
it for subsequent command line arguments. Turning wildcard expansion off
for selected arguments can be helpful if you have arguments that must 
contain the wildcard characters themselves. For example:

\begin{code}
    oiiotool input.@@@.tif --wildcardoff --sattrib Caption "lg@openimageio.org" \
        --wildcardon -o output.@@@.tif
\end{code}

\noindent In this example, the `{\cf @}' characters in the filenames should
be expanded into numeric file sequence wildcards, but the `{\cf @}' in the
caption (denoting an email address) should not.

\subsubsection*{Stereo wildcards}

\oiiotool can also handle image sequences with separate left and right
images per frame using {\cf views}. The {\cf \%V} wildcard will match
the full name of all views and {\cf \%v} will match the first character
of each view. View names default to ``left'' and ``right'', but may
be overridden using the {\cf --views} option.
For example,
\begin{code}
    oiiotool --frames 1-5 blah_%V.#.tif
\end{code}
\noindent would match {\cf blah_left.0001.tif}, {\cf blah_right.0001.tif},
{\cf blah_left.0002.tif}, {\cf blah_right.0002.tif}, {\cf blah_left.0003.tif},
{\cf blah_right.0003.tif}, {\cf blah_left.0004.tif}, 
{\cf blah_right.0004.tif}, {\cf blah_left.0005.tif}, 
{\cf blah_right.0005.tif}, and
\begin{code}
    oiiotool --frames 1-5 blah_%v.#.tif
\end{code}
\noindent would match {\cf blah_l.0001.tif}, {\cf blah_r.0001.tif},
{\cf blah_l.0002.tif}, {\cf blah_r.0002.tif}, {\cf blah_l.0003.tif},
{\cf blah_r.0003.tif}, {\cf blah_l.0004.tif}, {\cf blah_r.0004.tif}, 
{\cf blah_l.0005.tif}, {\cf blah_r.0005.tif}, but
\begin{code}
    oiiotool --views left --frames 1-5 blah_%v.#.tif
\end{code}
\noindent would only match {\cf blah_l.0001.tif}, {\cf blah_l.0002.tif},
{\cf blah_l.0003.tif}, {\cf blah_l.0004.tif}, {\cf blah_l.0005.tif}.


\section{\oiiotool Tutorial / Recipes}

This section will give quick examples of common uses of \oiiotool to get
you started.  They should be fairly intuitive, but you can read the
subsequent sections of this chapter for all the details on every
command.

\subsection*{Printing information about images}

To print the name, format, resolution, and data type of an image
(or many images):

\begin{code}
    oiiotool --info *.tif
\end{code}

\noindent To also print the full metadata about each input image, use both
{\cf --info} and {\cf -v}:

\begin{code}
    oiiotool --info -v *.tif
\end{code}

\noindent To print info about all subimages and/or MIP-map levels of each
input image, use the {\cf -a} flag:

\begin{code}
    oiiotool --info -v -a mipmap.exr
\end{code}

\noindent To print statistics giving the minimum, maximum, average, and
standard deviation of each channel of an image, as well as other
information about the pixels:

\begin{code}
    oiiotool --stats img_2012.jpg
\end{code}

\noindent The {\cf --info}, {\cf --stats}, {\cf -v}, and {\cf -a} flags may
be used in any combination.


\subsection*{Converting between file formats}

It's a snap to convert among image formats supported by \product
(i.e., for which \ImageInput and \ImageOutput plugins can be found).
The \oiiotool utility will simply infer the file format from the
file extension. The following example converts a PNG image to JPEG:

\begin{code}
    oiiotool lena.png -o lena.jpg
\end{code}

The first argument ({\cf lena.png}) is a filename, causing \oiiotool to
read the file and makes it the current image.  The {\cf -o} command
outputs the current image to the filename specified by the next
argument.

Thus, the above command should be read to mean, ``Read {\cf lena.png}
into the current image, then output the current image as {\cf lena.jpg}
(using whatever file format is traditionally associated with the {\cf
  .jpg} extension).''


\subsection*{Comparing two images}

To print a report of the differences between two images of the same
resolution:

\begin{code}
    oiiotool old.tif new.tif --diff
\end{code}

\noindent If you also want to save an image showing just the differences:

\begin{code}
    oiiotool old.tif new.tif --diff --sub --abs -o diff.tif
\end{code}

This looks complicated, but it's really simple: read {\cf old.tif},
read {\cf new.tif} (pushing {\cf old.tif} down on the image stack),
report the differences between them, subtract {\cf new.tif} from 
{\cf old.tif} and replace them both with the difference image,
replace that with its absolute value, then save that image to 
{\cf diff.tif}.


\subsection*{Changing the data format or bit depth}

Just use the {\cf -d} option to specify a pixel data format for all
subsequent outputs.  For example, assuming that {\cf in.tif} uses 16-bit
unsigned integer pixels, the following will convert it to an 8-bit
unsigned pixels:

\begin{code}
    oiiotool in.tif -d uint8 -o out.tif
\end{code}

For formats that support per-channel data formats, you can override
the format for one particular channel using {\cf -d CHNAME=TYPE}.
For example, assuming {\cf rgbaz.exr} is a {\cf float} RGBAZ file,
and we wish to convert it to be {\cf half} for RGBA, and {\cf float}
for Z.  That can be accomplished with the following command:

\begin{code}
    oiiotool rgbaz.tif -d half -d Z=float -o rgbaz2.exr
\end{code}


\subsection*{Changing the compression}

The following command converts writes a TIFF file, specifically using
LZW compression:

\begin{code}
    oiiotool in.tif --compression lzw -o compressed.tif
\end{code}

The following command writes its results as a JPEG file at a 
compression quality of 50 (pretty severe compression):

\begin{code}
    oiiotool big.jpg --quality 50 -o small.jpg
\end{code}



\subsection*{Converting between scanline and tiled images}

Convert a scanline file to a tiled file with $16 \times 16$ tiles:

\begin{code}
    oiiotool s.tif --tile 16 16 -o t.tif
\end{code}

\noindent Convert a tiled file to scanline:

\begin{code}
    oiiotool t.tif --scanline -o s.tif
\end{code}



\subsection*{Adding captions or metadata}

\noindent Add a caption to the metadata:
\begin{code}
    oiiotool foo.jpg --caption "Hawaii vacation" -o bar.jpg
\end{code}

\noindent Add keywords to the metadata:
\begin{code}
    oiiotool foo.jpg --keyword "volcano,lava" -o bar.jpg
\end{code}

\noindent Add other arbitrary metadata:
\begin{code}
    oiiotool in.exr --attrib "FStop" 22.0 \
            --attrib "IPTC:City" "Berkeley" -o out.exr
\end{code}


\subsection*{Changing image boundaries}

\noindent Change the origin of the pixel data window:
\begin{code}
    oiiotool in.exr --origin +256+80 -o offset.exr
\end{code}

\noindent Change the display window:
\begin{code}
    oiiotool in.exr --fullsize 1024x768+16+16 -o out.exr
\end{code}

\noindent Change the display window to match the data window:
\begin{code}
    oiiotool in.exr --fullpixels -o out.exr
\end{code}

\noindent Crop (trim) an image to a 128x128 region whose upper left corner
is at location (900,300), leaving the remaining pixels in their original
positions on the image plane (i.e., the resulting image will have origin at
900,300), and retaining its original display window:
\begin{code}
    oiiotool in.exr --crop 128x128+900+300 -o out.exr
\end{code}

\noindent Cut (trim and extract) a 128x128 region whose upper left corner
is at location (900,300), moving the result to the origin (0,0) of the image
plane and setting the display window to the new pixel data window:
\begin{code}
    oiiotool in.exr --cut 128x128+900+300 -o out.exr
\end{code}


\subsection*{Scale the values in an image}

Reduce the brightness of the R, G, and B channels by 10\%,
but leave the A channel at its original value:

\begin{code}
    oiiotool original.exr --cmul 0.9,0.9,0.9,1.0 -o out.exr
\end{code}

\subsection*{Remove gamma-correction from an image}

Convert a gamma-corrected image (with gamma = 2.2) to linear values.

\begin{code}
    oiiotool corrected.exr --cpow 2.2,2.2,2.2,1.0 -o linear.exr
\end{code}

\subsection*{Resize an image}

\noindent Resize to a specific resolution:

\begin{code}
    oiiotool original.tif --resize 1024x768 -o specific.tif
\end{code}

\noindent Resize both dimensions by a known scale factor:

\begin{code}
    oiiotool original.tif --resize 200% -o big.tif
    oiiotool original.tif --resize 25% -o small.tif
\end{code}

\noindent Resize each dimension, independently, by known scale factors:

\begin{code}
    oiiotool original.tif --resize 300%x200% -o big.tif
    oiiotool original.tif --resize 100%x25% -o small.tif
\end{code}

\noindent Resize to a known resolution in one dimension, with the other dimension
automatically computed to preserve aspect ratio (just specify 0 as the
resolution in the dimension to be automatically computed):

\begin{code}
    oiiotool original.tif --resize 200x0 -o out.tif
    oiiotool original.tif --resize 0x1024 -o out.tif
\end{code}

\noindent Resize to fit into a given resolution, keeping the original
aspect ratio and padding with black where necessary to fit into the
specified resolution:

\begin{code}
    oiiotool original.tif --fit 640x480 -o fit.tif
\end{code}


\subsection*{Color convert an image}

This command linearizes a JPEG assumed to be in sRGB, saving as
an HDRI OpenEXR file:

\begin{code}
    oiiotool photo.jpg --colorconvert sRGB linear -o output.exr
\end{code}

\noindent And the other direction:

\begin{code}
    oiiotool render.exr --colorconvert linear sRGB -o fortheweb.png
\end{code}

\noindent This converts between two named color spaces (presumably
defined by your facility's OpenColorIO configuration):

\begin{code}
    oiiotool in.dpx --colorconvert lg10 lnf -o out.exr
\end{code}


\subsection*{Grayscale and RGB}

\noindent Turn a single channel image into a 3-channel gray RGB:
\begin{code}
    oiiotool gray.tif --ch 0,0,0 -o rgb.tif
\end{code}

\noindent Convert a color image to luminance grayscale:

\begin{code}
    oiiotool RGB.tif --chsum:weight=.2126,.7152,.0722 -o luma.tif
\end{code}

\subsection*{Channel reordering and padding}

\noindent Copy just the color from an RGBA file, truncating the A,
yielding RGB only:
\begin{code}
    oiiotool rgba.tif --ch R,G,B -o rgb.tif
\end{code}

\noindent Zero out the red and green channels:
\begin{code}
    oiiotool rgb.tif --ch R=0,G=0,B -o justblue.tif
\end{code}

\noindent Swap the red and blue channels from an RGBA image:
\begin{code}
    oiiotool rgba.tif --ch R=B,G,B=R,A -o bgra.tif
\end{code}

\noindent Extract just the named channels from a complicted many-channel
image, and add an alpha channel that is 1 everywhere:
\begin{code}
    oiiotool allmyaovs.exr --ch spec.R,spec.G,spec.B,A=1 -o spec.exr
\end{code}

\noindent Add an alpha channel to an RGB image, setting it to 1.0 everywhere,
and naming it ``A'' so it will be recognized as an alpha channel:
\begin{code}
    oiiotool rgb.tif --ch R,G,B,A=1.0 -o rgba.tif
\end{code}

\noindent Add an alpha channel to an RGB image, setting it to be the same
as the R channel and naming it ``A'' so it will be recognized as an alpha channel:
\begin{code}
    oiiotool rgb.tif --ch R,G,B,A=R -o rgba.tif
\end{code}

\noindent Add a $z$ channel to an RGBA image, setting it to 3.0 everywhere,
and naming it ``Z'' so it will be recognized as a depth channel:
\begin{code}
    oiiotool rgba.exr --ch R,G,B,A,Z=3.0 -o rgbaz.exr
\end{code}


\subsection*{Fade between two images}

\noindent Fade 30\% of the way from A to B:

\begin{code}
    oiiotool A.exr --cmul 0.7 B.exr --cmul 0.3 --add -o fade.exr
\end{code}


\subsection*{Simple compositing}

\noindent Simple ``over'' composite of aligned foreground and background:

\begin{code}
    oiiotool fg.exr bg.exr --over -o composite.exr
\end{code}

\noindent Composite of small foreground over background, with offset:

\begin{code}
    oiiotool fg.exr --origin +512+89 bg.exr --over -o composite.exr
\end{code}



\subsection*{Frame sequences: composite a sequence of images}

\noindent Composite foreground images over background images for a
series of files with frame numbers in their names:
\begin{code}
    oiiotool fg.1-50%04d.exr bg.1-50%04d.exr --over -o comp.1-50%04d.exr
\end{code}

\noindent Or,
\begin{code}
    oiiotool --frames 1-50 fg.%04d.exr bg.%04d.exr --over -o comp.%04d.exr
\end{code}


\newpage
\section{\oiiotool commands: general}

\apiitem{--help}
Prints usage information to the terminal.
\apiend

\apiitem{-v}
Verbose status messages --- print out more information about what
\oiiotool is doing at every step.
\apiend

\apiitem{-q}
Quet mode --- print out less information about what \oiiotool is doing
(only errors).
\apiend

\apiitem{--runstats}
Print timing and memory statistics about the work done by \oiiotool.
\apiend

\apiitem{-a}
Performs all operations on all subimages and/or MIPmap levels of each
input image.  Without {\cf -a}, generally each input image will really
only read the top-level MIPmap of the first subimage of the file.
\apiend

\apiitem{--info}
Prints information about each input image as it is read.  If verbose mode
is turned on ({\cf -v}), all the metadata for the image is printed.
If verbose mode is not turned on, only the resolution and data format
are printed.
\apiend

\apiitem{--metamatch \emph{regex} \\
--no-metamatch \emph{regex}}
Regular expressions to restrict which metadata are output when using
{\cf oiiotool --info -v}.  The {\cf --metamatch} expression causes only
metadata whose name matches to print; non-matches are not output.  The
{\cf --no-metamatch} expression causes metadata whose name matches to be
suppressed; others (non-matches) are printed.  It is not advised to use
both of these options at the same time (probably nothing bad will
happen, but it's hard to reason about the behavior in that case).
\apiend

\apiitem{--stats}
Prints detailed statistical information about each input image as it is
read.
\apiend

\apiitem{--hash}
Print the SHA-1 hash of the pixels of each input image.
\apiend

\apiitem{--dumpdata}
Print to the console detailed information about the values in every pixel.

\noindent Optional appended arguments include:

\begin{tabular}{p{10pt} p{0.75in} p{3.75in}}
  & {\cf empty=}{\verb&0|1&} & If 0, will cause deep images to skip printing
                            of information about pixels with no samples.
\end{tabular}
\apiend

\apiitem{--diff}
This command computes the difference of the current image and the next
image on the stack, and prints a report of those differences (how
many pixels differed, the maximum amount, etc.).  This command does not
alter the image stack.
\apiend

\apiitem{--pdiff}
This command computes the difference of the current image and the next
image on the stack using a perceptual metric, and prints whether or not they
match according to that metric.  This command does not
alter the image stack.
\apiend

\apiitem{--colorcount \emph{r1,g1,b1,...:r2,g2,b2,...:...}}
Given a list of colors separated by colons or semicolons, where each
color is a list of comma-separated values (for each channel), examine
all pixels of the current image and print a short report of how many
pixels matched each of the colors.

\noindent Optional appended arguments include:

\begin{tabular}{p{10pt} p{0.75in} p{3.75in}}
  & {\cf eps=}\emph{r,g,b,...} & Tolerance for matching colors (default:
  0.001 for all channels).
\end{tabular}

\noindent Examples:

\begin{code}
    oiiotool test.tif --colorcount "0.792,0,0,1;0.722,0,0,1"
\end{code}
\noindent might produce the following output:
\begin{code}
   10290  0.792,0,0,1
   11281  0.722,0,0,1
\end{code}

\noindent Notice that use of double quotes (\qkw{ }) around the list of
color arguments, in order to make sure that the command shell does not
interpret the semicolon ({\cf ;}) as a statement separator.  An
alternate way to specify multiple colors is to separate them with a
colon ({\cf :}), for example:
\begin{code}
    oiiotool test.tif --colorcount 0.792,0,0,1:0.722,0,0,1
\end{code}

\noindent Another example:

\begin{code}
    oiiotool test.tif --colorcount:eps=.01,.01,.01,1000 "0.792,0,0,1"
\end{code}

\noindent This example sets a larger epsilon for the R, G, and B 
channels (so that, for example, a pixel with value [0.795,0,0] would
also match), and by setting the epsilon to 1000 for the alpha channel,
it effectively ensures that alpha will not be considered in the matching
of pixels to the color value.
\apiend

\apiitem{--rangecheck \emph{Rlow,Glow,Blow,...}  \emph{Rhi,Bhi,Ghi,...}}
Given a two colors (each a comma-separated list of values for each
channel), print a count of the number of pixels in the image that has
channel values outside the [low,hi] range.  Any channels not
specified will assume a low of 0.0 and high of 1.0.

\noindent Example:

\begin{code}
    oiiotool test.exr --rangecheck 0,0,0 1,1,1
\end{code}
\noindent might produce the following output:
\begin{code}
     0  < 0,0,0
   221  > 1,1,1
 65315  within range
\end{code}
\apiend

\apiitem{--no-clobber}
Sets ``no clobber'' mode, in which existing images on disk will never be 
overridden, even if the {\cf -o} command specifies that file.
\apiend

\apiitem{--threads \emph{n}}
Use \emph{n} execution threads if it helps to speed up image operations.
The default (also if $n=0$) is to use as many threads as there are cores
present in the hardware.
\apiend

\apiitem{--frames \emph{seq}\\
--framepadding \emph{n}}
Describes the frame range to substitute for the {\cf \#} or {\cf \%0Nd} 
numeric wildcards.  The
sequence is a comma-separated list of subsequences; each subsequence
is a single frame (e.g., {\cf 100}), a range of frames ({\cf 100-150}),
or a frame range with step ({\cf 100-150x4} means {\cf  100,104,108,...}).

The frame padding is the number of digits (with leading zeroes applied)
that the frame numbers should have.  It defaults to 4.

For example,
\begin{code}
    oiiotool --framepadding 3 --frames 3,4,10-20x2 blah.#.tif
\end{code}
\noindent would match {\cf blah.003.tif}, {\cf blah.004.tif},
{\cf blah.010.tif}, {\cf blah.012.tif}, 
{\cf blah.014.tif}, {\cf blah.016.tif}, {\cf blah.018.tif}, 
{\cf blah.020.tif}.
\apiend

\apiitem{--views \emph{name1,name2,...}}
Supplies a comma-separated list of view names (substituted for {\cf \%V}
and {\cf \%v}). If not supplied, the view list will be {\cf left,right}.
\apiend

\apiitem{--wildcardoff \\
--wildcardon}
\NEW % 1.5
Turns off (or on) numeric wildcard expansion for subsequent command
line arguments. This can be useful in selectively disabling numeric wildcard
expansion for a subset of the command line.
\apiend

\begin{comment}
\apiitem{--inplace}
Causes the output to \emph{replace} the input file, rather than create a
new file with a different name.

Without this flag, \oiiotool expects two file names, which will
be used to specify the input and output files, respectively.

But when {\cf --inplace} option is used, any number of file names $\ge 1$ may
be specified, and the image conversion commands are applied to each file
in turn, with the output being saved under the original file name.  This
is useful for applying the same conversion to many files.  

For example, the following example will add the caption ``Hawaii
vacation'' to all JPEG files in the current directory:

\begin{code}
        oiiotool --inplace --adjust-time --caption "Hawaii vacation" *.jpg
\end{code}
\apiend
\end{comment}


\section{\oiiotool commands: reading and writing images}

The commands described in this section read images, write images,
or control the way that subsequent images will be written upon output.

\apiitem{\rm \emph{filename}}
If a command-line option is the name of an image file, that file will
be read and will become the new \emph{current image}, with the previous
current image pushed onto the image stack.
\apiend

\apiitem{--no-autopremult \\
--autopremult}
\NEW  % 1.5
By default, \product's format readers convert any ``unassociated alpha''
(color values that are not ``premultiplied'' by alpha) to the usual
associated/premultiplied convention.  If the {\cf --no-autopremult}
flag is found, subsequent inputs will not do this premultiplication. It
can be turned on again via {\cf --autopremult}.
\apiend

\apiitem{--autoorient}
\NEW  % 1.5
Automatically do the equivalent of {\cf --reorient} on every image as it is
read in, if it has a nonstandard orientation. This is generally a good idea
to use if you are using oiiotool to combine images that may have different
orientations.
\apiend

\apiitem{--native}
\NEW  % 1.5

Normally, all image reads into an \ImageBuf will be performed via an
underlying \ImageCache. But since an \ImageCache does not support all
possible data formats, some lesser-used formats may be auto-converted upon
being read into the cache, and therefore lose precision or range compared to
what the equivalent {\cf ImageInput::read_image} is capable of. (An example
would be a rare file of {\cf uint32} or {\cf double} pixels, which would
lose data when read into an \ImageCache whose ``biggest'' data type is
{\cf float}.)

The {\cf --native} option is used for the small set of cases where this is
problematic in practice. It causes subsequent image loads to bypass the
\ImageCache and instead do an immediate read of the file that preserves its
native format (if it's not a format that can use the ImageCache without a
loss of precision).
\apiend

\apiitem{-o \rm \emph{filename}}
Outputs the current image to the named file.  This does not remove the
current image, it merely saves a copy of it.
\apiend

\apiitem{-d {\rm \emph{datatype}} \\
-d {\rm \emph{channelname}{\cf =}\emph{datatype}}}

Attempts to set the pixel data type of all subsequent outputs.  If no
channel is named, sets \emph{all} channels to be the specified data
type.  If a specific channel is named, then the data type will be
overridden for just that channel (multiple {\cf -d} commands may be
used).

Valid types are: {\cf uint8}, {\cf sint8}, 
{\cf uint16}, {\cf sint16}, {\cf  half}, {\cf float}, {\cf double}.
The types {\cf uint10} and {\cf uint12} may be used to request 10- or
12-bit unsigned integers.  If the output file format does not support
them, {\cf uint16} will be substituted.

If the {\cf -d} option is not supplied, the output data type will
be the same as the data format of the input files, if possible.

In any case, if the output file type does not support the requested
data type, it will instead use whichever supported data type results
in the least amount of precision lost.
\apiend

% FIXME -- no it doesn't!
%\apiitem{-g {\rm \emph{gamma}}}
%Applies a gamma correction of $1/\mathrm{gamma}$ to the pixels as they
%are output.
%\apiend

%\apiitem{--sRGB}
%Explicitly tags the image as being in sRGB color space.  Note that this
%does not alter pixel values, it only marks which color space those
%values refer to (and only works for file formats that understand such
%things).  An example use of this command is if you have an image 
%that is not explicitly marked as being in any particular color space,
%but you know that the values are sRGB.
%\apiend

\apiitem{--scanline}
Requests that subsequent output files be scanline-oriented, if scanline
orientation is supported by the output file format.  By default, the
output file will be scanline if the input is scanline, or tiled if the
input is tiled.
\apiend

\apiitem{--tile {\rm \emph{x}} {\rm \emph{y}}}
Requests that subsequent output files be tiled, with the given $x \times y$ 
tile size, if tiled images are supported by the output format.
By default, the output file will take on the tiledness and tile size
of the input file.
\apiend

\apiitem{--compression {\rm \emph{method}}}
Sets the compression method for subsequent output images.  Each
\ImageOutput plugin will have its own set of methods that it supports.
By default, the output image will use the same compression technique as
the input image (assuming it is supported by the output format,
otherwise it will use the default compression method of the output
plugin).  
\apiend

\apiitem{--quality {\rm \emph{q}}}
Sets the compression quality, on a 1--100 floating-point scale.
This only has an effect if the particular compression method supports
a quality metric (as JPEG does).
\apiend

\apiitem{--dither}
Turns on \emph{dither} when outputting to 8-bit image files (does not affect
other data types). This adds just a bit of noise that reduces visible
banding artifacts.
\apiend

\apiitem{--planarconfig {\rm \emph{config}}}
Sets the planar configuration of subsequent outputs (if supported by
their formats).  Valid choices are: {\cf config} for contiguous (or
interleaved) packing of channels in the file (e.g., RGBRGBRGB...), 
{\cf separate} for separate channel planes (e.g.,
RRRR...GGGG...BBBB...), or {\cf default} for the default choice for the
given format.  This command will be ignored for output files whose 
file format does not support the given choice.
\apiend

\apiitem{--adjust-time}
When this flag is present, after writing each output, the resulting
file's modification time will be adjusted to match any \qkw{DateTime}
metadata in the image.  After doing this, a directory listing will show
file times that match when the original image was created or captured,
rather than simply when \oiiotool was run.  This has no effect on
image files that don't contain any \qkw{DateTime} metadata.
\apiend

\apiitem{--noautocrop}
For subsequent outputs, do \emph{not} automatically crop images whose
formats don't support separate pixel data and full/display windows.
Without this, the default is that outputs will be cropped or padded with
black as necessary when written to formats that don't support the
concepts of pixel data windows and full/display windows.  This is a
non-issue for file formats that support these concepts, such as OpenEXR.
\apiend

\apiitem{--autotrim}
For subsequent outputs, if the output format supports separate pixel
data and full/display windows, automatically trim the output so that
it writes the minimal data window that contains all the non-zero valued
pixels.  In other words, trim off any all-black border rows and columns
before writing the file.
\apiend


\section{\oiiotool commands that change the current image metadata}

This section describes \oiiotool commands that alter the metadata
of the current image, but do not alter its pixel values.  Only the
current (i.e., top of stack) image is affected, not any images further
down the stack.

If the {\cf -a} flag has previously been set, these commands apply to
all subimages or MIPmap levels of the current top image.  Otherwise,
they only apply to the highest-resolution MIPmap level of the first
subimage of the current top image.

\apiitem{--attrib {\rm \emph{name value}}}
Adds or replaces metadata with the given \emph{name} to have the
specified \emph{value}.

It will try to infer the type of the metadata from the value: if the
value contains only numerals (with optional leading minus sign), it will
be saved as {\cf int} metadata; if it also contains a decimal point, it
will be saved as {\cf float} metadata; otherwise, it will be saved as
a {\cf string} metadata.

For example, you could explicitly set the IPTC location metadata fields
with:
\begin{code}
        oiiotool --attrib "IPTC:City" "Berkeley" in.jpg out.jpg
\end{code}
\apiend

\apiitem{--sattrib {\rm \emph{name value}}}
Adds or replaces metadata with the given \emph{name} to have the
specified \emph{value}, forcing it to be interpreted as a {\cf string}.
This is helpful if you want to set a {\cf string} metadata to a value
that the {\cf --attrib} command would normally interpret as a number.
\apiend

\apiitem{--caption {\rm \emph{text}}}
Sets the image metadata \qkw{ImageDescription}.
This has no effect if the output image format does not support some kind
of title, caption, or description metadata field.
Be careful to enclose \emph{text} in quotes if you want your caption to
include spaces or certain punctuation!
\apiend

\apiitem{--keyword {\rm \emph{text}}}
Adds a keyword to the image metadata \qkw{Keywords}.  Any existing
keywords will be preserved, not replaced, and the new keyword will not
be added if it is an exact duplicate of existing keywords.  This has no
effect if the output image format does not support some kind of keyword
field.  

Be careful to enclose \emph{text} in quotes if you want your keyword to
include spaces or certain punctuation.  For image formats that have only
a single field for keywords, \OpenImageIO will concatenate the keywords,
separated by semicolon (`;'), so don't use semicolons within your
keywords.
\apiend

\apiitem{--clear-keywords}
Clears all existing keywords in the current image.
\apiend

\apiitem{--nosoftwareattrib}
\NEW % 1.5
When set, this prevents the normal adjustment of \qkw{Software} and
\qkw{ImageHistory} metadata to reflect what \oiiotool is doing.
\apiend

\apiitem{--sansattrib}
\NEW % 1.5
When set, this edits the command line inserted in the \qkw{Software} and
\qkw{ImageHistory} metadata to omit any verbose {\cf --attrib} and
{\cf --sattrib} commands.
\apiend

\apiitem{--orientation {\rm \emph{orient}}}
Explicitly sets the image's \qkw{Orientation} metadata to a numeric
value (see Section~\ref{metadata:orientation} for the numeric codes).
This only changes the metadata field that specifies
how the image should be displayed, it does NOT alter the pixels
themselves, and so has no effect for image formats that don't
support some kind of orientation metadata.
\apiend

\apiitem{--orientcw \\
--orientccw \\
--orient180}
Adjusts the image's \qkw{Orientation} metadata by rotating
the suggested viewing orientation $90^\circ$
clockwise, $90^\circ$ degrees counter-clockwise, or $180^\circ$,
respectively, compared to its current setting.  This only changes the
metadata field that specifies how the image should be displayed, it does
NOT alter the pixels themselves, and so has no effect for image formats
that don't support some kind of orientation metadata.

See the {\cf --rotate90}, {\cf --rotate180}, {\cf --rotate270}, and
{\cf --reorient} commands for true rotation of the pixels (not just the
metadata).
\apiend

\apiitem{--origin {\rm \emph{offset}}}
Set the pixel data window origin, essentially translating the existing
pixel data window to a different position on the image plane.
The offset is in the form
\begin{code}
     [+-]x[+-]y
\end{code}
\noindent Examples: 
\begin{code}
    --origin +20+10           x=20, y=10
    --origin +0-40            x=0, y=-40
\end{code}
\apiend

\apiitem{--fullsize {\rm \emph{size}}}
Set the display/full window size and/or offset.  The size is in the
form 
\\ \emph{width}\,{\cf x}\,\emph{height}{\cf [+-]}\emph{xoffset}{\cf
  [+-]}\emph{yoffset} \\
If either the offset or resolution is omitted, it will remain
unchanged.

\noindent Examples: 

\begin{tabular}{p{2in} p{4in}}
    {\cf --fullsize 1920x1080}  &      resolution w=1920, h=1080, offset unchanged \\
    {\cf --fullsize -20-30} &          resolution unchanged, x=-20, y=-30 \\
    {\cf --fullsize 1024x768+100+0}  & resolution w=1024, h=768, offset
    x=100, y=0
\end{tabular}

\apiend

\apiitem{--fullpixels}
Set the full/display window range to exactly cover the pixel data window.
\apiend

\apiitem{--chnames {\rm \emph{name-list}}}
Rename some or all of the channels of the top image to the given
comma-separated list.  Any completely empty channel names in the
list will not be changed.  For example,

\begin{code}
    oiiotool in.exr --chnames ",,,A,Z" -o out.exr
\end{code}

\noindent will rename channel 3 to be \qkw{A} and channel 4 to be
\qkw{Z}, but will leave channels 0--3 with their old names.
\apiend


\section{\oiiotool commands that shuffle channels or subimages}

\apiitem{--selectmip {\rm \emph{level}}}
If the current image is MIP-mapped, replace the current image with a new
image consisting of only the given \emph{level} of the MIPmap.
Level 0 is the highest resolution version, level 1 is the next-lower
resolution version, etc.
\apiend

\apiitem{--unmip}
If the current image is MIP-mapped, discard all but the top level
(i.e., replacing the current image with a new image consisting of only the
highest-resolution level).  Note that this is equivalent to 
{\cf --selectmip 0}.
\apiend

\apiitem{--subimage {\rm \emph{n}}}
If the current image has multiple subimages, replace the current image
with a new image consisting of only the given subimage.
\apiend

\apiitem{--siappend}
Replaces the top two images on the stack with a new image comprised of the
subimages of both images appended together.
\apiend

\apiitem{--ch {\rm \emph{channellist}}}
Replaces the top image with a new image whose channels have been
reordered as given by the \emph{channellist}.  The {\cf channellist}
is a comma-separated list of channel designations, each of which may be
(a) an integer channel index of the channel to copy,
(b) the name of a channel to copy,
(c) \emph{newname}{\cf =}\emph{oldname}, which copies a named channel and
also renames it,
(d) {\cf =}\emph{float}, which will set the channel to a constant value,
or
(e) \emph{newname}{\cf =}\emph{float},
which sets the channel to a constant value as well as names the new channel.
Examples include:  \qkw{R,G,B}, \qkw{R=0.0,G,B,A=1.0}, \qkw{R=B,G,B=R},
\qkw{4,5,6,A}.

Channel numbers outside the valid range of input channels, or unknown names,
will be replaced by black channels. If the \emph{channellist} is shorter
than the number of channels in the source image, unspecified channels will
be omitted.
\apiend

\apiitem{--chappend}
Replaces the top two images on the stack with a new image comprised of
the channels of both images appended together.
\apiend

\apiitem{--flatten}
\index{deep images}
If the top image is ``deep,'' then ``flatten'' it by compositing the depth
samples in each pixel.
\apiend


\section{\oiiotool commands that adjust the image stack}

\apiitem{--pop}
Pop the image stack, discarding the current image and thereby
making the next image on the stack into the new current image.
\apiend

\apiitem{--dup}
Duplicate the current image and push the duplicate on the stack.
Note that this results in both the current and the next image 
on the stack being identical copies.
\apiend

\apiitem{--swap}
Swap the current image and the next one on the stack.
\apiend

\apiitem{--label {\rm \emph{name}}}
Gives a name to (and saves) the current image at the top of the stack.
Thereafter, the label name may be used to refer to that saved image,
in the usual manner that an ordinary input image would be specified by
filename.
\apiend


\section{\oiiotool commands that make entirely new images}

\apiitem{--create {\rm \emph{size channels}}}

Create new black image with the given size and number of channels,
pushing it onto the image stack and making it the new current image.

The \emph{size} is in the form
\\ \emph{width}\,{\cf x}\,\emph{height}{\cf [+-]}\emph{xoffset}{\cf
  [+-]}\emph{yoffset} \\
If the offset is omitted, it will be $x=0,y=0$.

\noindent Examples:

\begin{tabular}{p{2in} p{4in}}
    {\cf --create 1920x1080 3}  &      RGB with w=1920, h=1080, x=0, y=0 \\
    {\cf --create 1024x768+100+0 4}  & RGBA with w=1024, h=768, x=100, y=0
\end{tabular}
\apiend


\apiitem{--pattern {\rm \emph{patternname size channels}}}
Create new image with the given size and number of channels,
initialize its pixels to the named pattern, and push it onto 
the image stack to make it the new current image.

The \emph{size} is in the form
\\ \emph{width}\,{\cf x}\,\emph{height}{\cf [+-]}\emph{xoffset}{\cf
  [+-]}\emph{yoffset} \\
If the offset is omitted, it will be $x=0,y=0$.

The patterns recognized include the following:

\begin{tabular}{p{1in} p{4in}}
    {\cf black}  & A black image (all pixels 0.0) \\
    {\cf constant}  & A constant color image, defaulting to white, but
       the color can be set with the optional {\cf :color=r,g,b,...}
       arguments giving a numerical value for each channel. \\
    {\cf checker} & A black and white checkerboard pattern.  The
       optional argument {\cf :width=} sets with width of the checkers
       (defaulting to 8 pixels).
\end{tabular}

\noindent Examples:

\apiitem{--pattern constant:color=0.3,0.5,0.1,1.0 640x480 4}
\vspace{10pt}
A constant 4-channel, $640\times 480$ image with all pixels (0.5, 0.5,
0.1, 1).
\apiend

\apiitem{--pattern checker:width=16 512x512 3}
\vspace{10pt}
An $512 \times 512$ RGB image with a 16-pixel-wide checker pattern.
\apiend

\apiend


\apiitem{--kernel {\rm \emph{name size}}}
Create new 1-channel {\cf float} image big enough to hold the named
kernel and size (size is expressed as \emph{width}{\cf x}\emph{height},
e.g. {\cf 5x5}).  The \emph{width} and \emph{height} are allowed to be
floating-point numbers. The kernel image will have its origin offset so
that the kernel center is at (0,0), and and will be normalized (the sum
of all pixel values will be 1.0).

Kernel names can be: {\cf gaussian}, {\cf sharp-gaussian}, {\cf box},
{\cf triangle}, {\cf blackman-harris}, {\cf mitchell}, {\cf b-spline},
\qkw{cubic}, \qkw{keys}, \qkw{simon}, \qkw{rifman}, {\cf disk}.
There are also {\cf catmull-rom} and {\cf lanczos3}, but
they are fixed-size kernels that don't scale with the width, and are
therefore probably less useful in most cases.

\noindent Examples:

\begin{code}
    oiiotool --kernel gaussian 11x11 -o gaussian.exr
\end{code}
\apiend



\apiitem{--capture}

Capture a frame from a camera device, pushing it onto the image stack
and making it the new current image.  Optional appended arguments
include:

\begin{tabular}{p{10pt} p{1in} p{3.5in}}
  & {\cf camera=}\emph{num} & Select which camera number to capture
  (default: 0).
\end{tabular}

\noindent Examples:

\begin{tabular}{p{2in} p{4in}}
    {\cf --capture}  &      Capture from the default camera. \\
    {\cf --capture:camera=1}  & Capture from camera 2. \\
\end{tabular}
\apiend


\section{\oiiotool commands that do image processing}

\apiitem{--add}
Replace the \emph{two} top images with a new image that is the sum of
those images.
\apiend

\apiitem{--sub}
Replace the \emph{two} top images with a new image that is the difference
between the first and second images.
\apiend

\apiitem{--mul}
Replace the \emph{two} top images with a new image that the
pixel-by-pixel, channel-by-channel multiplicative product of
the first and second images.
\apiend

\apiitem{--abs}
Replace the current image with a new image that has each pixel
consisting of the \emph{absolute value} of he old pixel value.
\apiend

\apiitem{--cadd {\rm \emph{value}} \\
--cadd {\rm \emph{value0,value1,value2...}}}
Add a constant value to all the pixels in the current image.  If a
single constant value is given, it will be added to all color channels.
Alternatively, a series of comma-separated constant values (with no
spaces!) may be used to specifiy a different value to add to each
channel in the image, respectively.

\noindent Example:
\begin{code}
    oiiotool tahoe.jpg --cadd 0.5 -o cadd.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/tahoe-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/cadd.jpg} \\
\apiend

\apiitem{--cmul {\rm \emph{value}} \\
--cmul {\rm \emph{value0,value1,value2...}}}
Multiply all the pixel values in the top image by a constant value.
If a single constant value is given, all color channels will have their values
multiplied by the same value.  Alternatively, a series of
comma-separated constant values (with no spaces!) may be used to specifiy a
different multiplier for each channel in the image, respectively.

\noindent Example:
\begin{code}
    oiiotool tahoe.jpg --cmul 0.2 -o cmul.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/tahoe-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/cmul.jpg} \\
\apiend

\apiitem{--cpow {\rm \emph{value}} \\
--cpow {\rm \emph{value0,value1,value2...}}}
Raise all the pixel values in the top image to a constant power value.
If a single constant value is given, all color channels will have their values
raised to this power.  Alternatively, a series of
comma-separated constant values (with no spaces!) may be used to specifiy a
different exponent for each channel in the image, respectively.
\apiend

\apiitem{--chsum}
Replaces the top image by a copy that contains only 1 color channel,
whose value at each pixel is the sum of all channels of the original
image.  Using the optional {\cf weight} allows you to customize the
weight of each channel in the sum.

\begin{tabular}{p{10pt} p{1in} p{3.5in}}
  & {\cf weight=}\emph{r,g,...} & Specify the weight of each channel
  (default: 1).
\end{tabular}

\noindent Example:
\begin{code}
    oiiotool RGB.tif --chsum:weight=.2126,.7152,.0722 -o luma.tif
\end{code}
\spc \includegraphics[width=1.25in]{figures/tahoe-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/luma.jpg} \\
\apiend

\apiitem{--paste {\rm \emph{location}}}
Takes two images -- the first is the ``foreground'' and the second is
the ``background'' -- and uses the pixels of the foreground to replace
those of the backgroud beginning at the upper left \emph{location}
(expressed as {\cf +}\emph{xpos}{\cf +}\emph{ypos}, e.g., {\cf +100+50},
or of course using {\cf -} for negative offsets).
\apiend

\apiitem{--mosaic {\rm \emph{size}}}
Removes \emph{w}{\cf x}\emph{h} images, dictated by the
\emph{size}, and turns them into a single image mosaic.
Optional appended arguments
include:

\begin{tabular}{p{10pt} p{1in} p{3.5in}}
  & {\cf pad=}\emph{num} & Select the number of pixels of black padding
    to add between images (default: 0).
\end{tabular}

\noindent Examples:
\begin{code}
    oiiotool left.tif right.tif --mosaic:pad=16 2x1 -o out.tif

    oiiotool 0.tif 1.tif 2.tif 3.tif 4.tif --mosaic:pad=16 2x2 -o out.tif
\end{code}
\apiend

\apiitem{--over}
\index{composite}
Replace the \emph{two} top images with a new image that is the
Porter/Duff ``over'' composite with the first image as the foreground
and the second image as the background.
Both input images must have the same number and order of channels
and must contain an alpha channel.
\apiend

\apiitem{--zover}
\index{depth composite}
Replace the \emph{two} top images with a new image that is a \emph{depth
composite} of the two images -- the operation is the 
Porter/Duff ``over'' composite, but each pixel individually will choose
which of the two images is the foreground and which background, depending on
the ``Z'' channel values for that pixel (larger Z means farther away).
Both input images must have the same number and order of channels
and must contain both depth/Z and alpha channels. Optional appended arguments
include:

\begin{tabular}{p{10pt} p{1in} p{3.5in}}
  & {\cf zeroisinf=}\emph{num} & If nonzero, indicates that $z=0$ pixels
  should be treated as if they were infinitely far away. (The default is
  0, meaning that ``zero means zero.'').
\end{tabular}

\apiend

\apiitem{--rotate90}
\NEW % 1.5
Replace the current image with a new image that is rotated 90 degrees
clockwise.

\noindent Example:
\begin{code}
    oiiotool grid.jpg --rotate90 -o rotate90.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg}
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/rotate90.jpg} \\
\apiend

\apiitem{--rotate180}
\NEW % 1.5
Replace the current image with a new image that is rotated by
180 degrees.

\noindent Example:
\begin{code}
    oiiotool grid.jpg --rotate180 -o rotate180.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/rotate180.jpg} \\
\apiend

\apiitem{--rotate270}
\NEW % 1.5
Replace the current image with a new image that is rotated 270 degrees
clockwise (or 90 degrees counter-clockwise).

\noindent Example:
\begin{code}
    oiiotool grid.jpg --rotate270 -o rotate270.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg}
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/rotate270.jpg} \\
\apiend

\apiitem{--flip}
Replace the current image with a new image that is flipped vertically,
with the top scanline becoming the bottom, and vice versa.

\noindent Example:
\begin{code}
    oiiotool grid.jpg --flip -o flip.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/flip.jpg} \\
\apiend

\apiitem{--flop}
Replace the current image with a new image that is flopped horizontally,
with the leftmost column becoming the rightmost, and vice versa.

\noindent Example:
\begin{code}
    oiiotool grid.jpg --flop -o flop.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/flop.jpg} \\
\apiend

\apiitem{--reorient}
\NEW % 1.5
Replace the current image with a new image that is rotated and/or flipped
as necessary to move the pixels to match the Orientation metadata
that describes the desired display orientation.

\noindent Example:
\begin{code}
    oiiotool tahoe.jpg --reorient -o oriented.jpg
\end{code}
%\spc \includegraphics[width=1.25in]{figures/grid-small.jpg} 
%~ {\Huge $\rightarrow$} ~
%\includegraphics[width=1.25in]{figures/flop.jpg} \\
\apiend

\apiitem{--transpose}
Replace the current image with a new image that is trasposed about
the $xy$ axis (x and coordinates and size are flipped).

\noindent Example:
\begin{code}
    oiiotool grid.jpg --transpose -o transpose.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/transpose.jpg} \\
\apiend

\apiitem{--cshift {\rm \emph{offset}}}
Circularly shift the pixels of the image by the given offset (expressed
as {\cf +10+100} to move by 10 pixels horizontally and 100 pixels
vertically, or {\cf +50-30} to move by 50 pixels horizontally and
$-30$ pixels vertically.  \emph{Circular} shifting means that the
pixels wrap to the other side as they shift.

\noindent Example:
\begin{code}
    oiiotool grid.jpg --cshift +70+30 -o cshift.jpg
\end{code}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/cshift.jpg} \\
\apiend

\apiitem{--crop {\rm \emph{size}}}
Replace the current image with a new copy with the given \emph{size},
cropping old pixels no longer needed, padding black pixels where they
previously did not exist in the old image, and adjusting the offsets
if requested.

The size is in the form 
\\ \spc\spc \emph{width}\,{\cf x}\,\emph{height}{\cf [+-]}\emph{xoffset}{\cf
  [+-]}\emph{yoffset}
\\ or~~~~ \spc \emph{xmin,ymin,xmax,ymax} \\

\noindent Examples: 

\begin{tabular}{p{2in} p{4in}}
    {\cf --crop 100x120+35+40}  &      resolution w=100, h=120, offset x=35, y=40 \\
    {\cf --crop 35,40,134,159}  &      resolution w=100, h=120, offset x=35, y=40
\end{tabular}

Note that {\cf crop} does not \emph{reposition} pixels, it only trims or
pads to reset the image's pixel data window to the specified region.
\apiend

\apiitem{--croptofull}
Replace the current image with a new image that is cropped or padded
as necessary to make the pixel data window exactly cover
the full/display window.
\apiend

\apiitem{--cut {\rm \emph{size}}}
Replace the current image with a new copy with the given \emph{size},
cropping old pixels no longer needed, padding black pixels where they
previously did not exist in the old image, repositioning the cut region
at the image origin (0,0) and resetting the full/display window to be
identical to the new pixel data window.  (In other words, {\cf --cut}
is equavalent to {\cf --crop} followed by {\cf --origin +0+0 --fullpixels}.)

The size is in the form 
\\ \spc\spc \emph{width}\,{\cf x}\,\emph{height}{\cf [+-]}\emph{xoffset}{\cf
  [+-]}\emph{yoffset}
\\ or~~~~ \spc \emph{xmin,ymin,xmax,ymax} \\

\noindent Examples: 

\begin{tabular}{p{2in} p{4in}}
    {\cf --cut 100x120+35+40}  &      resolution w=100, h=120, offset x=35, y=40 \\
    {\cf --cut 35,40,134,159}  &      resolution w=100, h=120, offset x=35, y=40
\end{tabular}
\apiend

\apiitem{--resample {\rm \emph{size}}}
Replace the current image with a new image that is resampled to the
given pixel data resolution rapidly, but at a low quality, by simply
copying the ``closest'' pixel.  The \emph{size} is in the form 
\\ \spc\spc \emph{width}\,{\cf x}\,\emph{height}
\\ or~~~~ \spc \emph{scale}{\verb|%|} \\
\\ or~~~~ \spc \emph{wscale}{\verb|%|}\,{\cf x}\,\emph{hscale}{\verb|%|} \\

\noindent if {\cf width} or {\cf height} is 0, that dimension will be
automatically computed so as to preserve the original aspect ratio.

\noindent Examples (suppose that the original image is 640x480):

\begin{tabular}{p{2in} p{4in}}
    {\cf --resample 1024x768}  &     new resolution w=1024, h=768 \\
    {\cf --resample 50{\verb|%|}}  & reduce resolution to 320x240 \\
    {\cf --resample 300{\verb|%|}}  & increase resolution to 1920x1440 \\
    {\cf --resample 400x0}  &     new resolution will be 400x300
\end{tabular}

\apiend

\apiitem{--resize {\rm \emph{size}}}
Replace the current image with a new image that is resized to the 
given pixel data resolution.  The \emph{size} is in the form 
\\ \spc\spc \emph{width}\,{\cf x}\,\emph{height}
\\ or~~~~ \spc \emph{scale}{\verb|%|} \\
\\ or~~~~ \spc \emph{wscale}{\verb|%|}\,{\cf x}\,\emph{hscale}{\verb|%|} \\

\noindent if {\cf width} or {\cf height} is 0, that dimension will be
automatically computed so as to preserve the original aspect ratio.

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf filter=}\emph{name} & Filter name. The default is {\cf
  blackman-harris} when increasing resolution, {\cf lanczos3} when
decreasing resolution. \\
\end{tabular}

\noindent Examples (suppose that the original image is 640x480):

\begin{tabular}{p{2in} p{4in}}
    {\cf --resize 1024x768}  &     new resolution w=1024, h=768 \\
    {\cf --resize 50{\verb|%|}}  & reduce resolution to 320x240 \\
    {\cf --resize 300{\verb|%|}}  & increase resolution to 1920x1440 \\
    {\cf --resize 400x0}  &     new resolution will be 400x300
\end{tabular}

\apiend

\apiitem{--fit {\rm \emph{size}}}
Replace the current image with a new image that is resized to fit
into the given pixel data resolution, keeping the original aspect ratio
and padding with black pixels if the requested image size does not
have the same aspect ratio.  The \emph{size} is in the form 
\\ \spc\spc \emph{width}\,{\cf x}\,\emph{height}
\\ or~~~~ \spc \emph{width}\,{\cf x}\,\emph{height}{\cf [+-]}\emph{xorigin}{\cf [+-]}\emph{yorigin} \\

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf filter=}\emph{name} & Filter name. The default is {\cf
  blackman-harris} when increasing resolution, {\cf lanczos3} when
decreasing resolution. \\
 & {\cf pad=}\emph{p} & If the argument is nonzero, will pad with
  black pixels to make the resulting image exactly the size specified, if
  the source and desired size are not the same aspect ratio.
\end{tabular}

\noindent Examples:

\begin{code}
    oiiotool in.exr --fit:pad=1 640x480 -o out.exr

    oiiotool in.exr --fit 1024x1024 -o out.exr
\end{code}
\apiend

\apiitem{--rotate {\rm \emph{angle}}}
\NEW % 1.5
Replace the current image with a new image that is rotated by the given
angle (in degrees). Positive angles mean to rotate counter-clockwise,
negative angles mean clockwise. By default, the center of rotation is at the
exact center of the display window (a.k.a.\ ``full'' image), but can be
explicitly set with the optional {\cf center=\emph{x,y}} option.

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1.25in} p{3.5in}}
 & {\cf center=}\emph{x,y} & Alternate center of rotation. \\
 & {\cf filter=}\emph{name} & Filter name. The default is \qkw{lanczos3}. \\
 & {\small \cf recompute_roi=}\emph{val} & If nonzero, recompute the pixel data
     window to exactly hold the transformed image (default=0). \\
\end{tabular}

\noindent Examples:

\begin{tinycode}
  oiiotool mandrill.tif --rotate 45 -o rotated.tif

  oiiotool mandrill.tif --rotate:center=80,91.5:filter=lanczos3 45 -o rotated.tif
\end{tinycode}
\spc \includegraphics[width=1.25in]{figures/grid-small.jpg} 
~ {\Huge $\rightarrow$} ~
\includegraphics[width=1.25in]{figures/rotate45.jpg} \\
\apiend


\apiitem{--warp {\rm \emph{M33}}}
\NEW % 1.5
Replace the current image with a new image that is warped by the given
$3 \times 3$ matrix (presented as a comma-separated list of values, without
any spaces).

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1.25in} p{3.5in}}
 & {\cf filter=}\emph{name} & Filter name. The default is \qkw{lanczos3}. \\
 & {\small\cf recompute_roi=}\emph{val} & If nonzero, recompute the pixel data
     window to exactly hold the transformed image (default=0). \\
\end{tabular}

\noindent Examples:

\begin{tinycode}
  oiiotool mandrill.tif --warp "0.707,0.707,0,-0.707,0.707,0,128,-53.02,1" -o warped.tif
\end{tinycode}
\apiend


\apiitem{--convolve}
Use the top image as a kernel to convolve the next image farther down
the stack, replacing both with the result.

\noindent Examples:
\begin{code}
    # Use a kernel image already prepared
    oiiotool image.exr kernel.exr --convolve -o output.exr

    # Construct a kernel image on the fly with --kernel
    oiiotool image.exr --kernel gaussian 5x5 --convolve -o blurred.exr
\end{code}
\apiend

\apiitem{--blur {\rm \emph{size}}}
Blur the top image with a blur kernel of the given size expressed as
\emph{width}{\cf x}\emph{height}.  (The sizes may be floating point 
numbers.)

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf kernel=}\emph{name} & Kernel name. The default is {\cf
  gaussian}.
\end{tabular}

\noindent Examples:
\begin{code}
    oiiotool image.jpg --blur 5x5 -o blurred.jpg

    oiiotool image.jpg --blur:kernel=bspline 7x7 -o blurred.jpg
\end{code}
\apiend


\apiitem{--median {\rm \emph{size}}}

\NEW % 1.5
Perform a median filter on the top image with a window of the given size
expressed as \emph{width}{\cf x}\emph{height}.  (The sizes are integers.)
This helps to eliminate noise and other unwanted high-frequency detail, but
without blurring long edges the way a {\cf --blur} command would.
\noindent Examples:
\begin{code}
    oiiotool noisy.jpg --median 5x5 -o smoothed.jpg
\end{code}
% FIXME - should have a visual example
\apiend


\apiitem{--unsharp}
Unblur the top image using an ``unsharp mask.'' 

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf kernel=}\emph{name} & Name of the blur kernel (default: {\cf
    gaussian}). If the kernel name is {\cf median}, the unsarp mask
    algorithm will use a median filter rather than a blurring filter
    in order to compute the low-frequency image. \\
 & {\cf width=}\emph{w} & Width of the blur kernel (default: 3). \\
 & {\cf contrast=}\emph{c} & Contrast scale (default: 1.0) \\
 & {\cf threshold=}\emph{t} & Threshold for applying the difference
  (default: 0)
\end{tabular}

\noindent Examples:
\begin{code}
    oiiotool image.jpg --unsharp -o sharper.jpg

    oiiotool image.jpg --unsharp:width=5:contrast=1.5 -o sharper.jpg

    oiiotool image.jpg --unsharp:kernel=median -o sharper.jpg
    # Note: median filter helps emphasize compact high-frequency details
    # without over-sharpening long edges as the default unsharp filter
    # sometimes does.
\end{code}
% FIXME - should have a visual example
\apiend


\apiitem{--fft \\
--ifft}
Performs forward and inverse unitized discrete Fourier transform.
The forward FFT always transforms only the first channel of the
top image on the stack, and results in a 2-channel image (with real and
imaginary channels).  The inverse FFT transforms the first two
channels of the top image on the stack (assuming they are real and
imaginary, respectively) and results in a single channel result (with
the real component only of the spatial domain result).

\noindent Examples:
\begin{code}
    # Select the blue channel and take its DCT
    oiiotool image.jpg --ch 2 --fft -o fft.exr

    # Reconstruct from the FFT
    oiiotool fft.exr --ifft -o reconstructed.exr

    # Output the power spectrum: real^2 + imag^2
    oiiotool fft.exr --dup --mul --chsum -o powerspectrum.exr
\end{code}
\apiend


\apiitem{--polar \\
--unpolar}
The {\cf --polar} transforms a 2-channel image whose channels are
interpreted as complex values (real and imaginary components) into the
equivalent values expressed in polar form of amplitude and phase (with phase
between $0$ and $2\pi$).

The {\cf unpolar} performs the reverse transformation, converting from 
polar values (amplitude and phase) to complex (real and imaginary).

\noindent Examples:
\begin{code}
    oiiotool complex.exr --polar -o polar.exr
    oiiotool polar.exr --unpolar -o complex.exr
\end{code}
\apiend


\apiitem{--fixnan {\rm \emph{streategy}}}
Replace the top image with a copy in which any pixels that contained
{\cf NaN} or {\cf Inf} values (hereafter referred to collectively as
``nonfinite'') are repaired.  If \emph{strategy} is {\cf black},
nonfinite values will be replaced with {\cf 0}.  If \emph{strategy} is
{\cf box3}, nonfinite values will be replaced by the average of all the
finite values within a $3 \times 3$ region surrounding the pixel.
\apiend

\apiitem{--clamp}
Replace the top image with a copy in which pixel values have been
clamped.  Optional arguments include:

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf min=}\emph{val} & Specify a minimum value for all channels. \\
 & {\cf min=}\emph{val0,val1,...} & Specify minimum value for each 
                                    channel individually. \\
 & {\cf max=}\emph{val} & Specify a maximum value for all channels. \\
 & {\cf max=}\emph{val0,val1,...} & Specify maximum value for each 
                                    channel individually. \\
 & {\cf clampalpha=}\emph{val} & If \emph{val} is nonzero, will 
                                    additionally clamp the alpha channel
                                    to [0,1].  (Default: 0, no
                                    additional alpha clamp.)
\end{tabular}

If no value is given for either the minimum or maximum, it will NOT
clamp in that direction.  For the variety of minimum and maximum that
specify per-channel values, a missing value indicates that the
corresponding channel should not be clamped.  

\noindent Examples: 

\begin{tabular}{p{2in} p{4in}}
    {\cf --clamp:min=0} & Clamp all channels to a mimimum of 0 (all \\
                        &  negative values are changed to 0). \\
    {\cf --clamp:min=0:max=1} & Clamp all channels to [0,1]. \\
    {\cf --clamp:clampalpha=1} & Clamp the designated alpha channel to [0,1]. \\
    {\cf --clamp:min=,,0:max=,,3.0} & Clamp the third channel to [0,3],
                                      do not clamp \\ & other channels.
\end{tabular}

\apiend

\apiitem{--rangecompress \\
--rangeexpand}
Range compression re-maps input values to a logarithmic scale.
Range expansion is the inverse mapping back to a linear scale.
Range compression and expansion only applies to color
channels; alpha or z channels will not be modified.

By default, this transformation will happen to each color channel 
independently.  But if the optional {\cf luma} argument is nonzero and
the image has at least 3 channels and the first three channels are
not alpha or depth, they will be assumed to be RGB and the pixel scaling
will be done using the luminance and applied equally to all color
channels. This can help to preserve color even when remapping intensity.

Optional appended arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf luma=}\emph{val} & If \emph{val} is 0, turns off the luma behavior.
\end{tabular}

Range compression and expansion can be useful in cases where high
contrast super-white ($> 1$) pixels (such as very bright highlights in
HDR captured or rendered images) can produce undesirable artifacts, such
as if you resize an HDR image using a filter with negative lobes --
which could result in objectionable ringing or even negative result
pixel values.  For example,

\begin{smallcode}
    oiiotool hdr.exr --rangecompress --resize 512x512 --rangeexpand -o resized.exr
\end{smallcode}
\apiend

\apiitem{--fillholes}
Replace the top image with a copy in which any pixels that had
$\alpha < 1$ are ``filled'' in a smooth way using data from
surrounding $\alpha > 0$ pixels, resulting in an image that is
$\alpha = 1$ and plausible color everywhere.
This can be used both to fill internal ``holes'' as well as to extend an
image out.
\apiend


\apiitem{--text {\rm \emph{words}}}
Draw (rasterize) text overtop of the current image.

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf x=}\emph{xpos} & $x$ position (in pixel coordinates) of the text \\
 & {\cf y=}\emph{ypos} & $y$ position (in pixel coordinates) of the text  \\
 & {\cf size=}\emph{size} & font size (height, in pixels) \\
 & {\cf font=}\emph{name} & font name, full path to the font file on
  disk (use double quotes {\cf "name"} if the path name includes spaces) \\
 & {\cf color=}\emph{r,g,b,...} & specify the color of the text \\
\end{tabular}

The default positions the text starting at the center of the image,
drawn 16 pixels high in opaque white in all channels (1,1,1,...), and
using a default font (which may be system dependent).

\noindent Examples: 

\begin{smallcode}
    oiiotool in.exr --text:x=10:y=400:size=40 "Hello world" \
        --text:x=100:y=200:font="Arial Bold":color=1,0,0:size=60 "Go Big Red!" \
        --tocolorspace sRGB -o text.jpg
\end{smallcode}
\spc \includegraphics[width=2.5in]{figures/text.jpg}  \\

\noindent Note that because of slightly differing fonts and versions of
Freetype available, we do not expect drawn text to be pixel-for-pixel 
identical on different platforms supported by \product.
\apiend



\section{\oiiotool commands for color management}

\apiitem{--iscolorspace {\rm \emph{colorspace}}}
Alter the metadata of the current image so that it thinks its pixels
are in the named color space.  This does not alter the pixels of the
image, it only changes \oiiotool's understanding of what color
space those those pixels are in.
\apiend

\apiitem{--colorconvert {\rm \emph{fromspace tospace}}}
Replace the current image with a new image whose pixels are transformed
from the named \emph{fromspace} color space into the named
\emph{tospace} (disregarding any notion it may have previously had 
about the color space of the current image).  

If OIIO has been compiled with OpenColorIO support and the environment
variable {\cf \$OCIO} is set to point to a valid OpenColorIO
configuration file, you will have access to all the color spaces that
are known by that OCIO configuration.  If {\cf \$OCIO} does not point to
a valid configuration file or OIIO was not compiled with OCIO support,
then the only color space transformats available are {\cf linear} to
{\cf Rec709} (and vice versa) and {\cf linear} to {\cf sRGB} (and vice
versa).

If you ask for \oiiotool help ({\cf oiiotool --help}), at the very
bottom you will see the list of all color spaces that \oiiotool knows
about.
\apiend

\apiitem{--tocolorspace {\rm \emph{tospace}}}
Replace the current image with a new image whose pixels are transformed
from their existing color space (as best understood or guessed by OIIO)
into the named \emph{tospace}.  This is equivalent to a use of
{\cf oiiotool --colorconvert} where the \emph{fromspace} is
automatically deduced.
\apiend

\apiitem{--ociolook {\rm \emph{lookname}}}
Replace the current image with a new image whose pixels are transformed
using the named OpenColorIO look description.  Optional appended
arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf from=}\emph{val} & Assume the image is in the named color
  space. If no {\cf from=} is supplied, it will try to deduce it
  from the image's metadata or previous {\cf --iscolorspace}
  directives. \\
 & {\cf to=}\emph{val} & Convert to the named space after applying
  the look. \\
 & {\cf inverse=}\emph{val} & If \emph{val} is nonzero, inverts the 
  color transformation and look application. \\
 & {\cf key=}\emph{name} & \\
 & {\cf value=}\emph{str} & Adds a key/value pair to the ``context'' that
  OpenColorIO will used when applying the look. \\
\end{tabular}

This command is only meaningful if OIIO was compiled with OCIO support
and the environment variable {\cf \$OCIO} is set to point to a valid
OpenColorIO configuration file.  If you ask for \oiiotool help 
({\cf oiiotool --help}), at the very bottom you will see the list of all
looks that \oiiotool knows about.

\noindent Examples:
\begin{tinycode}
  oiiotool in.jpg --ociolook:from=vd8:to=vd8:key=SHOT:value=pe0012 match -o cc.jpg
\end{tinycode}

\apiend

\apiitem{--ociodisplay {\rm \emph{displayname viewname}}}
Replace the current image with a new image whose pixels are transformed
using the named OpenColorIO ``display'' transformation given by the
\emph{displayname} and \emph{viewname}.  Optional appended
arguments include:

\begin{tabular}{p{10pt} p{1in} p{3.75in}}
 & {\cf from=}\emph{val} & Assume the image is in the named color
  space. If no {\cf from=} is supplied, it will try to deduce it
  from the image's metadata or previous {\cf --iscolorspace}
  directives. \\
 & {\cf key=}\emph{name} & \\
 & {\cf value=}\emph{str} & Adds a key/value pair to the ``context'' that
  OpenColorIO will used when applying the look. \\
\end{tabular}

This command is only meaningful if OIIO was compiled with OCIO support
and the environment variable {\cf \$OCIO} is set to point to a valid
OpenColorIO configuration file.  If you ask for \oiiotool help 
({\cf oiiotool --help}), at the very bottom you will see the list of all
looks that \oiiotool knows about.

\noindent Examples:
\begin{tinycode}
  oiiotool in.exr --ociodisplay:from=lnf:key=SHOT:value=pe0012 sRGB Film -o cc.jpg
\end{tinycode}

\apiend

\apiitem{--unpremult}
Divide all color channels (those not alpha or z) of the current image by
the alpha value, to ``un-premultiply'' them.  This presumes that the
image starts of as ``associated alpha,'' a.k.a.\ ``premultipled.''
Pixels in which the alpha channel is 0 will not be modified (since the
operation is undefined in that case).  This is a no-op if there is no
identified alpha channel.
\apiend

\apiitem{--premult}
Multiply all color channels (those not alpha or z) of the current image
by the alpha value, to ``premultiply'' them.  This presumes that the
image starts of as ``unassociated alpha,'' a.k.a.\ ``non-premultipled.''
\apiend


