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