\chapter{Metadata conventions}
\label{chap:stdmetadata}


The \ImageSpec class, described thoroughly in
Section~\ref{sec:ImageSpec}, provides the basic description of an image
that are essential across all formats --- resolution, number of
channels, pixel data format, etc.  Individual images may have additional
data, stored as name/value pairs in the {\cf extra_attribs} field.
Though literally \emph{anything} can be stored in {\cf extra_attribs}
--- it's specifically designed for format- and user-extensibility ---
this chapter establishes some guidelines and lays out all of the field
names that \product understands.


\section{Description of the image}

\apiitem{"ImageDescription" : string}
The image description, title, caption, or comments.
\apiend

\apiitem{"Keywords" : string}

Semicolon-separated keywords describing the contents of the image.
(Semicolons are used rather than commas because of the common case
of a comma being part of a keyword itself, e.g., ``Kurt Vonnegut, Jr.''
or ``Washington, DC.'')
\apiend

\apiitem{"Artist" : string}
The artist, creator, or owner of the image.
\apiend

\apiitem{"Copyright" : string}
Any copyright notice or owner of the image.
\apiend

\apiitem{"DateTime" : string}
The creation date of the image, in the following format: {\cf YYYY:MM:DD
  HH:MM:SS} (exactly 19 characters long, not including a terminating
NULL).  For example, 7:30am on Dec
31, 2008 is encoded as \qkw{2008:12:31 07:30:00}.
\apiend

\apiitem{"DocumentName" : string}
The name of an overall document that this image is a part of.
\apiend

\apiitem{"Software" : string}
The software that was used to create the image.
\apiend

\apiitem{"HostComputer" : string}
The name or identity of the computer that created the image.
\apiend

\section{Display hints}
\label{metadata:displayhints}

\apiitem{"oiio:ColorSpace" : string}
The name of the color space of the color channels.  Values incude:
\qkw{Linear}, \qkw{sRGB}, \qkw{GammaCorrected}, \qkw{AdobeRGB},
\qkw{Rec709}, and \qkw{KodakLog}.
\apiend

\apiitem{"oiio:Gamma" : float}
If the color space is \qkw{GammaCorrected}, this value is the gamma
exponent.
\apiend

\apiitem{"oiio:BorderColor" : float[nchannels]}
The color presumed to be filling any parts of the display/full image
window that are not overlapping the pixel data window.  If not supplied,
the default is black (0 in all channels).
\apiend

\apiitem{"Orientation" : int}
\index{Orientation}
\label{metadata:orientation}

By default, image pixels are ordered from the top of the display to the
bottom, and within each scanline, from left to right (i.e., the same
ordering as English text and scan progression on a CRT).  But the
\qkw{Orientation} field can suggest that it should be displayed with
a different orientation, according to the TIFF/EXIF conventions:

\begin{tabular}{p{0.3in} p{4in}}
1 & normal (top to bottom, left to right)  \\
2 & flipped horizontally (top to botom, right to left)  \\
3 & rotate $180^\circ$ (bottom to top, right to left) \\
4 & flipped vertically (bottom to top, left to right)  \\
5 & transposed (left to right, top to bottom) \\
6 & rotated $90^\circ$ clockwise (right to left, top to bottom) \\
7 & transverse (right to left, bottom to top) \\
8 & rotated $90^\circ$ counter-clockwise (left to right, bottom to top) \\
\end{tabular}
\apiend

\apiitem{"PixelAspectRatio" : float}
The aspect ratio ($x/y$) of the individual pixels, with square pixels
being 1.0 (the default).
\apiend

\apiitem{"XResolution" : float \\
"YResolution" : float \\
"ResolutionUnit" : string}
The number of horizontal ($x$) and vertical ($y$) pixels per 
resolution unit.  This ties the image to a physical size (where 
applicable, such as with a scanned image, or an image that will
eventually be printed).

