\chapter{Bundled ImageIO Plugins}
\label{chap:bundledplugins}
\index{Plugins!bundled|(}

This chapter lists all the image format plugins that are bundled with
\product.  For each plugin, we delineate any limitations, custom
attributes, etc.  The plugins are listed alphabetically by format name.


\vspace{.25in}

\section{BMP}
\label{sec:bundledplugins:bmp}
\index{BMP}

BMP is a bitmap image file format used mostly on Windows systems.
BMP files use the file extension {\cf .bmp}.

BMP is not a nice format for high-quality or high-performance images.
It only supports unsigned integer 1-, 2-, 4-, and 8- bits per channel; only
grayscale, RGB, and RGBA; does not support MIPmaps, multiimage, or
tiles.

%\subsubsection*{Attributes}
\vspace{.125in}
\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.25in}}
\ImageSpec Attribute & Type & BMP header data or explanation \\
\hline
\qkw{XResolution} & float & hres \\
\qkw{YResolution} & float & vres \\
\qkw{ResolutionUnit} & string & always \qkw{m} (pixels per meter)
\end{tabular}



\vspace{.25in}

\section{Cineon}
\label{sec:bundledplugins:cineon}
\index{Cineon}

Cineon is an image file format developed by Kodak that is commonly
used for scanned motion picture film and digital intermediates.
Cineon files use the file extension {\cf .cin}.

%FIXME

\vspace{.25in}



\section{DDS}
\label{sec:bundledplugins:dds}
\index{DDS}

DDS (Direct Draw Surface) is an image file format designed by Microsoft
for use in Direct3D graphics.  DDS files use the extension {\cf .dds}.

DDS is an awful format, with several compression modes that are all so
lossy as to be completely useless for high-end graphics.  Nevertheless,
they are widely used in games and graphics hardware directly supports
these compression modes.  Alas.

\product currently only supports reading DDS files, not writing them.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.5in}}
\ImageSpec Attribute & Type & DDS header data or explanation \\
\hline
\qkw{compression} & string & compression type \\
\qkw{oiio:BitsPerSample} & int & bits per sample \\
\qkw{textureformat} & string & Set correctly to one of \qkws{Plain
  Texture}, \qkws{Volume Texture}, or \qkws{CubeFace Environment}. \\
\qkw{texturetype} & string & Set correctly to one of \qkws{Plain
  Texture}, \qkws{Volume Texture}, or \qkws{Environment}. \\
\qkw{dds:CubeMapSides} & string & For environment maps, which cube
  faces are present (e.g., \qkw{+x -x +y -y} if $x$ \& $y$ faces are
  present, but not $z$). \\
\end{tabular}

%\subsubsection*{Limitations}
%\begin{itemize}
%\item blah
%\end{itemize}


\vspace{.25in}

\section{DPX}
\label{sec:bundledplugins:dpx}
\index{DPX}


DPX (Digital Picture Exchange) is an image file format used for 
motion picture film scanning, output, and digital intermediates.
DPX files use the file extension {\cf .dpx}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.8in}|p{0.65in}|p{2.75in}}
OIIO Attribute & Type & DPX header data or explanation \\
\hline
\qkw{ImageDescription} & string & Description of image element \\
\qkw{Copyright} & string & Copyright statement \\
\qkw{Software} & string & Creator \\
\qkw{DocumentName} & string & Project name \\
\qkw{DateTime} & string & Creation date/time \\
\qkw{Orientation} & int & the orientation of the DPX image data (see
  \ref{metadata:orientation}) \\
\qkw{compression} & string & The compression type \\
\qkw{PixelAspectRatio} & float & pixel aspect ratio \\
\qkw{oiio:BitsPerSample} & int & the true bits per sample of the DPX file. \\
\qkw{oiio:Endian} & string & When writing, force a particular endianness
                             for the output file (\qkw{little} or \qkw{big}) \\
\qkw{smpte:TimeCode} & int[2] & SMPTE time code (vecsemantics will be
                                marked as TIMECODE) \\
\qkw{smpte:KeyCode} & int[7] & SMPTE key code (vecsemantics will be
                                marked as KEYCODE) \\

\end{tabular} 

\noindent\begin{tabular}{p{1.8in}|p{0.65in}|p{2.75in}}
OIIO Attribute & Type & DPX header data or explanation \\
\hline
\qkw{dpx:Transfer} & string & Transfer characteristic \\
\qkw{dpx:Colorimetric} & string & Colorimetric specification \\
\qkw{dpx:ImageDescriptor} & string & ImageDescriptor \\
\qkw{dpx:Packing} & string & Image packing method \\
\qkw{dpx:TimeCode} & int & SMPTE time code \\
\qkw{dpx:UserBits} & int & SMPTE user bits \\
\qkw{dpx:SourceDateTime} & string & source time and date \\
\qkw{dpx:FilmEdgeCode} & string & FilmEdgeCode \\
\qkw{dpx:Signal} & string & Signal (\qkw{Undefined}, \qkw{NTSC},
  \qkw{PAL}, etc.) \\
