exifreader 4.39.1 → 4.40.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +324 -166
- package/bin/profile-diff.js +171 -0
- package/bin/profile.js +852 -0
- package/dist/exif-reader.js +1 -1
- package/dist/exif-reader.js.map +1 -1
- package/exif-reader.d.ts +53 -10
- package/package.json +7 -7
- package/src/exif-reader.js +36 -142
- package/src/file-loaders.js +308 -0
- package/src/image-header-avif.js +7 -4
- package/src/image-header-gif.js +21 -1
- package/src/image-header-heic.js +7 -4
- package/src/image-header-iso-bmff.js +169 -18
- package/src/image-header-jpeg.js +53 -1
- package/src/image-header-jxl.js +63 -12
- package/src/image-header-png.js +51 -5
- package/src/image-header-webp.js +32 -2
- package/src/image-header.js +32 -12
- package/src/load-auto.js +310 -0
- package/src/loadview-pipeline.js +66 -1
- package/src/xml.js +39 -1
package/README.md
CHANGED
|
@@ -7,6 +7,10 @@ browser or from Node. Supports JPEG, JPEG XL, TIFF, PNG, HEIC, AVIF, WebP, and
|
|
|
7
7
|
GIF files with Exif, IPTC, XMP, ICC, MPF, and more metadata (depending on file
|
|
8
8
|
type).
|
|
9
9
|
|
|
10
|
+
If you use the `length: 'auto'` option, ExifReader reads only the bytes
|
|
11
|
+
that contain metadata, **well under 1 ms per file** for typical phone JPEGs
|
|
12
|
+
and **over 95% less bandwidth**.
|
|
13
|
+
|
|
10
14
|
ExifReader is highly and easily configurable and the resulting bundle can be as
|
|
11
15
|
small as **~4 KiB** (gzipped) if you're only interested in a few tags (e.g. date
|
|
12
16
|
and/or GPS values).
|
|
@@ -197,6 +201,319 @@ Where `fileBuffer` is one of
|
|
|
197
201
|
See the [examples site](https://mattiasw.github.io/ExifReader/) for more
|
|
198
202
|
directions on how to use the library.
|
|
199
203
|
|
|
204
|
+
#### Grouping
|
|
205
|
+
|
|
206
|
+
By default, Exif, IPTC and XMP tags are grouped together. This means that if
|
|
207
|
+
e.g. `Orientation` exists in both Exif and XMP, the first value (Exif) will be
|
|
208
|
+
overwritten by the second (XMP). If you need to separate between these values,
|
|
209
|
+
pass in an options object with the property `expanded` set to `true`:
|
|
210
|
+
|
|
211
|
+
```javascript
|
|
212
|
+
const tags = ExifReader.load(fileBuffer, {expanded: true});
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
#### Filtering tags (includeTags / excludeTags)
|
|
216
|
+
|
|
217
|
+
You can filter which tags are returned by using `includeTags` and/or
|
|
218
|
+
`excludeTags`.
|
|
219
|
+
|
|
220
|
+
- If `includeTags` is provided, it uses an **include-pattern**: only the groups
|
|
221
|
+
you specify will be included in the output.
|
|
222
|
+
- `excludeTags` can be used alone to remove tags/groups while keeping everything
|
|
223
|
+
else.
|
|
224
|
+
- If a group is specified in both `includeTags` and `excludeTags`, `excludeTags`
|
|
225
|
+
for that group will be ignored.
|
|
226
|
+
- An empty selector array (e.g. `includeTags: { xmp: [] }`) is treated as
|
|
227
|
+
excluding that group. The group will not be returned and ExifReader will skip
|
|
228
|
+
parsing it.
|
|
229
|
+
|
|
230
|
+
**Examples**
|
|
231
|
+
|
|
232
|
+
Exclude a few tags in the Exif group:
|
|
233
|
+
|
|
234
|
+
```javascript
|
|
235
|
+
const tags = ExifReader.load(fileBuffer, {
|
|
236
|
+
excludeTags: {
|
|
237
|
+
exif: ['MakerNote', 0x9286],
|
|
238
|
+
}
|
|
239
|
+
});
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Only return XMP tags (and exclude everything else):
|
|
243
|
+
|
|
244
|
+
```javascript
|
|
245
|
+
const tags = ExifReader.load(fileBuffer, {
|
|
246
|
+
includeTags: {
|
|
247
|
+
xmp: true,
|
|
248
|
+
}
|
|
249
|
+
});
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
**Filtering groups**
|
|
253
|
+
|
|
254
|
+
The group keys follow the same concept as the output when `expanded: true` is
|
|
255
|
+
used. (The `thumbnail` group controls the top-level `Thumbnail` value.)
|
|
256
|
+
|
|
257
|
+
For PNG, filtering is done with the `png` group only. (The `pngFile` and
|
|
258
|
+
`pngText` groups exist in `expanded` output today, but `png` is the filtering
|
|
259
|
+
key and those groups will be deprecated later.)
|
|
260
|
+
|
|
261
|
+
| Group key | Description | Supports IDs |
|
|
262
|
+
| ------------- | ------------------------------------------------ | ------------ |
|
|
263
|
+
| `exif` | Exif tags (including GPS IFD, interoperability). | yes |
|
|
264
|
+
| `iptc` | IPTC tags. | yes |
|
|
265
|
+
| `xmp` | XMP tags. | no |
|
|
266
|
+
| `icc` | ICC profile tags. | no |
|
|
267
|
+
| `photoshop` | Photoshop resource tags. | yes |
|
|
268
|
+
| `makerNotes` | MakerNote tags (e.g. Canon/Pentax). | yes |
|
|
269
|
+
| `mpf` | MPF tags. | yes |
|
|
270
|
+
| `file` | JPEG file details and `FileType`. | no |
|
|
271
|
+
| `jfif` | JFIF tags. | no |
|
|
272
|
+
| `png` | PNG header, chunk, and text tags. | no |
|
|
273
|
+
| `riff` | WebP (RIFF) tags. | no |
|
|
274
|
+
| `gif` | GIF tags. | no |
|
|
275
|
+
| `gps` | Computed GPS group (only when `expanded: true`). | no |
|
|
276
|
+
| `composite` | Composite tags (e.g. FieldOfView). | no |
|
|
277
|
+
| `thumbnail` | Top-level `Thumbnail` output. | no |
|
|
278
|
+
|
|
279
|
+
**Important: dependency tags**
|
|
280
|
+
|
|
281
|
+
Some tags act as pointers or containers to other metadata. Excluding them can
|
|
282
|
+
cause other tags or entire groups to disappear. Some important examples:
|
|
283
|
+
|
|
284
|
+
- `Exif IFD Pointer`, `GPS Info IFD Pointer`, `Interoperability IFD Pointer`
|
|
285
|
+
- `IPTC-NAA` (TIFF embedded IPTC), `ApplicationNotes` (TIFF embedded XMP),
|
|
286
|
+
`ICC_Profile` (TIFF embedded ICC)
|
|
287
|
+
- `MakerNote` and `Make` (maker note parsing)
|
|
288
|
+
- `ImageSourceData` and `PhotoshopSettings` (Photoshop parsing)
|
|
289
|
+
- `JPEGInterchangeFormat` and `JPEGInterchangeFormatLength` (thumbnails)
|
|
290
|
+
|
|
291
|
+
**NOTE:** When using `includeTags`, you **do not** have to list these dependency
|
|
292
|
+
tags. ExifReader will automatically include the required pointer/container tags
|
|
293
|
+
needed to find and parse the groups you requested. This section mainly matters
|
|
294
|
+
when using `excludeTags`.
|
|
295
|
+
|
|
296
|
+
Note that XMP and ICC tags are parsed from full metadata blocks, so ExifReader
|
|
297
|
+
cannot skip parsing individual XMP/ICC tags based on selectors. The returned
|
|
298
|
+
output is still filtered.
|
|
299
|
+
|
|
300
|
+
#### Unknown tags
|
|
301
|
+
|
|
302
|
+
Tags that are unknown, either because they have been excluded by making a custom
|
|
303
|
+
build or they are yet to be added into ExifReader, are by default not included
|
|
304
|
+
in the output. If you need to see them there is an option that can be passed in:
|
|
305
|
+
|
|
306
|
+
```javascript
|
|
307
|
+
const tags = ExifReader.load(fileBuffer, {includeUnknown: true});
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
If you discover an unknown tag that should be handled by ExifReader, please
|
|
311
|
+
reach out by filing an issue.
|
|
312
|
+
|
|
313
|
+
#### Computed tag values (opt-in)
|
|
314
|
+
|
|
315
|
+
ExifReader exposes three different values per Exif tag:
|
|
316
|
+
|
|
317
|
+
- **`value`**: A stable, raw-ish value that mirrors how the tag is stored in the
|
|
318
|
+
file.
|
|
319
|
+
- **`description`**: A human-friendly value meant for display.
|
|
320
|
+
- **`computed`**: An opt-in, type-aware value. This will often be the same as
|
|
321
|
+
`value` except for RATIONAL/SRATIONAL and ASCII tags.
|
|
322
|
+
|
|
323
|
+
Enable the `computed` value by passing `computed: true` in the options:
|
|
324
|
+
|
|
325
|
+
```javascript
|
|
326
|
+
const tags = ExifReader.load(fileBuffer, {computed: true});
|
|
327
|
+
|
|
328
|
+
const make = tags['Make'].computed; // e.g. "Apple"
|
|
329
|
+
const xResolution = tags['XResolution'].computed; // e.g. 72
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
`computed` is only added for tags parsed from TIFF IFD structures (Exif/GPS/etc,
|
|
333
|
+
including maker notes, MPF, and the Thumbnail IFD). It is not currently added to
|
|
334
|
+
XMP/IPTC/ICC tags or PNG text tags.
|
|
335
|
+
|
|
336
|
+
The `computed` conversion rules are based on the TIFF tag type:
|
|
337
|
+
|
|
338
|
+
- **ASCII**: If `value` contains a single string, `computed` is that string.
|
|
339
|
+
Otherwise `computed` is a string array.
|
|
340
|
+
- **RATIONAL / SRATIONAL**: `computed` is a number (or an array of numbers).
|
|
341
|
+
Division by zero yields `null`.
|
|
342
|
+
- **All other types**: `computed` equals `value`.
|
|
343
|
+
|
|
344
|
+
Note that `computed` may evolve in minor versions as the feature matures. If you
|
|
345
|
+
need a value with the strongest stability guarantees, prefer `value`.
|
|
346
|
+
|
|
347
|
+
#### Read only part of file
|
|
348
|
+
|
|
349
|
+
If you only want to read part of the image file you can use the `length` option:
|
|
350
|
+
|
|
351
|
+
```javascript
|
|
352
|
+
const tags = await ExifReader.load(filename, {length: 128 * 1024});
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
This will load only the first 128 KiB of the file. This could be useful if you
|
|
356
|
+
know the metadata is located at the beginning of the file. Just be aware that
|
|
357
|
+
it's common for the metadata to be spread out over a larger area so please try
|
|
358
|
+
it out on your set of files to know if it's suitable for your situation.
|
|
359
|
+
|
|
360
|
+
Note that this option only works when ExifReader handles the loading of the
|
|
361
|
+
file. If e.g. an already loaded ArrayBuffer or Buffer is passed into ExifReader,
|
|
362
|
+
the whole file will already have been loaded into memory and it's too late.
|
|
363
|
+
More specifically the length option will work for 1. local files when running
|
|
364
|
+
through Node.js, 2. remote files when passing a URL, and 3. browser File objects
|
|
365
|
+
(e.g., from form file fields). For remote files accessed through a web browser,
|
|
366
|
+
make sure the remote server is either on the same origin (domain) as your script
|
|
367
|
+
or that the server is passing correct CORS headers, specifically allowing the
|
|
368
|
+
`Range` header.
|
|
369
|
+
|
|
370
|
+
#### Read only the metadata bytes (`length: 'auto'`)
|
|
371
|
+
|
|
372
|
+
When you want to download or store just enough of an image to extract its
|
|
373
|
+
metadata, without guessing a fixed `length`, pass `length: 'auto'`:
|
|
374
|
+
|
|
375
|
+
```javascript
|
|
376
|
+
const tags = await ExifReader.load(url, {
|
|
377
|
+
length: 'auto',
|
|
378
|
+
expanded: true,
|
|
379
|
+
includeOffsets: true,
|
|
380
|
+
excludeTags: {mpf: true}, // skip embedded preview; see note below
|
|
381
|
+
});
|
|
382
|
+
|
|
383
|
+
tags.metadataRange.end // exact byte count needed for the metadata
|
|
384
|
+
tags.metadataRange.buffer // bytes [0, end), sliced from what we read.
|
|
385
|
+
// Same kind as the input (ArrayBuffer or
|
|
386
|
+
// Node Buffer). Save this to disk to keep
|
|
387
|
+
// only the metadata-bearing prefix.
|
|
388
|
+
tags.metadataRange.fetched // bytes actually read. May be greater than
|
|
389
|
+
// `end` because the loop reads in fixed-size
|
|
390
|
+
// chunks and so may read a little past `end`.
|
|
391
|
+
tags.metadataRange.requests // number of IO calls performed
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
ExifReader fetches an initial 128 KiB prefix and parses it. Only if the
|
|
395
|
+
metadata extends further does it issue an HTTP `Range` request (or a
|
|
396
|
+
follow-up filesystem read / `File.slice`) for exactly the additional bytes
|
|
397
|
+
needed. Most files finish in a single request. HEIC/AVIF files where the
|
|
398
|
+
Exif/XMP `iloc` entries point near the end of the file typically take two.
|
|
399
|
+
|
|
400
|
+
`length: 'auto'` is supported for the four IO inputs:
|
|
401
|
+
|
|
402
|
+
- URL via browser `fetch` (uses HTTP `Range`)
|
|
403
|
+
- URL via Node `http(s)` (uses HTTP `Range`)
|
|
404
|
+
- Local file path via Node `fs`
|
|
405
|
+
- Browser `File` object via `File.slice`
|
|
406
|
+
|
|
407
|
+
It is also accepted for in-memory inputs (`ArrayBuffer`, `Buffer`,
|
|
408
|
+
`SharedArrayBuffer`, `DataView`) as a convenience. There is no IO loop to
|
|
409
|
+
run in that case, but `metadataRange.buffer` is still attached as the
|
|
410
|
+
trimmed slice of what you passed in.
|
|
411
|
+
|
|
412
|
+
Requirements and caveats:
|
|
413
|
+
|
|
414
|
+
- `expanded: true` and `includeOffsets: true` are required. Passing
|
|
415
|
+
`length: 'auto'` without them throws a clear error (at runtime, and also a
|
|
416
|
+
type error in TypeScript).
|
|
417
|
+
- The return is always a `Promise` because the loop is asynchronous.
|
|
418
|
+
- Not supported for plain TIFF or bare JPEG XL codestreams. They have no
|
|
419
|
+
leading metadata container, so the loop has no convergence signal and
|
|
420
|
+
will reject with an error.
|
|
421
|
+
- If the loop fails to converge in 4 iterations (very rare, defensive
|
|
422
|
+
bound for unknown-size HTTP responses or files whose parsers can't
|
|
423
|
+
bootstrap from a small prefix), ExifReader reads the rest of the file
|
|
424
|
+
and emits a single `console.warn`. Correctness is preserved. The
|
|
425
|
+
bandwidth savings are forfeit.
|
|
426
|
+
|
|
427
|
+
**Why `excludeTags: {mpf: true}` is in the example.** Most modern phone
|
|
428
|
+
cameras (and many DSLRs) emit JPEGs with a Multi-Picture-Format sub-image
|
|
429
|
+
preview embedded a few MB into the file. Without `excludeTags: {mpf:
|
|
430
|
+
true}` ExifReader treats those sub-images as part of the metadata range,
|
|
431
|
+
so `metadataRange.end` lands near EOF and `length: 'auto'` ends up
|
|
432
|
+
reading most of the file anyway. On a corpus of about 1.5 GiB of phone
|
|
433
|
+
photos this single option took `length: 'auto'` from a ~17% slowdown vs
|
|
434
|
+
a regular full read to a **6× speedup with 98% of bytes saved**. The
|
|
435
|
+
regular `tags.exif`, `tags.xmp`, `tags.icc`, `tags.gps` and the rest are
|
|
436
|
+
unaffected. Drop the option only if you actually need the
|
|
437
|
+
`tags.mpf.Images` array.
|
|
438
|
+
|
|
439
|
+
#### Locating metadata in the file (`includeOffsets`)
|
|
440
|
+
|
|
441
|
+
Pass `includeOffsets: true` together with `expanded: true` to learn where in
|
|
442
|
+
the file the metadata sits. Useful for persisting only the metadata-bearing
|
|
443
|
+
prefix of an image rather than the whole file. The resulting slice is enough
|
|
444
|
+
for re-extracting metadata with ExifReader, not for opening the slice as an
|
|
445
|
+
image.
|
|
446
|
+
|
|
447
|
+
```javascript
|
|
448
|
+
const tags = ExifReader.load(fileBuffer, {expanded: true, includeOffsets: true});
|
|
449
|
+
|
|
450
|
+
tags.metadataRange.start // lowest block start (informational, can be deep
|
|
451
|
+
// into the file for HEIC/AVIF; do NOT use as a
|
|
452
|
+
// slice boundary, always slice from 0)
|
|
453
|
+
tags.metadataRange.end // exclusive end. Store bytes 0..end to keep all metadata
|
|
454
|
+
tags.metadataRange.complete // false when the input was truncated before all metadata
|
|
455
|
+
tags.metadataRange.blocks // [{type, start, end}, ...] sorted by start
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
Offsets are byte indices into the data you passed in. `metadataRange` is
|
|
459
|
+
attached only when both `expanded: true` and `includeOffsets: true` are set,
|
|
460
|
+
so default and flat-mode output are unchanged.
|
|
461
|
+
|
|
462
|
+
Block `type` reuses the filtering-group vocabulary (`exif`, `iptc`, `xmp`,
|
|
463
|
+
`icc`, `mpf`, `jfif`, `file`, `png`, `riff`, `gif`), plus `mpfImage` for the
|
|
464
|
+
sub-images of an MPF Multi-Picture JPEG. The same type may appear more than
|
|
465
|
+
once (multi-chunk ICC, extended XMP), one entry per physical container.
|
|
466
|
+
|
|
467
|
+
Typical workflow:
|
|
468
|
+
|
|
469
|
+
```javascript
|
|
470
|
+
const headChunk = await fetchFirstNBytes(url, 256 * 1024);
|
|
471
|
+
const tags = ExifReader.load(headChunk, {expanded: true, includeOffsets: true});
|
|
472
|
+
|
|
473
|
+
if (!tags.metadataRange.complete) {
|
|
474
|
+
// 256 KiB was not enough, fetch more
|
|
475
|
+
} else {
|
|
476
|
+
const minimalSlice = headChunk.slice(0, tags.metadataRange.end);
|
|
477
|
+
await uploadMetadata(minimalSlice);
|
|
478
|
+
}
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Notes and limitations:
|
|
482
|
+
|
|
483
|
+
- Not supported for plain TIFF or bare JPEG XL codestreams (no leading
|
|
484
|
+
metadata container). `metadataRange` is omitted in both cases.
|
|
485
|
+
- For JPEG XL containers, blocks cover the `Exif` and `xml ` boxes but not
|
|
486
|
+
the `jxlc`/`jxlp` codestream box (encoded image data, not metadata).
|
|
487
|
+
- `complete: true` means ExifReader did not detect truncation. For JPEG and
|
|
488
|
+
PNG it observed `SOS` or `IEND`, for standalone XMP it observed an
|
|
489
|
+
`<?xpacket end=?>` or `</x:xmpmeta>` token. For other formats it is
|
|
490
|
+
best-effort, a buffer ending cleanly between metadata segments can still
|
|
491
|
+
report `complete: true`. Non-standard trailers (JPEG-XT, post-SOS markers)
|
|
492
|
+
are never detected. Note the converse: re-parsing a slice produced by
|
|
493
|
+
`buffer.slice(0, metadataRange.end)` may report `complete: false` for
|
|
494
|
+
JPEG/PNG even though every metadata segment is intact, because the
|
|
495
|
+
slice ends before `SOS`/`IEND`. The block list and `tags.exif` etc. are
|
|
496
|
+
still complete in that case.
|
|
497
|
+
- Only the metadata segments ExifReader actively parses are present in
|
|
498
|
+
`blocks`. JPEG segments ExifReader does not currently extract tags from
|
|
499
|
+
(APP3-APP12, `COM` comments, JPEG-XT extensions) do not appear and are
|
|
500
|
+
not guaranteed to be preserved by a `0..end` slice. The slice is
|
|
501
|
+
enough to re-extract everything ExifReader itself reads, not to
|
|
502
|
+
preserve every byte a third-party tool might care about.
|
|
503
|
+
- For HEIC/AVIF, metadata can sit near the end of the file, so
|
|
504
|
+
`metadataRange.end` often lands close to the file size and trimming
|
|
505
|
+
saves little. The `icc` block here covers just the ICC profile bytes;
|
|
506
|
+
for JPEG/PNG/WebP it covers the full container wrapper.
|
|
507
|
+
- For MPF JPEGs, sub-images appear as `mpfImage` blocks and push `end`
|
|
508
|
+
toward the file size. If MPF parsing is suppressed by a tag filter (any
|
|
509
|
+
`excludeTags: {mpf: ...}` or `includeTags` that does not include `mpf`),
|
|
510
|
+
the `mpfImage` blocks are not emitted and `metadataRange.end` shrinks.
|
|
511
|
+
The parent `mpf` segment block always remains, since it is a real
|
|
512
|
+
metadata segment found during the header scan.
|
|
513
|
+
- Offsets come from length fields in the file. Treat `metadataRange.end`
|
|
514
|
+
and `block.end` as untrusted input. Clamp to your buffer length before
|
|
515
|
+
slicing, allocating, or issuing remote range requests.
|
|
516
|
+
|
|
200
517
|
#### Asynchronous tags
|
|
201
518
|
|
|
202
519
|
Some tags need to be parsed asynchronously. Currently this is the case for some
|
|
@@ -287,17 +604,6 @@ warning is logged via `console.warn`, and the rest of the tags are returned as
|
|
|
287
604
|
usual. The limit applies to the built-in Compression Streams paths and to any
|
|
288
605
|
result returned by a custom `brotli`/`deflate` function.
|
|
289
606
|
|
|
290
|
-
#### Grouping
|
|
291
|
-
|
|
292
|
-
By default, Exif, IPTC and XMP tags are grouped together. This means that if
|
|
293
|
-
e.g. `Orientation` exists in both Exif and XMP, the first value (Exif) will be
|
|
294
|
-
overwritten by the second (XMP). If you need to separate between these values,
|
|
295
|
-
pass in an options object with the property `expanded` set to `true`:
|
|
296
|
-
|
|
297
|
-
```javascript
|
|
298
|
-
const tags = ExifReader.load(fileBuffer, {expanded: true});
|
|
299
|
-
```
|
|
300
|
-
|
|
301
607
|
#### Parsing XMP tags when not in a DOM environment
|
|
302
608
|
|
|
303
609
|
When using for example Node.js or a web worker, there is no native
|
|
@@ -355,161 +661,6 @@ If you're having trouble getting the GPS location, see [this comment and
|
|
|
355
661
|
thread](https://github.com/mattiasw/ExifReader/issues/177#issuecomment-1172228225)
|
|
356
662
|
and the [GPS section below](#gps) for more details.
|
|
357
663
|
|
|
358
|
-
#### Read only part of file
|
|
359
|
-
|
|
360
|
-
If you only want to read part of the image file you can use the `length` option:
|
|
361
|
-
|
|
362
|
-
```javascript
|
|
363
|
-
const tags = await ExifReader.load(filename, {length: 128 * 1024});
|
|
364
|
-
```
|
|
365
|
-
|
|
366
|
-
This will load only the first 128 KiB of the file. This could be useful if you
|
|
367
|
-
know the metadata is located at the beginning of the file. Just be aware that
|
|
368
|
-
it's common for the metadata to be spread out over a larger area so please try
|
|
369
|
-
it out on your set of files to know if it's suitable for your situation.
|
|
370
|
-
|
|
371
|
-
Note that this option only works when ExifReader handles the loading of the
|
|
372
|
-
file. If e.g. an already loaded ArrayBuffer or Buffer is passed into ExifReader,
|
|
373
|
-
the whole file will already have been loaded into memory and it's too late.
|
|
374
|
-
More specifically the length option will work for 1. local files when running
|
|
375
|
-
through Node.js, 2. remote files when passing a URL, and 3. browser File objects
|
|
376
|
-
(e.g., from form file fields). For remote files accessed through a web browser,
|
|
377
|
-
make sure the remote server is either on the same origin (domain) as your script
|
|
378
|
-
or that the server is passing correct CORS headers, specifically allowing the
|
|
379
|
-
`Range` header.
|
|
380
|
-
|
|
381
|
-
#### Unknown tags
|
|
382
|
-
|
|
383
|
-
Tags that are unknown, either because they have been excluded by making a custom
|
|
384
|
-
build or they are yet to be added into ExifReader, are by default not included
|
|
385
|
-
in the output. If you need to see them there is an option that can be passed in:
|
|
386
|
-
|
|
387
|
-
```javascript
|
|
388
|
-
const tags = ExifReader.load(fileBuffer, {includeUnknown: true});
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
If you discover an unknown tag that should be handled by ExifReader, please
|
|
392
|
-
reach out by filing an issue.
|
|
393
|
-
|
|
394
|
-
#### Filtering tags (includeTags / excludeTags)
|
|
395
|
-
|
|
396
|
-
You can filter which tags are returned by using `includeTags` and/or
|
|
397
|
-
`excludeTags`.
|
|
398
|
-
|
|
399
|
-
- If `includeTags` is provided, it uses an **include-pattern**: only the groups
|
|
400
|
-
you specify will be included in the output.
|
|
401
|
-
- `excludeTags` can be used alone to remove tags/groups while keeping everything
|
|
402
|
-
else.
|
|
403
|
-
- If a group is specified in both `includeTags` and `excludeTags`, `excludeTags`
|
|
404
|
-
for that group will be ignored.
|
|
405
|
-
- An empty selector array (e.g. `includeTags: { xmp: [] }`) is treated as
|
|
406
|
-
excluding that group. The group will not be returned and ExifReader will skip
|
|
407
|
-
parsing it.
|
|
408
|
-
|
|
409
|
-
**Examples**
|
|
410
|
-
|
|
411
|
-
Exclude a few tags in the Exif group:
|
|
412
|
-
|
|
413
|
-
```javascript
|
|
414
|
-
const tags = ExifReader.load(fileBuffer, {
|
|
415
|
-
excludeTags: {
|
|
416
|
-
exif: ['MakerNote', 0x9286],
|
|
417
|
-
}
|
|
418
|
-
});
|
|
419
|
-
```
|
|
420
|
-
|
|
421
|
-
Only return XMP tags (and exclude everything else):
|
|
422
|
-
|
|
423
|
-
```javascript
|
|
424
|
-
const tags = ExifReader.load(fileBuffer, {
|
|
425
|
-
includeTags: {
|
|
426
|
-
xmp: true,
|
|
427
|
-
}
|
|
428
|
-
});
|
|
429
|
-
```
|
|
430
|
-
|
|
431
|
-
**Filtering groups**
|
|
432
|
-
|
|
433
|
-
The group keys follow the same concept as the output when `expanded: true` is
|
|
434
|
-
used. (The `thumbnail` group controls the top-level `Thumbnail` value.)
|
|
435
|
-
|
|
436
|
-
For PNG, filtering is done with the `png` group only. (The `pngFile` and
|
|
437
|
-
`pngText` groups exist in `expanded` output today, but `png` is the filtering key
|
|
438
|
-
and those groups will be deprecated later.)
|
|
439
|
-
|
|
440
|
-
| Group key | Description | Supports IDs |
|
|
441
|
-
| ------------- | ------------------------------------------------ | ------------ |
|
|
442
|
-
| `exif` | Exif tags (including GPS IFD, interoperability). | yes |
|
|
443
|
-
| `iptc` | IPTC tags. | yes |
|
|
444
|
-
| `xmp` | XMP tags. | no |
|
|
445
|
-
| `icc` | ICC profile tags. | no |
|
|
446
|
-
| `photoshop` | Photoshop resource tags. | yes |
|
|
447
|
-
| `makerNotes` | MakerNote tags (e.g. Canon/Pentax). | yes |
|
|
448
|
-
| `mpf` | MPF tags. | yes |
|
|
449
|
-
| `file` | JPEG file details and `FileType`. | no |
|
|
450
|
-
| `jfif` | JFIF tags. | no |
|
|
451
|
-
| `png` | PNG header, chunk, and text tags. | no |
|
|
452
|
-
| `riff` | WebP (RIFF) tags. | no |
|
|
453
|
-
| `gif` | GIF tags. | no |
|
|
454
|
-
| `gps` | Computed GPS group (only when `expanded: true`). | no |
|
|
455
|
-
| `composite` | Composite tags (e.g. FieldOfView). | no |
|
|
456
|
-
| `thumbnail` | Top-level `Thumbnail` output. | no |
|
|
457
|
-
|
|
458
|
-
**Important: dependency tags**
|
|
459
|
-
|
|
460
|
-
Some tags act as pointers or containers to other metadata. Excluding them can
|
|
461
|
-
cause other tags or entire groups to disappear. Some important examples:
|
|
462
|
-
|
|
463
|
-
- `Exif IFD Pointer`, `GPS Info IFD Pointer`, `Interoperability IFD Pointer`
|
|
464
|
-
- `IPTC-NAA` (TIFF embedded IPTC), `ApplicationNotes` (TIFF embedded XMP),
|
|
465
|
-
`ICC_Profile` (TIFF embedded ICC)
|
|
466
|
-
- `MakerNote` and `Make` (maker note parsing)
|
|
467
|
-
- `ImageSourceData` and `PhotoshopSettings` (Photoshop parsing)
|
|
468
|
-
- `JPEGInterchangeFormat` and `JPEGInterchangeFormatLength` (thumbnails)
|
|
469
|
-
|
|
470
|
-
**NOTE:** When using `includeTags`, you **do not** have to list these dependency
|
|
471
|
-
tags. ExifReader will automatically include the required pointer/container tags
|
|
472
|
-
needed to find and parse the groups you requested. This section mainly matters
|
|
473
|
-
when using `excludeTags`.
|
|
474
|
-
|
|
475
|
-
Note that XMP and ICC tags are parsed from full metadata blocks, so ExifReader
|
|
476
|
-
cannot skip parsing individual XMP/ICC tags based on selectors. The returned
|
|
477
|
-
output is still filtered.
|
|
478
|
-
|
|
479
|
-
#### Computed tag values (opt-in)
|
|
480
|
-
|
|
481
|
-
ExifReader exposes three different values per Exif tag:
|
|
482
|
-
|
|
483
|
-
- **`value`**: A stable, raw-ish value that mirrors how the tag is stored in the
|
|
484
|
-
file.
|
|
485
|
-
- **`description`**: A human-friendly value meant for display.
|
|
486
|
-
- **`computed`**: An opt-in, type-aware value. This will often be the same as
|
|
487
|
-
`value` except for RATIONAL/SRATIONAL and ASCII tags.
|
|
488
|
-
|
|
489
|
-
Enable the `computed` value by passing `computed: true` in the options:
|
|
490
|
-
|
|
491
|
-
```javascript
|
|
492
|
-
const tags = ExifReader.load(fileBuffer, {computed: true});
|
|
493
|
-
|
|
494
|
-
const make = tags['Make'].computed; // e.g. "Apple"
|
|
495
|
-
const xResolution = tags['XResolution'].computed; // e.g. 72
|
|
496
|
-
```
|
|
497
|
-
|
|
498
|
-
`computed` is only added for tags parsed from TIFF IFD structures (Exif/GPS/etc,
|
|
499
|
-
including maker notes, MPF, and the Thumbnail IFD). It is not currently added to
|
|
500
|
-
XMP/IPTC/ICC tags or PNG text tags.
|
|
501
|
-
|
|
502
|
-
The `computed` conversion rules are based on the TIFF tag type:
|
|
503
|
-
|
|
504
|
-
- **ASCII**: If `value` contains a single string, `computed` is that string.
|
|
505
|
-
Otherwise `computed` is a string array.
|
|
506
|
-
- **RATIONAL / SRATIONAL**: `computed` is a number (or an array of numbers).
|
|
507
|
-
Division by zero yields `null`.
|
|
508
|
-
- **All other types**: `computed` equals `value`.
|
|
509
|
-
|
|
510
|
-
Note that `computed` may evolve in minor versions as the feature matures. If you
|
|
511
|
-
need a value with the strongest stability guarantees, prefer `value`.
|
|
512
|
-
|
|
513
664
|
### GPS
|
|
514
665
|
|
|
515
666
|
If `expanded: true` is specified in the options, there will be a `gps` group.
|
|
@@ -748,6 +899,13 @@ Tips
|
|
|
748
899
|
possibly Exif too if they come in an irregular order) so please check if
|
|
749
900
|
this optimization fits your use case. Use the `length` option to only read
|
|
750
901
|
the beginning of the file. See above for more details on that.
|
|
902
|
+
- Excluding MPF (Multi-Picture Format) makes a big difference for phone
|
|
903
|
+
photos. Modern phone JPEGs embed a sub-image preview a few MB into the
|
|
904
|
+
file. If you do not need it, pass `excludeTags: {mpf: true}`. This is
|
|
905
|
+
especially impactful when combined with `length: 'auto'` (multi-x
|
|
906
|
+
speedup, see that section), but it also lets a numeric `length`
|
|
907
|
+
boundary land well before the sub-image. Regular Exif/XMP/ICC tags are
|
|
908
|
+
unaffected.
|
|
751
909
|
|
|
752
910
|
Known Limitations
|
|
753
911
|
-----------------
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
|
+
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
|
+
* file, You can obtain one at https://mozilla.org/MPL/2.0/. */
|
|
4
|
+
|
|
5
|
+
/* eslint-disable no-console */
|
|
6
|
+
|
|
7
|
+
const fs = require('fs');
|
|
8
|
+
const path = require('path');
|
|
9
|
+
|
|
10
|
+
const MIB = 1024 * 1024;
|
|
11
|
+
|
|
12
|
+
main();
|
|
13
|
+
|
|
14
|
+
function main() {
|
|
15
|
+
const args = process.argv.slice(2);
|
|
16
|
+
const helpRequested = args.includes('-h') || args.includes('--help');
|
|
17
|
+
if (helpRequested || args.length !== 2) {
|
|
18
|
+
printHelp();
|
|
19
|
+
process.exit(helpRequested ? 0 : 1);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const before = readReport(args[0]);
|
|
23
|
+
const after = readReport(args[1]);
|
|
24
|
+
|
|
25
|
+
console.log(`Diff: ${shortPath(args[0])} → ${shortPath(args[1])}`);
|
|
26
|
+
console.log(`Mode: before=${describeMode(before)} after=${describeMode(after)}`);
|
|
27
|
+
console.log('');
|
|
28
|
+
|
|
29
|
+
const byFormat = joinByFormat(before, after);
|
|
30
|
+
printFormatDiff(byFormat);
|
|
31
|
+
|
|
32
|
+
console.log('');
|
|
33
|
+
printOverallDiff(before, after);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function printHelp() {
|
|
37
|
+
console.log(`Usage: node bin/profile-diff.js <before.json> <after.json>
|
|
38
|
+
|
|
39
|
+
Compares two JSON reports produced by bin/profile.js. Per-format and overall
|
|
40
|
+
deltas in mean parse time and (when --length-auto was used) bytes read.
|
|
41
|
+
|
|
42
|
+
Recommended workflow:
|
|
43
|
+
node bin/profile.js --include-io -n 100 --probe-bytes --json \\
|
|
44
|
+
> .profile-results/baseline.json
|
|
45
|
+
node bin/profile.js --include-io -n 100 --length-auto --json \\
|
|
46
|
+
> .profile-results/after.json
|
|
47
|
+
node bin/profile-diff.js .profile-results/baseline.json .profile-results/after.json
|
|
48
|
+
`);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function readReport(p) {
|
|
52
|
+
try {
|
|
53
|
+
return JSON.parse(fs.readFileSync(p, 'utf8'));
|
|
54
|
+
} catch (error) {
|
|
55
|
+
console.error(`Failed to read ${p}: ${error.message || error}`);
|
|
56
|
+
process.exit(1);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function shortPath(p) {
|
|
61
|
+
const cwd = process.cwd();
|
|
62
|
+
return p.startsWith(cwd) ? path.relative(cwd, p) : p;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function describeMode(report) {
|
|
66
|
+
const o = report.options || {};
|
|
67
|
+
const parts = [];
|
|
68
|
+
parts.push(o.includeIo ? 'parse+IO' : 'parse-only');
|
|
69
|
+
if (o.lengthAuto) {
|
|
70
|
+
parts.push('length:auto');
|
|
71
|
+
}
|
|
72
|
+
if (o.excludeMpf) {
|
|
73
|
+
parts.push('no-mpf');
|
|
74
|
+
}
|
|
75
|
+
if (o.probeBytes) {
|
|
76
|
+
parts.push('probe');
|
|
77
|
+
}
|
|
78
|
+
parts.push(`n=${o.iterations}`);
|
|
79
|
+
return parts.join(' ');
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function joinByFormat(before, after) {
|
|
83
|
+
const beforeByFmt = new Map();
|
|
84
|
+
for (const f of before.formats) {
|
|
85
|
+
beforeByFmt.set(f.format, f);
|
|
86
|
+
}
|
|
87
|
+
const out = [];
|
|
88
|
+
for (const a of after.formats) {
|
|
89
|
+
const b = beforeByFmt.get(a.format) || null;
|
|
90
|
+
out.push({format: a.format, before: b, after: a});
|
|
91
|
+
}
|
|
92
|
+
return out;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function printFormatDiff(rows) {
|
|
96
|
+
const headers = [
|
|
97
|
+
'format', 'files', 'before-ms', 'after-ms', 'speedup',
|
|
98
|
+
'before-MiB-read', 'after-MiB-read', 'bytes-saved'
|
|
99
|
+
];
|
|
100
|
+
const tableRows = rows.map((r) => {
|
|
101
|
+
const beforeMs = r.before ? r.before.meanMs : null;
|
|
102
|
+
const afterMs = r.after ? r.after.meanMs : null;
|
|
103
|
+
const speedup = (beforeMs && afterMs && afterMs > 0) ? (beforeMs / afterMs) : null;
|
|
104
|
+
const beforeMiB = r.before ? r.before.bytes / MIB : null;
|
|
105
|
+
const afterFetchedRatio = (r.after && typeof r.after.fetchedRatio === 'number') ? r.after.fetchedRatio : null;
|
|
106
|
+
const afterMiB = (afterFetchedRatio !== null && r.after) ? (r.after.bytes * afterFetchedRatio) / MIB : null;
|
|
107
|
+
const saved = (beforeMiB !== null && afterMiB !== null && beforeMiB > 0) ? 1 - (afterMiB / beforeMiB) : null;
|
|
108
|
+
return [
|
|
109
|
+
r.format,
|
|
110
|
+
String((r.after && r.after.count) || 0),
|
|
111
|
+
beforeMs === null ? '-' : beforeMs.toFixed(2),
|
|
112
|
+
afterMs === null ? '-' : afterMs.toFixed(2),
|
|
113
|
+
speedup === null ? '-' : speedup.toFixed(2) + 'x',
|
|
114
|
+
beforeMiB === null ? '-' : beforeMiB.toFixed(1),
|
|
115
|
+
afterMiB === null ? '-' : afterMiB.toFixed(1),
|
|
116
|
+
saved === null ? '-' : (saved * 100).toFixed(1) + '%',
|
|
117
|
+
];
|
|
118
|
+
});
|
|
119
|
+
printTable(headers, tableRows);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function printOverallDiff(before, after) {
|
|
123
|
+
const b = before.overall || {};
|
|
124
|
+
const a = after.overall || {};
|
|
125
|
+
const beforeMs = b.totalTime;
|
|
126
|
+
const afterMs = a.totalTime;
|
|
127
|
+
const speedup = (beforeMs && afterMs && afterMs > 0) ? (beforeMs / afterMs) : null;
|
|
128
|
+
const beforeMiB = (b.totalBytes || 0) / MIB;
|
|
129
|
+
const afterMiB = (typeof a.fetchedTotal === 'number') ? a.fetchedTotal / MIB : beforeMiB;
|
|
130
|
+
const saved = (beforeMiB > 0) ? 1 - (afterMiB / beforeMiB) : 0;
|
|
131
|
+
|
|
132
|
+
console.log(`Overall: ${formatMs(beforeMs)} → ${formatMs(afterMs)} (${speedup === null ? '-' : speedup.toFixed(2) + 'x'} speedup)`);
|
|
133
|
+
if (typeof a.fetchedTotal === 'number') {
|
|
134
|
+
console.log(`Bytes: ${beforeMiB.toFixed(1)} MiB → ${afterMiB.toFixed(1)} MiB (${(saved * 100).toFixed(1)}% saved)`);
|
|
135
|
+
if (typeof a.requestsMean === 'number') {
|
|
136
|
+
console.log(`Requests: ${a.requestsMean.toFixed(2)} per file on average across ${a.fetchedFiles} files`);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function formatMs(v) {
|
|
142
|
+
if (v === undefined || v === null) {
|
|
143
|
+
return '-';
|
|
144
|
+
}
|
|
145
|
+
if (v >= 1000) {
|
|
146
|
+
return (v / 1000).toFixed(1) + ' s';
|
|
147
|
+
}
|
|
148
|
+
return v.toFixed(0) + ' ms';
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function printTable(headers, rows) {
|
|
152
|
+
const widths = headers.map((h, i) => {
|
|
153
|
+
let w = h.length;
|
|
154
|
+
for (const r of rows) {
|
|
155
|
+
if (r[i] && r[i].length > w) {
|
|
156
|
+
w = r[i].length;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
return w;
|
|
160
|
+
});
|
|
161
|
+
const align = (cell, i) => {
|
|
162
|
+
if (i === 0) {
|
|
163
|
+
return cell.padEnd(widths[i]);
|
|
164
|
+
}
|
|
165
|
+
return cell.padStart(widths[i]);
|
|
166
|
+
};
|
|
167
|
+
console.log(' ' + headers.map((h, i) => align(h, i)).join(' '));
|
|
168
|
+
for (const r of rows) {
|
|
169
|
+
console.log(' ' + r.map((c, i) => align(c, i)).join(' '));
|
|
170
|
+
}
|
|
171
|
+
}
|