Blame - jdk/src/share/classes/javax/imageio/metadata/doc-files/jpeg_metadata.html - platform/libcore

J. Duke

319a3b9

2007-12-01 00:00:00 +0000

[diff] [blame^]

1

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>

<head>

<!--

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. Sun designates this

11

particular file as subject to the "Classpath" exception as provided

12

by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

25

CA 95054 USA or visit www.sun.com if you need additional information or

have any questions.

-->

<title>JPEG Metadata Format Specification and Usage Notes</title>

</head>

JPEG Metadata Format Specification and Usage Notes

</h1></center>

<p>

<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.

<p>

The JPEG writer does not support replacing pixels.

<p>

<h2>

<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

other methods.

<p>

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

metadata will.

<p>

<h2>

<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.

</li>

</ol>

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

compression.

<p>

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

stream being read.

<p>

Note that if no image metadata object is specified for a particular image, a

195

default object is used, which includes default tables.

<p>

<h2>

<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

to any listeners.

<p>

When reading, the contents of the stream are interpreted by the usual

215

JPEG conventions, as follows:

216

217

<ul>

218

<li> If a JFIF <code>APP0</code> marker segment is present, the colorspace

219

is known to be either grayscale or YCbCr. If an <code>APP2</code>

220

marker segment containing an embedded ICC profile is also present, then

221

the YCbCr is converted to RGB according to the formulas given in the

222

JFIF spec, and the ICC profile is assumed to refer to the resulting RGB

223

space.

224

<p>

225

<li> If an Adobe <code>APP14</code> marker segment is present, the

226

colorspace is determined by consulting the <code>transform</code> flag.

227

The <code>transform</code> flag takes one of three values:

228

<ul>

229

<li> 2 - The image is encoded as YCCK (implicitly converted from

230

CMYK on encoding).

231

232

<li> 1 - The image is encoded as YCbCr (implicitly converted from RGB

233

on encoding).

234

235

<li> 0 - Unknown. 3-channel images are assumed to be RGB, 4-channel

236

images are assumed to be CMYK.

237

</ul>

238

<p>

239

<li> If neither marker segment is present, the following procedure is

240

followed: Single-channel images are assumed to be grayscale, and

241

2-channel images are assumed to be grayscale with an alpha channel.

242

For 3- and 4-channel images, the component ids are consulted. If these

243

values are 1-3 for a 3-channel image, then the image is assumed to be

244

YCbCr. If these values are 1-4 for a 4-channel image, then the image

245

is assumed to be YCbCrA. If these values are > 4, they are checked

246

against the ASCII codes for 'R', 'G', 'B', 'A', 'C', 'c'. These can

247

encode the following colorspaces:

<p>

<br>RGB

<br>RGBA

<br>YCC (as 'Y','C','c'), assumed to be PhotoYCC

252

<br>YCCA (as 'Y','C','c','A'), assumed to be PhotoYCCA

253

<p>

254

Otherwise, 3-channel subsampled images are assumed to be YCbCr,

255

3-channel non-subsampled images are assumed to be RGB, 4-channel

256

subsampled images are assumed to be YCCK, and 4-channel, non-subsampled

257

images are assumed to be CMYK.

258

259

<p>

260

<li> All other images are declared uninterpretable and an exception is

261

thrown if an attempt is made to read one as a

262

<code>BufferedImage</code>. Such an image may be read only as a

263

<code>Raster</code>. If an image is interpretable but there is no Java

264

<code>ColorSpace</code> available corresponding to the encoded

265

colorspace (<italic>e.g.</italic> YCbCr), then

266

<code>ImageReader.getRawImageType</code> will return <code>null</code>.

267

</ul>

268

269

Once an encoded colorspace is determined, then the target colorspace is

270

determined as follows:

271

272

<ul>

273

<li> If a destination type is not set, then the following default

274

transformations take place after upsampling: YCbCr (and YCbCrA) images

275

are converted to RGB (and RGBA) using the conversion provided by the

276

underlying IJG library and either the built-in sRGB

277

<code>ColorSpace</code> or a custom RGB <code>ColorSpace</code> object

278

based on an embedded ICC profile is used to create the output

279

<code>ColorModel</code>. PhotoYCC and PhotoYCCA images are not

280

converted. CMYK and YCCK images are currently not supported.</li>

281

282

<li> If a destination image or type is set, it is used as follows:

283

If the IJG library provides an appropriate conversion, it is used.

284

Otherwise the default library conversion is followed by a colorspace

285

conversion in Java.</li>

286

287

<li> Bands are selected AFTER any library colorspace conversion. If a

288

subset of either source or destination bands is used, then the default

289

library conversions are used with no further conversion in Java,

290

regardless of any destination type.</li>

291

292

<li> An exception is thrown if an attempt is made to read an image in an

293

unsupported jpeg colorspace as a <code>BufferedImage</code>

294

(<italic>e.g.</italic> CMYK). Such images may be read as

