<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!--Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. This code is free software; you can redistribute it and/or modify itunder the terms of the GNU General Public License version 2 only, aspublished by the Free Software Foundation.  Oracle designates thisparticular file as subject to the "Classpath" exception as providedby Oracle in the LICENSE file that accompanied this code. This code is distributed in the hope that it will be useful, but WITHOUTANY WARRANTY; without even the implied warranty of MERCHANTABILITY orFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licenseversion 2 for more details (a copy is included in the LICENSE file thataccompanied this code). You should have received a copy of the GNU General Public License version2 along with this work; if not, write to the Free Software Foundation,Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USAor visit www.oracle.com if you need additional information or have anyquestions.--> <title>JPEG Metadata Format Specification and Usage Notes</title></head> <body bgcolor="white"> <center><h1>JPEG Metadata Format Specification and Usage Notes</h1></center> <p><a href=#metadata>JPEG Metadata</a><br><a href=#abbrev>Abbreviated Streams</a><br><a href=#tables>Sources of Tables</a><br><a href=#color>Colorspace Transformations and Conventional Markers</a><br><a href=#thumbs>Thumbnail Images</a><br><a href=#prog>Progressive Encoding</a><br><a href=#tree>Native Metadata Format Tree Structure and Editing</a><br><a href=#image>Image Metadata DTD</a><br><a href=#stream>Stream Metadata DTD</a><p><bold>NOTE</bold>: It is important to call <code>dispose()</code> on the JPEG reader and writer objects when they are no longer needed, as they consume significant native resources which are not adequately recovered by garbage collection.  Both reader and writer call <code>dispose()</code> in their finalizers, but those finalizers may not be called before the native code has exhausted native memory. <p> The JPEG writer does not support replacing pixels. <p><h2><a name=metadata>JPEG Metadata</a></h2>JPEG metadata consists of the data contained in marker segments in a JPEGstream.  The image metadata object returned from a read describes thecontents of the marker segments between the <code>SOI</code> marker and the <code>EOI</code> marker for that image.  The image metadata object passed into a write determines the contents of the stream between the <code>SOI</code> marker and the <code>EOI</code> marker for that image, subject to the controls in any <code>ImageWriteParam</code>. <p>Stream metadata is used only for tables-only images found (or to be placed) at the beginning of a stream containing abbreviated images.  Tables-only images are not treated as images and do not consume an image index.  The stream metadata object returned from a read describes thecontents of the marker segments between the <code>SOI</code> marker and the <code>EOI</code> marker for the single tables-only image at the beginning of the stream, if one is present.  If no tables-only image is present at the front of the stream, the <code>getStreamMetadata</code> method of <code>ImageReader</code> returns <code>null</code>.  If stream metadata is provided to the writer, a single tables-only image containing the tables from the stream metadata object will be written at the beginning of the stream.  If the stream metadata object contains notables, default tables will be written.  As the sole purpose of streammetadata is for specifying tables-only images at the front of abbreviated streams, the stream metadata argument is useful only on the <code>ImageWriter.prepareWriteSequence</code> method.  It is ignored on all other methods. <p> The <code>ImageWriter.getDefaultStreamMetadata</code> method returns an object containing the tables from the <code>ImageWriteParam</code> argument, if it is a <code>JPEGImageWriteParam</code> and contains tables.  Otherwise, the returned object will contain default tables. <p>The <code>ImageWriter.getDefaultImageMetadata</code> method returns a metadata object containing <bold>no</bold> tables if the <code>ImageWriteParam</code> argument contains tables.  Otherwise the returned metadata object will contain default visually lossless tables.  Of course, only a <code>JPEGImageWriteParam</code> may contain tables. <p>If <code>ignoreMetadata</code> is set to <code>true</code> when the inputis set on the reader, stream metadata will not be available, but imagemetadata will. <p><h2><a name=abbrev>Abbreviated Streams</a></h2>Both the reader and the writer retain their tables from one operation to the next, thus permitting the use of abbreviated streams quite naturally, with a few minor restrictions:  <ol>  <li> Abbreviated streams may contain only one tables-only image, which must        come first in the stream.  Subsequent tables-only images will cause       undefined behavior.</li>  <li> Abbreviated streams must be read fully and in order.  No random access       is allowed, in either direction.  The same image may be read multiple        times.  If a call is made with an image index that is not the same as       or one greater than the most recent call (or 0 if no calls have been       made), then an <code>IllegalArgumentException</code> is thrown.</li></ol>These restrictions mean that streams may contain abbreviated images interspersed with images containing tables.  As required by JPEG, any tablesappearing in the stream override previous tables, regardless of the sourceof the previous tables.   <p>Note that once a tables-only image has been read, it's contents is availableas stream metadata from the reader until either another tables-only imageis read from another stream or the reader is reset.  Changing the input doesnot reset the stream metadata.  This is useful for reading the tables fromone file, then changing the input to read an abbreviated stream containing a sequence of images.  The tables will be used automatically, and will remainavailable as "stream" metadata. <p>Abbreviated streams are written using the sequence methods of <code>ImageWriter</code>.  Stream metadata is used to write a tables-only image at the beginning of the stream, and the tables are set up for use, using<code>ImageWriter.prepareWriteSequence</code>.  If no stream metadata is supplied to <code>ImageWriter.prepareWriteSequence</code>, then no tables-only image is written.  If stream metadata containing no tables issupplied to <code>ImageWriter.prepareWriteSequence</code>, then a tables-onlyimage containing default visually lossless tables is written. <h2><a name=tables>Sources of Tables</a></h2><p>Images are written with tables if tables are present in their metadata objects or without them if no tables are present in their metadata objects.  If nometadata object is present then the tables are written.  The tables used for compression are taken from one of the following sources, which are consulted in order: <ol>  <li> If there is an <code>ImageWriteParam</code> and the compression mode is       set to <code>EXPLICIT</code>, default tables constructed using the       quality setting are used.  They are written only if the metadata        contains tables or if there is no metadata, but they replace the        tables in the metadata.</li>  <li> If there is an <code>ImageWriteParam</code> and the compression mode is       set to <code>DEFAULT</code>, default visually lossles tables are used.       They are written only if the metadata contains tables or if       there is no metadata, but they replace the tables in the       metadata.</li>  <li> Otherwise the compression mode on the <code>ImageWriteParam</code> must       be MODE_COPY_FROM_<code>METADATA</code>, in which case the following       are used:    <ol>      <li> the tables in the image metadata, if present</li>      <li> the tables in the stream metadata, if present</li>      <li> the tables in the <code>JPEGImageWriteParam</code>, if present</li>      <li> default visually lossless tables</li>    </ol> Tables are written only if they are taken from image metadata.  </li></ol> This ordering implements the design intention that tables should be included in <code>JPEGImageWriteParam</code>s only as a means of specifying tables when no other source is available, and this can occur only when writing to anabbreviated stream without tables using known non-standard tables for compression. <p>When reading, tables in a <code>JPEGImageReadParam</code> are consulted only if tables have not been set by any previous read.  Tables set from a <code>JPEGImageReadParam</code> are overridden by any tables present in the stream being read. <p>Note that if no image metadata object is specified for a particular image, a default object is used, which includes default tables. <p><h2><a name=color>Colorspace Transformations and Conventional Markers</a></h2>Colorspace transformations are controlled by the destination type forboth reading and writing of images.  When <code>Raster</code>s areread, no colorspace transformation is performed, and any destination type is ignored.  A warning is sent to any listeners if a destination type is specified in this case.  When <code>Raster</code>s are written, any destination type is used to interpret the bands.  This might result in aJFIF or Adobe header being written, or different component ids being written to the frame and scan headers.  If values present in a metadata object do not match the destination type, the destination type is used and a warning is sent to any listeners. <p> <a name=optcolor><b>Optional ColorSpace support:</b></a>Handling of PhotoYCC (YCC), PhotoYCCA (YCCA), RGBA and YCbCrA color spacesby the standard plugin, as described below, is dependent on capabilitiesof the libraries used to interpret the JPEG data. Thus all consequentialbehaviors are optional. If the support is not available when decoding,the color space will be treated as unrecognized and the appropriatedefault color space for the specified number of component channelsmay be used.When writing, an Exception may be thrown if no suitable conversioncan be applied before encoding.But where the support for these color spaces is available, the behaviormust be as documented. <p> When reading, the contents of the stream are interpreted by the usualJPEG conventions, as follows: <ul>  <li> If a JFIF <code>APP0</code> marker segment is present, the colorspace       is known to be either grayscale or YCbCr.  If an <code>APP2</code>       marker segment containing an embedded ICC profile is also present, then       the YCbCr is converted to RGB according to the formulas given in the       JFIF spec, and the ICC profile is assumed to refer to the resulting RGB       space.  <p>  <li> If an Adobe <code>APP14</code> marker segment is present, the        colorspace is determined by consulting the <code>transform</code> flag.       The <code>transform</code> flag takes one of three values:    <ul>      <li> 2 - The image is encoded as YCCK (implicitly converted from           CMYK on encoding).       <li> 1 - The image is encoded as YCbCr (implicitly converted from RGB           on encoding).       <li> 0 - Unknown.  3-channel images are assumed to be RGB, 4-channel            images are assumed to be CMYK.    </ul>   <p>  <li> If neither marker segment is present, the following procedure is       followed: Single-channel images are assumed to be grayscale, and       2-channel images are assumed to be grayscale with an alpha channel.       For 3- and 4-channel images, the component ids are consulted.  If these       values are 1-3 for a 3-channel image, then the image is assumed to be       YCbCr. Subject to the availability of the       <a href=#optcolor>optional color space support</a>       described above, if these values are 1-4 for a 4-channel image,       then the image is assumed to be YCbCrA.        If these values are > 4, they are checked        against the ASCII codes for 'R', 'G', 'B', 'A', 'C', 'c'.  These can        encode the following colorspaces:       <p>       <br>RGB       <br>RGBA       <br>YCC (as 'Y','C','c'), assumed to be PhotoYCC       <br>YCCA (as 'Y','C','c','A'), assumed to be PhotoYCCA       <p>       Otherwise, 3-channel subsampled images are assumed to be YCbCr,        3-channel non-subsampled images are assumed to be RGB, 4-channel        subsampled images are assumed to be YCCK, and 4-channel, non-subsampled       images are assumed to be CMYK.   <p>  <li> All other images are declared uninterpretable and an exception is       thrown if an attempt is made to read one as a        <code>BufferedImage</code>.  Such an image may be read only as a        <code>Raster</code>.  If an image is interpretable but there is no Java       <code>ColorSpace</code> available corresponding to the encoded        colorspace (<italic>e.g.</italic> YCbCr), then        <code>ImageReader.getRawImageType</code> will return <code>null</code>.</ul> Once an encoded colorspace is determined, then the target colorspace is determined as follows: <ul>  <li> If a destination type is not set, then the following default       transformations take place after upsampling: YCbCr (and YCbCrA) images        are converted to RGB (and RGBA) using the conversion provided by the       underlying IJG library and either the built-in sRGB        <code>ColorSpace</code> or a custom RGB <code>ColorSpace</code> object       based on an embedded ICC profile is used to create the output       <code>ColorModel</code>.  PhotoYCC and PhotoYCCA images are not       converted.  CMYK and YCCK images are currently not supported.</li>   <li> If a destination image or type is set, it is used as follows:       If the IJG library provides an appropriate conversion, it is used.       Otherwise the default library conversion is followed by a colorspace        conversion in Java.</li>   <li> Bands are selected AFTER any library colorspace conversion.  If a        subset of either source or destination bands is used, then the default        library conversions are used with no further conversion in Java,       regardless of any destination type.</li>   <li> An exception is thrown if an attempt is made to read an image in an        unsupported jpeg colorspace as a <code>BufferedImage</code>        (<italic>e.g.</italic> CMYK).  Such images may be read as       <code>Raster</code>s.  If an image colorspace is unsupported or       uninterpretable, then <code>ImageReader.getImageTypes</code> will       return an empty <code>Iterator</code>.   If a subset of the raw bands       are required, a <code>Raster</code> must be obtained first and the       bands obtained from that. </li></ul> <p>For writing, the color transformation to apply is determined asfollows: <p>If a subset of the source bands is to be written, no color conversion is performed.  Any destination, if set, must match the number of bands that will be written, and serves as an interpretation of the selected bands, rather than a conversion request.  This behavior is identical to that for <code>Raster</code>s.  If all the bands are to be written and an image (as opposed to a <code>Raster</code>) is being written, any destination type is ignored and a warning is sent to any listeners. <p>If a destination type is used and any aspect of the metadata object, if there is one, is not compatible with that type, the destination type is used, the metadata written is modified from that provided, and a warning is sent to listeners.  This includes the <code>app0JFIF</code> and <code>app14Adobe</code> nodes.  The component ids in the <code>sof</code> and <code>sos</code> nodes are not modified, however, as unless a <code>app0JFIF</code> node is present, any values may be used.<p> When a full image is written, a destination colorspace will be chosen based on the image contents and the metadata settings, according to the following algorithm: <p> If no metadata object is specified, then the following defaults apply: <ul>  <li> Grayscale images are written with a JFIF <code>APP0</code> marker       segment.  Grayscale images with alpha are written with no special       marker.  As required by JFIF, the component ids in the frame and       scan header is set to 1.   <li> RGB images are converted to YCbCr, subsampled in the chrominance       channels by half both vertically and horizontally, and written with a       JFIF <code>APP0</code> marker segment.  If the <code>ColorSpace</code>       of the image is based on an <code>ICCProfile</code> (it is an instance       of <code>ICC_ColorSpace</code>, but is not one of the standard built-in        <code>ColorSpaces</code>), then that profile is embedded in an        <code>APP2</code> marker segment.  As required by JFIF, the        component ids in the frame and scan headers are set to 1, 2, and 3.    <li> Subject to the <a href=#optcolor>optional library support</a>        described above,       RGBA images are converted to YCbCrA, subsampled in the       chrominance channels by half both vertically and horizontally, and       written without any special marker segments.  The component ids        in the frame and scan headers are set to 1, 2, 3, and 4.   <li> Subject to the <a href=#optcolor>optional library support</a>       described above,       PhotoYCC and YCCAimages are subsampled by half in the chrominance       channels both vertically and horizontally and written with an       Adobe <code>APP14</code> marker segment and 'Y','C', and 'c' (and       'A' if an alpha channel is present) as component ids in the frame        and scan headers.</ul> Default metadata objects for these image types will reflect these settings. <p> If a metadata object is specified, then the number of channels in theframe and scan headers must always match the number of bands to be written, or an exception is thrown.  <code>app0JFIF</code> and <code>app14Adobe</code> nodes may appear in the same metadata object only if the <code>app14Adobe</code> node indicates YCbCr, and the component ids are JFIF compatible (0-2).  The various image types are processed in the following ways: <br> (All multi-channel images are subsampled according to the sampling factors in the frame header node of the metadata object, regardless of color space.) <ul>  <li> Grayscale Images:    <ul>      <li> If an <code>app0JFIF</code> node is present in the metadata object,           a JFIF <code>APP0</code> marker segment is written.      <li> If an <code>app14Adobe</code> node is present in the metadata            object, it is checked for validity (<code>transform</code> must be           <code>UNKNOWN</code>) and written.      <li> If neither node is present in the metadata object, no special            marker segment is written.    </ul>   <li> Grayscale Images with an Alpha Channel:    <ul>      <li> If an <code>app0JFIF</code> node is present in the metadata object,           it is ignored and a warning is sent to listeners, as JFIF does not           support 2-channel images.      <li> If an <code>app14Adobe</code> node is present in the metadata           object, it is checked for validity (<code>transform</code> must be           <code>UNKNOWN</code>) and written.  If <code>transform</code> is           not <code>UNKNOWN</code>, a warning is sent to listeners and the           correct transform is written.      <li> If neither node is present in the metadata object, no special            marker segment is written.    </ul>   <li> RGB Images:    <ul>      <li> If an <code>app0JFIF</code> node is present in the metadata object,           the image is converted to YCbCr and written with a JFIF            <code>APP0</code> marker segment.  If the <code>ColorSpace</code>           of the image is based on a non-standard ICC Profile, then that           profile is embedded in an <code>APP2</code> marker segment.  If the           <code>ColorSpace</code> is not based on a non-standard ICC Profile,           but an <code>app2ICC</code> node appears in the metadata, then an           <code>APP2</code> marker segment is written with the appropriate           standard profile.  Note that the profile must specify an RGB color           space, as the file must be JFIF compliant.       <li> If an <code>app14Adobe</code> node is present in the metadata           object, the image is converted according to the color transform           setting and written with an Adobe <code>APP14</code> marker           segment.  Component ids are written just as they appear in the           frame and scan headers.  The color transform must be either YCbCr           or <code>UNKNOWN</code>.  If it is <code>UNKNOWN</code>, the image           is not color converted.       <li> If neither node is present, the component ids in the frame           header are consulted.  If these indicate a colorspace as described           above, then the image is converted to that colorspace if possible.             If the component ids do not indicate a colorspace, then the           sampling factors are consulted.  If the image is to be subsampled,           it is converted to YCbCr first.  If the image is not to be           subsampled, then no conversion is applied.  No special marker           segmentss are written.    </ul>   <li> RGBA images:       Subject to the <a href=#optcolor>optional library support</a>       described above,    <ul>      <li> If an <code>app0JFIF</code> node is present in the metadata object,           it is ignored and a warning is sent to listeners, as JFIF does not           support 4-channel images.       <li> If an <code>app14Adobe</code> node is present in the metadata           object, the image is written with an Adobe <code>APP14</code> marker           segment.  No colorspace conversion is performed.  Component ids           are written just as they appear in the frame and scan  headers.           The color transform must be <code>UNKNOWN</code>.  If it is            not, a warning is sent to listeners.       <li> If no <code>app14Adobe</code> node is present, the component ids in           the frame header are consulted.  If these indicate a colorspace as           described above, then the image is converted to that colorspace if           possible.  If the component ids do not indicate a colorspace, then           the sampling factors are consulted.  If the image is to be           subsampled, it is converted to YCbCrA.  If the image is not to be           subsampled, then no conversion is applied.  No special marker           segments are written.    </ul>   <li> PhotoYCC Images:       Subject to the <a href=#optcolor>optional library support</a>       described above,    <ul>      <li> If an <code>app0JFIF</code> node is present in the metadata object,           the image is converted to sRGB, and then to YCbCr during encoding,           and a JFIF <code>APP0</code> marker segment is written.       <li> If an <code>app14Adobe</code> node is present in the metadata           object, no conversion is applied, and an Adobe <code>APP14</code>           marker segment is written.  The color transform must be YCC.  If it           is not, a warning is sent to listeners.       <li> If neither node is present in the metadata object, no conversion           is applied, and no special marker segment is written.    </ul>   <li> PhotoYCCA Images:       Subject to the <a href=#optcolor>optional library support</a>       described above,

Lines 1–500 of 1175. Load more