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