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