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 <!DOCTYPE "javax_imageio_jpeg_image_1.0" [ 887 888 <!ELEMENT "javax_imageio_jpeg_image_1.0" (JPEGvariety, markerSequence)> 889 890 <!ELEMENT "JPEGvariety" (app0JFIF)> 891 <!-- A node grouping all marker segments specific to the variety of 892 stream being read/written (e.g. JFIF) - may be empty --> 893 894 <!ELEMENT "app0JFIF" (JFXX?, app2ICC?)> 895 <!ATTLIST "app0JFIF" "majorVersion" #CDATA "1"> 896 <!-- The major JFIF version number --> 897 <!-- Data type: Integer --> 898 <!-- Min value: 0 (inclusive) --> 899 <!-- Max value: 255 (inclusive) --> 900 <!ATTLIST "app0JFIF" "minorVersion" #CDATA "2"> 901 <!-- The minor JFIF version number --> 902 <!-- Data type: Integer --> 903 <!-- Min value: 0 (inclusive) --> 904 <!-- Max value: 255 (inclusive) --> 905 <!ATTLIST "app0JFIF" "resUnits" ("0" | "1" | "2") "0"> 906 <!-- The resolution units for Xdensisty and Ydensity (0 = no 907 units, just aspect ratio; 1 = dots/inch; 2 = dots/cm) --> 908 <!ATTLIST "app0JFIF" "Xdensity" #CDATA "1"> 909 <!-- The horizontal density or aspect ratio numerator --> 910 <!-- Data type: Integer --> 911 <!-- Min value: 1 (inclusive) --> 912 <!-- Max value: 65535 (inclusive) --> 913 <!ATTLIST "app0JFIF" "Ydensity" #CDATA "1"> 914 <!-- The vertical density or aspect ratio denominator --> 915 <!-- Data type: Integer --> 916 <!-- Min value: 1 (inclusive) --> 917 <!-- Max value: 65535 (inclusive) --> 918 <!ATTLIST "app0JFIF" "thumbWidth" #CDATA "0"> 919 <!-- The width of the thumbnail, or 0 if there isn't one --> 920 <!-- Data type: Integer --> 921 <!-- Min value: 0 (inclusive) --> 922 <!-- Max value: 255 (inclusive) --> 923 <!ATTLIST "app0JFIF" "thumbHeight" #CDATA "0"> 924 <!-- The height of the thumbnail, or 0 if there isn't one --> 925 <!-- Data type: Integer --> 926 <!-- Min value: 0 (inclusive) --> 927 <!-- Max value: 255 (inclusive) --> 928 929 <!ELEMENT "JFXX" (app0JFXX)*> 930 <!-- Min children: 1 --> 931 932 <!ELEMENT "app0JFXX" (JFIFthumbJPEG | JFIFthumbPalette | 933 JFIFthumbRGB)> 934 <!-- A JFIF extension marker segment --> 935 <!ATTLIST "app0JFXX" "extensionCode" ("16" | "17" | "19") 936 #IMPLIED> 937 <!-- The JFXX extension code identifying thumbnail type: (16 = 938 JPEG, 17 = indexed, 19 = RGB --> 939 940 <!ELEMENT "JFIFthumbJPEG" (markerSequence?)> 941 <!-- A JFIF thumbnail in JPEG format (no JFIF segments 942 permitted) --> 943 944 <!ELEMENT "JFIFthumbPalette" EMPTY> 945 <!-- A JFIF thumbnail as an RGB indexed image --> 946 <!ATTLIST "JFIFthumbPalette" "thumbWidth" #CDATA #IMPLIED> 947 <!-- The width of the thumbnail --> 948 <!-- Data type: Integer --> 949 <!-- Min value: 0 (inclusive) --> 950 <!-- Max value: 255 (inclusive) --> 951 <!ATTLIST "JFIFthumbPalette" "thumbHeight" #CDATA #IMPLIED> 952 <!-- The height of the thumbnail --> 953 <!-- Data type: Integer --> 954 <!-- Min value: 0 (inclusive) --> 955 <!-- Max value: 255 (inclusive) --> 956 957 <!ELEMENT "JFIFthumbRGB" EMPTY> 958 <!-- A JFIF thumbnail as an RGB image --> 959 <!ATTLIST "JFIFthumbRGB" "thumbWidth" #CDATA #IMPLIED> 960 <!-- The width of the thumbnail --> 961 <!-- Data type: Integer --> 962 <!-- Min value: 0 (inclusive) --> 963 <!-- Max value: 255 (inclusive) --> 964 <!ATTLIST "JFIFthumbRGB" "thumbHeight" #CDATA #IMPLIED> 965 <!-- The height of the thumbnail --> 966 <!-- Data type: Integer --> 967 <!-- Min value: 0 (inclusive) --> 968 <!-- Max value: 255 (inclusive) --> 969 970 <!ELEMENT "app2ICC" EMPTY> 971 <!-- An ICC profile APP2 marker segment --> 972 <!-- Optional User object: java.awt.color.ICC_Profile --> 973 974 <!ELEMENT "markerSequence" (dqt | dht | dri | com | unknown | 975 app14Adobe | sof | sos)*> 976 <!-- A node grouping all non-jfif marker segments --> 977 978 <!ELEMENT "dqt" (dqtable)*> 979 <!-- A Define Quantization Table(s) marker segment --> 980 <!-- Min children: 1 --> 981 <!-- Max children: 4 --> 982 983 <!ELEMENT "dqtable" EMPTY> 984 <!-- A single quantization table --> 985 <!-- User object: javax.imageio.plugins.jpeg.JPEGQTable --> 986 <!ATTLIST "dqtable" "elementPrecision" #CDATA "0"> 987 <!-- The number of bits in each table element (0 = 8, 1 = 16) 988 --> 989 <!-- Data type: Integer --> 990 <!ATTLIST "dqtable" "qtableId" ("0" | "1" | "2" | "3") #REQUIRED> 991 992 <!ELEMENT "dht" (dhtable)*> 993 <!-- A Define Huffman Table(s) marker segment --> 994 <!-- Min children: 1 --> 995 <!-- Max children: 4 --> 996 997 <!ELEMENT "dhtable" EMPTY> 998 <!-- A single Huffman table --> 999 <!-- User object: javax.imageio.plugins.jpeg.JPEGHuffmanTable --> 1000 <!ATTLIST "dhtable" "class" ("0" | "1") #REQUIRED> 1001 <!-- Indicates whether this is a DC (0) or an AC (1) table --> 1002 <!ATTLIST "dhtable" "htableId" ("0" | "1" | "2" | "3") #REQUIRED> 1003 <!-- The table id --> 1004 1005 <!ELEMENT "dri" EMPTY> 1006 <!-- A Define Restart Interval marker segment --> 1007 <!ATTLIST "dri" "interval" #CDATA #REQUIRED> 1008 <!-- The restart interval in MCUs --> 1009 <!-- Data type: Integer --> 1010 <!-- Min value: 0 (inclusive) --> 1011 <!-- Max value: 65535 (inclusive) --> 1012 1013 <!ELEMENT "com" EMPTY> 1014 <!-- A Comment marker segment. The user object contains the actual 1015 bytes. --> 1016 <!-- User object: array of [B --> 1017 <!-- Min length: 1 --> 1018 <!-- Max length: 65533 --> 1019 <!ATTLIST "com" "comment" #CDATA #IMPLIED> 1020 <!-- The comment as a string (used only if user object is null) 1021 --> 1022 <!-- Data type: String --> 1023 1024 <!ELEMENT "unknown" EMPTY> 1025 <!-- An unrecognized marker segment. The user object contains the 1026 data not including length. --> 1027 <!-- User object: array of [B --> 1028 <!-- Min length: 1 --> 1029 <!-- Max length: 65533 --> 1030 <!ATTLIST "unknown" "MarkerTag" #CDATA #REQUIRED> 1031 <!-- The tag identifying this marker segment --> 1032 <!-- Data type: Integer --> 1033 <!-- Min value: 0 (inclusive) --> 1034 <!-- Max value: 255 (inclusive) --> 1035 1036 <!ELEMENT "app14Adobe" EMPTY> 1037 <!-- An Adobe APP14 marker segment --> 1038 <!ATTLIST "app14Adobe" "version" #CDATA "100"> 1039 <!-- The version of Adobe APP14 marker segment --> 1040 <!-- Data type: Integer --> 1041 <!-- Min value: 100 (inclusive) --> 1042 <!-- Max value: 255 (inclusive) --> 1043 <!ATTLIST "app14Adobe" "flags0" #CDATA "0"> 1044 <!-- The flags0 variable of an APP14 marker segment --> 1045 <!-- Data type: Integer --> 1046 <!-- Min value: 0 (inclusive) --> 1047 <!-- Max value: 65535 (inclusive) --> 1048 <!ATTLIST "app14Adobe" "flags1" #CDATA "0"> 1049 <!-- The flags1 variable of an APP14 marker segment --> 1050 <!-- Data type: Integer --> 1051 <!-- Min value: 0 (inclusive) --> 1052 <!-- Max value: 65535 (inclusive) --> 1053 <!ATTLIST "app14Adobe" "transform" ("0" | "1" | "2") #REQUIRED> 1054 <!-- The color transform applied to the image (0 = Unknown, 1 = 1055 YCbCr, 2 = YCCK) --> 1056 1057 <!ELEMENT "sof" (componentSpec)*> 1058 <!-- A Start Of Frame marker segment --> 1059 <!-- Min children: 1 --> 1060 <!-- Max children: 4 --> 1061 <!ATTLIST "sof" "process" ("0" | "1" | "2") #IMPLIED> 1062 <!-- The JPEG process (0 = Baseline sequential, 1 = Extended 1063 sequential, 2 = Progressive) --> 1064 <!ATTLIST "sof" "samplePrecision" #CDATA "8"> 1065 <!-- The number of bits per sample --> 1066 <!-- Data type: Integer --> 1067 <!ATTLIST "sof" "numLines" #CDATA #IMPLIED> 1068 <!-- The number of lines in the image --> 1069 <!-- Data type: Integer --> 1070 <!-- Min value: 0 (inclusive) --> 1071 <!-- Max value: 65535 (inclusive) --> 1072 <!ATTLIST "sof" "samplesPerLine" #CDATA #IMPLIED> 1073 <!-- The number of samples per line --> 1074 <!-- Data type: Integer --> 1075 <!-- Min value: 0 (inclusive) --> 1076 <!-- Max value: 65535 (inclusive) --> 1077 <!ATTLIST "sof" "numFrameComponents" ("1" | "2" | "3" | "4") 1078 #IMPLIED> 1079 <!-- The number of components in the image --> 1080 1081 <!ELEMENT "componentSpec" EMPTY> 1082 <!-- A component specification for a frame --> 1083 <!ATTLIST "componentSpec" "componentId" #CDATA #REQUIRED> 1084 <!-- The id for this component --> 1085 <!-- Data type: Integer --> 1086 <!-- Min value: 0 (inclusive) --> 1087 <!-- Max value: 255 (inclusive) --> 1088 <!ATTLIST "componentSpec" "HsamplingFactor" #CDATA #REQUIRED> 1089 <!-- The horizontal sampling factor for this component --> 1090 <!-- Data type: Integer --> 1091 <!-- Min value: 1 (inclusive) --> 1092 <!-- Max value: 255 (inclusive) --> 1093 <!ATTLIST "componentSpec" "VsamplingFactor" #CDATA #REQUIRED> 1094 <!-- The vertical sampling factor for this component --> 1095 <!-- Data type: Integer --> 1096 <!-- Min value: 1 (inclusive) --> 1097 <!-- Max value: 255 (inclusive) --> 1098 <!ATTLIST "componentSpec" "QtableSelector" ("0" | "1" | "2" | 1099 "3") #REQUIRED> 1100 <!-- The quantization table to use for this component --> 1101 1102 <!ELEMENT "sos" (scanComponentSpec)*> 1103 <!-- A Start Of Scan marker segment --> 1104 <!-- Min children: 1 --> 1105 <!-- Max children: 4 --> 1106 <!ATTLIST "sos" "numScanComponents" ("1" | "2" | "3" | "4") 1107 #REQUIRED> 1108 <!-- The number of components in the scan --> 1109 <!ATTLIST "sos" "startSpectralSelection" #CDATA "0"> 1110 <!-- The first spectral band included in this scan --> 1111 <!-- Data type: Integer --> 1112 <!-- Min value: 0 (inclusive) --> 1113 <!-- Max value: 63 (inclusive) --> 1114 <!ATTLIST "sos" "endSpectralSelection" #CDATA "63"> 1115 <!-- The last spectral band included in this scan --> 1116 <!-- Data type: Integer --> 1117 <!-- Min value: 0 (inclusive) --> 1118 <!-- Max value: 63 (inclusive) --> 1119 <!ATTLIST "sos" "approxHigh" #CDATA "0"> 1120 <!-- The highest bit position included in this scan --> 1121 <!-- Data type: Integer --> 1122 <!-- Min value: 0 (inclusive) --> 1123 <!-- Max value: 15 (inclusive) --> 1124 <!ATTLIST "sos" "approxLow" #CDATA "0"> 1125 <!-- The lowest bit position included in this scan --> 1126 <!-- Data type: Integer --> 1127 <!-- Min value: 0 (inclusive) --> 1128 <!-- Max value: 15 (inclusive) --> 1129 1130 <!ELEMENT "scanComponentSpec" EMPTY> 1131 <!-- A component specification for a scan --> 1132 <!ATTLIST "scanComponentSpec" "componentSelector" #CDATA 1133 #REQUIRED> 1134 <!-- The id of this component --> 1135 <!-- Data type: Integer --> 1136 <!-- Min value: 0 (inclusive) --> 1137 <!-- Max value: 255 (inclusive) --> 1138 <!ATTLIST "scanComponentSpec" "dcHuffTable" ("0" | "1" | "2" | 1139 "3") #REQUIRED> 1140 <!-- The huffman table to use for encoding DC coefficients --> 1141 <!ATTLIST "scanComponentSpec" "acHuffTable" ("0" | "1" | "2" | 1142 "3") #REQUIRED> 1143 <!-- The huffman table to use for encoding AC coefficients --> 1144 ]> 1145 </pre> 1146 1147 <h2> 1148 <a id=stream>Stream Metadata DTD</a> 1149 </h2> 1150 1151 <pre> 1152 <!DOCTYPE "javax_imageio_jpeg_stream_1.0" [ 1153 <!ELEMENT "javax_imageio_jpeg_stream_1.0" (dqt | 1154 dht | 1155 dri | 1156 com | 1157 unknown)*> 1158 1159 <!-- All elements are as defined above for image metadata --> 1160 ]> 1161 </pre> 1162 1163 </body> 1164 </html> --- EOF ---