Different file formats may dictate different resolution units.
For example, the TIFF ImageIO plugin supports \qkw{none}, \qkw{in}, 
and \qkw{cm}.
\apiend

\section{Disk file format info/hints}

\apiitem{"oiio:BitsPerSample" : int}
Number of bits per sample \emph{in the file}.  

Note that this may not match the reported {\cf ImageSpec::format}, if
the plugin is translating from an unsupported format.  For example, if a
file stores 4 bit grayscale per channel, the {\cf "oiio:BitsPerSample"} may
be 4 but the {\cf format} field may be {\cf TypeDesc::UINT8} (because
the \product APIs do not support fewer than 8 bits per sample).
\apiend

\apiitem{"oiio:UnassociatedAlpha" : int}
Whether the data in the file stored alpha channels (if any) that were
unassociated with the color (i.e., color not ``premultiplied'' by the
alpha coverage value).
\apiend

\apiitem{"planarconfig" : string}
\qkw{contig} indicates that the file has contiguous pixels (RGB RGB
RGB...), whereas \qkw{separate} indicate that the file stores each
channel separately (RRR...GGG...BBB...).

Note that only contiguous pixels are transmitted through the \product
APIs, but this metadata indicates how it is (or should be) stored in the
file, if possible.
\apiend

\apiitem{"compression" : string}
Indicates the type of compression the file uses.  Supported compression
modes will vary from \ImageInput plugin to plugin, and each plugin
should document the modes it supports.  If {\cf ImageInput::open} is
called with an \ImageSpec that specifies an compression mode not
supported by that \ImageInput, it will choose a reasonable default.
As an example, the TIFF \ImageInput plugin supports \qkw{none},
\qkw{lzw}, \qkw{ccittrle}, \qkw{zip} (the default), \qkw{packbits}.
\apiend

\apiitem{"CompressionQuality" : int}
Indicates the quality of compression to use (0--100), for those 
plugins and compression methods that allow a variable amount of 
compression, with higher numbers indicating higher image fidelity.
\apiend

\section{Photographs or scanned images}

The following metadata items are specific to photos or captured images.

\apiitem{"Make" : string}
For captured or scanned image, the make of the camera or scanner.
\apiend

\apiitem{"Model" : string}
For captured or scanned image, the model of the camera or scanner.
\apiend

\apiitem{"ExposureTime" : float}
The exposure time (in seconds) of the captured image.
\apiend

\apiitem{"FNumber" : float}
The f/stop of the camera when it captured the image.
\apiend

\section{Texture Information}