295

<code>Raster</code>s. If an image colorspace is unsupported or

296

uninterpretable, then <code>ImageReader.getImageTypes</code> will

297

return an empty <code>Iterator</code>. If a subset of the raw bands

298

are required, a <code>Raster</code> must be obtained first and the

299

bands obtained from that. </li>

</ul>

<p>

For writing, the color transformation to apply is determined as

follows:

<p>

If a subset of the source bands is to be written, no color conversion is

308

performed. Any destination, if set, must match the number of bands that will

309

be written, and serves as an interpretation of the selected bands, rather than

310

a conversion request. This behavior is identical to that for

311

<code>Raster</code>s. If all the bands are to be written and an image

312

(as opposed to a <code>Raster</code>) is being written, any destination type

313

is ignored and a warning is sent to any listeners.

314

315

<p>

316

If a destination type is used and any aspect of the metadata object, if there

317

is one, is not compatible with that type, the destination type is used, the

318

metadata written is modified from that provided, and a warning is sent to

319

listeners. This includes the <code>app0JFIF</code> and

320

<code>app14Adobe</code> nodes. The component ids in the <code>sof</code> and

321

<code>sos</code> nodes are not modified, however, as unless a

322

<code>app0JFIF</code> node is present, any values may be used.

323

<p>

324

325

When a full image is written, a destination colorspace will be

326

chosen based on the image contents and the metadata settings, according to

327

the following algorithm:

<p>

If no metadata object is specified, then the following defaults apply:

332

333

<ul>

334

<li> Grayscale images are written with a JFIF <code>APP0</code> marker

335

segment. Grayscale images with alpha are written with no special

336

marker. As required by JFIF, the component ids in the frame and

337

scan header is set to 1.

338

339

<li> RGB images are converted to YCbCr, subsampled in the chrominance

340

channels by half both vertically and horizontally, and written with a

341

JFIF <code>APP0</code> marker segment. If the <code>ColorSpace</code>

342

of the image is based on an <code>ICCProfile</code> (it is an instance

343

of <code>ICC_ColorSpace</code>, but is not one of the standard built-in

344

<code>ColorSpaces</code>), then that profile is embedded in an

345

<code>APP2</code> marker segment. As required by JFIF, the

346

component ids in the frame and scan headers are set to 1, 2, and 3.

347

348

349

<li> RGBA images are converted to YCbCrA, subsampled in the

350

chrominance channels by half both vertically and horizontally, and

351

written without any special marker segments. The component ids

352

in the frame and scan headers are set to 1, 2, 3, and 4.

353

354

<li> PhotoYCC and YCCAimages are subsampled by half in the chrominance

355

channels both vertically and horizontally and written with an

356

Adobe <code>APP14</code> marker segment and 'Y','C', and 'c' (and

357

'A' if an alpha channel is present) as component ids in the frame

and scan headers.

</ul>

Default metadata objects for these image types will reflect these settings.

<p>

If a metadata object is specified, then the number of channels in the

366

frame and scan headers must always match the number of bands to be

367

written, or an exception is thrown. <code>app0JFIF</code> and

368

<code>app14Adobe</code> nodes may appear in the same metadata object only

369

if the <code>app14Adobe</code> node indicates YCbCr, and the component ids

370

are JFIF compatible (0-2). The various image types are processed in the

following ways:

<br>

(All multi-channel images are subsampled according to the sampling factors

376

in the frame header node of the metadata object, regardless of color space.)

377

378

<ul>

379

<li> Grayscale Images:

380

<ul>

381

<li> If an <code>app0JFIF</code> node is present in the metadata object,

382

a JFIF <code>APP0</code> marker segment is written.

383

<li> If an <code>app14Adobe</code> node is present in the metadata

384

object, it is checked for validity (<code>transform</code> must be

385

<code>UNKNOWN</code>) and written.

386

<li> If neither node is present in the metadata object, no special

387

marker segment is written.

388

</ul>

389

390

<li> Grayscale Images with an Alpha Channel:

391

<ul>

392

<li> If an <code>app0JFIF</code> node is present in the metadata object,

393

it is ignored and a warning is sent to listeners, as JFIF does not

394

support 2-channel images.

395

<li> If an <code>app14Adobe</code> node is present in the metadata

396

object, it is checked for validity (<code>transform</code> must be

397

<code>UNKNOWN</code>) and written. If <code>transform</code> is

398

not <code>UNKNOWN</code>, a warning is sent to listeners and the

399

correct transform is written.

400

<li> If neither node is present in the metadata object, no special

401

marker segment is written.

</ul>

<li> RGB Images:

<ul>

<li> If an <code>app0JFIF</code> node is present in the metadata object,

407

the image is converted to YCbCr and written with a JFIF

408

<code>APP0</code> marker segment. If the <code>ColorSpace</code>

409

of the image is based on a non-standard ICC Profile, then that

410