\qkw{dpx:UserData} & UCHAR[*] & User data (stored in an array
  whose length is whatever it was in the DPX file) \\
\qkw{dpx:EncryptKey} & int & Encryption key (-1 is not encrypted) \\
\qkw{dpx:DittoKey} & int & Ditto (0 = same as previous frame, 1 =
  new) \\
\qkw{dpx:LowData} & int & reference low data code value \\
\qkw{dpx:LowQuantity} & float & reference low quantity \\
\qkw{dpx:HighData} & int & reference high data code value \\
\qkw{dpx:HighQuantity} & float & reference high quantity \\
\qkw{dpx:XScannedSize} & float & X scanned size \\
\qkw{dpx:YScannedSize} & float & Y scanned size \\
\qkw{dpx:FramePosition} & int & frame position in sequence \\
\qkw{dpx:SequenceLength} & int & sequence length (frames) \\
\qkw{dpx:HeldCount} & int & held count (1 = default) \\
\qkw{dpx:FrameRate} & float & frame rate of original (frames/s) \\
\qkw{dpx:ShutterAngle} & float & shutter angle of camera (deg) \\
\qkw{dpx:Version} & string & version of header format \\
\qkw{dpx:Format} & string & format (e.g., \qkw{Academy}) \\
\qkw{dpx:FrameId} & string & frame identification \\
\qkw{dpx:SlateInfo} & string & slate information \\
\qkws{dpx:SourceImageFileName} & string & source image filename \\
\qkw{dpx:InputDevice} & string & input device name \\
\qkwf{dpx:InputDeviceSerialNumber} & string & input device serial number \\
\qkw{dpx:Interlace} & int & interlace (0 = noninterlace, 1 = 2:1 interlace)\\
\qkw{dpx:FieldNumber} & int & field number \\
\qkws{dpx:HorizontalSampleRate} & float & horizontal sampling rate (Hz) \\
\qkws{dpx:VerticalSampleRate} & float & vertical sampling rate (Hz) \\
\qkws{dpx:TemporalFrameRate} & float & temporal sampling rate (Hz) \\
\qkw{dpx:TimeOffset} & float & time offset from sync to first
pixel (ms) \\
\qkw{dpx:BlackLevel} & float & black level code value \\
\qkw{dpx:BlackGain} & float & black gain \\
\qkw{dpx:BreakPoint} & float & breakpoint \\
\qkw{dpx:WhiteLevel} & float & reference white level code value \\
\qkw{dpx:IntegrationTimes} & float & integration time (s) \\
\qkw{dpx:EndOfLinePadding} & int & Padded bytes at the end of each line \\
\qkw{dpx:EndOfImagePadding} & int & Padded bytes at the end of each image \\
\end{tabular}

%\subsubsection*{Limitations}
%\begin{itemize}
%\item blah
%\end{itemize}


\vspace{.25in}

\section{Field3D}
\label{sec:bundledplugins:field3d}
\index{Field3D}

Field3d is an open-source volume data file format.  Field3d files
commonly use the extension {\cf .f3d}.
The official Field3D site is:
\url{http://sites.google.com/site/field3d/}
Currently, \product only reads Field3d files, and does not write them.

Fields are comprised of multiple \emph{layers} (which appear to \product
as subimages).  Each layer/subimage may have a different name,
resolution, and coordinate mapping.  Layers may be scalar (1 channel) or
vector (3 channel) fields, and the data may be {\cf half}, {\cf float},
or {\cf double}.

\product always reports Field3D files as tiled.  If the Field3d file has
a ``block size'', the block size will be reported as the tile size.
Otherwise, the tile size will be the size of the entire volume.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.6in}|p{0.6in}|p{3.0in}}
\ImageSpec Attribute & Type & Field3d header data or explanation \\
\hline
\qkw{ImageDescription} & string & unique layer name \\
\qkw{oiio:subimagename} & string & unique layer name \\
\qkw{field3d:partition} & string & the partition name \\
\qkw{field3d:layer} & string & the layer (a.k.a.\ attribute) name \\
\qkw{field3d:fieldtype} & string & field type, one of:
   \qkw{dense}, \qkw{sparse}, or \qkw{MAC} \\
\qkw{field3d:mapping} & string & the coordinate mapping type \\
\qkws{field3d:localtoworld} & matrix of doubles & if a
  matrixMapping, the local-to-world transformation matrix \\
\qkw{worldtocamera} & matrix & if a matrixMapping, the
  world-to-local coordinate mapping \\
\end{tabular}

\vspace{10pt}

The ``unique layer name'' is generally the partition name + ``:'' +
attribute name (example: \qkw{defaultfield:density}), with the following
exceptions: (1) if the partition and attribute names are identical, just
one is used rather than it being pointlessly concatenated (e.g.,
\qkw{density}, not \qkw{density:density}); (2) if there are mutiple
partitions + attribute combinations with identical names in the same
file, ``.\emph{number}'' will be added after the partition name for 
subsequent layers (e.g., \qkw{default:density}, \qkw{default.2:density},
\qkw{default.3:density}).

\vspace{.25in}