Several standard metadata are very helpful for images that are intended
to be used as textures (especially for \product's \TextureSystem).

\apiitem{"textureformat" : string}
The kind of texture that this image is intended to be.  We suggest the
following names:

\noindent \begin{tabular}{p{1.75in} p{3.25in}}
\qkw{Plain Texture} & Ordinary 2D texture \\
\qkw{Volume Texture} & 3D volumetric texture \\
\qkw{Shadow} & Ordinary $z$-depth shadow map \\
\qkw{CubeFace Shadow} & Cube-face shadow map \\
\qkw{Volume Shadow} & Volumetric (``deep'') shadow map \\
\qkw{LatLong Environment} & Latitude-longitude (rectangular) environment
map \\
\qkw{CubeFace Environment} & Cube-face environment map \\
\end{tabular}
\apiend

\apiitem{"wrapmodes" : string}
Give the intended texture \emph{wrap mode} indicating what happens with
texture coordinates outside the $[0...1]$ range.  We suggest the
following names: \qkw{black}, \qkw{periodic}, \qkw{clamp}, \qkw{mirror}.
If the wrap mode is different in each direction, they should simply be
separated by a comma.  For example, \qkw{black} means black wrap in both
directions, whereas \qkw{clamp,periodic} means to clamp in $u$ and be
periodic in $v$.
\apiend

\apiitem{"fovcot" : float}
The cotangent ($x/y$) of the field of view of the original image (which
may not be the same as the aspect ratio of the pixels of the texture,
which may have been resized).
\apiend

\apiitem{"worldtocamera" : matrix44}
For shadow maps or rendered images this item (of type {\cf TypeDesc::PT_MATRIX})
is the world-to-camera matrix describing the camera position.
\apiend

\apiitem{"worldtoscreen" : matrix44}
For shadow maps or rendered images this item (of type {\cf TypeDesc::PT_MATRIX})
is the world-to-screen matrix describing the full projection of the 3D
view onto a $[-1...1] \times [-1...1]$ 2D domain.
\apiend

\apiitem{"oiio:updirection" : string}
For environment maps, indicates which direction is ``up'' (valid values
are \qkw{y} or \qkw{z}), to disambiguate conventions for environment map
orientation.
\apiend

\apiitem{"oiio:sampleborder" : int}
If not present or 0 (the default), the conversion from pixel integer
coordinates $(i,j)$ to texture coordinates $(s,t)$ follows the usual
convention of $s = (i+0.5)/\mathit{xres}$ and $t = (j+0.5)/\mathit{yres}$.
However, if this attribute is present and nonzero, the first and last
row/column of pixels lie exactly at the $s$ or $t = 0$ or $1$
boundaries, i.e., $s = i/(\mathit{xres}-1)$ and $t = j/(\mathit{yres}-1)$.
\apiend


\section{Exif metadata}
\label{sec:metadata:exif}
\index{Exif metadata}

% FIXME -- unsupported/undocumented: ExifVersion, FlashpixVersion,
% ComponentsConfiguration, MakerNote, UserComment, RelatedSoundFile,
% OECF, SubjectArea, SpatialFrequencyResponse, 
% CFAPattern, DeviceSettingDescription
%
% SubjectLocation -- unsupported, but we could do it

The following Exif metadata tags correspond to items in the ``standard''
set of metadata.

\medskip

\begin{tabular}{p{1.5in} p{3.5in}}
{\bf Exif tag} & {\bf \product metadata convention} \\
\hline
ColorSpace & (reflected in \qkw{oiio:ColorSpace}) \\
ExposureTime & \qkw{ExposureTime} \\
FNumber & \qkw{FNumber} \\
\end{tabular}

\medskip

The other remaining Exif metadata tags all include the ``Exif:'' prefix
to keep it from clashing with other names that may be used for other
purposes.

\apiitem{"Exif:ExposureProgram" : int}
The exposure program used to set exposure when the picture was taken:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & unknown \\
1 & manual \\
2 & normal program \\
3 & aperture priority \\
4 & shutter priority \\
5 & Creative program (biased toward depth of field) \\
6 & Action program (biased toward fast shutter speed) \\
7 & Portrait mode (closeup photo with background out of focus) \\
8 & Landscape mode (background in focus)
\end{tabular}
\apiend

\apiitem{"Exif:SpectralSensitivity" : string}
The camera's spectral sensitivity, using the ASTM conventions.
\apiend

\apiitem{"Exif:ISOSpeedRatings" : int}
The ISO speed and ISO latitude of the camera as specified in ISO 12232.
\apiend

%\apiitem{"Exif:OECF",	TIFF_NOTYPE }	 // skip it
%\apiitem{"Exif:ExifVersion",	TIFF_NOTYPE }	 // skip it

\apiitem{"Exif:DateTimeOriginal" : string}
Date and time that the original image data was generated (in
\qkw{YYYY:MM:DD HH:MM:SS} format).
\apiend

\apiitem{"Exif:DateTimeDigitized" : string}
Date and time that the image was stored as digital data (in
\qkw{YYYY:MM:DD HH:MM:SS} format).
\apiend

%\apiitem{"Exif:ComponentsConfiguration",TIFF_UNDEFINED }
\apiitem{"Exif:CompressedBitsPerPixel" : float }
The compression mode used, measured in compressed bits per pixel.
\apiend

\apiitem{"Exif:ShutterSpeedValue" : float }
Shutter speed, in APEX units: $-\log_2 (\mathit{exposure time})$
\apiend

\apiitem{"Exif:ApertureValue" : float }
Aperture, in APEX units: $2 \log_2 (\mathit{fnumber})$
\apiend

\apiitem{"Exif:BrightnessValue" : float }
Brightness value, assumed to be in the range of $-99.99$ -- $99.99$.
\apiend

\apiitem{"Exif:ExposureBiasValue" : float }
Exposure bias, assumed to be in the range of $-99.99$ -- $99.99$.
\apiend

\apiitem{"Exif:MaxApertureValue" : float }
Smallest F number of the lens, in APEX units: $2 \log_2 (\mathit{fnumber})$
\apiend

\apiitem{"Exif:SubjectDistance" : float }
Distance to the subject, in meters.
\apiend

\apiitem{"Exif:MeteringMode" : int}
The metering mode:

\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & unknown \\
1 & average \\
2 & center-weighted average \\
3 & spot \\
4 & multi-spot \\
5 & pattern \\
6 & partial \\
255 & other
\end{tabular}
\apiend

\apiitem{"Exif:LightSource" : int}
The kind of light source:

\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & unknown \\
1 & daylight \\
2 & tungsten (incandescent light) \\
4 & flash \\
9 & fine weather \\
10 & cloudy weather \\
11 & shade \\
12 & daylight fluorescent (D 5700-7100K) \\
13 & day white fluorescent (N 4600-5400K) \\
14 & cool white fuorescent (W 3900 - 4500K) \\
15 & white fluorescent (WW 3200 - 3700K) \\
17 & standard light A \\
18 & standard light B \\
19 & standard light C \\
20 & D55 \\
21 & D65 \\
22 & D75 \\
23 & D50 \\
24 & ISO studio tungsten \\
255 & other light source
\end{tabular}
\apiend

\apiitem{"Exif:Flash" int}
A sum of:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
1 & if the flash fired \\
\hline
0 & no strobe return detection function \\
4 & strobe return light was not detected \\
6 & strobe return light was detected \\
\hline
8 & compulsary flash firing \\
16 & compulsary flash supression \\
24 & auto-flash mode \\
\hline 
32 & no flash function (0 if flash function present) \\
\hline
64 & red-eye reduction supported (0 if no red-eye reduction mode) 
\end{tabular}

\apiend

\apiitem{"Exif:FocalLength" : float }
Actual focal length of the lens, in mm.
\apiend

\apiitem{"Exif:SecurityClassification" : string}
Security classification of the image: `C' = confidential,
`R' = restricted, `S' = secret, `T' = top secret,
`U' = unclassified.
\apiend

\apiitem{"Exif:ImageHistory" : string}
Image history.
\apiend


%\apiitem{"Exif:SubjectArea",TIFF_NOTYPE } // skip
%\apiitem{"Exif:MakerNote",TIFF_NOTYPE } // skip it
%\apiitem{"Exif:UserComment",TIFF_NOTYPE }// skip it

\apiitem{"Exif:SubsecTime" : string}
Fractions of a second to augment the \qkw{DateTime} (expressed
as text of the digits to the right of the decimal).
\apiend

\apiitem{"Exif:SubsecTimeOriginal" : string}
Fractions of a second to augment the \qkw{Exif:DateTimeOriginal} (expressed
as text of the digits to the right of the decimal).
\apiend

\apiitem{"Exif:SubsecTimeDigitized" : string}
Fractions of a second to augment the \qkw{Exif:DateTimeDigital} (expressed
as text of the digits to the right of the decimal).
\apiend

%\apiitem{"Exif:FlashPixVersion",TIFF_NOTYPE }

\apiitem{"Exif:PixelXDimension" : int \\
"Exif:PixelYDimension" : int }
The $x$ and $y$ dimensions of the valid pixel area.
FIXME -- better explanation?
\apiend

%\apiitem{"Exif:RelatedSoundFile", TIFF_NOTYPE }// skip

\apiitem{"Exif:FlashEnergy" : float }
Strobe energy when the image was captures, measured in Beam Candle Power
Seconds (BCPS).
\apiend

%\apiitem{"Exif:SpatialFrequencyResponse",TIFF_NOTYPE }

\apiitem{"Exif:FocalPlaneXResolution" : float \\
"Exif:FocalPlaneYResolution" : float \\
"Exif:FocalPlaneResolutionUnit" : int} 
The number of pixels in the $x$ and $y$ dimension, per resolution unit.
The codes for resolution units are:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
1 & none \\
2 & inches \\
3 & cm \\
4 & mm \\
5 & $\mu$m \\
\end{tabular}
\apiend


%\apiitem{"Exif:SubjectLocation" : int} // FIXME: short[2]

\apiitem{"Exif:ExposureIndex" : float }
The exposure index selected on the camera.
\apiend

\apiitem{"Exif:SensingMethod" : int}
The image sensor type on the camra:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
1 & undefined \\
2 & one-chip color area sensor \\
3 & two-chip color area sensor \\
4 & three-chip color area sensor \\
5 & color sequential area sensor \\
7 & trilinear sensor \\
8 & color trilinear sensor 
\end{tabular}
\apiend

\apiitem{"Exif:FileSource" : int}
The source type of the scanned image, if known:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
1 & film scanner \\
2 & reflection print scanner \\
3 & digital camera \\
\end{tabular}
\apiend

\apiitem{"Exif:SceneType" : int}
Set to 1, if a directly-photographed image, otherwise it should not be
present.
\apiend

%\apiitem{"Exif:CFAPattern",TIFF_NOTYPE }

\apiitem{"Exif:CustomRendered" : int}
Set to 0 for a normal process, 1 if some custom processing has been
performed on the image data.
\apiend

\apiitem{"Exif:ExposureMode" : int}
The exposure mode:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & auto \\
1 & manual \\
2 & auto-bracket
\end{tabular}
\apiend

\apiitem{"Exif:WhiteBalance" : int}
Set to 0 for auto white balance, 1 for manual white balance.
\apiend

\apiitem{"Exif:DigitalZoomRatio" : float }
The digital zoom ratio used when the image was shot.
\apiend

\apiitem{"Exif:FocalLengthIn35mmFilm" : int}
The equivalent focal length of a 35mm camera, in mm.
\apiend

\apiitem{"Exif:SceneCaptureType" : int}
The type of scene that was shot:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & standard \\
1 & landscape \\
2 & portrait \\
3 & night scene
\end{tabular}
\apiend

\apiitem{"Exif:GainControl" : float }
The degree of overall gain adjustment:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & none \\
1 & low gain up \\
2 & high gain up \\
3 & low gain down \\
4 & high gain down
\end{tabular}
\apiend

\apiitem{"Exif:Contrast" : int}
The direction of contrast processing applied by the camera:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & normal \\
1 & soft \\
2 & hard
\end{tabular}
\apiend

\apiitem{"Exif:Saturation" : int}
The direction of saturation processing applied by the camera:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & normal \\
1 & low saturation \\
2 & high saturation
\end{tabular}
\apiend

\apiitem{"Exif:Sharpness" : int}
The direction of sharpness processing applied by the camera:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & normal \\
1 & soft \\
2 & hard
\end{tabular}
\apiend

%\apiitem{"Exif:DeviceSettingDescription",TIFF_NOTYPE }

\apiitem{"Exif:SubjectDistanceRange" : int}
The distance to the subject:
\smallskip

\begin{tabular}{p{0.3in} p{4in}}
0 & unknown \\
1 & macro \\
2 & close \\
3 & distant
\end{tabular}
\apiend

\apiitem{"Exif:ImageUniqueID" : string}
A unique identifier for the image, as 16 ASCII hexidecimal digits 
representing a 128-bit number.
\apiend


\section{GPS Exif metadata}
\label{sec:metadata:GPS}
\index{GPS metadata}

The following GPS-related Exif metadata tags correspond to items in the
``standard'' set of metadata.

%\apiitem{"GPS:VersionID" : int}
%\apiend

\apiitem{"GPS:LatitudeRef" : string}
Whether the \qkw{GPS:Latitude} tag refers to north or south: \qkw{N} or 
\qkw{S}.
\apiend

\apiitem{"GPS:Latitude" : float[3]}
The degrees, minutes, and seconds of latitude (see also \qkw{GPS:LatitudeRef}).
\apiend

\apiitem{"GPS:LongitudeRef" : string}
Whether the \qkw{GPS:Longitude} tag refers to east or west: \qkw{E} or 
\qkw{W}.
\apiend

\apiitem{"GPS:Longitude" : float[3]}
The degrees, minutes, and seconds of longitude (see also 
\qkw{GPS:LongitudeRef}).
\apiend

\apiitem{"GPS:AltitudeRef" : string}
A value of 0 indicates that the altitude is above sea level, 1 indicates
below sea level.
\apiend

\apiitem{"GPS:Altitude" : float}
Absolute value of the altitude, in meters, relative to sea level 
(see \qkw{GPS:AltitudeRef} for whether it's above or below sea level).
\apiend

\apiitem{"GPS:TimeStamp" : float[3]}
Gives the hours, minutes, and seconds, in UTC.
\apiend

\apiitem{"GPS:Satellites" : string}
Information about what satellites were visible.
\apiend

\apiitem{"GPS:Status" : string}
\qkw{A} indicates a measurement in progress, \qkw{V} indicates
measurement interoperability.
\apiend

\apiitem{"GPS:MeasureMode" : string}
\qkw{2} indicates a 2D measurement, \qkw{3} indicates a 3D measurement.
\apiend

\apiitem{"GPS:DOP" : float}
Data degree of precision.
\apiend

\apiitem{"GPS:SpeedRef" : string}
Indicates the units of the related \qkw{GPS:Speed} tag: 
\qkw{K} for km/h, \qkw{M} for miles/h, \qkw{N} for knots.
\apiend

\apiitem{"GPS:Speed" : float}
Speed of the GPS receiver (see \qkw{GPS:SpeedRef} for the units).
\apiend

\apiitem{"GPS:TrackRef" : string}
Describes the meaning of the \qkw{GPS:Track} field: \qkw{T} for true
direction, \qkw{M} for magnetic direction.
\apiend

\apiitem{"GPS:Track" : float}
Direction of the GPS receiver movement (from 0--359.99).  The
related \qkw{GPS:TrackRef} indicate whether it's true or magnetic.
\apiend

\apiitem{"GPS:ImgDirectionRef" : string}
Describes the meaning of the \qkw{GPS:ImgDirection} field: \qkw{T} for true
direction, \qkw{M} for magnetic direction.
\apiend

\apiitem{"GPS:ImgDirection" : float}
Direction of the image when captured (from 0--359.99).  The
related \qkw{GPS:ImgDirectionRef} indicate whether it's true or magnetic.

\apiend

\apiitem{"GPS:MapDatum" : string}
The geodetic survey data used by the GPS receiver.
\apiend

\apiitem{"GPS:DestLatitudeRef" : string}
Whether the \qkw{GPS:DestLatitude} tag refers to north or south: \qkw{N} or 
\qkw{S}.
\apiend

\apiitem{"GPS:DestLatitude" : float[3]}
The degrees, minutes, and seconds of latitude of the destination (see also 
\qkw{GPS:DestLatitudeRef}).
\apiend

\apiitem{"GPS:DestLongitudeRef" : string}
Whether the \qkw{GPS:DestLongitude} tag refers to east or west: \qkw{E} or 
\qkw{W}.
\apiend

\apiitem{"GPS:DestLongitude" : float[3]}
The degrees, minutes, and seconds of longitude of the destination (see also 
\qkw{GPS:DestLongitudeRef}).
\apiend

\apiitem{"GPS:DestBearingRef" : string}
Describes the meaning of the \qkw{GPS:DestBearing} field: \qkw{T} for true
direction, \qkw{M} for magnetic direction.
\apiend

\apiitem{"GPS:DestBearing" : float}
Bearing to the destination point (from 0--359.99).  The
related \qkw{GPS:DestBearingRef} indicate whether it's true or magnetic.
\apiend

\apiitem{"GPS:DestDistanceRef" : string}
Indicates the units of the related \qkw{GPS:DestDistance} tag: 
\qkw{K} for km, \qkw{M} for miles, \qkw{N} for knots.
\apiend

\apiitem{"GPS:DestDistance" : float}
Distance to the destination (see \qkw{GPS:DestDistanceRef} for the units).
\apiend

\apiitem{"GPS:ProcessingMethod" : string}
Processing method information.
\apiend

\apiitem{"GPS:AreaInformation" : string}
Name of the GPS area.
\apiend

\apiitem{"GPS:DateStamp" : string}
Date according to the GPS device, in format \qkw{YYYY:MM:DD}.
\apiend

\apiitem{"GPS:Differential" : int}
If 1, indicates that differential correction was applied.
\apiend

\apiitem{"GPS:HPositioningError" : float}
Positioning error.
\apiend



\section{IPTC metadata}
\label{sec:metadata:iptc}
\index{IPTC metadata}

The IPTC (International Press Telecommunications Council) publishes
conventions for storing image metadata, and this standard is growing
in popularity and is commonly used in photo-browsing programs to
record captions and keywords.

The following IPTC metadata items correspond exactly to metadata in the
\product conventions, so it is recommended that you use the standards
and that plugins supporting IPTC metadata respond likewise:

\medskip

\begin{tabular}{p{1.5in} p{3.5in}}
{\bf IPTC tag} & {\bf \product metadata convention} \\
\hline
Caption & \qkw{ImageDescription} \\[0.5ex]
Keyword & IPTC keywords should be concatenated, separated by semicolons
({\cf ;}), and stored as the \qkw{Keywords} attribute. \\[0.5ex]
ExposureTime & \qkw{ExposureTime} \\[0.5ex]
CopyrightNotice & \qkw{Copyright} \\[0.5ex]
Creator & \qkw{Artist} \\
\end{tabular}

\bigskip

The remainder of IPTC metadata fields should use the following names,
prefixed with ``IPTC:'' to avoid conflicts with other plugins or
standards.

\apiitem{"IPTC:ObjecTypeReference" : string}
Object type reference.
\apiend

\apiitem{"IPTC:ObjectAttributeReference" : string}
Object attribute reference.
\apiend

\apiitem{"IPTC:ObjectName" : string}
The name of the object in the picture.
\apiend

\apiitem{"IPTC:EditStatus" : string}
Edit status.
\apiend

\apiitem{"IPTC:SubjectReference" : string}
Subject reference.
\apiend

\apiitem{"IPTC:Category" : string}
Category.
\apiend

% \apiitem{  25, "Keywords" : string}
%\apiend
% FIXME

\apiitem{"IPTC:ContentLocationCode" : string}
Code for content location.
\apiend

\apiitem{"IPTC:ContentLocationName" : string}
Name of content location.
\apiend

\apiitem{"IPTC:ReleaseDate" : string \\
"IPTC:ReleaseTime" : string}
Release date and time.
\apiend

\apiitem{"IPTC:ExpirationDate" : string \\
"IPTC:ExpirationTime" : string}
Expiration date and time.
\apiend

\apiitem{"IPTC:Instructions" : string}
Special instructions for handling the image.
\apiend

\apiitem{"IPTC:ReferenceService" : string \\
"IPTC:ReferenceDate" : string \\
"IPTC:ReferenceNumber" : string}
Reference date, service, and number.
\apiend

\apiitem{"IPTC:DateCreated" : string \\
"IPTC:TimeCreated" : string}
Date and time that the image was created.
\apiend

\apiitem{"IPTC:DigitalCreationDate" : string \\
"IPTC:DigitalCreationTime" : string}
Date and time that the image was digitized.
\apiend


%\apiitem{"IPTC:Creator" : string}
%The creator of the image.  This is optinal and, If present, 
%is expected to be the same as the data in the standard \qkw{Artist} field.
%\apiend

\apiitem{"IPTC:ProgramVersion" : string}
The version number of the creation software.
\apiend

\apiitem{"IPTC:AuthorsPosition" : string}
The job title or position of the creator of the image.
\apiend

\apiitem{"IPTC:City" : string \\
"IPTC:Sublocation" : string \\
"IPTC:State" : string \\
"IPTC:Country" : string \\
"IPTC:CountryCode" : string}
The city, sublocation within the city,
state, country, and country code of the location of the image.
\apiend

\apiitem{"IPTC:Headline" : string}
Any headline that is meant to accompany the image.
\apiend

\apiitem{"IPTC:Provider" : string}
The provider of the image, or credit line.
\apiend

\apiitem{"IPTC:Source" : string}
The source of the image.
\apiend

%\apiitem{"IPTC:CopyrightNotice" : string}
%The copyright notice for the image.  This is optinal and, If present, 
%is expected to be the same as the data in the standard \qkw{Copyright} field.
%\apiend

\apiitem{"IPTC:Contact" : string}
The contact information for the image (possibly including name, address,
email, etc.).
\apiend

%\apiitem{"IPTC:Caption", string }
%The caption, abstract, or description of the image.
%This is optional and, if present, is expected to be the same as the
%data in the standard \qkw{ImageDescription} field.
%\apiend

\apiitem{"IPTC:CaptionWriter" : string}
The name of the person who wrote the caption or description of the image.
\apiend

\apiitem{"IPTC:JobID" : string \\
"IPTC:MasterDocumentID" : string \\
"IPTC:ShortDocumentID" : string \\
"IPTC:UniqueDocumentID" : string \\
"IPTC:OwnerID" : string }
Various identification tags.
\apiend

\apiitem{"IPTC:Prefs" : string \\
"IPTC:ClassifyState" : string \\
"IPTC:SimilarityIndex" : string}
Who knows what the heck these are?
\apiend

\apiitem{"IPTC:DocumentNotes" : string}
Notes about the image or document.
\apiend

\apiitem{"IPTC:DocumentHistory" : string}
The history of the image or document.
\apiend


\section{SMPTE metadata}
\label{sec:metadata:smpte}
\index{SMPTE metadata}

\apiitem{"smpte:TimeCode" : int[2]}
SMPTE time code, encoded as an array of 2 32-bit integers (as a
\TypeDesc, it will be tagged with vecsemantics {\cf TIMECODE}).
\apiend

\apiitem{"smpte:KeyCode" : int[7]}
SMPTE key code, encoded as an array of 7 32-bit integers (as a
\TypeDesc, it will be tagged with vecsemantics {\cf KEYCODE}).
\apiend




\section{Extension conventions}

To avoid conflicts with other plugins, or with any additional standard
metadata names that may be added in future verions of \product, it is
strongly advised that writers of new plugins should prefix their
metadata with the name of the format, much like the \qkw{Exif:}
and \qkw{IPTC:} metadata.


\chapwidthend