profile is embedded in an <code>APP2</code> marker segment. If the

411

<code>ColorSpace</code> is not based on a non-standard ICC Profile,

412

but an <code>app2ICC</code> node appears in the metadata, then an

413

<code>APP2</code> marker segment is written with the appropriate

414

standard profile. Note that the profile must specify an RGB color

415

space, as the file must be JFIF compliant.

416

417

<li> If an <code>app14Adobe</code> node is present in the metadata

418

object, the image is converted according to the color transform

419

setting and written with an Adobe <code>APP14</code> marker

420

segment. Component ids are written just as they appear in the

421

frame and scan headers. The color transform must be either YCbCr

422

or <code>UNKNOWN</code>. If it is <code>UNKNOWN</code>, the image

423

is not color converted.

424

425

<li> If neither node is present, the component ids in the frame

426

header are consulted. If these indicate a colorspace as described

427

above, then the image is converted to that colorspace if possible.

428

If the component ids do not indicate a colorspace, then the

429

sampling factors are consulted. If the image is to be subsampled,

430

it is converted to YCbCr first. If the image is not to be

431

subsampled, then no conversion is applied. No special marker

432

segmentss are written.

</ul>

<li> RGBA images:

<ul>

<li> If an <code>app0JFIF</code> node is present in the metadata object,

438

it is ignored and a warning is sent to listeners, as JFIF does not

439

support 4-channel images.

440

441

<li> If an <code>app14Adobe</code> node is present in the metadata

442

object, the image is written with an Adobe <code>APP14</code> marker

443

segment. No colorspace conversion is performed. Component ids

444

are written just as they appear in the frame and scan headers.

445

The color transform must be <code>UNKNOWN</code>. If it is

446

not, a warning is sent to listeners.

447

448

<li> If no <code>app14Adobe</code> node is present, the component ids in

449

the frame header are consulted. If these indicate a colorspace as

450

described above, then the image is converted to that colorspace if

451

possible. If the component ids do not indicate a colorspace, then

452

the sampling factors are consulted. If the image is to be

453

subsampled, it is converted to YCbCrA. If the image is not to be

454

subsampled, then no conversion is applied. No special marker

455

segments are written.

456

</ul>

457

458

<li> PhotoYCC Images:

459

<ul>

460

<li> If an <code>app0JFIF</code> node is present in the metadata object,

461

the image is converted to sRGB, and then to YCbCr during encoding,

462

and a JFIF <code>APP0</code> marker segment is written.

463

464

<li> If an <code>app14Adobe</code> node is present in the metadata

465

object, no conversion is applied, and an Adobe <code>APP14</code>

466

marker segment is written. The color transform must be YCC. If it

467

is not, a warning is sent to listeners.

468

469

<li> If neither node is present in the metadata object, no conversion

470

is applied, and no special marker segment is written.

471

</ul>

472

473

<li> PhotoYCCA Images:

474

<ul>

475

<li> If an <code>app0JFIF</code> node is present in the metadata object,

476

it is ignored and a warning is sent to listeners, as JFIF does not

477

support 4-channel images.

478

479

<li> If an <code>app14Adobe</code> node is present in the metadata

480

object, no conversion is applied, and an Adobe <code>APP14</code>

481

marker segment is written. The color transform must be

482

<code>UNKNOWN</code>. If it is not, a warning is sent to

483

listeners.

484

485

<li> If neither node is present in the metadata object, no conversion

486

is applied, and no special marker segment is written.

</ul>

</ul>

<p>

<h2>

<a name=thumbs>Thumbnail Images</a>

493

</h2>

494

Thumbnails are supported by the use of JFIF and JFIF extension marker segments.

495

Thumbnails provided on the write methods determine the thumbnails that will be

496

included. <code>app0JFIF</code> and <code>app0JFXX</code> nodes present in

497

the metadata do not contain any thumbnail pixel data. However, the kinds of

498

thumbnails written depend on the contents of the metadata object, as follows.

499

Any thumbnail which is to be written as an indexed or RGB image and which is

500

larger than 255 by 255 will be clipped, not scaled, to 255 by 255. Thumbnails

501

written as JPEG images may be any size. A warning is sent to any listeners

502

whenever a thumbnail is clipped.

503

<ul>

504

<li> If there is a single thumbnail, it is processed as follows:

505

<ul>

506

<li> If the thumbnail image is an RGB palette image, it is processed as

507

follows:

508

<ul>

509

<li> If no <code>app0JFXX</code> node is present in the metadata, or

510

the first <code>app0JFXX</code> node present in the metadata

511

contains a <code>JFIFthumbPalette</code> element, a

512

palette thumbnail is written in a JFXX <code>APP0</code> marker

513

segment.

514

<li> If the first <code>app0JFXX</code> node present in the metadata

515

contains another thumbnail form (RGB or JPEG), the palette

516

image is expanded to RGB and the indicated thumbnail form is

written.

</ul>