\section{FITS}
\label{sec:bundledplugins:fits}
\index{FITS}

FITS (Flexible Image Transport System) is an image file format used
for scientific applications, particularly professional astronomy.
FITS files use the file extension {\cf .fits}.
Official FITS specs and other info may be found at:
\url{http://fits.gsfc.nasa.gov/} 

\product supports multiple images in FITS files, and supports the
following pixel data types: UINT8, UINT16, UINT32, FLOAT, DOUBLE.

FITS files can store various kinds of arbitrary data arrays, but
\product's support of FITS is mostly limited using FITS for image
storage.  Currently, \product only supports 2D FITS data (images), not
3D (volume) data, nor 1-D or higher-dimensional arrays.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.5in}}
\ImageSpec Attribute & Type & FITS header data or explanation \\
\hline
\qkw{Orientation} & int & derived from FITS ``ORIENTAT'' field. \\
\qkw{DateTime} & string & derived from the FITS ``DATE'' field. \\
\qkw{Comment} & string & FITS ``COMMENT'' (*) \\
\qkw{History} & string & FITS ``HISTORY'' (*) \\
\qkw{Hierarch} & string & FITS ``HIERARCH'' (*) \\[1.5ex]
\emph{other} & & all other FITS keywords will be added to the \ImageSpec
    as arbitrary named metadata.
\end{tabular}

\noindent (*) Note: If the file contains multiple COMMENT, HISTORY, or HIERARCH
  fields, their text will be appended to form a single attribute (of
  each) in \product's \ImageSpec.

\vspace{.25in}

\section{GIF}
\label{sec:bundledplugins:gif}
\index{GIF}

GIF (Graphics Interchange Format) is an image file format developed by 
CompuServe in 1987.  Nowadays it is widely used to display basic animations
despite its technical limitations.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.25in}}
\ImageSpec Attribute & Type & GIF header data or explanation \\
\hline
\qkw{gif:DelayMs} & int & Delay between frames in miliseconds. \\
\qkw{gif:Interlacing} & int & Specifies if image is interlaced (0 or 1). \\
\qkw{gif:LoopCount} & int & Number of times the animation should be played 
(0--65535, 0 stands for infinity). \\
\qkw{ImageDescription} & string & The GIF comment field.
\end{tabular}

\subsubsection*{Limitations}

\begin{itemize}
\item GIF only supports 3-channel (RGB) images and at most 8 bits per 
channel.
\item Each subimage can include its own palette or use global palette.
Palettes contain up to 256 colors of which one can be used as background 
color. It is then emulated with additional Alpha channel by \product's reader.
\end{itemize}

\vspace{.25in}

\section{HDR/RGBE}
\label{sec:bundledplugins:hdr}
\index{HDR} \index{RGBE}

HDR (High Dynamic Range), also known as RGBE (rgb with extended range),
is a simple format developed for the Radiance renderer to store high
dynamic range images.  HDR/RGBE files commonly use the file extensions
{\cf .hdr}.  The format is described in this section of the Radiance
documentation: \url{http://radsite.lbl.gov/radiance/refer/filefmts.pdf}

RGBE does not support tiles, multiple subimages, mipmapping, true half
or float pixel values, or arbitrary metadata.  Only RGB (3 channel)
files are supported.

RGBE became important because it was developed at a time when no
standard file formats supported high dynamic range, and is still used
for many legacy applications and to distribute HDR environment maps.
But newer formats with native HDR support, such as OpenEXR, are vastly
superior and should be preferred except when legacy file access is
required.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.25in}}
\ImageSpec Attribute & Type & RGBE header data or explanation \\
\hline
\qkw{Orientation} & int & encodes the orientation (see
  \ref{metadata:orientation}) \\
{\cf ImageSpec.gamma} & float & the gamma correction specified in the
  RGBE header.
\end{tabular}


\vspace{.25in}

\section{ICO}
\label{sec:bundledplugins:ico}
\index{ICO}

ICO is an image file format used for small images (usually icons) on
Windows.  ICO files use the file extension {\cf .ico}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.25in}}
\ImageSpec Attribute & Type & ICO header data or explanation \\
\hline
\qkw{oiio:BitsPerSample} & int & the true bits per sample in the ICO file. \\
\qkw{ico:PNG} & int & if nonzero, will cause the ICO to be written
  out using PNG format.
\end{tabular}

\subsubsection*{Limitations}

\begin{itemize}
\item ICO only supports UINT8 and UINT16 formats; all output images will
  be silently converted to one of these.
\item ICO only supports \emph{small} images, up to $256 \times 256$.
  Requests to write larger images will fail their {\cf open()} call.
\end{itemize}


\vspace{.25in}

\vspace{.25in}

\section{IFF}
\label{sec:bundledplugins:iff}
\index{IFF}

IFF files are used by Autodesk Maya and use the file extension {\cf .iff}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.8in}|p{0.65in}|p{2.75in}}
OIIO Attribute & Type & DPX header data or explanation \\
\hline
\qkw{Artist} & string & The IFF ``author'' \\
\qkw{DateTime} & string & Creation date/time \\
\qkw{compression} & string & The compression type \\
\qkw{oiio:BitsPerSample} & int & the true bits per sample of the IFF file. \\
\end{tabular} 



