builtinplugins.rst

Bundled ImageIO Plugins

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

BMP

BMP is a bitmap image file format used mostly on Windows systems. BMP files use the file extension .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.

ImageSpec Attribute	Type	BMP header data or explanation
XResolution	float	hres
YResolution	float	vres
ResolutionUnit	string	always "m" (pixels per meter)

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

DDS

DDS (Direct Draw Surface) is an image file format designed by Microsoft for use in Direct3D graphics. DDS files use the extension .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.

OpenImageIO currently only supports reading DDS files, not writing them.

ImageSpec Attribute	Type	DDS header data or explanation
compression	string	Compression type
oiio:BitsPerSample	int	bits per sample
textureformat	string	Set correctly to one of "Plain Texture", "Volume Texture", or "CubeFace Environment".
texturetype	string	Set correctly to one of "Plain Texture", "Volume Texture", or "Environment".
dds:CubeMapSides	string	For environment maps, which cube faces are present (e.g., "+x -x +y -y" if x & y faces are present, but not z).

DICOM

DICOM (Digital Imaging and Communications in Medicine) is the standard format used for medical images. DICOM files usually have the extension .dcm.

OpenImageIO currently only supports reading DICOM files, not writing them.

ImageSpec Attribute	Type	DDS header data or explanation
oiio:BitsPerSample	int	Bits per sample.
dicom:*	any	DICOM header information and metadata is currently all preceded by the dicom: prefix.

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

Configuration settings for DPX input

When opening a DPX ImageInput with a configuration (see Section sec-inputwithconfig), the following special configuration options are supported:

Input Configuration Attribute	Type	Meaning
oiio:RawColor	int	If nonzero, reading images with non-RGB color models (such as YCbCr) will return unaltered pixel values (versus the default OIIO behavior of automatically converting to RGB).

Configuration settings for DPX output

When opening a DPX ImageOutput, the following special metadata tokens control aspects of the writing itself:

Output configuration Attribute	Type	Meaning
oiio:RawColor	int	If nonzero, writing images with non-RGB color models (such as YCbCr) will keep unaltered pixel values (versus the default OIIO behavior of automatically converting from RGB to the designated color space as the pixels are written).

DPX Attributes