<li> If the thumbnail image is an RGB image, it is processed as follows:

521

<ul>

522

<li> If no <code>app0JFXX</code> node is present in the metadata,

523

the thumbnail is written as part of the JFIF <code>APP0</code>

524

marker segment.

525

<li> If the first <code>app0JFXX</code> node present in the metadata

526

contains a <code>JFIFthumbRGB</code> element, an

527

RGB thumbnail is written in a JFXX <code>APP0</code> marker

528

segment.

529

<li> If the first <code>app0JFXX</code> node present in the metadata

530

contains a <code>JFIFthumbJPEG</code> element, a

531

JPEG thumbnail is written in a JFXX <code>APP0</code> marker

532

segment.

533

<li> If the first <code>app0JFXX</code> node present in the metadata

534

contains a <code>JFIFthumbPalette</code> element, an

535

RGB thumbnail is written in a JFXX <code>APP0</code> marker

536

segment and a warning is sent to any listeners.

537

</ul>

538

539

<li> If the thumbnail image is a grayscale image, it is processed as

540

follows:

541

<ul>

542

<li> If no <code>app0JFXX</code> node is present in the metadata,

543

the thumbnail is expanded to RGB and written as part of the

544

JFIF <code>APP0</code> marker segment.

545

<li> If the first <code>app0JFXX</code> node present in the metadata

546

contains a <code>JFIFthumbRGB</code> element, the thumbnail is

547

expanded to RGB and written in a separate <code>JFXX</code> RGB

548

marker segment.

549

<li> If the first <code>app0JFXX</code> node present in the metadata

550

contains a <code>JFIFthumbJPEG</code> element, a

551

JPEG thumbnail is written in a JFXX <code>APP0</code> marker

552

segment.

553

<li> If the first <code>app0JFXX</code> node present in the metadata

554

contains a <code>JFIFthumbPalette</code> element, a

555

JPEG thumbnail is written in a JFXX <code>APP0</code> marker

556

segment and a warning is sent to any listeners.

557

</ul>

558

559

<li> Any other thumbnail image types are ignored and a warning is sent

to any listeners.

</ul>

<li> If there are multiple thumbnails, each one is processed as above, except

564

that no thumbnail is placed in the JFIF <code>APP0</code> segment, and

565

the <code>app0JFXX</code> node consulted for each thumbnail is the

566

<code>app0JFXX</code> node from the metadata that occurs in the same

567

sequence as the thumbnail. <italic>I.e.</italic> the first

568

<code>app0JFXX</code> node applies to the first thumbnail, the second

569

node to the second thumbnail, and so on. If there are fewer

570

<code>app0JFXX</code> nodes in the metadata than thumbnails, then

571

those thumbnails are considered to have no matching

572

<code>app0JFXX</code> node. An RGB thumbnail with no matching

573

<code>app0JFXX</code> node is written in a JFXX <code>APP0</code> marker

574

segment. A grayscale thumbnail with no matching

575

<code>app0JFXX</code> node is written as a JPEG image to a JFXX

576

<code>APP0</code> marker segment.

</ul>

<p>

Note that as the only mechanism for storing thumbnails is via the

581

JFIF or JFIF extension marker segments, only grayscale or RGB images

582

may have thumbnails. If thumbnails are present when writing any other type

583

of image, the thumbnails are ignored and a warning is sent to any warning

listeners.

<p>

<h2>

<a name=prog>Progressive Encoding</a>

589

</h2>

590

591

Progressive encoding must be enabled on the <code>ImageWriteParam</code>

592

passed in to a write operation, or the image will be written sequentially,

593

regardless of the scan headers included in the metadata object. If

594

progressive encoding is enabled and set to copy from metadata, then

595

the sequence of scan headers from the metadata is used to write the

596

image. If progressive encoding is enabled and set to use a default,

597

then the scans in the metadata are ignored and a default set of scans

598

is used. Progressive encoding always forces optimized Huffman tables to

599

be used. Any Huffman tables present in the metadata will be ignored,

600

and a warning will be sent to any warning listeners.

601

602

If Huffman-table optimization is requested on the <code>ImageWriteParam</code>,

603

all Huffman tables in the metadata or in the <code>ImageWriteParam</code>

604

itself are ignored, and a warning will be sent to any warning listeners if

605

any such tables are present.

<p>

<h2>

<a name=tree>Native Metadata Format Tree Structure and Editing</a>

610

</h2>

611

612

The DTDs below describe just the trees of metadata objects actually returned

613

by the <code>IIOMetadata</code> object. They do not include nodes

614

corresponding to <code>SOI</code>, <code>EOI</code>, or <code>RST</code>

615

markers, as these parsing delimiters do not carry any meaningful metadata.

616

<p>

617

618

The first node is always a <code>JPEGvariety</code> node. In the

619

<code>javax_imageio_jpeg_image_1.0</code> version of the JPEG metadata

620

