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