%\subsubsection*{Limitations}
%\begin{itemize}
%\item blah
%\end{itemize}


\vspace{.25in}

\section{JPEG}
\label{sec:bundledplugins:jpeg}
\index{JPEG}

JPEG (Joint Photographic Experts Group), or more properly the JFIF file
format containing JPEG-compressed pixel data, is one of the most popular
file formats on the Internet, with applications, and from digital
cameras, scanners, and other image acquisition devices.  JPEG/JFIF files
usually have the file extension {\cf .jpg}, {\cf .jpe}, {\cf .jpeg},
{\cf .jif}, {\cf .jfif}, or {\cf .jfi}.  The JFIF file format is
described by \url{http://www.w3.org/Graphics/JPEG/jfif3.pdf}.

Although we strive to support JPEG/JFIF because it is so widely used, we
acknowledge that it is a poor format for high-end work: it supports only
1- and 3-channel images, has no support for alpha channels, no support
for high dynamic range or even 16 bit integer pixel data, by convention
stores sRGB data and is ill-suited to linear color spaces, and does not
support multiple subimages or MIPmap levels.  There are newer formats
also blessed by the Joint Photographic Experts Group that attempt to
address some of these issues, such as JPEG-2000, but these do not have
anywhere near the acceptance of the original JPEG/JFIF format.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.25in}}
\ImageSpec Attribute & Type & JPEG header data or explanation \\
\hline
\qkw{ImageDescription} & string & the JPEG Comment field \\
\qkw{Orientation} & int & the image orientation \\[2ex]
\qkw{XResolution}, \qkw{YResolution},
\qkw{ResolutionUnit} & & The resolution and units from the Exif header
\\
& & \\
Exif, IPTC, XMP, GPS & & Extensive Exif, IPTC, XMP, and GPS data are supported by the
  reader/writer, and you should assume that nearly everything described
  Appendix~\ref{chap:stdmetadata} is properly translated when using
  JPEG files.
\end{tabular}

\subsubsection*{Limitations}
\begin{itemize}
\item JPEG/JFIF only supports 1- (grayscale) and 3-channel (RGB) images.
  As a special case, \product's JPEG writer will accept 4-channel image
  data and silently drop the alpha channel while outputting.  Other
  channel count requests (i.e., anything other than 1, 3, and 4) will
  cause {\cf open()} to fail, since it is not possible to write a JFIF
  file with other than 1 or 3 channels.
\item Since JPEG/JFIF only supports 8 bits per channel, \product's
  JPEG/JFIF writer will silently convert to UINT8 upon output,
  regardless of requests to the contrary from the calling program.
\item \product's JPEG/JFIF reader and writer always operate in scanline
  mode and do not support tiled image input or output.
\end{itemize}



\vspace{.25in}

\section{JPEG-2000}
\label{sec:bundledplugins:jpeg2000}
\index{Jpeg 2000}