format, this node may have one child, an <code>app0JFIF</code> node,

621

indicating that the JPEG stream contains a JFIF marker segment and related

622

data, or no children, indicating that the stream contains no JFIF marker.

623

In future versions of the JPEG metadata format, other varieties of JPEG

624

metadata may be supported (e.g. Exif) by defining other types of nodes

625

which may appear as a child of the <code>JPEGvariety</code> node.

626

<p>

627

628

(Note that an application wishing to interpret Exif metadata given

629

a metadata tree structure in the <code>javax_imageio_jpeg_image_1.0</code>

630

format must check for an <code>unknown</code> marker segment with a tag

631

indicating an <code>APP1</code> marker and containing data identifying it

632

as an Exif marker segment. Then it may use application-specific code to

633

interpret the data in the marker segment. If such an application were

634

to encounter a metadata tree formatted according to a future version of

635

the JPEG metadata format, the Exif marker segment might not be

636

<code>unknown</code> in that format - it might be structured as a

637

child node of the <code>JPEGvariety</code> node. Thus, it is important

638

for an application to specify which version to use by passing the string

639

identifying the version to the method/constructor used to obtain an

640

<code>IIOMetadata</code> object.)

<p>

On reading, <code>JFXX</code> and <code>app2ICC</code> nodes occur as

645

children of an <code>app0JFIF</code> node.

646

This is true regardless of where the JFXX <code>APP0</code> and

647

<code>APP2</code> marker segments actually occur in the stream. The ordering

648

of nodes within the <code>markerSequence</code> node corresponds to the

649

ordering of marker segments found in the JPEG stream.

650

<p>

651

On writing, any <code>JFXX</code> and <code>app2ICC</code> nodes must

652

occur as children of an <code>app0JFIF</code> node, itself a child of a

653

<code>JPEGvariety</code> node, which must always be the first node.

654

(If the stream is not to be JFIF compliant, no <code>app0JFIF</code> node

655

should be provided, and the <code>JPEGvariety</code> node should have no

656

children.) Any

657

JFIF <code>APP0</code>, JFXX <code>APP0</code>, and <code>APP2</code> marker

658

segments are written first, followed by all Adobe <code>APP14</code>,

659

<code>APPn</code>, <code>COM</code> and unknown segments in the

660

order in which their corresponding nodes appear in the

661

<code>markerSequence</code> node, followed by <code>DQT</code> (and

662

<code>DHT</code> for non-progressive writes) marker segments, followed by the

663

<code>SOF</code> and <code>SOS</code> marker segments. For progressive writes

664

using metadata to control progression, the <code>SOS</code> segments are used

665

in the order in which their corresponding nodes occur in the

666

<code>markerSequence</code> node.

667

<p>

668

669

The <code>reset</code>, <code>mergeTree</code> and <code>setFromTree</code>

670

operations have the following semantics for the JPEG plug-in metadata object:

671

672

<p> <code>reset</code> - A call to <code>reset</code> will restore the

673

metadata object to the same state it had immediately after creation, whether

674

this came about from reading a stream or by obtaining a default object from

675

the <code>ImageWriter</code>. This is true regardless of how many times the

676

metadata object has been modified since creation.

677

678

<p> <code>mergeTree</code> - Native Format

679

<br> The <code>mergeTree</code> operation accepts valid trees conforming to

680

the DTD below, and merges the nodes using the following ordering rules. In

681

all cases, only data present in the new node is changed in a corresponding

682

existing node, if any. This means that nodes cannot be removed using

683

<code>mergeTree</code>. To remove nodes, use <code>setFromTree</code>. The

684

tree must consist of <code>IIOMetadataNode</code>s.

<ul>

<ul>

<li> If an <code>app0JFIF</code> node already exists, the contents

689

of the new one modify the existing one.

690

<li> If there is no such node, a new one is created and inserted in

691

the appropriate position.

</ul>

<ul>

<li> If there already exist <code>dqt</code> nodes in the sequence,

696

then each table in the node replaces the first table, in any

697

<code>dqt</code> node, with the same table id.

698

<li> If none of the existing <code>dqt</code> nodes contain a table

699

with the same id, then the table is added to the last existing

700

<code>dqt</code> node.

701

<li> If there are no <code>dqt</code> nodes, then a new one is

702

created and added as follows:

703

<ul>

704

<li> If there are <code>dht</code> nodes, the new

705

<code>dqt</code> node is inserted before the first one.

706

<li> If there are no <code>dht</code> nodes, the new

707

<code>dqt</code> node is inserted before an

708

<code>sof</code> node, if there is one.

709

<li> If there is no <code>sof</code> node, the new

710

<code>dqt</code> node is inserted before the first

711

<code>sos</code> node, if there is one.

712

<li> If there is no <code>sos</code> node, the new

713

<code>dqt</code> node is added to the end of the sequence.

</ul>

</ul>

<ul>

