1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <!--
   5 Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
   6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   7 
   8 This code is free software; you can redistribute it and/or modify it
   9 under the terms of the GNU General Public License version 2 only, as
  10 published by the Free Software Foundation.  Oracle designates this
  11 particular file as subject to the "Classpath" exception as provided
  12 by Oracle in the LICENSE file that accompanied this code.
  13 
  14 This code is distributed in the hope that it will be useful, but WITHOUT
  15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  16 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17 version 2 for more details (a copy is included in the LICENSE file that
  18 accompanied this code).
  19 
  20 You should have received a copy of the GNU General Public License version
  21 2 along with this work; if not, write to the Free Software Foundation,
  22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  23 
  24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  25 or visit www.oracle.com if you need additional information or have any
  26 questions.
  27 -->
  28 
  29 <title>JPEG Metadata Format Specification and Usage Notes</title>
  30 </head>
  31 
  32 <body bgcolor="white">
  33 
  34 <center><h1>
  35 JPEG Metadata Format Specification and Usage Notes
  36 </h1></center>
  37 
  38 <p>
  39 <a href=#metadata>JPEG Metadata</a><br>
  40 <a href=#abbrev>Abbreviated Streams</a><br>
  41 <a href=#tables>Sources of Tables</a><br>
  42 <a href=#color>Colorspace Transformations and Conventional Markers</a><br>
  43 <a href=#thumbs>Thumbnail Images</a><br>
  44 <a href=#prog>Progressive Encoding</a><br>
  45 <a href=#tree>Native Metadata Format Tree Structure and Editing</a><br>
  46 <a href=#image>Image Metadata DTD</a><br>
  47 <a href=#stream>Stream Metadata DTD</a>
  48 <p>
  49 <b>NOTE</b>: It is important to call <code>dispose()</code> 
  50 on the JPEG reader and writer objects when they are no longer needed, as 
  51 they consume significant native resources which are not adequately recovered 
  52 by garbage collection.  Both reader and writer call <code>dispose()</code> 
  53 in their finalizers, but those finalizers may not be called before the native 
  54 code has exhausted native memory.
  55 
  56 <p>
  57 
  58 The JPEG writer does not support replacing pixels.
  59 
  60 <h2>
  61 <a name=metadata>JPEG Metadata</a>
  62 </h2>
  63 JPEG metadata consists of the data contained in marker segments in a JPEG
  64 stream.  The image metadata object returned from a read describes the
  65 contents of the marker segments between the <code>SOI</code> marker and 
  66 the <code>EOI</code> marker for that image.  The image metadata object 
  67 passed into a write determines the contents of the stream between the 
  68 <code>SOI</code> marker and the <code>EOI</code> marker for that image, 
  69 subject to the controls in any <code>ImageWriteParam</code>.
  70 
  71 <p>
  72 Stream metadata is used only for tables-only images found (or to be 
  73 placed) at the beginning of a stream containing abbreviated images.  
  74 Tables-only images are not treated as images and do not consume an 
  75 image index.  The stream metadata object returned from a read describes the
  76 contents of the marker segments between the <code>SOI</code> marker and 
  77 the <code>EOI</code> marker for the single tables-only image at the 
  78 beginning of the stream, if one is present.  If no tables-only image is 
  79 present at the front of the stream, the <code>getStreamMetadata</code> 
  80 method of <code>ImageReader</code> returns <code>null</code>.  If 
  81 stream metadata is provided to the writer, a single tables-only image 
  82 containing the tables from the stream metadata object will be written at 
  83 the beginning of the stream.  If the stream metadata object contains no
  84 tables, default tables will be written.  As the sole purpose of stream
  85 metadata is for specifying tables-only images at the front of abbreviated 
  86 streams, the stream metadata argument is useful only on the 
  87 <code>ImageWriter.prepareWriteSequence</code> method.  It is ignored on all 
  88 other methods.
  89 
  90 <p> 
  91 The <code>ImageWriter.getDefaultStreamMetadata</code> method returns an 
  92 object containing the tables from the <code>ImageWriteParam</code> argument, 
  93 if it is a <code>JPEGImageWriteParam</code> and contains tables.  Otherwise, 
  94 the returned object will contain default tables.
  95 
  96 <p>The <code>ImageWriter.getDefaultImageMetadata</code> method returns a 
  97 metadata object containing <b>no</b> tables if the 
  98 <code>ImageWriteParam</code> argument contains tables.  Otherwise the 
  99 returned metadata object will contain default visually lossless tables.  
 100 Of course, only a <code>JPEGImageWriteParam</code> may contain tables.
 101 
 102 <p>
 103 If <code>ignoreMetadata</code> is set to <code>true</code> when the input
 104 is set on the reader, stream metadata will not be available, but image
 105 metadata will.
 106 
 107 <h2>
 108 <a name=abbrev>Abbreviated Streams</a>
 109 </h2>
 110 Both the reader and the writer retain their tables from one operation to the 
 111 next, thus permitting the use of abbreviated streams quite naturally, with a 
 112 few minor restrictions:  
 113 <ol>
 114   <li> Abbreviated streams may contain only one tables-only image, which must 
 115        come first in the stream.  Subsequent tables-only images will cause
 116        undefined behavior.</li>
 117   <li> Abbreviated streams must be read fully and in order.  No random access
 118        is allowed, in either direction.  The same image may be read multiple 
 119        times.  If a call is made with an image index that is not the same as
 120        or one greater than the most recent call (or 0 if no calls have been
 121        made), then an <code>IllegalArgumentException</code> is thrown.</li>
 122 </ol>
 123 These restrictions mean that streams may contain abbreviated images 
 124 interspersed with images containing tables.  As required by JPEG, any tables
 125 appearing in the stream override previous tables, regardless of the source
 126 of the previous tables.  
 127 
 128 <p>
 129 Note that once a tables-only image has been read, it's contents is available
 130 as stream metadata from the reader until either another tables-only image
 131 is read from another stream or the reader is reset.  Changing the input does
 132 not reset the stream metadata.  This is useful for reading the tables from
 133 one file, then changing the input to read an abbreviated stream containing 
 134 a sequence of images.  The tables will be used automatically, and will remain
 135 available as "stream" metadata.
 136 
 137 <p>
 138 Abbreviated streams are written using the sequence methods of 
 139 <code>ImageWriter</code>.  Stream metadata is used to write a tables-only 
 140 image at the beginning of the stream, and the tables are set up for use, using
 141 <code>ImageWriter.prepareWriteSequence</code>.  If no stream metadata is 
 142 supplied to <code>ImageWriter.prepareWriteSequence</code>, then no 
 143 tables-only image is written.  If stream metadata containing no tables is
 144 supplied to <code>ImageWriter.prepareWriteSequence</code>, then a tables-only
 145 image containing default visually lossless tables is written.
 146 
 147 <h2>
 148 <a name=tables>Sources of Tables</a>
 149 </h2>
 150 <p>
 151 Images are written with tables if tables are present in their metadata objects 
 152 or without them if no tables are present in their metadata objects.  If no
 153 metadata object is present then the tables are written.  The tables used for 
 154 compression are taken from one of the following sources, which are consulted 
 155 in order: 
 156 <ol>
 157   <li> If there is an <code>ImageWriteParam</code> and the compression mode is
 158        set to <code>EXPLICIT</code>, default tables constructed using the
 159        quality setting are used.  They are written only if the metadata 
 160        contains tables or if there is no metadata, but they replace the 
 161        tables in the metadata.</li>
 162   <li> If there is an <code>ImageWriteParam</code> and the compression mode is
 163        set to <code>DEFAULT</code>, default visually lossles tables are used.
 164        They are written only if the metadata contains tables or if
 165        there is no metadata, but they replace the tables in the
 166        metadata.</li>
 167   <li> Otherwise the compression mode on the <code>ImageWriteParam</code> must
 168        be MODE_COPY_FROM_<code>METADATA</code>, in which case the following
 169        are used:
 170     <ol>
 171       <li> the tables in the image metadata, if present</li>
 172       <li> the tables in the stream metadata, if present</li>
 173       <li> the tables in the <code>JPEGImageWriteParam</code>, if present</li>
 174       <li> default visually lossless tables</li>
 175     </ol> Tables are written only if they are taken from image metadata.
 176   </li>
 177 </ol>
 178 
 179 This ordering implements the design intention that tables should be included 
 180 in <code>JPEGImageWriteParam</code>s only as a means of specifying tables 
 181 when no other source is available, and this can occur only when writing to an
 182 abbreviated stream without tables using known non-standard tables for 
 183 compression.
 184 
 185 <p>
 186 When reading, tables in a <code>JPEGImageReadParam</code> are consulted only 
 187 if tables have not been set by any previous read.  Tables set from a 
 188 <code>JPEGImageReadParam</code> are overridden by any tables present in the 
 189 stream being read.
 190 
 191 <p>
 192 Note that if no image metadata object is specified for a particular image, a 
 193 default object is used, which includes default tables.
 194 
 195 <h2>
 196 <a name=color>Colorspace Transformations and Conventional Markers</a>
 197 </h2>
 198 Colorspace transformations are controlled by the destination type for
 199 both reading and writing of images.  When <code>Raster</code>s are
 200 read, no colorspace transformation is performed, and any destination type 
 201 is ignored.  A warning is sent to any listeners if a destination type is 
 202 specified in this case.  When <code>Raster</code>s are written, any 
 203 destination type is used to interpret the bands.  This might result in a
 204 JFIF or Adobe header being written, or different component ids being written 
 205 to the frame and scan headers.  If values present in a metadata object do not 
 206 match the destination type, the destination type is used and a warning is sent 
 207 to any listeners.
 208 
 209 <p>
 210 
 211 <a name=optcolor><b>Optional ColorSpace support:</b></a>
 212 Handling of PhotoYCC (YCC), PhotoYCCA (YCCA), RGBA and YCbCrA color spaces
 213 by the standard plugin, as described below, is dependent on capabilities
 214 of the libraries used to interpret the JPEG data. Thus all consequential
 215 behaviors are optional. If the support is not available when decoding,
 216 the color space will be treated as unrecognized and the appropriate
 217 default color space for the specified number of component channels
 218 may be used.
 219 When writing, an Exception may be thrown if no suitable conversion
 220 can be applied before encoding.
 221 But where the support for these color spaces is available, the behavior
 222 must be as documented. 
 223 <p>
 224 
 225 When reading, the contents of the stream are interpreted by the usual
 226 JPEG conventions, as follows:
 227 
 228 <ul>
 229   <li> If a JFIF <code>APP0</code> marker segment is present, the colorspace
 230        is known to be either grayscale or YCbCr.  If an <code>APP2</code>
 231        marker segment containing an embedded ICC profile is also present, then
 232        the YCbCr is converted to RGB according to the formulas given in the
 233        JFIF spec, and the ICC profile is assumed to refer to the resulting RGB
 234        space.
 235   <li> If an Adobe <code>APP14</code> marker segment is present, the 
 236        colorspace is determined by consulting the <code>transform</code> flag.
 237        The <code>transform</code> flag takes one of three values:
 238     <ul>
 239       <li> 2 - The image is encoded as YCCK (implicitly converted from
 240            CMYK on encoding).
 241 
 242       <li> 1 - The image is encoded as YCbCr (implicitly converted from RGB
 243            on encoding).
 244 
 245       <li> 0 - Unknown.  3-channel images are assumed to be RGB, 4-channel 
 246            images are assumed to be CMYK.
 247     </ul>
 248   <li> If neither marker segment is present, the following procedure is
 249        followed: Single-channel images are assumed to be grayscale, and
 250        2-channel images are assumed to be grayscale with an alpha channel.
 251        For 3- and 4-channel images, the component ids are consulted.  If these
 252        values are 1-3 for a 3-channel image, then the image is assumed to be
 253        YCbCr. Subject to the availability of the
 254        <a href=#optcolor>optional color space support</a>
 255        described above, if these values are 1-4 for a 4-channel image,
 256        then the image is assumed to be YCbCrA. 
 257        If these values are > 4, they are checked 
 258        against the ASCII codes for 'R', 'G', 'B', 'A', 'C', 'c'.  These can 
 259        encode the following colorspaces:
 260        <p>
 261        <br>RGB
 262        <br>RGBA
 263        <br>YCC (as 'Y','C','c'), assumed to be PhotoYCC
 264        <br>YCCA (as 'Y','C','c','A'), assumed to be PhotoYCCA
 265        <p>
 266        Otherwise, 3-channel subsampled images are assumed to be YCbCr, 
 267        3-channel non-subsampled images are assumed to be RGB, 4-channel 
 268        subsampled images are assumed to be YCCK, and 4-channel, non-subsampled
 269        images are assumed to be CMYK.
 270 
 271   <li> All other images are declared uninterpretable and an exception is
 272        thrown if an attempt is made to read one as a 
 273        <code>BufferedImage</code>.  Such an image may be read only as a 
 274        <code>Raster</code>.  If an image is interpretable but there is no Java
 275        <code>ColorSpace</code> available corresponding to the encoded 
 276        colorspace (<i>e.g.</i> YCbCr), then 
 277        <code>ImageReader.getRawImageType</code> will return <code>null</code>.
 278 </ul>
 279 
 280 Once an encoded colorspace is determined, then the target colorspace is 
 281 determined as follows:
 282 
 283 <ul>
 284   <li> If a destination type is not set, then the following default
 285        transformations take place after upsampling: YCbCr (and YCbCrA) images 
 286        are converted to RGB (and RGBA) using the conversion provided by the
 287        underlying IJG library and either the built-in sRGB 
 288        <code>ColorSpace</code> or a custom RGB <code>ColorSpace</code> object
 289        based on an embedded ICC profile is used to create the output
 290        <code>ColorModel</code>.  PhotoYCC and PhotoYCCA images are not
 291        converted.  CMYK and YCCK images are currently not supported.</li>
 292 
 293   <li> If a destination image or type is set, it is used as follows:
 294        If the IJG library provides an appropriate conversion, it is used.
 295        Otherwise the default library conversion is followed by a colorspace 
 296        conversion in Java.</li>
 297 
 298   <li> Bands are selected AFTER any library colorspace conversion.  If a 
 299        subset of either source or destination bands is used, then the default 
 300        library conversions are used with no further conversion in Java,
 301        regardless of any destination type.</li>
 302 
 303   <li> An exception is thrown if an attempt is made to read an image in an 
 304        unsupported jpeg colorspace as a <code>BufferedImage</code> 
 305        (<i>e.g.</i> CMYK).  Such images may be read as
 306        <code>Raster</code>s.  If an image colorspace is unsupported or
 307        uninterpretable, then <code>ImageReader.getImageTypes</code> will
 308        return an empty <code>Iterator</code>.   If a subset of the raw bands
 309        are required, a <code>Raster</code> must be obtained first and the
 310        bands obtained from that. </li>
 311 </ul>
 312 
 313 <p>
 314 For writing, the color transformation to apply is determined as
 315 follows:
 316 
 317 <p>
 318 If a subset of the source bands is to be written, no color conversion is 
 319 performed.  Any destination, if set, must match the number of bands that will 
 320 be written, and serves as an interpretation of the selected bands, rather than 
 321 a conversion request.  This behavior is identical to that for 
 322 <code>Raster</code>s.  If all the bands are to be written and an image 
 323 (as opposed to a <code>Raster</code>) is being written, any destination type 
 324 is ignored and a warning is sent to any listeners.
 325 
 326 <p>
 327 If a destination type is used and any aspect of the metadata object, if there 
 328 is one, is not compatible with that type, the destination type is used, the 
 329 metadata written is modified from that provided, and a warning is sent to 
 330 listeners.  This includes the <code>app0JFIF</code> and 
 331 <code>app14Adobe</code> nodes.  The component ids in the <code>sof</code> and 
 332 <code>sos</code> nodes are not modified, however, as unless a 
 333 <code>app0JFIF</code> node is present, any values may be used.
 334 <p>
 335 
 336 When a full image is written, a destination colorspace will be 
 337 chosen based on the image contents and the metadata settings, according to 
 338 the following algorithm:
 339 
 340 <p>
 341 
 342 If no metadata object is specified, then the following defaults apply:
 343 
 344 <ul>
 345   <li> Grayscale images are written with a JFIF <code>APP0</code> marker
 346        segment.  Grayscale images with alpha are written with no special
 347        marker.  As required by JFIF, the component ids in the frame and
 348        scan header is set to 1.
 349 
 350   <li> RGB images are converted to YCbCr, subsampled in the chrominance
 351        channels by half both vertically and horizontally, and written with a
 352        JFIF <code>APP0</code> marker segment.  If the <code>ColorSpace</code>
 353        of the image is based on an <code>ICCProfile</code> (it is an instance
 354        of <code>ICC_ColorSpace</code>, but is not one of the standard built-in 
 355        <code>ColorSpaces</code>), then that profile is embedded in an 
 356        <code>APP2</code> marker segment.  As required by JFIF, the 
 357        component ids in the frame and scan headers are set to 1, 2, and 3.
 358 
 359 
 360   <li> Subject to the <a href=#optcolor>optional library support</a>
 361         described above,
 362        RGBA images are converted to YCbCrA, subsampled in the
 363        chrominance channels by half both vertically and horizontally, and
 364        written without any special marker segments.  The component ids 
 365        in the frame and scan headers are set to 1, 2, 3, and 4.
 366 
 367   <li> Subject to the <a href=#optcolor>optional library support</a>
 368        described above,
 369        PhotoYCC and YCCAimages are subsampled by half in the chrominance
 370        channels both vertically and horizontally and written with an
 371        Adobe <code>APP14</code> marker segment and 'Y','C', and 'c' (and
 372        'A' if an alpha channel is present) as component ids in the frame
 373         and scan headers.
 374 </ul>
 375 
 376 Default metadata objects for these image types will reflect these settings.
 377 
 378 <p>
 379 
 380 If a metadata object is specified, then the number of channels in the
 381 frame and scan headers must always match the number of bands to be 
 382 written, or an exception is thrown.  <code>app0JFIF</code> and 
 383 <code>app14Adobe</code> nodes may appear in the same metadata object only 
 384 if the <code>app14Adobe</code> node indicates YCbCr, and the component ids 
 385 are JFIF compatible (0-2).  The various image types are processed in the 
 386 following ways:
 387 
 388 <br>
 389 
 390 (All multi-channel images are subsampled according to the sampling factors 
 391 in the frame header node of the metadata object, regardless of color space.)
 392 
 393 <ul>
 394   <li> Grayscale Images:
 395     <ul>
 396       <li> If an <code>app0JFIF</code> node is present in the metadata object,
 397            a JFIF <code>APP0</code> marker segment is written.
 398       <li> If an <code>app14Adobe</code> node is present in the metadata 
 399            object, it is checked for validity (<code>transform</code> must be
 400            <code>UNKNOWN</code>) and written.
 401       <li> If neither node is present in the metadata object, no special 
 402            marker segment is written.
 403     </ul>
 404 
 405   <li> Grayscale Images with an Alpha Channel:
 406     <ul>
 407       <li> If an <code>app0JFIF</code> node is present in the metadata object,
 408            it is ignored and a warning is sent to listeners, as JFIF does not
 409            support 2-channel images.
 410       <li> If an <code>app14Adobe</code> node is present in the metadata
 411            object, it is checked for validity (<code>transform</code> must be
 412            <code>UNKNOWN</code>) and written.  If <code>transform</code> is
 413            not <code>UNKNOWN</code>, a warning is sent to listeners and the
 414            correct transform is written.
 415       <li> If neither node is present in the metadata object, no special 
 416            marker segment is written.
 417     </ul>
 418 
 419   <li> RGB Images:
 420     <ul>
 421       <li> If an <code>app0JFIF</code> node is present in the metadata object,
 422            the image is converted to YCbCr and written with a JFIF 
 423            <code>APP0</code> marker segment.  If the <code>ColorSpace</code>
 424            of the image is based on a non-standard ICC Profile, then that
 425            profile is embedded in an <code>APP2</code> marker segment.  If the
 426            <code>ColorSpace</code> is not based on a non-standard ICC Profile,
 427            but an <code>app2ICC</code> node appears in the metadata, then an
 428            <code>APP2</code> marker segment is written with the appropriate
 429            standard profile.  Note that the profile must specify an RGB color
 430            space, as the file must be JFIF compliant.
 431 
 432       <li> If an <code>app14Adobe</code> node is present in the metadata
 433            object, the image is converted according to the color transform
 434            setting and written with an Adobe <code>APP14</code> marker
 435            segment.  Component ids are written just as they appear in the
 436            frame and scan headers.  The color transform must be either YCbCr
 437            or <code>UNKNOWN</code>.  If it is <code>UNKNOWN</code>, the image
 438            is not color converted.
 439 
 440       <li> If neither node is present, the component ids in the frame
 441            header are consulted.  If these indicate a colorspace as described
 442            above, then the image is converted to that colorspace if possible.  
 443            If the component ids do not indicate a colorspace, then the
 444            sampling factors are consulted.  If the image is to be subsampled,
 445            it is converted to YCbCr first.  If the image is not to be
 446            subsampled, then no conversion is applied.  No special marker
 447            segmentss are written.
 448     </ul>
 449 
 450   <li> RGBA images:
 451        Subject to the <a href=#optcolor>optional library support</a>
 452        described above,
 453     <ul>
 454       <li> If an <code>app0JFIF</code> node is present in the metadata object,
 455            it is ignored and a warning is sent to listeners, as JFIF does not
 456            support 4-channel images.
 457 
 458       <li> If an <code>app14Adobe</code> node is present in the metadata
 459            object, the image is written with an Adobe <code>APP14</code> marker
 460            segment.  No colorspace conversion is performed.  Component ids
 461            are written just as they appear in the frame and scan  headers.
 462            The color transform must be <code>UNKNOWN</code>.  If it is 
 463            not, a warning is sent to listeners.
 464 
 465       <li> If no <code>app14Adobe</code> node is present, the component ids in
 466            the frame header are consulted.  If these indicate a colorspace as
 467            described above, then the image is converted to that colorspace if
 468            possible.  If the component ids do not indicate a colorspace, then
 469            the sampling factors are consulted.  If the image is to be
 470            subsampled, it is converted to YCbCrA.  If the image is not to be
 471            subsampled, then no conversion is applied.  No special marker
 472            segments are written.
 473     </ul>
 474 
 475   <li> PhotoYCC Images:
 476        Subject to the <a href=#optcolor>optional library support</a>
 477        described above,
 478     <ul>
 479       <li> If an <code>app0JFIF</code> node is present in the metadata object,
 480            the image is converted to sRGB, and then to YCbCr during encoding,
 481            and a JFIF <code>APP0</code> marker segment is written.
 482 
 483       <li> If an <code>app14Adobe</code> node is present in the metadata
 484            object, no conversion is applied, and an Adobe <code>APP14</code>
 485            marker segment is written.  The color transform must be YCC.  If it
 486            is not, a warning is sent to listeners.
 487 
 488       <li> If neither node is present in the metadata object, no conversion
 489            is applied, and no special marker segment is written.
 490     </ul>
 491 
 492   <li> PhotoYCCA Images:
 493        Subject to the <a href=#optcolor>optional library support</a>
 494        described above,
 495     <ul>
 496       <li> If an <code>app0JFIF</code> node is present in the metadata object,
 497            it is ignored and a warning is sent to listeners, as JFIF does not
 498            support 4-channel images.
 499 
 500       <li> If an <code>app14Adobe</code> node is present in the metadata
 501            object, no conversion is applied, and an Adobe <code>APP14</code>
 502            marker segment is written.  The color transform must be
 503            <code>UNKNOWN</code>.  If it is not, a warning is sent to
 504            listeners.
 505 
 506       <li> If neither node is present in the metadata object, no conversion
 507            is applied, and no special marker segment is written.
 508     </ul>
 509 </ul>
 510 
 511 <h2>
 512 <a name=thumbs>Thumbnail Images</a>
 513 </h2>
 514 Thumbnails are supported by the use of JFIF and JFIF extension marker segments.
 515 Thumbnails provided on the write methods determine the thumbnails that will be 
 516 included.  <code>app0JFIF</code> and <code>app0JFXX</code> nodes present in 
 517 the metadata do not contain any thumbnail pixel data.  However, the kinds of 
 518 thumbnails written depend on the contents of the metadata object, as follows.  
 519 Any thumbnail which is to be written as an indexed or RGB image and which is 
 520 larger than 255 by 255 will be clipped, not scaled, to 255 by 255.  Thumbnails 
 521 written as JPEG images may be any size.  A warning is sent to any listeners 
 522 whenever a thumbnail is clipped.
 523 <ul>
 524   <li> If there is a single thumbnail, it is processed as follows:
 525     <ul>
 526       <li> If the thumbnail image is an RGB palette image, it is processed as
 527            follows:
 528         <ul>
 529           <li> If no <code>app0JFXX</code> node is present in the metadata, or
 530                the first <code>app0JFXX</code> node present in the metadata
 531                contains a <code>JFIFthumbPalette</code> element, a
 532                palette thumbnail is written in a JFXX <code>APP0</code> marker
 533                segment.
 534           <li> If the first <code>app0JFXX</code> node present in the metadata
 535                contains another thumbnail form (RGB or JPEG), the palette
 536                image is expanded to RGB and the indicated thumbnail form is
 537                written.  
 538         </ul>
 539 
 540       <li> If the thumbnail image is an RGB image, it is processed as follows:
 541         <ul>
 542           <li> If no <code>app0JFXX</code> node is present in the metadata,
 543                the thumbnail is written as part of the JFIF <code>APP0</code>
 544                marker segment. 
 545           <li> If the first <code>app0JFXX</code> node present in the metadata
 546                contains a <code>JFIFthumbRGB</code> element, an
 547                RGB thumbnail is written in a JFXX <code>APP0</code> marker
 548                segment.
 549           <li> If the first <code>app0JFXX</code> node present in the metadata
 550                contains a <code>JFIFthumbJPEG</code> element, a
 551                JPEG thumbnail is written in a JFXX <code>APP0</code> marker
 552                segment.
 553           <li> If the first <code>app0JFXX</code> node present in the metadata
 554                contains a <code>JFIFthumbPalette</code> element, an
 555                RGB thumbnail is written in a JFXX <code>APP0</code> marker
 556                segment and a warning is sent to any listeners.
 557         </ul>
 558 
 559       <li> If the thumbnail image is a grayscale image, it is processed as
 560            follows:
 561         <ul>
 562           <li> If no <code>app0JFXX</code> node is present in the metadata,
 563                the thumbnail is expanded to RGB and written as part of the
 564                JFIF <code>APP0</code> marker segment. 
 565           <li> If the first <code>app0JFXX</code> node present in the metadata
 566                contains a <code>JFIFthumbRGB</code> element, the thumbnail is
 567                expanded to RGB and written in a separate <code>JFXX</code> RGB
 568                marker segment.
 569           <li> If the first <code>app0JFXX</code> node present in the metadata
 570                contains a <code>JFIFthumbJPEG</code> element, a
 571                JPEG thumbnail is written in a JFXX <code>APP0</code> marker
 572                segment.
 573           <li> If the first <code>app0JFXX</code> node present in the metadata
 574                contains a <code>JFIFthumbPalette</code> element, a
 575                JPEG thumbnail is written in a JFXX <code>APP0</code> marker
 576                segment and a warning is sent to any listeners.
 577         </ul>
 578 
 579       <li> Any other thumbnail image types are ignored and a warning is sent
 580            to any listeners.
 581     </ul>
 582 
 583   <li> If there are multiple thumbnails, each one is processed as above, except
 584        that no thumbnail is placed in the JFIF <code>APP0</code> segment, and
 585        the <code>app0JFXX</code> node consulted for each thumbnail is the
 586        <code>app0JFXX</code> node from the metadata that occurs in the same
 587        sequence as the thumbnail.  <i>I.e.</i> the first
 588        <code>app0JFXX</code> node applies to the first thumbnail, the second
 589        node to the second thumbnail, and so on.  If there are fewer
 590        <code>app0JFXX</code> nodes in the metadata than thumbnails, then 
 591        those thumbnails are considered to have no matching
 592        <code>app0JFXX</code> node.  An RGB thumbnail with no matching
 593        <code>app0JFXX</code> node is written in a JFXX <code>APP0</code> marker
 594        segment.  A grayscale thumbnail with no matching
 595        <code>app0JFXX</code> node is written as a JPEG image to a JFXX 
 596        <code>APP0</code> marker segment.
 597 </ul>
 598 <p>
 599 
 600 Note that as the only mechanism for storing thumbnails is via the
 601 JFIF or JFIF extension marker segments, only grayscale or RGB images 
 602 may have thumbnails.  If thumbnails are present when writing any other type 
 603 of image, the thumbnails are ignored and a warning is sent to any warning
 604 listeners.
 605 
 606 <h2>
 607 <a name=prog>Progressive Encoding</a>
 608 </h2>
 609 
 610 Progressive encoding must be enabled on the <code>ImageWriteParam</code>
 611 passed in to a write operation, or the image will be written sequentially,
 612 regardless of the scan headers included in the metadata object.  If 
 613 progressive encoding is enabled and set to copy from metadata, then
 614 the sequence of scan headers from the metadata is used to write the 
 615 image.  If progressive encoding is enabled and set to use a default, 
 616 then the scans in the metadata are ignored and a default set of scans 
 617 is used.  Progressive encoding always forces optimized Huffman tables to
 618 be used.  Any Huffman tables present in the metadata will be ignored,
 619 and a warning will be sent to any warning listeners.
 620 
 621 If Huffman-table optimization is requested on the <code>ImageWriteParam</code>,
 622 all Huffman tables in the metadata or in the <code>ImageWriteParam</code> 
 623 itself are ignored, and a warning will be sent to any warning listeners if 
 624 any such tables are present.
 625 
 626 <h2>
 627 <a name=tree>Native Metadata Format Tree Structure and Editing</a>
 628 </h2>
 629 
 630 The DTDs below describe just the trees of metadata objects actually returned
 631 by the <code>IIOMetadata</code> object.  They do not include nodes 
 632 corresponding to <code>SOI</code>, <code>EOI</code>, or <code>RST</code> 
 633 markers, as these parsing delimiters do not carry any meaningful metadata.  
 634 <p>
 635 
 636 The first node is always a <code>JPEGvariety</code> node.  In the
 637 <code>javax_imageio_jpeg_image_1.0</code> version of the JPEG metadata
 638 format, this node may have one child, an <code>app0JFIF</code> node,
 639 indicating that the JPEG stream contains a JFIF marker segment and related
 640 data, or no children, indicating that the stream contains no JFIF marker.
 641 In future versions of the JPEG metadata format, other varieties of JPEG
 642 metadata may be supported (e.g. Exif) by defining other types of nodes
 643 which may appear as a child of the <code>JPEGvariety</code> node.
 644 <p>
 645 
 646 (Note that an application wishing to interpret Exif metadata given
 647 a metadata tree structure in the <code>javax_imageio_jpeg_image_1.0</code>
 648 format must check for an <code>unknown</code> marker segment with a tag
 649 indicating an <code>APP1</code> marker and containing data identifying it
 650 as an Exif marker segment.  Then it may use application-specific code to
 651 interpret the data in the marker segment.  If such an application were
 652 to encounter a metadata tree formatted according to a future version of
 653 the JPEG metadata format, the Exif marker segment might not be
 654 <code>unknown</code> in that format - it might be structured as a
 655 child node of the <code>JPEGvariety</code> node.  Thus, it is important
 656 for an application to specify which version to use by passing the string
 657 identifying the version to the method/constructor used to obtain an
 658 <code>IIOMetadata</code> object.)
 659 
 660 <p>
 661 
 662 On reading, <code>JFXX</code> and <code>app2ICC</code> nodes occur as 
 663 children of an <code>app0JFIF</code> node.
 664 This is true regardless of where the JFXX <code>APP0</code> and 
 665 <code>APP2</code> marker segments actually occur in the stream.  The ordering 
 666 of nodes within the <code>markerSequence</code> node corresponds to the 
 667 ordering of marker segments found in the JPEG stream.
 668 <p>
 669 On writing, any <code>JFXX</code> and <code>app2ICC</code> nodes must 
 670 occur as children of an <code>app0JFIF</code> node, itself a child of a 
 671 <code>JPEGvariety</code> node, which must always be the first node.
 672 (If the stream is not to be JFIF compliant, no <code>app0JFIF</code> node
 673 should be provided, and the <code>JPEGvariety</code> node should have no
 674 children.)  Any 
 675 JFIF <code>APP0</code>, JFXX <code>APP0</code>, and <code>APP2</code> marker 
 676 segments are written first, followed by all Adobe <code>APP14</code>, 
 677 <code>APPn</code>, <code>COM</code> and unknown segments in the 
 678 order in which their corresponding nodes appear in the 
 679 <code>markerSequence</code> node, followed by <code>DQT</code> (and 
 680 <code>DHT</code> for non-progressive writes) marker segments, followed by the 
 681 <code>SOF</code> and <code>SOS</code> marker segments.  For progressive writes
 682 using metadata to control progression, the <code>SOS</code> segments are used 
 683 in the order in which their corresponding nodes occur in the 
 684 <code>markerSequence</code> node.
 685 <p>
 686 
 687 The <code>reset</code>, <code>mergeTree</code> and <code>setFromTree</code> 
 688 operations have the following semantics for the JPEG plug-in metadata object:
 689 
 690 <p> <code>reset</code> - A call to <code>reset</code> will restore the 
 691 metadata object to the same state it had immediately after creation, whether 
 692 this came about from reading a stream or by obtaining a default object from 
 693 the <code>ImageWriter</code>.  This is true regardless of how many times the 
 694 metadata object has been modified since creation.
 695 
 696 <p> <code>mergeTree</code> - Native Format
 697 <br> The <code>mergeTree</code> operation accepts valid trees conforming to 
 698 the DTD below, and merges the nodes using the following ordering rules.  In 
 699 all cases, only data present in the new node is changed in a corresponding 
 700 existing node, if any.  This means that nodes cannot be removed using 
 701 <code>mergeTree</code>.  To remove nodes, use <code>setFromTree</code>.  The 
 702 tree must consist of <code>IIOMetadataNode</code>s.
 703 <ul>
 704   <li> <code>app0JFIF</code>
 705         <ul>
 706           <li> If an <code>app0JFIF</code> node already exists, the contents 
 707                of the new one modify the existing one. 
 708           <li> If there is no such node, a new one is created and inserted in
 709                the appropriate position.
 710         </ul>    
 711   <li> <code>dqt</code>
 712         <ul>
 713           <li> If there already exist <code>dqt</code> nodes in the sequence,
 714                then each table in the node replaces the first table, in any
 715                <code>dqt</code> node, with the same table id.  
 716           <li> If none of the existing <code>dqt</code> nodes contain a table
 717                with the same id, then the table is added to the last existing
 718                <code>dqt</code> node.
 719           <li> If there are no <code>dqt</code> nodes, then a new one is
 720                created and added as follows:
 721             <ul>
 722               <li> If there are <code>dht</code> nodes, the new
 723                    <code>dqt</code> node is inserted before the first one.  
 724               <li> If there are no <code>dht</code> nodes, the new
 725                    <code>dqt</code> node is inserted  before an
 726                    <code>sof</code> node, if there is one. 
 727               <li> If there is no <code>sof</code> node, the new
 728                    <code>dqt</code> node is inserted before the first
 729                    <code>sos</code> node, if there is one.
 730               <li> If there is no <code>sos</code> node, the new
 731                    <code>dqt</code> node is added to the end of the sequence.
 732             </ul>
 733         </ul>
 734   <li> <code>dht</code>
 735         <ul>
 736           <li> If there already exist <code>dht</code> nodes in the sequence,
 737                then each table in the node replaces the first table, in any
 738                <code>dht</code> node, with the same table class and table id.
 739           <li> If none of the existing <code>dht</code> nodes contain a table
 740                with the same class and id, then the table is added to the last
 741                existing <code>dht</code> node.
 742           <li> If there are no <code>dht</code> nodes, then a new one is
 743                created and added as follows:
 744             <ul>
 745               <li> If there are <code>dqt</code> nodes, the new
 746                    <code>dht</code> node is inserted immediately following the
 747                    last <code>dqt</code> node.
 748               <li> If there are no <code>dqt</code> nodes, the new
 749                    <code>dht</code> node is inserted before an
 750                    <code>sof</code> node, if there is one. 
 751               <li> If there is no <code>sof</code> node, the new
 752                    <code>dht</code> node is inserted before the first
 753                    <code>sos</code> node, if there is one.
 754               <li> If there is no <code>sos</code> node, the new
 755                    <code>dht</code> node is added to the end of the sequence.
 756             </ul>
 757         </ul>
 758   <li> <code>dri</code>
 759         <ul>
 760           <li> If there already exists a <code>dri</code> node, the restart 
 761                interval value is updated.
 762           <li> If there is no <code>dri</code> node, then a new one is created
 763                and added as follows:
 764             <ul>
 765               <li> If there is an <code>sof</code> node, the new
 766                    <code>dri</code> node is inserted before it.
 767               <li> If there is no <code>sof</code> node, the new
 768                    <code>dri</code> node is inserted before the first
 769                    <code>sos</code> node, if there is one.
 770               <li> If there is no <code>sos</code> node, the new
 771                    <code>dri</code> node is added to the end of the sequence.
 772             </ul>
 773         </ul>
 774   <li> <code>com</code>
 775         <br> A new <code>com</code> node is created and inserted as follows:
 776         <ul>
 777           <li> If there already exist <code>com</code> nodes, the new one is
 778                inserted after the last one.
 779           <li> If there are no <code>com</code> nodes, the new
 780                <code>com</code> node is inserted after the
 781                <code>app14Adobe</code> node, if there is one.
 782           <li> If there is no <code>app14Adobe</code> node, the new
 783                <code>com</code> node is inserted at the beginning of the
 784                sequence.
 785         </ul>
 786   <li> <code>app14Adobe</code>
 787         <ul>
 788           <li> If there already exists an <code>app14Adobe</code> node, then 
 789                its attributes are updated from the node.
 790           <li> If there is no <code>app14Adobe</code> node, then a new one is 
 791                created and  added as follows:
 792             <ul> 
 793               <li> The new <code>app14Adobe</code> node is inserted after the
 794                    last <code>unknown</code> node, if there are any.
 795               <li> If there are no <code>unknown</code> nodes, the new
 796                    <code>app14Adobe</code> node is inserted at the beginning
 797                    of the sequence.
 798             </ul>
 799         </ul>
 800   <li> <code>unknown</code>
 801        <br> A new <code>unknown</code> node is created and added to the
 802             sequence as follows:
 803         <ul>
 804           <li> If there already exist <code>unknown</code> marker nodes, the
 805                new one is inserted after the last one.
 806           <li> If there are no <code>unknown</code> nodes, the new
 807                <code>unknown</code> node is inserted before the
 808                <code>app14Adobe</code> node, if there is one.
 809           <li> If there is no <code>app14Adobe</code> node, the new
 810                <code>unknown</code> node is inserted at the beginning of the
 811                sequence.
 812         </ul>
 813   <li> <code>sof</code>
 814         <ul>
 815           <li> If there already exists an <code>sof</code> node in the
 816                sequence, then its values are updated from the node.
 817           <li> If there is no <code>sof</code> node, then a new one is created
 818                and added as follows:
 819             <ul>
 820               <li> If there are any <code>sos</code> nodes, the new
 821                    <code>sof</code> node is inserted before the first one.
 822               <li> If there is no <code>sos</code> node, the new
 823                    <code>sof</code> node is added to the end of the sequence.
 824             </ul>
 825         </ul>
 826   <li> <code>sos</code>
 827         <ul>
 828           <li> If there already exists a single <code>sos</code> node, then
 829                the values are updated from the node.
 830           <li> If there are more than one existing <code>sos</code> nodes,
 831                then an <code>IIOInvalidTreeException</code> is thrown, as
 832                <code>sos</code> nodes cannot be merged into a set of
 833                progressive scans.
 834           <li> If there are no <code>sos</code> nodes, a new one is created
 835                and added to the end of the sequence.
 836         </ul>
 837 </ul>
 838 
 839 <p> <code>mergeTree</code> - Standard Format
 840 <br>
 841 The <code>mergeTree</code> operation, when given a tree in the standard 
 842 format, will modify the native tree in the following ways:
 843 <ul>
 844    <li> <code>Chroma</code> - The <code>ColorSpaceType</code> subnode of a
 845         <code>Chroma</code> node may change the target colorspace of the
 846         compressed image.  The selection of a new colorspace can cause a number
 847         of changes, in keeping with the algorithms described above: 
 848         <code>app0JFIF</code> and <code>app14Adobe</code> nodes may be added
 849         or removed, subsampling may be added or removed, component ids may
 850         be changed, and <code>sof</code> and <code>sos</code> nodes will be
 851         updated accordingly.  If necessary, additional quantization and
 852         huffman tables are added.  In the case of quantization tables, the
 853         default will be scaled to match the quality level of any existing
 854         tables.  No tables are added to metadata that does not already contain
 855         tables.  If the existing metadata specifies progressive encoding, then
 856         the number of channels must not change.  Any <code>Transparency</code>
 857         node is also taken into account, as an explicit value of
 858         <code>none</code> for the <code>Alpha</code> subnode can cause the
 859         removal of an alpha channel, and anything other than <code>none</code>
 860         can cause the addition of an alpha channel.
 861    <li> <code>Dimension</code> - A <code>PixelAspectRatio</code> specification
 862         can cause the contents of an <code>app0JFIF</code> node to change, if
 863         there is one present, or the addition of an <code>app0JFIF</code> node
 864         containing appropriate values, if there can be one.  An appropriate
 865         pair of integers is computed from the floating-point ratio for
 866         inclusion in the node.
 867    <li> <code>Text</code> - Each uncompressed text item is converted to a
 868         <code>com</code> node and inserted according to the rules above for
 869         merging <code>com</code> nodes.
 870 </ul>
 871 
 872 <p> <code>setFromTree</code> - Native Format
 873 <br>
 874 The <code>setFromTree</code> operation, when given a tree in the native 
 875 format described below, will simply replace the existing tree in its entirety 
 876 with the new one.  The tree must consist of <code>IIOMetadataNode</code>s.
 877 
 878 <p> <code>setFromTree</code> - Standard Format
 879 <br>
 880 The <code>setFromTree</code> operation, when given a tree in the standard 
 881 format, performs a <code>reset</code> followed by a merge of the new tree.
 882 
 883 <h2>
 884 <a name=image>Image Metadata DTD</a>
 885 </h2>
 886 
 887 <pre>
 888 &lt;!DOCTYPE "javax_imageio_jpeg_image_1.0" [
 889 
 890   &lt;!ELEMENT "javax_imageio_jpeg_image_1.0" (JPEGvariety, markerSequence)&gt;
 891 
 892     &lt;!ELEMENT "JPEGvariety" (app0JFIF)&gt;
 893       &lt;!-- A node grouping all marker segments specific to the variety of
 894               stream being read/written (e.g. JFIF) - may be empty --&gt; 
 895 
 896       &lt;!ELEMENT "app0JFIF" (JFXX?, app2ICC?)&gt;
 897         &lt;!ATTLIST "app0JFIF" "majorVersion" #CDATA "1"&gt;
 898           &lt;!-- The major JFIF version number --&gt; 
 899           &lt;!-- Data type: Integer --&gt;
 900           &lt;!-- Min value: 0 (inclusive) --&gt;
 901           &lt;!-- Max value: 255 (inclusive) --&gt;
 902         &lt;!ATTLIST "app0JFIF" "minorVersion" #CDATA "2"&gt;
 903           &lt;!-- The minor JFIF version number --&gt; 
 904           &lt;!-- Data type: Integer --&gt;
 905           &lt;!-- Min value: 0 (inclusive) --&gt;
 906           &lt;!-- Max value: 255 (inclusive) --&gt;
 907         &lt;!ATTLIST "app0JFIF" "resUnits" ("0" | "1" | "2") "0"&gt;
 908           &lt;!-- The resolution units for Xdensisty and Ydensity (0 = no 
 909                units, just aspect ratio; 1 = dots/inch; 2 = dots/cm) --&gt; 
 910         &lt;!ATTLIST "app0JFIF" "Xdensity" #CDATA "1"&gt;
 911           &lt;!-- The horizontal density or aspect ratio numerator --&gt; 
 912           &lt;!-- Data type: Integer --&gt;
 913           &lt;!-- Min value: 1 (inclusive) --&gt;
 914           &lt;!-- Max value: 65535 (inclusive) --&gt;
 915         &lt;!ATTLIST "app0JFIF" "Ydensity" #CDATA "1"&gt;
 916           &lt;!-- The vertical density or aspect ratio denominator --&gt; 
 917           &lt;!-- Data type: Integer --&gt;
 918           &lt;!-- Min value: 1 (inclusive) --&gt;
 919           &lt;!-- Max value: 65535 (inclusive) --&gt;
 920         &lt;!ATTLIST "app0JFIF" "thumbWidth" #CDATA "0"&gt;
 921           &lt;!-- The width of the thumbnail, or 0 if there isn't one --&gt; 
 922           &lt;!-- Data type: Integer --&gt;
 923           &lt;!-- Min value: 0 (inclusive) --&gt;
 924           &lt;!-- Max value: 255 (inclusive) --&gt;
 925         &lt;!ATTLIST "app0JFIF" "thumbHeight" #CDATA "0"&gt;
 926           &lt;!-- The height of the thumbnail, or 0 if there isn't one --&gt; 
 927           &lt;!-- Data type: Integer --&gt;
 928           &lt;!-- Min value: 0 (inclusive) --&gt;
 929           &lt;!-- Max value: 255 (inclusive) --&gt;
 930 
 931         &lt;!ELEMENT "JFXX" (app0JFXX)*&gt;
 932           &lt;!-- Min children: 1 --&gt;
 933 
 934         &lt;!ELEMENT "app0JFXX" (JFIFthumbJPEG | JFIFthumbPalette | 
 935           JFIFthumbRGB)&gt;
 936           &lt;!-- A JFIF extension marker segment --&gt; 
 937           &lt;!ATTLIST "app0JFXX" "extensionCode" ("16" | "17" | "19")
 938              #IMPLIED&gt;
 939             &lt;!-- The JFXX extension code identifying thumbnail type: (16 = 
 940                  JPEG, 17 = indexed, 19 = RGB --&gt; 
 941 
 942           &lt;!ELEMENT "JFIFthumbJPEG" (markerSequence?)&gt;
 943             &lt;!-- A JFIF thumbnail in JPEG format (no JFIF segments 
 944                  permitted) --&gt; 
 945 
 946           &lt;!ELEMENT "JFIFthumbPalette" EMPTY&gt;
 947             &lt;!-- A JFIF thumbnail as an RGB indexed image --&gt; 
 948             &lt;!ATTLIST "JFIFthumbPalette" "thumbWidth" #CDATA #IMPLIED&gt;
 949               &lt;!-- The width of the thumbnail --&gt; 
 950               &lt;!-- Data type: Integer --&gt;
 951               &lt;!-- Min value: 0 (inclusive) --&gt;
 952               &lt;!-- Max value: 255 (inclusive) --&gt;
 953             &lt;!ATTLIST "JFIFthumbPalette" "thumbHeight" #CDATA #IMPLIED&gt;
 954               &lt;!-- The height of the thumbnail --&gt; 
 955               &lt;!-- Data type: Integer --&gt;
 956               &lt;!-- Min value: 0 (inclusive) --&gt;
 957               &lt;!-- Max value: 255 (inclusive) --&gt;
 958 
 959           &lt;!ELEMENT "JFIFthumbRGB" EMPTY&gt;
 960             &lt;!-- A JFIF thumbnail as an RGB image --&gt; 
 961             &lt;!ATTLIST "JFIFthumbRGB" "thumbWidth" #CDATA #IMPLIED&gt;
 962               &lt;!-- The width of the thumbnail --&gt; 
 963               &lt;!-- Data type: Integer --&gt;
 964               &lt;!-- Min value: 0 (inclusive) --&gt;
 965               &lt;!-- Max value: 255 (inclusive) --&gt;
 966             &lt;!ATTLIST "JFIFthumbRGB" "thumbHeight" #CDATA #IMPLIED&gt;
 967               &lt;!-- The height of the thumbnail --&gt; 
 968               &lt;!-- Data type: Integer --&gt;
 969               &lt;!-- Min value: 0 (inclusive) --&gt;
 970               &lt;!-- Max value: 255 (inclusive) --&gt;
 971 
 972         &lt;!ELEMENT "app2ICC" EMPTY&gt;
 973           &lt;!-- An ICC profile APP2 marker segment --&gt; 
 974           &lt;!-- Optional User object: java.awt.color.ICC_Profile --&gt;
 975 
 976     &lt;!ELEMENT "markerSequence" (dqt | dht | dri | com | unknown | 
 977       app14Adobe | sof | sos)*&gt;
 978       &lt;!-- A node grouping all non-jfif marker segments --&gt; 
 979 
 980       &lt;!ELEMENT "dqt" (dqtable)*&gt;
 981         &lt;!-- A Define Quantization Table(s) marker segment --&gt; 
 982         &lt;!-- Min children: 1 --&gt;
 983         &lt;!-- Max children: 4 --&gt;
 984 
 985         &lt;!ELEMENT "dqtable" EMPTY&gt;
 986           &lt;!-- A single quantization table --&gt; 
 987           &lt;!-- User object: javax.imageio.plugins.jpeg.JPEGQTable --&gt;
 988           &lt;!ATTLIST "dqtable" "elementPrecision" #CDATA "0"&gt;
 989             &lt;!-- The number of bits in each table element (0 = 8, 1 = 16) 
 990                  --&gt; 
 991             &lt;!-- Data type: Integer --&gt;
 992           &lt;!ATTLIST "dqtable" "qtableId" ("0" | "1" | "2" | "3") #REQUIRED&gt;
 993 
 994       &lt;!ELEMENT "dht" (dhtable)*&gt;
 995         &lt;!-- A Define Huffman Table(s) marker segment --&gt; 
 996         &lt;!-- Min children: 1 --&gt;
 997         &lt;!-- Max children: 4 --&gt;
 998 
 999         &lt;!ELEMENT "dhtable" EMPTY&gt;
1000           &lt;!-- A single Huffman table --&gt; 
1001           &lt;!-- User object: javax.imageio.plugins.jpeg.JPEGHuffmanTable --&gt;
1002           &lt;!ATTLIST "dhtable" "class" ("0" | "1") #REQUIRED&gt;
1003             &lt;!-- Indicates whether this is a DC (0) or an AC (1) table --&gt; 
1004           &lt;!ATTLIST "dhtable" "htableId" ("0" | "1" | "2" | "3") #REQUIRED&gt;
1005             &lt;!-- The table id --&gt; 
1006 
1007       &lt;!ELEMENT "dri" EMPTY&gt;
1008         &lt;!-- A Define Restart Interval marker segment --&gt; 
1009         &lt;!ATTLIST "dri" "interval" #CDATA #REQUIRED&gt;
1010           &lt;!-- The restart interval in MCUs --&gt; 
1011           &lt;!-- Data type: Integer --&gt;
1012           &lt;!-- Min value: 0 (inclusive) --&gt;
1013           &lt;!-- Max value: 65535 (inclusive) --&gt;
1014 
1015       &lt;!ELEMENT "com" EMPTY&gt;
1016         &lt;!-- A Comment marker segment. The user object contains the actual 
1017              bytes. --&gt; 
1018         &lt;!-- User object: array of [B --&gt;
1019         &lt;!-- Min length: 1 --&gt;
1020         &lt;!-- Max length: 65533 --&gt;
1021         &lt;!ATTLIST "com" "comment" #CDATA #IMPLIED&gt;
1022           &lt;!-- The comment as a string (used only if user object is null) 
1023                --&gt; 
1024           &lt;!-- Data type: String --&gt;
1025 
1026       &lt;!ELEMENT "unknown" EMPTY&gt;
1027         &lt;!-- An unrecognized marker segment. The user object contains the 
1028              data not including length. --&gt; 
1029         &lt;!-- User object: array of [B --&gt;
1030         &lt;!-- Min length: 1 --&gt;
1031         &lt;!-- Max length: 65533 --&gt;
1032         &lt;!ATTLIST "unknown" "MarkerTag" #CDATA #REQUIRED&gt;
1033           &lt;!-- The tag identifying this marker segment --&gt; 
1034           &lt;!-- Data type: Integer --&gt;
1035           &lt;!-- Min value: 0 (inclusive) --&gt;
1036           &lt;!-- Max value: 255 (inclusive) --&gt;
1037 
1038       &lt;!ELEMENT "app14Adobe" EMPTY&gt;
1039         &lt;!-- An Adobe APP14 marker segment --&gt; 
1040         &lt;!ATTLIST "app14Adobe" "version" #CDATA "100"&gt;
1041           &lt;!-- The version of Adobe APP14 marker segment --&gt; 
1042           &lt;!-- Data type: Integer --&gt;
1043           &lt;!-- Min value: 100 (inclusive) --&gt;
1044           &lt;!-- Max value: 255 (inclusive) --&gt;
1045         &lt;!ATTLIST "app14Adobe" "flags0" #CDATA "0"&gt;
1046           &lt;!-- The flags0 variable of an APP14 marker segment --&gt; 
1047           &lt;!-- Data type: Integer --&gt;
1048           &lt;!-- Min value: 0 (inclusive) --&gt;
1049           &lt;!-- Max value: 65535 (inclusive) --&gt;
1050         &lt;!ATTLIST "app14Adobe" "flags1" #CDATA "0"&gt;
1051           &lt;!-- The flags1 variable of an APP14 marker segment --&gt; 
1052           &lt;!-- Data type: Integer --&gt;
1053           &lt;!-- Min value: 0 (inclusive) --&gt;
1054           &lt;!-- Max value: 65535 (inclusive) --&gt;
1055         &lt;!ATTLIST "app14Adobe" "transform" ("0" | "1" | "2") #REQUIRED&gt;
1056           &lt;!-- The color transform applied to the image (0 = Unknown, 1 = 
1057                YCbCr, 2 = YCCK) --&gt; 
1058 
1059       &lt;!ELEMENT "sof" (componentSpec)*&gt;
1060         &lt;!-- A Start Of Frame marker segment --&gt; 
1061         &lt;!-- Min children: 1 --&gt;
1062         &lt;!-- Max children: 4 --&gt;
1063         &lt;!ATTLIST "sof" "process" ("0" | "1" | "2") #IMPLIED&gt;
1064           &lt;!-- The JPEG process (0 = Baseline sequential, 1 = Extended 
1065                sequential, 2 = Progressive) --&gt; 
1066         &lt;!ATTLIST "sof" "samplePrecision" #CDATA "8"&gt;
1067           &lt;!-- The number of bits per sample --&gt; 
1068           &lt;!-- Data type: Integer --&gt;
1069         &lt;!ATTLIST "sof" "numLines" #CDATA #IMPLIED&gt;
1070           &lt;!-- The number of lines in the image --&gt; 
1071           &lt;!-- Data type: Integer --&gt;
1072           &lt;!-- Min value: 0 (inclusive) --&gt;
1073           &lt;!-- Max value: 65535 (inclusive) --&gt;
1074         &lt;!ATTLIST "sof" "samplesPerLine" #CDATA #IMPLIED&gt;
1075           &lt;!-- The number of samples per line --&gt; 
1076           &lt;!-- Data type: Integer --&gt;
1077           &lt;!-- Min value: 0 (inclusive) --&gt;
1078           &lt;!-- Max value: 65535 (inclusive) --&gt;
1079         &lt;!ATTLIST "sof" "numFrameComponents" ("1" | "2" | "3" | "4")
1080            #IMPLIED&gt;
1081           &lt;!-- The number of components in the image --&gt; 
1082 
1083         &lt;!ELEMENT "componentSpec" EMPTY&gt;
1084           &lt;!-- A component specification for a frame --&gt; 
1085           &lt;!ATTLIST "componentSpec" "componentId" #CDATA #REQUIRED&gt;
1086             &lt;!-- The id for this component --&gt; 
1087             &lt;!-- Data type: Integer --&gt;
1088             &lt;!-- Min value: 0 (inclusive) --&gt;
1089             &lt;!-- Max value: 255 (inclusive) --&gt;
1090           &lt;!ATTLIST "componentSpec" "HsamplingFactor" #CDATA #REQUIRED&gt;
1091             &lt;!-- The horizontal sampling factor for this component --&gt; 
1092             &lt;!-- Data type: Integer --&gt;
1093             &lt;!-- Min value: 1 (inclusive) --&gt;
1094             &lt;!-- Max value: 255 (inclusive) --&gt;
1095           &lt;!ATTLIST "componentSpec" "VsamplingFactor" #CDATA #REQUIRED&gt;
1096             &lt;!-- The vertical sampling factor for this component --&gt; 
1097             &lt;!-- Data type: Integer --&gt;
1098             &lt;!-- Min value: 1 (inclusive) --&gt;
1099             &lt;!-- Max value: 255 (inclusive) --&gt;
1100           &lt;!ATTLIST "componentSpec" "QtableSelector" ("0" | "1" | "2" | 
1101             "3") #REQUIRED&gt;
1102             &lt;!-- The quantization table to use for this component --&gt; 
1103 
1104       &lt;!ELEMENT "sos" (scanComponentSpec)*&gt;
1105         &lt;!-- A Start Of Scan marker segment --&gt; 
1106         &lt;!-- Min children: 1 --&gt;
1107         &lt;!-- Max children: 4 --&gt;
1108         &lt;!ATTLIST "sos" "numScanComponents" ("1" | "2" | "3" | "4")
1109            #REQUIRED&gt;
1110           &lt;!-- The number of components in the scan --&gt; 
1111         &lt;!ATTLIST "sos" "startSpectralSelection" #CDATA "0"&gt;
1112           &lt;!-- The first spectral band included in this scan --&gt; 
1113           &lt;!-- Data type: Integer --&gt;
1114           &lt;!-- Min value: 0 (inclusive) --&gt;
1115           &lt;!-- Max value: 63 (inclusive) --&gt;
1116         &lt;!ATTLIST "sos" "endSpectralSelection" #CDATA "63"&gt;
1117           &lt;!-- The last spectral band included in this scan --&gt; 
1118           &lt;!-- Data type: Integer --&gt;
1119           &lt;!-- Min value: 0 (inclusive) --&gt;
1120           &lt;!-- Max value: 63 (inclusive) --&gt;
1121         &lt;!ATTLIST "sos" "approxHigh" #CDATA "0"&gt;
1122           &lt;!-- The highest bit position included in this scan --&gt; 
1123           &lt;!-- Data type: Integer --&gt;
1124           &lt;!-- Min value: 0 (inclusive) --&gt;
1125           &lt;!-- Max value: 15 (inclusive) --&gt;
1126         &lt;!ATTLIST "sos" "approxLow" #CDATA "0"&gt;
1127           &lt;!-- The lowest bit position included in this scan --&gt; 
1128           &lt;!-- Data type: Integer --&gt;
1129           &lt;!-- Min value: 0 (inclusive) --&gt;
1130           &lt;!-- Max value: 15 (inclusive) --&gt;
1131 
1132         &lt;!ELEMENT "scanComponentSpec" EMPTY&gt;
1133           &lt;!-- A component specification for a scan --&gt; 
1134           &lt;!ATTLIST "scanComponentSpec" "componentSelector" #CDATA
1135              #REQUIRED&gt;
1136             &lt;!-- The id of this component --&gt; 
1137             &lt;!-- Data type: Integer --&gt;
1138             &lt;!-- Min value: 0 (inclusive) --&gt;
1139             &lt;!-- Max value: 255 (inclusive) --&gt;
1140           &lt;!ATTLIST "scanComponentSpec" "dcHuffTable" ("0" | "1" | "2" | 
1141             "3") #REQUIRED&gt;
1142             &lt;!-- The huffman table to use for encoding DC coefficients --&gt; 
1143           &lt;!ATTLIST "scanComponentSpec" "acHuffTable" ("0" | "1" | "2" | 
1144             "3") #REQUIRED&gt;
1145             &lt;!-- The huffman table to use for encoding AC coefficients --&gt; 
1146 ]&gt;
1147 </pre>
1148 
1149 <h2>
1150 <a name=stream>Stream Metadata DTD</a>
1151 </h2>
1152 
1153 <pre>
1154 &lt;!DOCTYPE "javax_imageio_jpeg_stream_1.0" [
1155   &lt;!ELEMENT "javax_imageio_jpeg_stream_1.0" (dqt |
1156                       dht | 
1157                       dri | 
1158                       com | 
1159                       unknown)*&gt;
1160    
1161   &lt;!-- All elements are as defined above for image metadata --&gt;
1162 ]&gt;
1163 </pre>
1164 
1165 </body>
1166 </html>