src/java.desktop/share/classes/javax/imageio/metadata/doc-files/jpeg_metadata.html
Print this page
*** 1,10 ****
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
! Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
--- 1,10 ----
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
! Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
*** 44,65 ****
<a href=#prog>Progressive Encoding</a><br>
<a href=#tree>Native Metadata Format Tree Structure and Editing</a><br>
<a href=#image>Image Metadata DTD</a><br>
<a href=#stream>Stream Metadata DTD</a>
<p>
! <bold>NOTE</bold>: It is important to call <code>dispose()</code>
on the JPEG reader and writer objects when they are no longer needed, as
they consume significant native resources which are not adequately recovered
by garbage collection. Both reader and writer call <code>dispose()</code>
in their finalizers, but those finalizers may not be called before the native
code has exhausted native memory.
<p>
The JPEG writer does not support replacing pixels.
- <p>
<h2>
<a name=metadata>JPEG Metadata</a>
</h2>
JPEG metadata consists of the data contained in marker segments in a JPEG
stream. The image metadata object returned from a read describes the
--- 44,64 ----
<a href=#prog>Progressive Encoding</a><br>
<a href=#tree>Native Metadata Format Tree Structure and Editing</a><br>
<a href=#image>Image Metadata DTD</a><br>
<a href=#stream>Stream Metadata DTD</a>
<p>
! <b>NOTE</b>: It is important to call <code>dispose()</code>
on the JPEG reader and writer objects when they are no longer needed, as
they consume significant native resources which are not adequately recovered
by garbage collection. Both reader and writer call <code>dispose()</code>
in their finalizers, but those finalizers may not be called before the native
code has exhausted native memory.
<p>
The JPEG writer does not support replacing pixels.
<h2>
<a name=metadata>JPEG Metadata</a>
</h2>
JPEG metadata consists of the data contained in marker segments in a JPEG
stream. The image metadata object returned from a read describes the
*** 93,113 ****
object containing the tables from the <code>ImageWriteParam</code> argument,
if it is a <code>JPEGImageWriteParam</code> and contains tables. Otherwise,
the returned object will contain default tables.
<p>The <code>ImageWriter.getDefaultImageMetadata</code> method returns a
! metadata object containing <bold>no</bold> tables if the
<code>ImageWriteParam</code> argument contains tables. Otherwise the
returned metadata object will contain default visually lossless tables.
Of course, only a <code>JPEGImageWriteParam</code> may contain tables.
<p>
If <code>ignoreMetadata</code> is set to <code>true</code> when the input
is set on the reader, stream metadata will not be available, but image
metadata will.
- <p>
<h2>
<a name=abbrev>Abbreviated Streams</a>
</h2>
Both the reader and the writer retain their tables from one operation to the
next, thus permitting the use of abbreviated streams quite naturally, with a
--- 92,111 ----
object containing the tables from the <code>ImageWriteParam</code> argument,
if it is a <code>JPEGImageWriteParam</code> and contains tables. Otherwise,
the returned object will contain default tables.
<p>The <code>ImageWriter.getDefaultImageMetadata</code> method returns a
! metadata object containing <b>no</b> tables if the
<code>ImageWriteParam</code> argument contains tables. Otherwise the
returned metadata object will contain default visually lossless tables.
Of course, only a <code>JPEGImageWriteParam</code> may contain tables.
<p>
If <code>ignoreMetadata</code> is set to <code>true</code> when the input
is set on the reader, stream metadata will not be available, but image
metadata will.
<h2>
<a name=abbrev>Abbreviated Streams</a>
</h2>
Both the reader and the writer retain their tables from one operation to the
next, thus permitting the use of abbreviated streams quite naturally, with a
*** 192,202 ****
<p>
Note that if no image metadata object is specified for a particular image, a
default object is used, which includes default tables.
- <p>
<h2>
<a name=color>Colorspace Transformations and Conventional Markers</a>
</h2>
Colorspace transformations are controlled by the destination type for
both reading and writing of images. When <code>Raster</code>s are
--- 190,199 ----
*** 233,243 ****
is known to be either grayscale or YCbCr. If an <code>APP2</code>
marker segment containing an embedded ICC profile is also present, then
the YCbCr is converted to RGB according to the formulas given in the
JFIF spec, and the ICC profile is assumed to refer to the resulting RGB
space.
- <p>
<li> If an Adobe <code>APP14</code> marker segment is present, the
colorspace is determined by consulting the <code>transform</code> flag.
The <code>transform</code> flag takes one of three values:
<ul>
<li> 2 - The image is encoded as YCCK (implicitly converted from
--- 230,239 ----
*** 247,257 ****
on encoding).
<li> 0 - Unknown. 3-channel images are assumed to be RGB, 4-channel
images are assumed to be CMYK.
</ul>
- <p>
<li> If neither marker segment is present, the following procedure is
followed: Single-channel images are assumed to be grayscale, and
2-channel images are assumed to be grayscale with an alpha channel.
For 3- and 4-channel images, the component ids are consulted. If these
values are 1-3 for a 3-channel image, then the image is assumed to be
--- 243,252 ----
*** 271,287 ****
Otherwise, 3-channel subsampled images are assumed to be YCbCr,
3-channel non-subsampled images are assumed to be RGB, 4-channel
subsampled images are assumed to be YCCK, and 4-channel, non-subsampled
images are assumed to be CMYK.
- <p>
<li> All other images are declared uninterpretable and an exception is
thrown if an attempt is made to read one as a
<code>BufferedImage</code>. Such an image may be read only as a
<code>Raster</code>. If an image is interpretable but there is no Java
<code>ColorSpace</code> available corresponding to the encoded
! colorspace (<italic>e.g.</italic> YCbCr), then
<code>ImageReader.getRawImageType</code> will return <code>null</code>.
</ul>
Once an encoded colorspace is determined, then the target colorspace is
determined as follows:
--- 266,281 ----
Otherwise, 3-channel subsampled images are assumed to be YCbCr,
3-channel non-subsampled images are assumed to be RGB, 4-channel
subsampled images are assumed to be YCCK, and 4-channel, non-subsampled
images are assumed to be CMYK.
<li> All other images are declared uninterpretable and an exception is
thrown if an attempt is made to read one as a
<code>BufferedImage</code>. Such an image may be read only as a
<code>Raster</code>. If an image is interpretable but there is no Java
<code>ColorSpace</code> available corresponding to the encoded
! colorspace (<i>e.g.</i> YCbCr), then
<code>ImageReader.getRawImageType</code> will return <code>null</code>.
</ul>
Once an encoded colorspace is determined, then the target colorspace is
determined as follows:
*** 306,316 ****
library conversions are used with no further conversion in Java,
regardless of any destination type.</li>
<li> An exception is thrown if an attempt is made to read an image in an
unsupported jpeg colorspace as a <code>BufferedImage</code>
! (<italic>e.g.</italic> CMYK). Such images may be read as
<code>Raster</code>s. If an image colorspace is unsupported or
uninterpretable, then <code>ImageReader.getImageTypes</code> will
return an empty <code>Iterator</code>. If a subset of the raw bands
are required, a <code>Raster</code> must be obtained first and the
bands obtained from that. </li>
--- 300,310 ----
library conversions are used with no further conversion in Java,
regardless of any destination type.</li>
<li> An exception is thrown if an attempt is made to read an image in an
unsupported jpeg colorspace as a <code>BufferedImage</code>
! (<i>e.g.</i> CMYK). Such images may be read as
<code>Raster</code>s. If an image colorspace is unsupported or
uninterpretable, then <code>ImageReader.getImageTypes</code> will
return an empty <code>Iterator</code>. If a subset of the raw bands
are required, a <code>Raster</code> must be obtained first and the
bands obtained from that. </li>
*** 512,522 ****
<li> If neither node is present in the metadata object, no conversion
is applied, and no special marker segment is written.
</ul>
</ul>
- <p>
<h2>
<a name=thumbs>Thumbnail Images</a>
</h2>
Thumbnails are supported by the use of JFIF and JFIF extension marker segments.
Thumbnails provided on the write methods determine the thumbnails that will be
--- 506,515 ----
*** 589,599 ****
<li> If there are multiple thumbnails, each one is processed as above, except
that no thumbnail is placed in the JFIF <code>APP0</code> segment, and
the <code>app0JFXX</code> node consulted for each thumbnail is the
<code>app0JFXX</code> node from the metadata that occurs in the same
! sequence as the thumbnail. <italic>I.e.</italic> the first
<code>app0JFXX</code> node applies to the first thumbnail, the second
node to the second thumbnail, and so on. If there are fewer
<code>app0JFXX</code> nodes in the metadata than thumbnails, then
those thumbnails are considered to have no matching
<code>app0JFXX</code> node. An RGB thumbnail with no matching
--- 582,592 ----
<li> If there are multiple thumbnails, each one is processed as above, except
that no thumbnail is placed in the JFIF <code>APP0</code> segment, and
the <code>app0JFXX</code> node consulted for each thumbnail is the
<code>app0JFXX</code> node from the metadata that occurs in the same
! sequence as the thumbnail. <i>I.e.</i> the first
<code>app0JFXX</code> node applies to the first thumbnail, the second
node to the second thumbnail, and so on. If there are fewer
<code>app0JFXX</code> nodes in the metadata than thumbnails, then
those thumbnails are considered to have no matching
<code>app0JFXX</code> node. An RGB thumbnail with no matching
*** 608,618 ****
JFIF or JFIF extension marker segments, only grayscale or RGB images
may have thumbnails. If thumbnails are present when writing any other type
of image, the thumbnails are ignored and a warning is sent to any warning
listeners.
- <p>
<h2>
<a name=prog>Progressive Encoding</a>
</h2>
Progressive encoding must be enabled on the <code>ImageWriteParam</code>
--- 601,610 ----
*** 629,639 ****
If Huffman-table optimization is requested on the <code>ImageWriteParam</code>,
all Huffman tables in the metadata or in the <code>ImageWriteParam</code>
itself are ignored, and a warning will be sent to any warning listeners if
any such tables are present.
- <p>
<h2>
<a name=tree>Native Metadata Format Tree Structure and Editing</a>
</h2>
The DTDs below describe just the trees of metadata objects actually returned
--- 621,630 ----