<li> If there already exist <code>dht</code> nodes in the sequence,

719

then each table in the node replaces the first table, in any

720

<code>dht</code> node, with the same table class and table id.

721

<li> If none of the existing <code>dht</code> nodes contain a table

722

with the same class and id, then the table is added to the last

723

existing <code>dht</code> node.

724

<li> If there are no <code>dht</code> nodes, then a new one is

725

created and added as follows:

726

<ul>

727

<li> If there are <code>dqt</code> nodes, the new

728

<code>dht</code> node is inserted immediately following the

729

last <code>dqt</code> node.

730

<li> If there are no <code>dqt</code> nodes, the new

731

<code>dht</code> node is inserted before an

732

<code>sof</code> node, if there is one.

733

<li> If there is no <code>sof</code> node, the new

734

<code>dht</code> node is inserted before the first

735

<code>sos</code> node, if there is one.

736

<li> If there is no <code>sos</code> node, the new

737

<code>dht</code> node is added to the end of the sequence.

</ul>

</ul>

<ul>

<li> If there already exists a <code>dri</code> node, the restart

743

interval value is updated.

744

<li> If there is no <code>dri</code> node, then a new one is created

745

and added as follows:

746

<ul>

747

<li> If there is an <code>sof</code> node, the new

748

<code>dri</code> node is inserted before it.

749

<li> If there is no <code>sof</code> node, the new

750

<code>dri</code> node is inserted before the first

751

<code>sos</code> node, if there is one.

752

<li> If there is no <code>sos</code> node, the new

753

<code>dri</code> node is added to the end of the sequence.

</ul>

</ul>

<br> A new <code>com</code> node is created and inserted as follows:

758

<ul>

759

<li> If there already exist <code>com</code> nodes, the new one is

760

inserted after the last one.

761

<li> If there are no <code>com</code> nodes, the new

762

<code>com</code> node is inserted after the

763

<code>app14Adobe</code> node, if there is one.

764

<li> If there is no <code>app14Adobe</code> node, the new

765

<code>com</code> node is inserted at the beginning of the

766

sequence.

767

</ul>

768

<li> <code>app14Adobe</code>

769

<ul>

770

<li> If there already exists an <code>app14Adobe</code> node, then

771

its attributes are updated from the node.

772

<li> If there is no <code>app14Adobe</code> node, then a new one is

773

created and added as follows:

774

<ul>

775

<li> The new <code>app14Adobe</code> node is inserted after the

776

last <code>unknown</code> node, if there are any.

777

<li> If there are no <code>unknown</code> nodes, the new

778

<code>app14Adobe</code> node is inserted at the beginning

of the sequence.

</ul>

</ul>

<li> <code>unknown</code>

783

<br> A new <code>unknown</code> node is created and added to the

784

sequence as follows:

785

<ul>

786

<li> If there already exist <code>unknown</code> marker nodes, the

787

new one is inserted after the last one.

788

<li> If there are no <code>unknown</code> nodes, the new

789

<code>unknown</code> node is inserted before the

790

<code>app14Adobe</code> node, if there is one.

791

<li> If there is no <code>app14Adobe</code> node, the new

792

<code>unknown</code> node is inserted at the beginning of the

sequence.

</ul>

<ul>

<li> If there already exists an <code>sof</code> node in the

798

sequence, then its values are updated from the node.

799

<li> If there is no <code>sof</code> node, then a new one is created

800

and added as follows:

801

<ul>

802

<li> If there are any <code>sos</code> nodes, the new

803

<code>sof</code> node is inserted before the first one.

804

<li> If there is no <code>sos</code> node, the new

805

<code>sof</code> node is added to the end of the sequence.

</ul>

</ul>

<ul>

<li> If there already exists a single <code>sos</code> node, then

811

the values are updated from the node.

812

<li> If there are more than one existing <code>sos</code> nodes,

813

then an <code>IIOInvalidTreeException</code> is thrown, as

814

<code>sos</code> nodes cannot be merged into a set of

815

progressive scans.

816

<li> If there are no <code>sos</code> nodes, a new one is created

817

and added to the end of the sequence.

</ul>

</ul>

<p> <code>mergeTree</code> - Standard Format

822

<br>

823

The <code>mergeTree</code> operation, when given a tree in the standard

824

format, will modify the native tree in the following ways:

825

<ul>

826

<li> <code>Chroma</code> - The <code>ColorSpaceType</code> subnode of a

827

<code>Chroma</code> node may change the target colorspace of the

828

compressed image. The selection of a new colorspace can cause a number

829

of changes, in keeping with the algorithms described above:

830

<code>app0JFIF</code> and <code>app14Adobe</code> nodes may be added

831

or removed, subsampling may be added or removed, component ids may

832

be changed, and <code>sof</code> and <code>sos</code> nodes will be

833

updated accordingly. If necessary, additional quantization and

834

huffman tables are added. In the case of quantization tables, the

835