ImageSpec Attribute	Type	DPX header data or explanation
ImageDescription	string	Description of image element
Copyright	string	Copyright statement
Software	string	Creator
DocumentName	string	Project name
DateTime	string	Creation date/time
Orientation	int	the orientation of the DPX image data (see metadata:orientation)
compression	string	The compression type
PixelAspectRatio	float	pixel aspect ratio
oiio:BitsPerSample	int	the true bits per sample of the DPX file.
oiio:Endian	string	When writing, force a particular endianness for the output "little" or "big")
smpte:TimeCode	int[2]	SMPTE time code (vecsemantics will be marked as TIMECODE)
smpte:KeyCode	int[7]	SMPTE key code (vecsemantics will be marked as KEYCODE)
dpx:Transfer	string	Transfer characteristic
dpx:Colorimetric	string	Colorimetric specification
dpx:ImageDescriptor	string	ImageDescriptor
dpx:Packing	string	Image packing method
dpx:TimeCode	int	SMPTE time code
dpx:UserBits	int	SMPTE user bits
dpx:SourceDateTime	string	source time and date
dpx:FilmEdgeCode	string	FilmEdgeCode
dpx:Signal	string	Signal ("Undefined", "NTSC", "PAL", etc.)
dpx:UserData	UCHAR[*]	User data (stored in an array whose length is whatever it it was in the DPX file)
dpx:EncryptKey	int	Encryption key (-1 is not encrypted)
dpx:DittoKey	int	Ditto (0 = same as previous frame, 1 = new)
dpx:LowData	int	reference low data code value
dpx:LowQuantity	float	reference low quantity
dpx:HighData	int	reference high data code value
dpx:HighQuantity	float	reference high quantity
dpx:XScannedSize	float	X scanned size
dpx:YScannedSize	float	Y scanned size
dpx:FramePosition	int	frame position in sequence
dpx:SequenceLength	int	sequence length (frames)
dpx:HeldCount	int	held count (1 = default)
dpx:FrameRate	float	frame rate of original (frames/s)
dpx:ShutterAngle	float	shutter angle of camera (deg)
dpx:Version	string	version of header format
dpx:Format	string	format (e.g., "Academy")
dpx:FrameId	string	frame identification
dpx:SlateInfo	string	slate information
dpx:SourceImageFileName	string	source image filename
dpx:InputDevice	string	input device name
dpx:InputDeviceSerialNumber	string	input device serial number
dpx:Interlace	int	interlace (0 = noninterlace, 1 = 2:1 interlace
dpx:FieldNumber	int	field number
dpx:HorizontalSampleRate	float	horizontal sampling rate (Hz)
dpx:VerticalSampleRate	float	vertical sampling rate (Hz)
dpx:TemporalFrameRate	float	temporal sampling rate (Hz)
dpx:TimeOffset	float	time offset from sync to first pixel (ms)
dpx:BlackLevel	float	black level code value
dpx:BlackGain	float	black gain
dpx:BreakPoint	float	breakpoint
dpx:WhiteLevel	float	reference white level code value
dpx:IntegrationTimes	float	integration time (s)
dpx:EndOfLinePadding	int	Padded bytes at the end of each line
dpx:EndOfImagePadding	int	Padded bytes at the end of each image

Field3D

Field3d is an open-source volume data file format. Field3d files commonly use the extension .f3d. The official Field3D site is: https://github.com/imageworks/Field3D Currently, OpenImageIO only reads Field3d files, and does not write them.

Fields are comprised of multiple layers (which appear to OpenImageIO 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 half, float, or double.

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

ImageSpec Attribute	Type	Field3d header data or explanation
ImageDescription	string	unique layer name
oiio:subimagename	string	unique layer name
field3d:partition	string	the partition name
field3d:layer	string	the layer (a.k.a. attribute) name
field3d:fieldtype	string	field type, one of: "dense", "sparse", or "MAC"
field3d:mapping	string	the coordinate mapping type
field3d:localtoworld	matrix of doubles	if a matrixMapping, the local-to-world transformation matrix
worldtolocal	matrix	if a matrixMapping, the world-to-local coordinate mapping

The "unique layer name" is generally the partition name + : + attribute name (example: "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., "density", not "density:density"); (2) if there are mutiple partitions + attribute combinations with identical names in the same file, "number" will be added after the partition name for subsequent layers (e.g., "default:density", "default.2:density", "default.3:density").

FITS

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

OpenImageIO 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 OpenImageIO's support of FITS is mostly limited using FITS for image storage. Currently, OpenImageIO only supports 2D FITS data (images), not 3D (volume) data, nor 1-D or higher-dimensional arrays.

ImageSpec Attribute	Type	FITS header data or explanation
Orientation	int	derived from FITS "ORIENTAT" field.
DateTime	string	derived from the FITS "DATE" field.
Comment	string	FITS "COMMENT" (*)
History	string	FITS "HISTORY" (*)
Hierarch	string	FITS "HIERARCH" (*)
other		all other FITS keywords will be added to the ImageSpec as arbitrary named metadata.

Note

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

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.

ImageSpec Attribute	Type	GIF header data or explanation
gif:Interlacing	int	Specifies if image is interlaced (0 or 1).
FramesPerSecond	int[2] (rational)	Frames per second
oiio:Movie	int	If nonzero, indicates that it's an animated GIF.
gif:LoopCount	int	Number of times the animation should be played (0-65535, 0 stands for infinity).
ImageDescription	string	The GIF comment field.

Limitations

• GIF only supports 3-channel (RGB) images and at most 8 bits per channel.
• 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 OpenImageIO's reader.

HDR/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 .hdr. The format is described in this section of the Radiance documentation: 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.

ImageSpec Attribute	Type	RGBE header data or explanation
Orientation	int	encodes the orientation (see Section sec-metadata-orientation)
oiio:ColorSpace	string	Color space (see Section sec-metadata-color).
oiio:Gamma	float	the gamma correction specified in the RGBE header (if it's gamma corrected).

HEIF/HEIC

HEIF is a container format for images compressed with the HEIC compression standard (same compression as HEVC/H.265). It is used commonly for iPhone camera pictures, but it is not Apple-specific and will probably become more popualar on other platforms in coming years. HEIF files usually use the file extension .HEIC.

HEIC compression is lossy, but is higher visual quality than JPEG while taking only half the file size. Currently, OIIO's HEIF reader supports reading files as RGB or RGBA, uint8 pixel values. Multi-image files are currently supported for reading, but not yet writing. All pixel data is uint8, though we hope to add support for HDR (more than 8 bits) in the future.

Configuration settings for HEIF output

When opening an HEIF ImageOutput, the following special metadata tokens control aspects of the writing itself:

ImageSpec Attribute	Type	HEIF header data or explanation
Compression	string	If supplied, must be "heic", but may optionally have a quality value appended, like "heic:90". Quality can be 1-100, with 100 meaning lossless. The default is 75.

ICO

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

ImageSpec Attribute	Type	ICO header data or explanation
oiio:BitsPerSample	int	the true bits per sample in the ICO file.
ico:PNG	int	if nonzero, will cause the ICO to be written out using PNG format.

Limitations

• ICO only supports UINT8 and UINT16 formats; all output images will be silently converted to one of these.
• ICO only supports small images, up to 256 x 256. Requests to write larger images will fail their open() call.

IFF

IFF files are used by Autodesk Maya and use the file extension .iff.

ImageSpec Attribute	Type	IFF header data or explanation
Artist	string	The IFF "author"
DateTime	string	Creation date/time
compression	string	The compression type ("none" or "rle" [default])
oiio:BitsPerSample	int	the true bits per sample of the IFF file.

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 .jpg, .jpe, .jpeg, .jif, .jfif, or .jfi. The JFIF file format is described by 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.

ImageSpec Attribute	Type	JPEG header data or explanation
ImageDescription	string	the JPEG Comment field
Orientation	int	the image orientation
XResolution, YResolution, ResolutionUnit		The resolution and units from the Exif header
Compression	string	If supplied, must be "jpeg", but may optionally have a quality value appended, like "jpeg:90". Quality can be 1-100, with 100 meaning lossless.
ICCProfile	uint8[]	The ICC color profile
jpeg:subsampling	string	Describes the chroma subsampling, e.g., "4:2:0" (the default), "4:4:4", "4:2:2", "4:2:1".
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 chap-stdmetadata is properly translated when using JPEG files.

Limitations

• JPEG/JFIF only supports 1- (grayscale) and 3-channel (RGB) images. As a special case, OpenImageIO's JPEG writer will accept n-channel image data, but will only output the first 3 channels (if n >= 3) or the first channel (if n <= 2), silently drop any extra channels from the output.
• Since JPEG/JFIF only supports 8 bits per channel, OpenImageIO's JPEG/JFIF writer will silently convert to UINT8 upon output, regardless of requests to the contrary from the calling program.
• OpenImageIO's JPEG/JFIF reader and writer always operate in scanline mode and do not support tiled image input or output.

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 .jp2 or .j2k. The official JPEG-2000 format specification and other helpful info may be found at: http://www.jpeg.org/JPEG2000.htm

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

ImageSpec Attribute	Type	JPEG-2000 header data or explanation
jpeg2000:streamformat	string	specifies the JPEG-2000 stream format ("none" or "jpc")

Movie formats (using ffmpeg)

The ffmpeg-based reader is capable of reading the individual frames from a variety of movie file formats, including:

Format	Extensions
AVI	.avi
QuickTime	.qt, .mov
MPEG-4	.mp4, .m4a, .m4v
3GPP files	.3gp, .3g2
Motion JPEG-2000	.mj2
Apple M4V	.m4v
MPEG-1/MPEG-2	.mpg

Currently, these files may only be read. Write support may be added in a future release. Also, currently, these files simply look to OIIO like simple multi-image files and not much support is given to the fact that they are technically movies (for example, there is no support for reading audio information).

Some special attributes are used for movie files:

ImageSpec Attribute	Type	Header data or explanation
oiio:Movie	int	Nonzero value for movie files
oiio:subimages	int	The number of frames in the movie, positive if it can be known without reading the entire file. Zero or not present if the number of frames cannot be determinend from reading from just the file header.
FramesPerSecond	int[2] (rational)	Frames per second

Null format

The nullptr reader/writer is a mock-up that does not perform any actual I/O. The reader just returns constant-colored pixels, and the writer just returns directly without saving any data. This has several uses:

• Benchmarking, if you want to have OIIO's input or output truly take as close to no time whatsoever.
• "Dry run" of applications where you don't want it to produce any real output (akin to a Unix command that you redirect output to /dev/null).
• Make "fake" input that looks like a file, but the file doesn't exist (if you are happy with constant-colored pixels).

The filename allows a REST-ful syntax, where you can append modifiers that specify things like resolution (of the non-existent file), etc. For example:

foo.null?RES=640x480&CHANNELS=3

would specify a null file with resolution 640x480 and 3 channels. Token/value pairs accepted are:

RES=1024x1024	Set resolution (3D example: 256x256x100)
CHANNELS=4	Set number of channels
TILES=64x64	Makes it look like a tiled image with tile size
TYPE=uint8	Set the pixel data type
PIXEL=r,g,b,...	Set pixel values (comma separates channel values)
TEX=1	Make it look like a full MIP-mapped texture
attrib=value	Anything else will set metadata

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 (half and 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 .exr. The official OpenEXR site is http://www.openexr.com/.

Attributes

ImageSpec Attribute	Type	OpeneEXR header data or explanation
width, height, x, y	int	dataWindow
full_width, full_height, full_x, full_y	int	displayWindow
worldtocamera	matrix	worldToCamera
worldtoscreen	matrix	worldToNDC
ImageDescription	string	comments
Copyright	string	owner
DateTime	string	capDate
PixelAspectRatio	float	pixelAspectRatio
ExposureTime	float	expTime
FNumber	float	aperture
compression	string	one of: "none", "rle", "zip", "zips", "piz", "pxr24", "b44", "b44a", "dwaa", or "dwab". If the writer receives a request for a compression type it does not recognize or is not supported by the version of OpenEXR on the system, it will use "zip" by default. For "dwaa" and "dwab", the dwaCompressionLevel may be optionally appended to the compression name after a colon, like this: "dwaa:200". (The default DWA compression value is 45.)
textureformat	string	"Plain Texture" for MIP-mapped OpenEXR files, "CubeFace Environment" or "Latlong Environment" for OpenEXR environment maps. Non-environment non-MIP-mapped OpenEXR files will not set this attribute.
wrapmodes	string	wrapmodes
FramesPerSecond	int[2]	Frames per second playback rate (vecsemantics will be marked as RATIONAL)
captureRate	int[2]	Frames per second capture rate (vecsemantics will be marked as RATIONAL)
smpte:TimeCode	int[2]	SMPTE time code (vecsemantics will be marked as TIMECODE)
smpte:KeyCode	int[7]	SMPTE key code (vecsemantics will be marked as KEYCODE)
openexr:lineOrder	string	OpenEXR lineOrder attribute: "increasingY", "randomY", or "decreasingY".
openexr:roundingmode	int	the MIPmap rounding mode of the file.
openexr:dwaCompressionLevel	float	compression level for dwaa or dwab compression (default: 45.0).
other		All other attributes will be added to the ImageSpec by their name and apparent type.

Configuration settings for OpenEXR input

When opening an OpenEXR ImageInput with a configuration (see Section sec-inputwithconfig), the following special configuration attributes are supported:

Input Configuration Attribute	Type	Meaning
oiio:ioproxy	ptr	Pointer to a Filesystem::IOProxy that will handle the I/O, for example by reading from memory rather than the file system.
oiio:missingcolor	float or string	Either an array of float values or a string holding a comma-separated list of values, if present this is a request to use this color for pixels of any missing tiles or scanlines, rather than considering a tile/scanline read failure to be an error. This can be helpful when intentionally reading partially-written or incomplete files (such as an in-progress render).

Configuration settings for OpenEXR output

When opening an OpenEXR ImageOutput, the following special metadata tokens control aspects of the writing itself:

Output Configuration Attribute	Type	Meaning
oiio:RawColor	int	If nonzero, writing images with non-RGB color models (such as YCbCr) will keep unaltered pixel values (versus the default OIIO behavior of automatically converting from RGB to the designated color space as the pixels are written).
oiio:ioproxy	ptr	Pointer to a Filesystem::IOProxy that will handle the I/O, for example by writing to a memory buffer.

Custom I/O Overrides

OpenEXR input and output both support the "custom I/O" feature via the special "oiio:ioproxy" attributes (see Sections sec-imageoutput-ioproxy and sec-imageinput-ioproxy).

A note on channel names

The underlying OpenEXR library (libIlmImf) always saves channels into lexicographic order, so the channel order on disk (and thus when read!) will NOT match the order when the image was created.

But in order to adhere to OIIO's convention that RGBAZ will always be the first channels (if they exist), OIIO's OpenEXR reader will automatically reorder just those channels to appear at the front and in that order. All other channel names will remain in their relative order as presented to OIIO by libIlmImf.

Limitations

• The OpenEXR format only supports HALF, FLOAT, and UINT32 pixel data. OpenImageIO's OpenEXR writer will silently convert data in formats (including the common UINT8 and UINT16 cases) to HALF data for output.

OpenVDB

OpenVDB is an open-source volume data file format. OpenVDB files commonly use the extension .vdb. The official OpenVDB site is: http://www.openvdb.org/ Currently, OpenImageIO only reads OpenVDB files, and does not write them.

Volumes are comprised of multiple layers (which appear to OpenImageIO 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 voxel data are always float. OpenVDB files always report as tiled, using the leaf dimension size.

ImageSpec Attribute	Type	OpenVDB header data or explanation
ImageDescription	string	Description of image element
oiio:subimagename	string	unique layer name
openvdb:indextoworld	matrix of doubles	conversion of voxel index to world space coordinates.
openvdb:worldtoindex	matrix of doubles	conversion of world space coordinates to voxel index.
worldtocamera	matrix	World-to-local coordinate mapping.

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

Attributes

ImageSpec Attribute	Type	PNG header data or explanation
ImageDescription	string	Description
Artist	string	Author
DocumentName	string	Title
DateTime	string	the timestamp in the PNG header
PixelAspectRatio	float	pixel aspect ratio
XResolution, YResolution, ResolutionUnit		resolution and units from the PNG header.
oiio:ColorSpace	string	Color space (see Section sec-metadata-color).
oiio:Gamma	float	the gamma correction value (if specified).
ICCProfile	uint8[]	The ICC color profile

Configuration settings for PNG input

When opening an PNG ImageInput with a configuration (see Section sec-inputwithconfig), the following special configuration attributes are supported:

Input Configuration Attribute	Type	Meaning
oiio:UnassociatedAlpha	int	If nonzero, will leave alpha unassociated (versus the default of premultiplying color channels by alpha if the alpha channel is unassociated).
oiio:ioproxy	ptr	Pointer to a Filesystem::IOProxy that will handle the I/O, for example by reading from memory rather than the file system.

Configuration settings for PNG output

When opening an PNG ImageOutput, the following special metadata tokens control aspects of the writing itself:

Output Configuration Attribute	Type	Meaning
png:compressionLevel	int	Compression level for zip/deflate compression, on a scale from 0 (fastest, minimal compression) to 9 (slowest, maximal compression). The default is 6. PNG compression is always lossless.
png:filter	int	Controls the "row filters" that prepare the image for optimal compression. The default is 0 (PNG_NO_FILTERS), but other values (which may be "or-ed" or summed to combine their effects) are 8 (PNG_FILTER_NONE), 16 (PNG_FILTER_SUB), 32 (PNG_FILTER_UP), 64 (PNG_FILTER_AVG), or 128 (PNG_FILTER_PAETH).
oiio:ioproxy	ptr	Pointer to a Filesystem::IOProxy that will handle the I/O, for example by writing to a memory buffer.
oiio:dither	int	If nonzero and outputting UINT8 values in the file, will add a small amount of random dither to combat the appearance of banding

Custom I/O Overrides

PNG output supports the "custom I/O" feature via the special "oiio:ioproxy" attributes (see Section sec-imageoutput-ioproxy).

Limitations

• 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. OpenImageIO 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.
• PNG only supports UINT8 and UINT16 output; other requested formats will be automatically converted to one of these.

PNM / Netpbm

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 .pbm, .pgm, and .ppm and customarily correspond to bi-level bitmaps, 1-channel grayscale, and 3-channel RGB files, respectively, or .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), OpenImageIO 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.

ImageSpec Attribute	Type	PNM header data or explanation
oiio:BitsPerSample	int	The true bits per sample of the file (1 for true PBM files, even though OIIO will report the format as UINT8).
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.

PSD

PSD is the file format used for storing Adobe PhotoShop images. OpenImageIO provides limited read abilities for PSD, but not currently the ability to write PSD files.

Configuration settings for PSD input

When opening an ImageInput with a configuration (see Section sec-inputwithconfig), the following special configuration options are supported:

Input Configuration Attribute	Type	Meaning
oiio:RawColor	int	If nonzero, reading images with non-RGB color models (such as YCbCr or CMYK) will return unaltered pixel values (versus the default OIIO behavior of automatically converting to RGB).

Currently, the PSD format reader supports color modes RGB, CMYK, multichannel, grayscale, indexed, and bitmap. It does NOT currenty support Lab or duotone modes.

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 http://ptex.us/. Ptex files commonly use the file extension .ptex.

OpenImageIO'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. OpenImageIO currently does not write Ptex files at all.

ImageSpec Attribute	Type	Ptex header data or explanation
ptex:meshType	string	the mesh type, either "triangle" or "quad".
ptex:hasEdits	int	nonzero if the Ptex file has edits.
wrapmode	string	the wrap mode as specified by the Ptex file.
other		Any other arbitrary metadata in the Ptex file will be stored directly as attributes in the ImageSpec.

RAW digital camera files

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

Configuration settings for RAW input

When opening an ImageInput with a configuration (see Section sec-inputwithconfig), the following special configuration options are supported:

Input Configuration Attribute	Type	Meaning
raw:auto_bright	int	If nonzero, will use libraw's exposure correction. (Default: 0)
raw:use_camera_wb	int	If 1, use libraw's camera white balance adjustment. (Default: 1)
raw:use_camera_matrix	int	Whether to use the embedded color profile, if it's present: 0 = never, 1 (default) = only for DNG files, 3 = always.
raw:adjust_maximum_thr	float	If nonzero, auto-adjusting maximum value. (Default:0.0)
raw:user_sat	int	If nonzero, sets the camera maximum value that will be normalized to appear saturated. (Default: 0)
raw:aber	float[2]	Red and blue scale factors for chromatic aberration correction when decoding the raw image. The default (1,1) means to perform no correction. This is an overall spatial scale, sensible values will be very close to 1.0.
raw:half_size	int	If nonzero, outputs the image in half size. (Default: 0)
raw:user_mul	float[4]	Sets user white balance coefficients. Only applies if raw:use_camera_wb is not equal to 0.
raw:ColorSpace	string	Which color primaries to use: raw, sRGB, Adobe, Wide, ProPhoto, ACES, XYZ. (Default: sRGB)
raw:Exposure	float	Amount of exposure before de-mosaicing, from 0.25 (2 stop darken) to 8 (3 stop brighten). (Default: 0, meaning no correction.)
raw:Demosaic	string	Force a demosaicing algorithm: linear, VNG, PPG, AHD (default), DCB, AHD-Mod, AFD, VCD, Mixed, LMMSE, AMaZE, DHT, AAHD, none.
raw:HighlightMode	int	Set libraw highlight mode processing: 0 = clip, 1 = unclip, 2 = blend, 3+ = rebuild. (Default: 0.)

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

ImageSpec Attribute	Type	RLA header data or explanation
width, height, x, y	int	RLA "active/viewable" window.
full_width, full_height, full_x, full_y	int	RLA "full" window.
rla:FrameNumber	int	frame sequence number.
rla:Revision	int	file format revision number, currently 0xFFFE.
rla:JobNumber	int	job number ID of the file.
rla:FieldRendered	int	whether the image is a field-rendered (interlaced) one 0 for false, non-zero for true.
rla:FileName	string	name under which the file was orignally saved.
ImageDescription	string	RLA "Description" of the image.
Software	string	name of software used to save the image.
HostComputer	string	name of machine used to save the image.
Artist	string	RLA "UserName": logon name of user who saved the image.
rla:Aspect	string	aspect format description string.
rla:ColorChannel	string	textual description of color channel data format (usually rgb).
rla:Time	string	description (format not standardized) of amount of time spent on creating the image.
rla:Filter	string	name of post-processing filter applied to the image.
rla:AuxData	string	textual description of auxiliary channel data format.
rla:AspectRatio	float	image aspect ratio.
rla:RedChroma	vec2 or vec3 of floats	red point XY (vec2) or XYZ (vec3) coordinates.
rla:GreenChroma	vec2 or vec3 of floats	green point XY (vec2) or XYZ (vec3) coordinates.
rla:BlueChroma	vec2 or vec3 of floats	blue point XY (vec2) or XYZ (vec3) coordinates.
rla:WhitePoint	vec2 or vec3 of floats	white point XY (vec2) or XYZ (vec3) coordinates.
oiio:ColorSpace	string	Color space (see Section sec-metadata-color).
oiio:Gamma	float	the gamma correction value (if specified).

Limitations

• OpenImageIO will only write a single image to each file, multiple subimages are not supported by the writer (but are supported by the reader).

SGI

The SGI image format was a simple raster format used long ago on SGI machines. SGI files use the file extensions sgi, rgb, rgba, bw, int, and 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.

ImageSpec Attribute	Type	SGI header data or explanation
compression	string	The compression of the SGI file (rle, if RLE compression is used).
ImageDescription	string	Image name.

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

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

ImageSpec Attribute	Type	PIC header data or explanation
compression	string	The compression of the SGI file (rle, if RLE compression is used).
ImageDescription	string	Comment
oiio:BitsPerSample	int	the true bits per sample of the PIC file.

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 .tga, or, much more rarely, .tpic. The official Targa format specification may be found at: http://www.dca.fee.unicamp.br/~martino/disciplinas/ea978/tgaffs.pdf

ImageSpec Attribute	Type	TGA header data or explanation
ImageDescription	string	Comment
Artist	string	author
DocumentName	string	job name/ID
Software	string	software name
DateTime	string	TGA time stamp
targa:JobTime	string	TGA "job time."
compression	string	values of none and rle are supported. The writer will use RLE compression if any unknown compression methods are requested.
targa:ImageID	string	Image ID
PixelAspectRatio	float	pixel aspect ratio
oiio:BitsPerSample	int	the true bits per sample of the PIC file.
oiio:ColorSpace	string	Color space (see Section sec-metadata-color).
oiio:Gamma	float	the gamma correction value (if specified).

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

Limitations

• 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.
• Targa files only support 8- and 16-bit unsigned integers (no signed, floating point, or HDR capabilities); the OpenImageIO TGA writer will silently convert all output images to UINT8 (except if UINT16 is explicitly requested).
• Targa only supports grayscale, RGB, and RGBA; the OpenImageIO TGA writer will fail its call to open() if it is asked create a file with more than 4 color channels.

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 .tif or, .tiff. Additionally, OpenImageIO associates the following extensions with TIFF files by default: .tx, .env, .sm, .vsm.

The official TIFF format specification may be found here: http://partners.adobe.com/public/developer/tiff/index.html The most popular library for reading TIFF directly is libtiff, available here: http://www.remotesensing.org/libtiff/ OpenImageIO uses 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 half), an arbitrary number of channels, tiles and multiple subimages (which makes it our preferred texture format), and a rich set of metadata.

OpenImageIO supports the vast majority of TIFF features, including: tiled images (tiled) as well as scanline images; multiple subimages per file (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.

Configuration settings for TIFF input

When opening an ImageInput with a configuration (see Section sec-inputwithconfig), the following special configuration options are supported:

Input Configuration Attribute	Type	Meaning
oiio:UnassociatedAlpha	int	If nonzero, will leave alpha unassociated (versus the default of premultiplying color channels by alpha if the alpha channel is unassociated).
oiio:RawColor	int	If nonzero, reading images with non-RGB color models (such as YCbCr) will return unaltered pixel values (versus the default OIIO behavior of automatically converting to RGB).

Configuration settings for TIFF output

When opening an ImageOutput, the following special metadata tokens control aspects of the writing itself:

Output Configuration Attribute	Type	Meaning
oiio:UnassociatedAlpha	int	If nonzero, any alpha channel is understood to be unassociated, and the EXTRASAMPLES tag in the TIFF file will be set to reflect this).
oiio:BitsPerSample	int	Requests a rescaling to a specific bits per sample (such as writing 12-bit TIFFs).
tiff:write_exif	int	If zero, will not write any Exif data to the TIFF file. (The default is 1.)
tiff:half	int	If nonzero, allow writing TIFF files with half (16 bit float) pixels. The default of 0 will automatically translate to float pixels, since most non-OIIO applications will not properly read half TIFF files despite their being legal.
tiff:ColorSpace	string	Requests that the file be saved with a non-RGB color spaces. Choices are RGB, CMYK. % , YCbCr, CIELAB, ICCLAB, ITULAB.
tiff:zipquality	int	A time-vs-quality knob for zip compression, ranging from 1-9 (default is 6). Higher means compress to less space, but taking longer to do so. It is strictly a time vs space tradeoff, the quality is identical (lossless) no matter what the setting.
tiff:RowsPerStrip	int	Overrides TIFF scanline rows per strip with a specific request (if not supplied, OIIO will choose a reasonable default).

TIFF compression modes

The full list of possible TIFF compression mode values are as follows ($ ^*$ indicates that OpenImageIO can write that format, and is not part of the format name):

none $ ^*$ lzw $ ^*$ zip $ ^*$ ccitt_t4 ccitt_t6 ccittfax3 ccittfax4 ccittrle2 ccittrle $ ^*$ dcs isojbig IT8BL IT8CTPAD IT8LW IT8MP jp2000 jpeg $ ^*$ lzma next ojpeg packbits $ ^*$ pixarfilm pixarlog sgilog24 sgilog T43 T85 thunderscan

Limitations

OpenImageIO's TIFF reader and writer have some limitations you should be aware of:

• No separate per-channel data formats (not supported by libtiff).
• Only multiples of 8 bits per pixel may be passed through OpenImageIO's APIs, e.g., 1-, 2-, and 4-bits per pixel will be passed by OIIO as 8 bit images; 12 bits per pixel will be passed as 16, etc. But the oiio:BitsPerSample attribute in the ImageSpec will correctly report the original bit depth of the file. Similarly for output, you must pass 8 or 16 bit output, but oiio:BitsPerSample gives a hint about how you want it to be when written to the file, and it will try to accommodate the request (for signed integers, TIFF output can accommodate 2, 4, 8, 10, 12, and 16 bits).
• JPEG compression is limited to 8-bit per channel, 3-channel files.

TIFF Attributes

ImageSpec Attribute	Type	TIFF header data or explanation
ImageSpec::x	int	XPosition
ImageSpec::y	int	YPosition
ImageSpec::full_width	int	PIXAR_IMAGEFULLWIDTH
ImageSpec::full_length	int	PIXAR_IMAGEFULLLENGTH
ImageDescription	string	ImageDescription
DateTime	string	DateTime
Software	string	Software
Artist	string	Artist
Copyright	string	Copyright
Make	string	Make
Model	string	Model
DocumentName	string	DocumentName
HostComputer	string	HostComputer
XResultion, YResolution	float	XResolution, YResolution
ResolutionUnit	string	ResolutionUnit (in or cm).
Orientation	int	Orientation
ICCProfile	uint8[]	The ICC color profile
textureformat	string	PIXAR_TEXTUREFORMAT
wrapmodes	string	PIXAR_WRAPMODES
fovcot	float	PIXAR_FOVCOT
worldtocamera	matrix	PIXAR_MATRIX_WORLDTOCAMERA
worldtoscreen	matrix	PIXAR_MATRIX_WORLDTOSCREEN
compression	string	based on TIFF Compression (one of none, lzw, zip, or others listed above).
tiff:compression	int	the original integer code from the TIFF Compression tag.
tiff:planarconfig	string	PlanarConfiguration (separate or contig). The OpenImageIO TIFF writer will honor such a request in the ImageSpec.
tiff:PhotometricInterpretation	int	Photometric
tiff:PageName	string	PageName
tiff:PageNumber	int	PageNumber
tiff:RowsPerStrip	int	RowsPerStrip
tiff:subfiletype	int	SubfileType
Exif:*		A wide variety of EXIF data are honored, and are all prefixed with Exif.
oiio:BitsPerSample	int	The actual bits per sample in the file (may differ from ImageSpec::format).
oiio:UnassociatedAlpha	int	Nonzero if the alpha channel contained "unassociated" alpha.

Webp

FIXME

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

ImageSpec Attribute	Type	Zfile header data or explanation
worldtocamera	matrix	NP
worldtoscreen	matrix	Nl