JPEG-2000 is a successor to the popular JPEG/JFIF format, that supports
better (wavelet) compression and a number of other extensions.  It's
geared toward photography.
JPEG-2000 files use the file extensions {\cf .jp2} or {\cf .j2k}.
The official JPEG-2000 format specification and other helpful info
may be found at \url{http://www.jpeg.org/JPEG2000.htm}.

JPEG-2000 is not yet widely used, so \product's support of it is 
preliminary.  In particular, we are not yet very good at handling
the metadata robustly.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & JPEG-2000 header data or explanation \\
\hline
\qkws{jpeg2000:streamformat} & string & specifies the JPEG-2000
  stream format (\qkw{none} or \qkw{jpc})
\end{tabular}



\vspace{.25in}

\section{OpenEXR}
\label{sec:bundledplugins:openexr}
\index{OpenEXR}

OpenEXR is an image file format developed by Industrial Light \& Magic,
and subsequently open-sourced.  OpenEXR's strengths include support of
high dynamic range imagery ({\cf half} and {\cf float} pixels), tiled
images, explicit support of MIPmaps and cubic environment maps,
arbitrary metadata, and arbitrary numbers of color channels.  OpenEXR
files use the file extension {\cf .exr}.
The official OpenEXR site is \url{http://www.openexr.com/}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & OpenEXR header data or explanation \\
\hline
{\cf width}, {\cf height}, {\cf x}, {\cf y} & & {\cf dataWindow} \\
& & \\
{\cf\small full_width}, {\cf\small full_height}, {\cf\small full_x}, 
  {\cf\small full_y} & & {\cf displayWindow}.  \\
& & \\
\qkw{worldtocamera} & matrix & worldToCamera \\
\qkw{worldtoscreen} & matrix & worldToNDC \\
\qkw{ImageDescription} & string & comments \\
\qkw{Copyright} & string & owner \\
\qkw{DateTime} & string & capDate \\
\qkw{PixelAspectRatio} & float & pixelAspectRatio \\
\qkw{ExposureTime} & float & expTime \\
\qkw{FNumber} & float & aperture \\
\qkw{compression} & string & one of: \qkw{none}, \qkw{rle},
  \qkw{zip}, \qkw{piz}, \qkw{pxr24}, \qkw{b44}, or \qkw{b44a}.  If the
  writer receives a request for a compression type it does not
  recognize, it will use \qkw{zip} by default. \\
\qkw{textureformat} & string & set to \qkw{Plain Texture} for
  MIP-mapped OpenEXR files, \qkw{CubeFace Environment} or \qkw{Latlong
    Environment} for OpenEXR environment maps.  Non-environment
  non-MIP-mapped OpenEXR files will not set this attribute. \\
\qkw{wrapmodes} & string & wrapmodes \\
\qkw{smpte:TimeCode} & int[2] & SMPTE time code (vecsemantics will be
                                marked as TIMECODE) \\
\qkw{smpte:KeyCode} & int[7] & SMPTE key code (vecsemantics will be
                                marked as KEYCODE) \\
%\qkw{oiio:updirection} & string & Will be set to \qkw{y} for OpenEXR
% latlong environment maps to indicate that OpenEXR dictates a
% right-handed, ``$y$ is up'' coordinate system. \\
%\qkw{oiio:sampleborder} & int & Will be set to 1 for OpenEXR environment
% maps to indicate that OpenEXR dictates that boundary texels sample exactly
% on the texture border (pole, meridian, or cube edge).\\[2ex]
\qkw{openexr:lineOrder} & string & the OpenEXR lineOrder attribute
  (set to \qkws{increasingY}, \qkws{randomY}, or \qkws{decreasingY}).
 \\
\qkws{openexr:roundingmode} & int & the MIPmap rounding mode of the
  file. \\[2ex]
\emph{other} & & All other attributes will be added to the \ImageSpec by their
  name and apparent type.
\end{tabular}

\subsubsection*{Limitations}

\begin{itemize}
\item The OpenEXR format does not currently support multiple subimages,
  except for the special case of MIP-maps.
\item The OpenEXR format only supports HALF, FLOAT, and UINT32 pixel
  data.  \product's OpenEXR writer will silently convert data in formats
  (including the common UINT8 and UINT16 cases) to HALF data for output.
\end{itemize}


\vspace{.25in}

\section{PNG}
\label{sec:bundledplugins:png}
\index{PNG}

PNG (Portable Network Graphics) is an image file format developed by the
open source community as an alternative to the GIF, after Unisys started
enforcing patents allegedly covering techniques necessary to use GIF.
PNG files use the file extension {\cf .png}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & PNG header data or explanation \\
\hline
\qkw{ImageDescription} & string & Description \\
\qkw{Artist} & string & Author  \\
\qkw{DocumentName} & string & Title \\
\qkw{DateTime} & string & the timestamp in the PNG header \\
\qkw{PixelAspectRatio} & float & pixel aspect ratio \\
\qkw{XResolution} \qkw{YResolution}
  \qkw{ResolutionUnit} & & resolution and units from the PNG header. 
\end{tabular}

\subsubsection*{Limitations}

\begin{itemize}
\item PNG stupidly specifies that any alpha channel is ``unassociated''
  (i.e., that the color channels are not ``premultiplied'' by alpha).
  This is a disaster, since it results in bad loss of precision for
  alpha image compositing, and even makes it impossible to properly
  represent certain additive glows and other desirable pixel values.
  \product automatically associates alpha (i.e., multiplies colors by
  alpha) upon input and deassociates alpha (divides colors by alpha)
  upon output in order to properly conform to the OIIO convention (and
  common sense) that all pixel values passed through the OIIO APIs
  should use associated alpha.
\item PNG only supports UINT8 and UINT16 output; other requested formats
  will be automatically converted to one of these.
\end{itemize}


\vspace{.25in}

\section{PNM / Netpbm}
\label{sec:bundledplugins:pnm}
\index{PNM}

The Netpbm project, a.k.a.\ PNM (portable ``any'' map) defines PBM, PGM,
and PPM (portable bitmap, portable graymap, portable pixmap) files.
Without loss of generality, we will refer to these all collectively as
``PNM.''  These files have extensions {\cf .pbm}, {\cf .pgm}, and 
{\cf .ppm} and customarily correspond to bi-level bitmaps, 1-channel
grayscale, and 3-channel RGB files, respectively, or {\cf .pnm} for
those who reject the nonsense about naming the files depending on the
number of channels and bitdepth.

PNM files are not much good for anything, but because of their
historical significance and extreme simplicity (that causes many
``amateur'' programs to write images in these formats), \product
supports them.  PNM files do not support floating point images, anything
other than 1 or 3 channels, no tiles, no multi-image, no MIPmapping.
It's not a smart choice unless you are sending your images back to the
1980's via a time machine.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.3in}|p{0.5in}|p{3.50in}}
\ImageSpec Attribute & Type & PNG header data or explanation \\
\hline
\qkw{oiio:BitsPerSample} & int & the true bits per sample of the file
  (1 for true PBM files, even though OIIO will report the {\cf format}
  as UINT8). \\
\qkw{pnm:binary} & int & nonzero if the file itself used the PNM
  binary format, 0 if it used ASCII.  The PNM writer honors this
  attribute in the \ImageSpec to determine whether to write an ASCII
  or binary file.
\end{tabular}



\vspace{.25in}

\section{PSD}
\label{sec:bundledplugins:psd}
\index{PSD}

% FIXME


\vspace{.25in}

\section{Ptex}
\label{sec:bundledplugins:ptex}
\index{Ptex}

Ptex is a special per-face texture format developed by Walt Disney
Feature Animation.  The format and software to read/write it are open
source, and available from \url{http://ptex.us/}.  Ptex files commonly
use the file extension {\cf .ptex}.

\product's support of Ptex is still incomplete.  We can read pixels from
Ptex files, but the \TextureSystem doesn't properly filter across face
boundaries when using it as a texture.  \product currently does not
write Ptex files at all.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & Ptex header data or explanation \\
\hline
\qkw{ptex:meshType} & string & the mesh type, either
  \qkw{triangle} or \qkw{quad}. \\
\qkw{ptex:hasEdits} & int & nonzero if the Ptex file has edits. \\
\qkw{wrapmode} & string & the wrap mode as specified by the
  Ptex file. \\
\emph{other} & & Any other arbitrary metadata in the Ptex file will be stored
  directly as attributes in the \ImageSpec.
\end{tabular}



\vspace{.25in}

\section{RLA}
\label{sec:bundledplugins:rla}
\index{RLA}

RLA (Run-Length encoded, version A) is an early CGI renderer output format,
originating from Wavefront Advanced Visualizer and used primarily by software
developed at Wavefront.  RLA files commonly use the file extension {\cf .rla}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & RLA header data or explanation \\
\hline
{\cf width}, {\cf height}, {\cf x}, {\cf y} & & RLA ``active/viewable'' window. \\
& & \\
{\cf\small full_width}, {\cf\small full_height}, {\cf\small full_x}, 
  {\cf\small full_y} & & RLA ``full'' window.  \\
& & \\
\qkw{rla:FrameNumber} & int & frame sequence number. \\
\qkw{rla:Revision} & int & file format revision number, currently
  \qkw{0xFFFE}. \\
\qkw{rla:JobNumber} & int & job number ID of the file. \\
\qkw{rla:FieldRendered} & int & whether the image is a field-rendered
  (interlaced) one (\qkw{0} for false, non-zero for true). \\
\qkw{rla:FileName} & string & name under which the file was orignally saved. \\
\qkw{ImageDescription} & string & RLA ``Description'' of the image. \\
\qkw{Software} & string & name of software used to save the image. \\
\qkw{HostComputer} & string & name of machine used to save the image. \\
\qkw{Artist} & string & RLA ``UserName'': logon name of user who saved the image. \\
\qkw{rla:Aspect} & string & aspect format description string. \\
\qkw{rla:ColorChannel} & string & textual description of color channel data
  format (usually \qkw{rgb}). \\
\qkw{rla:Time} & string & description (format not standardized) of amount of
  time spent on creating the image. \\
\qkw{rla:Filter} & string & name of post-processing filter applied to the
  image. \\
\qkw{rla:AuxData} & string & textual description of auxiliary channel data
  format. \\
\qkw{rla:AspectRatio} & float & image aspect ratio. \\
\qkw{rla:RedChroma} & vec2 or vec3 of floats & red point XY (vec2) or XYZ
  (vec3) coordinates. \\
\qkw{rla:GreenChroma} & vec2 or vec3 of floats & green point XY (vec2) or XYZ
  (vec3) coordinates. \\
\qkw{rla:BlueChroma} & vec2 or vec3 of floats & blue point XY (vec2) or XYZ
  (vec3) coordinates. \\
\qkw{rla:WhitePoint} & vec2 or vec3 of floats & white point XY (vec2) or XYZ
  (vec3) coordinates. \\
\end{tabular}

\subsubsection*{Limitations}

\begin{itemize}
\item \product will only write 1 image to 1 file, multiple subimages
  are not supported by the writer (but are supported by the reader).
\end{itemize}



\vspace{.25in}

\section{SGI}
\label{sec:bundledplugins:sgi}
\index{SGI files}

The SGI image format was a simple raster format used long ago on SGI
machines.  SGI files use the file extensions {\cf sgi}, {\cf rgb}, 
{\cf rgba}, \qkw{bw}, \qkw{int}, and \qkw{inta}.

The SGI format is sometimes used for legacy apps, but has little merit
otherwise: no support for tiles, no MIPmaps, no multi-subimage, only 8-
and 16-bit integer pixels (no floating point), only 1-4 channels.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & SGI header data or explanation \\
\hline
\qkw{ImageDescription} & string & image name \\
\qkw{Compression} & string & thee compression of the SGI file (\qkw{rle}, if
  RLE compression is used).
\end{tabular}



\vspace{.25in}

\section{Softimage PIC}
\label{sec:bundledplugins:pic}
\index{Softimage PIC}

Softimage PIC is an image file format used by the SoftImage 3D
application, and some other programs that needed to be compatible with
it.  Softimage files use the file extension {\cf .pic}.

The Softimage PIC format is sometimes used for legacy apps, but has
little merit otherwise, so currently \product only reads Softimage
files and is unable to write them.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & PIC header data or explanation \\
\hline
\qkw{ImageDescription} & string & comment \\
\qkw{oiio:BitsPerSample} & int & the true bits per sample in the PIC file.
\end{tabular}



\vspace{.25in}

\section{RAW digital camera files}
\label{sec:bundledplugins:raw}
\index{RAW digital camera files}

A variety of digital camera ``raw'' formats are supported via this
plugin that is based on the LibRaw library ({\cf http://www.libraw.org/}).


% FIXME - fill in more docs here

\begin{comment}
%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & PIC header data or explanation \\
\hline
\qkw{ImageDescription} & string & comment \\
\qkw{oiio:BitsPerSample} & int & the true bits per sample in the PIC file.
\end{tabular}
\end{comment}


\vspace{.25in}

\section{Targa}
\label{sec:bundledplugins:targa}
\index{Targa}

Targa (a.k.a.\ Truevision TGA) is an image file format with little merit
except that it is very simple and is used by many legacy applications.
Targa files use the file extension {\cf .tga}, or, much
more rarely, {\cf .tpic}.
The official Targa format specification may be found at\\
\url{http://www.dca.fee.unicamp.br/~martino/disciplinas/ea978/tgaffs.pdf}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & TGA header data or explanation \\
\hline
\qkw{ImageDescription} & string & comment \\
\qkw{Artist} & string & author \\
\qkw{DocumentName} & string & job name/ID \\
\qkw{Software} & string & software name \\
\qkw{DateTime} & string & TGA time stamp \\
\qkw{targa:JobTime} & string & TGA ``job time.'' \\
\qkw{Compression} & string & values of \qkw{none} and \qkw{rle} are
  supported.  The writer will use RLE compression if any unknown
  compression methods are requested. \\
\qkw{targa:ImageID} & string & Image ID \\
\qkw{PixelAspectRatio} & float & pixel aspect ratio \\
\qkw{oiio:BitsPerSample} & int & the true (in the file) bits per sample. \\
\end{tabular}
\\ 
\vspace{.25in}

If the TGA file contains a thumbnail, its dimensions will be
  stored in the attributes \qkw{thumbnail_width},
  \qkw{thumbnail_height}, and \qkw{thumbnail_nchannels}, and the
  thumbnail pixels themselves will be stored in \qkw{thumbnail_image}
  (as an array of UINT8 values, whose length is the total number of
  channel samples in the thumbnail).

\subsubsection*{Limitations}

\begin{itemize}
\item The Targa reader reserves enough memory for the entire image.
  Therefore it is not a good choice for high-performance image use such 
  as would be used for \ImageCache or \TextureSystem.
\item Targa files only support 8- and 16-bit unsigned integers (no
  signed, floating point, or HDR capabilities); the \product TGA writer
  will silently convert all output images to UINT8 (except if UINT16 is
  explicitly requested).
\item Targa only supports grayscale, RGB, and RGBA; the \product TGA
  writer will fail its call to {\cf open()} if it is asked create a file
  with more than 4 color channels.
\end{itemize}


\vspace{.25in}

\section{TIFF}
\label{sec:bundledplugins:tiff}
\index{TIFF}

TIFF (Tagged Image File Format) is a flexible file format created by
Aldus, now controlled by Adobe.  TIFF supports nearly everything anybody
could want in an image format (and has extactly the complexity you would
expect from such a requirement).
TIFF files commonly use the file extensions {\cf .tif} or, {\cf .tiff}.
Additionally, \product associates the following extensions with TIFF
files by default: {\cf .tx}, {\cf .env}, {\cf .sm}, {\cf .vsm}.

The official TIFF format specification may be found here:
\url{http://partners.adobe.com/public/developer/tiff/index.html} 
~ The most popular library for reading TIFF directly is {\cf libtiff},
available here: 
\url{http://www.remotesensing.org/libtiff/} ~ \product uses {\cf libtiff}
for its TIFF reading/writing.

We like TIFF a lot, especially since its complexity can be nicely hidden
behind OIIO's simple APIs.  It supports a wide variety of data formats
(though unfortunately not {\cf half}), an arbitrary number of channels,
tiles and multiple subimages (which makes it our preferred texture
format), and a rich set of metadata.

\product supports the vast majority of TIFF features, including: tiled
images (\qkw{tiled}) as well as scanline images; multiple subimages per
file (\qkw{multiimage}); MIPmapping (using multi-subimage; that means 
you can't use multiimage and MIPmaps simultaneously); data formats
8- 16, and 32 bit integer (both signed and unsigned), and 32- and 64-bit
floating point; palette images (will convert to RGB); ``miniswhite''
photometric mode (will convert to ``minisblack'').

The TIFF plugin attempts to support all the standard Exif, IPTC, and XMP
metadata if present.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{2.0in}|p{0.5in}|p{2.75in}}
\ImageSpec Attribute & Type & TIFF header data or explanation \\
\hline
{\cf ImageSpec::x} & int & XPosition \\
{\cf ImageSpec::y} & int & YPosition \\
{\cf ImageSpec::full_width} & int & PIXAR\_IMAGEFULLWIDTH \\
{\cf ImageSpec::full_length} & int & PIXAR\_IMAGEFULLLENGTH \\
\qkw{ImageDescription} & string & ImageDescription \\
\qkw{DateTime} & string & DateTime \\
\qkw{Software} & string & Software \\
\qkw{Artist} & string & Artist \\
\qkw{Copyright} & string & Copyright \\
\qkw{Make} & string & Make \\
\qkw{Model} & string & Model \\
\qkw{DocumentName} & string & DocumentName \\
\qkw{HostComputer} & string & HostComputer \\
\qkws{XResultion} \qkws{YResolution} & float & XResolution, YResolution \\
\qkws{ResolutionUnit} & string & ResolutionUnit (\qkw{in} or
  \qkw{cm}). \\
\qkw{Orientation} & int & Orientation \\
\qkw{textureformat} & string & {\cf PIXAR_TEXTUREFORMAT} \\
\qkw{wrapmodes} & string & {\cf PIXAR_WRAPMODES} \\
\qkw{fovcot} & float & {\cf PIXAR_FOVCOT} \\
\qkw{worldtocamera} & matrix & PIXAR\_MATRIX\_WORLDTOCAMERA \\
\qkw{worldtoscreen} & matrix & PIXAR\_MATRIX\_WORLDTOSCREEN\\
\qkw{comrpession} & string & based on TIFF Compression 
  (one of \qkw{none}, \qkw{lzw}, \qkw{ccittrle}, \qkw{zip}, \qkw{packbits}).\\
\qkw{tiff:compression} & int & the original integer code
  from the TIFF Compression tag.\\
\qkw{tiff:planarconfig} & string & PlanarConfiguration (\qkw{separate} or
  \qkw{contig}).  The \product TIFF writer will honor such a request in
  the \ImageSpec.\\
\qkwf{tiff:PhotometricInterpretation} & int & Photometric \\
\qkw{tiff:PageName} & string & PageName \\
\qkw{tiff:PageNumber} & int & PageNumber \\
\qkw{tiff:RowsPerStrip} & int & RowsPerStrip \\
\qkw{tiff:subfiletype} & 1 & SubfileType \\
\qkw{Exif:*} & & A wide variety of EXIF data are honored, and are all prefixed
  with \qkw{Exif:}.\\
\qkw{oiio:BitsPerSample} & int & The actual bits per sample in the file (may
  differ from {\cf ImageSpec::format}).\\
\qkw{oiio:UnassociatedAlpha} & int & Nonzero if the alpha channel
  contained ``unassociated'' alpha. \\
\end{tabular}

\subsubsection*{Limitations}

\product's TIFF reader and writer have some limitations you should be
aware of:
\begin{itemize}
\item No separate per-channel data formats (not supported by {\cf
  libtiff}).
\item Only multiples of 8 bits per pixel may be passed through
  \product's APIs, e.g., 1-, 2-, and 4-bits per pixel will be reported
  by OIIO as 8 bit images; 12 bits per pixel will be reported as 16,
  etc.  But the \qkw{oiio:BitsPerSample} attribute in the \ImageSpec
  will correctly report the original bit depth of the file.  Note that
  the TIFF specification itself does not support 16-bit floating point
  pixels ({\cf half} data).
\end{itemize}



\vspace{.25in}

\section{Webp}
\label{sec:bundledplugins:webp}
\index{WebP}

% FIXME


\vspace{.25in}

\section{Zfile}
\label{sec:bundledplugins:zfile}
\index{Zfile}

Zfile is a very simple format for writing a depth ($z$) image,
originally from Pixar's PhotoRealistic RenderMan but now supported by
many other renderers.  It's extremely minimal, holding only a width,
height, world-to-screen and camera-to-screen matrices, and uncompressed
float pixels of the z-buffer.
Zfile files use the file extension {\cf .zfile}.

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.75in}|p{0.5in}|p{3.0in}}
\ImageSpec Attribute & Type & Zfile header data or explanation \\
\hline
\qkw{worldtocamera} & matrix & NP \\
\qkw{worldtoscreen} & matrix & Nl \\
\end{tabular}



\index{Plugins!bundled|)}
\chapwidthend


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\begin{comment}

FOO () is an image file format.
Strengths.
FOO files use the file extension {\cf .foo}.

The official FOO format specification may be found at \url{} .

%\subsubsection*{Attributes}
\vspace{.125in}

\noindent\begin{tabular}{p{1.5in}|p{0.5in}|p{3.5in}}
\ImageSpec Attribute & Type & FOO header data or explanation \\
\hline
\end{tabular}

\subsubsection*{Limitations}

\begin{itemize}
\item blah
\end{itemize}

\end{comment}