default will be scaled to match the quality level of any existing

836

tables. No tables are added to metadata that does not already contain

837

tables. If the existing metadata specifies progressive encoding, then

838

the number of channels must not change. Any <code>Transparency</code>

839

node is also taken into account, as an explicit value of

840

<code>none</code> for the <code>Alpha</code> subnode can cause the

841

removal of an alpha channel, and anything other than <code>none</code>

842

can cause the addition of an alpha channel.

843

<li> <code>Dimension</code> - A <code>PixelAspectRatio</code> specification

844

can cause the contents of an <code>app0JFIF</code> node to change, if

845

there is one present, or the addition of an <code>app0JFIF</code> node

846

containing appropriate values, if there can be one. An appropriate

847

pair of integers is computed from the floating-point ratio for

848

inclusion in the node.

849

<li> <code>Text</code> - Each uncompressed text item is converted to a

850

<code>com</code> node and inserted according to the rules above for

851

merging <code>com</code> nodes.

852

</ul>

853

854

<p> <code>setFromTree</code> - Native Format

855

<br>

856

The <code>setFromTree</code> operation, when given a tree in the native

857

format described below, will simply replace the existing tree in its entirety

858

with the new one. The tree must consist of <code>IIOMetadataNode</code>s.

859

860

<p> <code>setFromTree</code> - Standard Format

861

<br>

862

The <code>setFromTree</code> operation, when given a tree in the standard

863

format, performs a <code>reset</code> followed by a merge of the new tree.

864

865

<h2>

866

<a name=image>Image Metadata DTD</a>

</h2>

<pre>

