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
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
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
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
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>
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 -->
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>
|
1 <!doctype html>
2 <html lang="en">
3 <head>
4 <meta charset="utf-8"/>
5 <title>JPEG Metadata Format Specification and Usage Notes</title>
6 </head>
7 <!--
8 Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
9 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10
11 This code is free software; you can redistribute it and/or modify it
12 under the terms of the GNU General Public License version 2 only, as
13 published by the Free Software Foundation. Oracle designates this
14 particular file as subject to the "Classpath" exception as provided
15 by Oracle in the LICENSE file that accompanied this code.
16
17 This code is distributed in the hope that it will be useful, but WITHOUT
18 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 version 2 for more details (a copy is included in the LICENSE file that
21 accompanied this code).
22
23 You should have received a copy of the GNU General Public License version
24 2 along with this work; if not, write to the Free Software Foundation,
25 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
26
27 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
28 or visit www.oracle.com if you need additional information or have any
29 questions.
30 -->
31
32 <body>
33
34 <h1>JPEG Metadata Format Specification and Usage Notes</h1>
35
36 <p>
37 <a href=#metadata>JPEG Metadata</a><br>
38 <a href=#abbrev>Abbreviated Streams</a><br>
39 <a href=#tables>Sources of Tables</a><br>
40 <a href=#color>Colorspace Transformations and Conventional Markers</a><br>
41 <a href=#thumbs>Thumbnail Images</a><br>
42 <a href=#prog>Progressive Encoding</a><br>
43 <a href=#tree>Native Metadata Format Tree Structure and Editing</a><br>
44 <a href=#image>Image Metadata DTD</a><br>
45 <a href=#stream>Stream Metadata DTD</a>
46 <p>
47 <b>NOTE</b>: It is important to call <code>dispose()</code>
48 on the JPEG reader and writer objects when they are no longer needed, as
49 they consume significant native resources which are not adequately recovered
50 by garbage collection. Both reader and writer call <code>dispose()</code>
51 in their finalizers, but those finalizers may not be called before the native
52 code has exhausted native memory.
53
54 <p>
55
56 The JPEG writer does not support replacing pixels.
57
58 <h2>
59 <a id=metadata>JPEG Metadata</a>
60 </h2>
61 JPEG metadata consists of the data contained in marker segments in a JPEG
62 stream. The image metadata object returned from a read describes the
63 contents of the marker segments between the <code>SOI</code> marker and
64 the <code>EOI</code> marker for that image. The image metadata object
65 passed into a write determines the contents of the stream between the
66 <code>SOI</code> marker and the <code>EOI</code> marker for that image,
67 subject to the controls in any <code>ImageWriteParam</code>.
68
69 <p>
70 Stream metadata is used only for tables-only images found (or to be
71 placed) at the beginning of a stream containing abbreviated images.
72 Tables-only images are not treated as images and do not consume an
73 image index. The stream metadata object returned from a read describes the
74 contents of the marker segments between the <code>SOI</code> marker and
75 the <code>EOI</code> marker for the single tables-only image at the
76 beginning of the stream, if one is present. If no tables-only image is
77 present at the front of the stream, the <code>getStreamMetadata</code>
78 method of <code>ImageReader</code> returns <code>null</code>. If
79 stream metadata is provided to the writer, a single tables-only image
86 other methods.
87
88 <p>
89 The <code>ImageWriter.getDefaultStreamMetadata</code> method returns an
90 object containing the tables from the <code>ImageWriteParam</code> argument,
91 if it is a <code>JPEGImageWriteParam</code> and contains tables. Otherwise,
92 the returned object will contain default tables.
93
94 <p>The <code>ImageWriter.getDefaultImageMetadata</code> method returns a
95 metadata object containing <b>no</b> tables if the
96 <code>ImageWriteParam</code> argument contains tables. Otherwise the
97 returned metadata object will contain default visually lossless tables.
98 Of course, only a <code>JPEGImageWriteParam</code> may contain tables.
99
100 <p>
101 If <code>ignoreMetadata</code> is set to <code>true</code> when the input
102 is set on the reader, stream metadata will not be available, but image
103 metadata will.
104
105 <h2>
106 <a id=abbrev>Abbreviated Streams</a>
107 </h2>
108 Both the reader and the writer retain their tables from one operation to the
109 next, thus permitting the use of abbreviated streams quite naturally, with a
110 few minor restrictions:
111 <ol>
112 <li> Abbreviated streams may contain only one tables-only image, which must
113 come first in the stream. Subsequent tables-only images will cause
114 undefined behavior.</li>
115 <li> Abbreviated streams must be read fully and in order. No random access
116 is allowed, in either direction. The same image may be read multiple
117 times. If a call is made with an image index that is not the same as
118 or one greater than the most recent call (or 0 if no calls have been
119 made), then an <code>IllegalArgumentException</code> is thrown.</li>
120 </ol>
121 These restrictions mean that streams may contain abbreviated images
122 interspersed with images containing tables. As required by JPEG, any tables
123 appearing in the stream override previous tables, regardless of the source
124 of the previous tables.
125
126 <p>
127 Note that once a tables-only image has been read, it's contents is available
128 as stream metadata from the reader until either another tables-only image
129 is read from another stream or the reader is reset. Changing the input does
130 not reset the stream metadata. This is useful for reading the tables from
131 one file, then changing the input to read an abbreviated stream containing
132 a sequence of images. The tables will be used automatically, and will remain
133 available as "stream" metadata.
134
135 <p>
136 Abbreviated streams are written using the sequence methods of
137 <code>ImageWriter</code>. Stream metadata is used to write a tables-only
138 image at the beginning of the stream, and the tables are set up for use, using
139 <code>ImageWriter.prepareWriteSequence</code>. If no stream metadata is
140 supplied to <code>ImageWriter.prepareWriteSequence</code>, then no
141 tables-only image is written. If stream metadata containing no tables is
142 supplied to <code>ImageWriter.prepareWriteSequence</code>, then a tables-only
143 image containing default visually lossless tables is written.
144
145 <h2>
146 <a id=tables>Sources of Tables</a>
147 </h2>
148 <p>
149 Images are written with tables if tables are present in their metadata objects
150 or without them if no tables are present in their metadata objects. If no
151 metadata object is present then the tables are written. The tables used for
152 compression are taken from one of the following sources, which are consulted
153 in order:
154 <ol>
155 <li> If there is an <code>ImageWriteParam</code> and the compression mode is
156 set to <code>EXPLICIT</code>, default tables constructed using the
157 quality setting are used. They are written only if the metadata
158 contains tables or if there is no metadata, but they replace the
159 tables in the metadata.</li>
160 <li> If there is an <code>ImageWriteParam</code> and the compression mode is
161 set to <code>DEFAULT</code>, default visually lossles tables are used.
162 They are written only if the metadata contains tables or if
163 there is no metadata, but they replace the tables in the
164 metadata.</li>
165 <li> Otherwise the compression mode on the <code>ImageWriteParam</code> must
166 be MODE_COPY_FROM_<code>METADATA</code>, in which case the following
174 </li>
175 </ol>
176
177 This ordering implements the design intention that tables should be included
178 in <code>JPEGImageWriteParam</code>s only as a means of specifying tables
179 when no other source is available, and this can occur only when writing to an
180 abbreviated stream without tables using known non-standard tables for
181 compression.
182
183 <p>
184 When reading, tables in a <code>JPEGImageReadParam</code> are consulted only
185 if tables have not been set by any previous read. Tables set from a
186 <code>JPEGImageReadParam</code> are overridden by any tables present in the
187 stream being read.
188
189 <p>
190 Note that if no image metadata object is specified for a particular image, a
191 default object is used, which includes default tables.
192
193 <h2>
194 <a id=color>Colorspace Transformations and Conventional Markers</a>
195 </h2>
196 Colorspace transformations are controlled by the destination type for
197 both reading and writing of images. When <code>Raster</code>s are
198 read, no colorspace transformation is performed, and any destination type
199 is ignored. A warning is sent to any listeners if a destination type is
200 specified in this case. When <code>Raster</code>s are written, any
201 destination type is used to interpret the bands. This might result in a
202 JFIF or Adobe header being written, or different component ids being written
203 to the frame and scan headers. If values present in a metadata object do not
204 match the destination type, the destination type is used and a warning is sent
205 to any listeners.
206
207 <p>
208
209 <a id=optcolor><b>Optional ColorSpace support:</b></a>
210 Handling of PhotoYCC (YCC), PhotoYCCA (YCCA), RGBA and YCbCrA color spaces
211 by the standard plugin, as described below, is dependent on capabilities
212 of the libraries used to interpret the JPEG data. Thus all consequential
213 behaviors are optional. If the support is not available when decoding,
214 the color space will be treated as unrecognized and the appropriate
215 default color space for the specified number of component channels
216 may be used.
217 When writing, an Exception may be thrown if no suitable conversion
218 can be applied before encoding.
219 But where the support for these color spaces is available, the behavior
220 must be as documented.
221 <p>
222
223 When reading, the contents of the stream are interpreted by the usual
224 JPEG conventions, as follows:
225
226 <ul>
227 <li> If a JFIF <code>APP0</code> marker segment is present, the colorspace
228 is known to be either grayscale or YCbCr. If an <code>APP2</code>
229 marker segment containing an embedded ICC profile is also present, then
490 <li> PhotoYCCA Images:
491 Subject to the <a href=#optcolor>optional library support</a>
492 described above,
493 <ul>
494 <li> If an <code>app0JFIF</code> node is present in the metadata object,
495 it is ignored and a warning is sent to listeners, as JFIF does not
496 support 4-channel images.
497
498 <li> If an <code>app14Adobe</code> node is present in the metadata
499 object, no conversion is applied, and an Adobe <code>APP14</code>
500 marker segment is written. The color transform must be
501 <code>UNKNOWN</code>. If it is not, a warning is sent to
502 listeners.
503
504 <li> If neither node is present in the metadata object, no conversion
505 is applied, and no special marker segment is written.
506 </ul>
507 </ul>
508
509 <h2>
510 <a id=thumbs>Thumbnail Images</a>
511 </h2>
512 Thumbnails are supported by the use of JFIF and JFIF extension marker segments.
513 Thumbnails provided on the write methods determine the thumbnails that will be
514 included. <code>app0JFIF</code> and <code>app0JFXX</code> nodes present in
515 the metadata do not contain any thumbnail pixel data. However, the kinds of
516 thumbnails written depend on the contents of the metadata object, as follows.
517 Any thumbnail which is to be written as an indexed or RGB image and which is
518 larger than 255 by 255 will be clipped, not scaled, to 255 by 255. Thumbnails
519 written as JPEG images may be any size. A warning is sent to any listeners
520 whenever a thumbnail is clipped.
521 <ul>
522 <li> If there is a single thumbnail, it is processed as follows:
523 <ul>
524 <li> If the thumbnail image is an RGB palette image, it is processed as
525 follows:
526 <ul>
527 <li> If no <code>app0JFXX</code> node is present in the metadata, or
528 the first <code>app0JFXX</code> node present in the metadata
529 contains a <code>JFIFthumbPalette</code> element, a
530 palette thumbnail is written in a JFXX <code>APP0</code> marker
585 sequence as the thumbnail. <i>I.e.</i> the first
586 <code>app0JFXX</code> node applies to the first thumbnail, the second
587 node to the second thumbnail, and so on. If there are fewer
588 <code>app0JFXX</code> nodes in the metadata than thumbnails, then
589 those thumbnails are considered to have no matching
590 <code>app0JFXX</code> node. An RGB thumbnail with no matching
591 <code>app0JFXX</code> node is written in a JFXX <code>APP0</code> marker
592 segment. A grayscale thumbnail with no matching
593 <code>app0JFXX</code> node is written as a JPEG image to a JFXX
594 <code>APP0</code> marker segment.
595 </ul>
596 <p>
597
598 Note that as the only mechanism for storing thumbnails is via the
599 JFIF or JFIF extension marker segments, only grayscale or RGB images
600 may have thumbnails. If thumbnails are present when writing any other type
601 of image, the thumbnails are ignored and a warning is sent to any warning
602 listeners.
603
604 <h2>
605 <a id=prog>Progressive Encoding</a>
606 </h2>
607
608 Progressive encoding must be enabled on the <code>ImageWriteParam</code>
609 passed in to a write operation, or the image will be written sequentially,
610 regardless of the scan headers included in the metadata object. If
611 progressive encoding is enabled and set to copy from metadata, then
612 the sequence of scan headers from the metadata is used to write the
613 image. If progressive encoding is enabled and set to use a default,
614 then the scans in the metadata are ignored and a default set of scans
615 is used. Progressive encoding always forces optimized Huffman tables to
616 be used. Any Huffman tables present in the metadata will be ignored,
617 and a warning will be sent to any warning listeners.
618
619 If Huffman-table optimization is requested on the <code>ImageWriteParam</code>,
620 all Huffman tables in the metadata or in the <code>ImageWriteParam</code>
621 itself are ignored, and a warning will be sent to any warning listeners if
622 any such tables are present.
623
624 <h2>
625 <a id=tree>Native Metadata Format Tree Structure and Editing</a>
626 </h2>
627
628 The DTDs below describe just the trees of metadata objects actually returned
629 by the <code>IIOMetadata</code> object. They do not include nodes
630 corresponding to <code>SOI</code>, <code>EOI</code>, or <code>RST</code>
631 markers, as these parsing delimiters do not carry any meaningful metadata.
632 <p>
633
634 The first node is always a <code>JPEGvariety</code> node. In the
635 <code>javax_imageio_jpeg_image_1.0</code> version of the JPEG metadata
636 format, this node may have one child, an <code>app0JFIF</code> node,
637 indicating that the JPEG stream contains a JFIF marker segment and related
638 data, or no children, indicating that the stream contains no JFIF marker.
639 In future versions of the JPEG metadata format, other varieties of JPEG
640 metadata may be supported (e.g. Exif) by defining other types of nodes
641 which may appear as a child of the <code>JPEGvariety</code> node.
642 <p>
643
644 (Note that an application wishing to interpret Exif metadata given
645 a metadata tree structure in the <code>javax_imageio_jpeg_image_1.0</code>
862 containing appropriate values, if there can be one. An appropriate
863 pair of integers is computed from the floating-point ratio for
864 inclusion in the node.
865 <li> <code>Text</code> - Each uncompressed text item is converted to a
866 <code>com</code> node and inserted according to the rules above for
867 merging <code>com</code> nodes.
868 </ul>
869
870 <p> <code>setFromTree</code> - Native Format
871 <br>
872 The <code>setFromTree</code> operation, when given a tree in the native
873 format described below, will simply replace the existing tree in its entirety
874 with the new one. The tree must consist of <code>IIOMetadataNode</code>s.
875
876 <p> <code>setFromTree</code> - Standard Format
877 <br>
878 The <code>setFromTree</code> operation, when given a tree in the standard
879 format, performs a <code>reset</code> followed by a merge of the new tree.
880
881 <h2>
882 <a id=image>Image Metadata DTD</a>
883 </h2>
884
885 <pre>
886 <!DOCTYPE "javax_imageio_jpeg_image_1.0" [
887
888 <!ELEMENT "javax_imageio_jpeg_image_1.0" (JPEGvariety, markerSequence)>
889
890 <!ELEMENT "JPEGvariety" (app0JFIF)>
891 <!-- A node grouping all marker segments specific to the variety of
892 stream being read/written (e.g. JFIF) - may be empty -->
893
894 <!ELEMENT "app0JFIF" (JFXX?, app2ICC?)>
895 <!ATTLIST "app0JFIF" "majorVersion" #CDATA "1">
896 <!-- The major JFIF version number -->
897 <!-- Data type: Integer -->
898 <!-- Min value: 0 (inclusive) -->
899 <!-- Max value: 255 (inclusive) -->
900 <!ATTLIST "app0JFIF" "minorVersion" #CDATA "2">
901 <!-- The minor JFIF version number -->
902 <!-- Data type: Integer -->
1128 <!-- Max value: 15 (inclusive) -->
1129
1130 <!ELEMENT "scanComponentSpec" EMPTY>
1131 <!-- A component specification for a scan -->
1132 <!ATTLIST "scanComponentSpec" "componentSelector" #CDATA
1133 #REQUIRED>
1134 <!-- The id of this component -->
1135 <!-- Data type: Integer -->
1136 <!-- Min value: 0 (inclusive) -->
1137 <!-- Max value: 255 (inclusive) -->
1138 <!ATTLIST "scanComponentSpec" "dcHuffTable" ("0" | "1" | "2" |
1139 "3") #REQUIRED>
1140 <!-- The huffman table to use for encoding DC coefficients -->
1141 <!ATTLIST "scanComponentSpec" "acHuffTable" ("0" | "1" | "2" |
1142 "3") #REQUIRED>
1143 <!-- The huffman table to use for encoding AC coefficients -->
1144 ]>
1145 </pre>
1146
1147 <h2>
1148 <a id=stream>Stream Metadata DTD</a>
1149 </h2>
1150
1151 <pre>
1152 <!DOCTYPE "javax_imageio_jpeg_stream_1.0" [
1153 <!ELEMENT "javax_imageio_jpeg_stream_1.0" (dqt |
1154 dht |
1155 dri |
1156 com |
1157 unknown)*>
1158
1159 <!-- All elements are as defined above for image metadata -->
1160 ]>
1161 </pre>
1162
1163 </body>
1164 </html>
|