<!DOCTYPE "javax_imageio_jpeg_image_1.0" [

871

872

<!ELEMENT "javax_imageio_jpeg_image_1.0" (JPEGvariety, markerSequence)>

873

874

<!ELEMENT "JPEGvariety" (app0JFIF)>

875

<!-- A node grouping all marker segments specific to the variety of

876

stream being read/written (e.g. JFIF) - may be empty -->

877

878

<!ELEMENT "app0JFIF" (JFXX?, app2ICC?)>

879

<!ATTLIST "app0JFIF" "majorVersion" #CDATA "1">

880

881

882

883

884

<!ATTLIST "app0JFIF" "minorVersion" #CDATA "2">

885

886

887

888

889

<!ATTLIST "app0JFIF" "resUnits" ("0" | "1" | "2") "0">

890

<!-- The resolution units for Xdensisty and Ydensity (0 = no

891

units, just aspect ratio; 1 = dots/inch; 2 = dots/cm) -->

892

<!ATTLIST "app0JFIF" "Xdensity" #CDATA "1">

893

894

895

896

897

<!ATTLIST "app0JFIF" "Ydensity" #CDATA "1">

898

899

900

901

902

<!ATTLIST "app0JFIF" "thumbWidth" #CDATA "0">

903

904

905

906

907

<!ATTLIST "app0JFIF" "thumbHeight" #CDATA "0">

908

909

910

911

912

913

<!ELEMENT "JFXX" (app0JFXX)*>

914

915

916

<!ELEMENT "app0JFXX" (JFIFthumbJPEG | JFIFthumbPalette |

917

JFIFthumbRGB)>

918

919

<!ATTLIST "app0JFXX" "extensionCode" ("16" | "17" | "19")

920

#IMPLIED>

921

<!-- The JFXX extension code identifying thumbnail type: (16 =

922

JPEG, 17 = indexed, 19 = RGB -->

923

924

<!ELEMENT "JFIFthumbJPEG" (markerSequence?)>

925

<!-- A JFIF thumbnail in JPEG format (no JFIF segments

926

permitted) -->

927

928

<!ELEMENT "JFIFthumbPalette" EMPTY>

929

930

<!ATTLIST "JFIFthumbPalette" "thumbWidth" #CDATA #IMPLIED>

931

932

933

934

935

<!ATTLIST "JFIFthumbPalette" "thumbHeight" #CDATA #IMPLIED>

936

937

938

939

940

941

<!ELEMENT "JFIFthumbRGB" EMPTY>

942

943

<!ATTLIST "JFIFthumbRGB" "thumbWidth" #CDATA #IMPLIED>

944

945

946

947

948

<!ATTLIST "JFIFthumbRGB" "thumbHeight" #CDATA #IMPLIED>

949

950

951

952

953

954

<!ELEMENT "app2ICC" EMPTY>

955

956

957

958

<!ELEMENT "markerSequence" (dqt | dht | dri | com | unknown |

959

app14Adobe | sof | sos)*>

960

961

962

<!ELEMENT "dqt" (dqtable)*>

963

964

965

966

967

<!ELEMENT "dqtable" EMPTY>

968

969

970

<!ATTLIST "dqtable" "elementPrecision" #CDATA "0">

971

<!-- The number of bits in each table element (0 = 8, 1 = 16)

972

-->

973

974

<!ATTLIST "dqtable" "qtableId" ("0" | "1" | "2" | "3") #REQUIRED>

975

976

<!ELEMENT "dht" (dhtable)*>

977

978

979

980

981

<!ELEMENT "dhtable" EMPTY>

982

983

984

<!ATTLIST "dhtable" "class" ("0" | "1") #REQUIRED>

985

986

<!ATTLIST "dhtable" "htableId" ("0" | "1" | "2" | "3") #REQUIRED>

987

988

989

<!ELEMENT "dri" EMPTY>

990

991

<!ATTLIST "dri" "interval" #CDATA #REQUIRED>

992

993

994

995

996

997

<!ELEMENT "com" EMPTY>

998

<!-- A Comment marker segment. The user object contains the actual

999

bytes. -->

1000

1001

1002

1003

<!ATTLIST "com" "comment" #CDATA #IMPLIED>

1004

<!-- The comment as a string (used only if user object is null)

1005

-->

1006

1007

1008

<!ELEMENT "unknown" EMPTY>

1009

<!-- An unrecognized marker segment. The user object contains the

1010

data not including length. -->

1011

1012

1013

1014

<!ATTLIST "unknown" "MarkerTag" #CDATA #REQUIRED>

1015

1016

1017

1018

1019

1020

<!ELEMENT "app14Adobe" EMPTY>

1021

1022

<!ATTLIST "app14Adobe" "version" #CDATA "100">

1023

1024

1025

1026

1027

<!ATTLIST "app14Adobe" "flags0" #CDATA "0">

1028

1029

1030

1031

1032

<!ATTLIST "app14Adobe" "flags1" #CDATA "0">

1033

1034

1035

1036

1037

<!ATTLIST "app14Adobe" "transform" ("0" | "1" | "2") #REQUIRED>

1038

<!-- The color transform applied to the image (0 = Unknown, 1 =

1039

YCbCr, 2 = YCCK) -->

1040

1041

<!ELEMENT "sof" (componentSpec)*>

1042

1043

1044

1045

<!ATTLIST "sof" "process" ("0" | "1" | "2") #IMPLIED>

1046

<!-- The JPEG process (0 = Baseline sequential, 1 = Extended

1047

sequential, 2 = Progressive) -->

1048

<!ATTLIST "sof" "samplePrecision" #CDATA "8">

1049

1050

1051

<!ATTLIST "sof" "numLines" #CDATA #IMPLIED>

1052

1053

1054

1055

1056

<!ATTLIST "sof" "samplesPerLine" #CDATA #IMPLIED>

1057

1058

1059

1060

1061

<!ATTLIST "sof" "numFrameComponents" ("1" | "2" | "3" | "4")

1062

#IMPLIED>

1063

1064

1065

<!ELEMENT "componentSpec" EMPTY>

1066

1067

<!ATTLIST "componentSpec" "componentId" #CDATA #REQUIRED>

1068

1069

1070

1071

1072

<!ATTLIST "componentSpec" "HsamplingFactor" #CDATA #REQUIRED>

1073

1074

1075

1076

1077

<!ATTLIST "componentSpec" "VsamplingFactor" #CDATA #REQUIRED>

1078

1079

1080

1081

1082

<!ATTLIST "componentSpec" "QtableSelector" ("0" | "1" | "2" |

1083

"3") #REQUIRED>

1084

1085

1086

<!ELEMENT "sos" (scanComponentSpec)*>

1087

1088

1089

1090

<!ATTLIST "sos" "numScanComponents" ("1" | "2" | "3" | "4")

1091

#REQUIRED>

1092

1093

<!ATTLIST "sos" "startSpectralSelection" #CDATA "0">

1094

1095

1096

1097

1098

<!ATTLIST "sos" "endSpectralSelection" #CDATA "63">

1099

1100

1101

1102

1103

<!ATTLIST "sos" "approxHigh" #CDATA "0">

1104

1105

1106

1107

1108

<!ATTLIST "sos" "approxLow" #CDATA "0">

1109

1110

1111

1112

1113

1114

<!ELEMENT "scanComponentSpec" EMPTY>

1115

1116

<!ATTLIST "scanComponentSpec" "componentSelector" #CDATA

1117

#REQUIRED>

1118

1119

1120

1121

1122

<!ATTLIST "scanComponentSpec" "dcHuffTable" ("0" | "1" | "2" |

1123

"3") #REQUIRED>

1124

1125

<!ATTLIST "scanComponentSpec" "acHuffTable" ("0" | "1" | "2" |

1126

"3") #REQUIRED>

1127

]>

</pre>

<h2>

<a name=stream>Stream Metadata DTD</a>

</h2>

<pre>

<!DOCTYPE "javax_imageio_jpeg_stream_1.0" [

1137

<!ELEMENT "javax_imageio_jpeg_stream_1.0" (dqt |

dht |

dri |

com |

unknown)*>

]>

</pre>

</body>

</html>