diff --git a/README.md b/README.md index 2c8b6a7..97b703e 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,8 @@ requires one, and writes: photo its image, its video and the `.livephoto.json` file naming them - beside each original, a JSON file named after it with `.json` added, for example `2026-03-01.12345.jpg.json`: the photo's record (`photo.record()`) - without its cache paths, and its EXIF fields (`photo.exif()`) under `exif` + without its cache paths, and every EXIF tag of the photo (`photo.exif()`) + under `exif` - `albums/.json` for each album: its `collectionID`, its `name`, and under `savePaths` the save paths of its photos relative to `dir`, newest first @@ -773,21 +774,25 @@ These async methods may download: - `await photo.thumbnail(opts?)` → `{ path, bytes }`. - `await photo.content(opts?)` → `Uint8Array` — the original's bytes, read through `original()`; for a live photo, its image's. -- `await photo.exif(opts?)` → `PhotoExif` — `make`, `model`, `lensModel`, - `dateTimeOriginal`, `offsetTimeOriginal`, `exposureTime`, `fNumber`, `iso`, - `focalLength`, `orientation`, `gpsLatitude`, `gpsLongitude` and `gpsAltitude`, - each absent when the file lacks it. GPS values are signed decimal degrees and - metres. `dateTimeOriginal` is the camera's clock reading held in the `Date`'s - UTC fields; `offsetTimeOriginal`, when present, is that clock's offset from - UTC. EXIF is read from any image format exifreader reads (such as JPEG, - HEIC/HEIF, AVIF, PNG, WebP and TIFF), a live photo's image included. Any other - original gives `{}`, and a video gives `{}` without being downloaded. +- `await photo.exif(opts?)` → `ExifTags` — every EXIF tag in the file, keyed by + tag name, each as exifreader decodes it, with its `id`, `value`, `description` + and `computed` value: for example `Make` is + `{ id: 271, value: ["Canon"], description: "Canon", computed: "Canon" }`. A + tag exifreader has no name for is keyed `undefined-`. The embedded + thumbnail's tags are under `Thumbnail`, so they cannot hide the main image's + tags of the same name; the thumbnail image itself is left out. EXIF is read + from any image format exifreader reads (such as JPEG, HEIC/HEIF, AVIF, PNG, + WebP and TIFF), a live photo's image included. Any other original gives `{}`, + and a video gives `{}` without being downloaded. - `await photo.make(opts?)`, and likewise `model()`, `lensModel()`, `dateTimeOriginal()`, `offsetTimeOriginal()`, `exposureTime()`, `fNumber()`, `iso()`, `focalLength()`, `orientation()`, `gpsLatitude()`, `gpsLongitude()` - and `gpsAltitude()` → one field of `exif()` each, typed as in `PhotoExif`, or - `undefined` when the file lacks it. Each calls `exif()` with its `opts`, so - each call reads the original again. + and `gpsAltitude()` → one common field each, picked from the tags `exif()` + returns and typed as in `PhotoExif`, or `undefined` when the file lacks it. + GPS values are signed decimal degrees and metres. `dateTimeOriginal()` is the + camera's clock reading held in the `Date`'s UTC fields; + `offsetTimeOriginal()`, when present, is that clock's offset from UTC. Each + calls `exif()` with its `opts`, so each call reads the original again. They serve from the on-disk content cache when the bytes are present and otherwise fetch through the pools; `original()`, `content()` and `exif()` also @@ -904,7 +909,7 @@ from a very old client, is stored unchecked. - `src/library/records.ts`: `PhotoRecord`, `AlbumRecord`, `LibrarySnapshot`, `LibraryChange` - `src/library/mlsearch.ts`: `MLDataAPI`, `SimilarResult` -- `src/exif.ts`: `PhotoExif` +- `src/exif.ts`: `ExifTags`, `PhotoExif` - `src/library/pools.ts`: `RequestPools`, `RequestPoolsOptions`, `BoundedPool` - `src/backup.ts`: `BackupOptions`, `BackupResult`, `BackupError` - `src/client.ts`: `Client`, `LoginOptions`, `ClientSnapshot` diff --git a/TODO.md b/TODO.md index f37e1cb..d6972af 100644 --- a/TODO.md +++ b/TODO.md @@ -25,6 +25,13 @@ declares one. # Completed Steps +- 2026-10-02: `photo.exif()` returns every EXIF tag in the file as `ExifTags`, + keyed by tag name, each as exifreader decodes it, not only the thirteen common + fields (issue 156). The embedded thumbnail's tags are under `Thumbnail`, + without the thumbnail image. The thirteen typed methods stay, each picking its + field from the tags `exif()` returns, typed as in `PhotoExif`. The example + script's JSON files now carry every tag. + - 2026-10-01: The content cache no longer looks for a live photo that an earlier version cached as one ZIP (issue 151). When the cache opens, a live photo's file that no JSON file names is now always left alone. diff --git a/src/exif.ts b/src/exif.ts index b0f13f5..3819cd8 100644 --- a/src/exif.ts +++ b/src/exif.ts @@ -1,19 +1,19 @@ // EXIF in an original's bytes, read with exifreader, which reads it from JPEG, // HEIC/HEIF, AVIF, PNG, WebP and the other image formats it supports. // `backup-metadata --exif` records every EXIF tag it finds except the -// thumbnail's; `Photo.exif()` returns the common fields picked from them here. +// thumbnail's. `Photo.exif()` returns every tag, the thumbnail's included, and +// `Photo`'s typed methods return the common fields picked from them here. import ExifReader, { type ExpandedTags } from "exifreader"; -// The EXIF tags in `bytes` (`exif`), the GPS position exifreader computes from -// them (`gps`), and where the EXIF block lies in `bytes` (`metadataRange`). +// The EXIF tags in `bytes` (`exif`), the embedded thumbnail's tags +// (`Thumbnail`), and where the EXIF block lies in `bytes` (`metadataRange`). // Undefined when exifreader cannot read the file at all, such as a video. An -// EXIF block it finds but reads no tag from comes back as an empty `exif`. -// `exif` holds every tag except the thumbnail's; a tag exifreader has no name -// for is keyed `undefined-`. Each tag's `computed` holds its value -// as a string or number, or as an array of them for a tag with several values, -// such as `GPSLatitude`'s `[40, 26, 46]`. A fraction with a zero denominator -// computes to null. +// EXIF block it finds but reads no tag from comes back as an empty `exif`. A +// tag exifreader has no name for is keyed `undefined-`. Each tag's +// `computed` holds its value as a string or number, or as an array of them for +// a tag with several values, such as `GPSLatitude`'s `[40, 26, 46]`. A +// fraction with a zero denominator computes to null. export const readExifTags = (bytes: Uint8Array): ExpandedTags | undefined => { try { return ExifReader.loadView( @@ -23,7 +23,7 @@ export const readExifTags = (bytes: Uint8Array): ExpandedTags | undefined => { computed: true, includeOffsets: true, includeUnknown: true, - includeTags: { exif: true, gps: true }, + includeTags: { exif: true, thumbnail: true }, }, ); } catch { @@ -31,7 +31,35 @@ export const readExifTags = (bytes: Uint8Array): ExpandedTags | undefined => { } }; -// The common EXIF fields of an original. Each is absent when the file lacks it. +// Every EXIF tag of an original, keyed by name, each as exifreader decodes it +// (see `readExifTags`). The embedded thumbnail's own tags are under +// `Thumbnail`, so its `Orientation` or `ImageWidth` cannot hide the main +// image's. +export type ExifTags = Omit, "Thumbnail"> & { + Thumbnail?: Omit< + NonNullable, + "type" | "image" | "base64" + >; +}; + +// Every EXIF tag in `bytes`: `{}` when the file has no EXIF, exifreader cannot +// read its EXIF, or it is not an image exifreader reads. +export const readAllExifTags = (bytes: Uint8Array): ExifTags => { + const tags = readExifTags(bytes); + if (!tags?.Thumbnail) return tags?.exif ?? {}; + // exifreader puts the thumbnail's JPEG image beside its tags, as `type`, + // `image` and `base64`. The image is not a tag, so it is left out. + const { + type: _type, + image: _image, + base64: _base64, + ...thumbnail + } = tags.Thumbnail; + return { ...tags.exif, Thumbnail: thumbnail }; +}; + +// The common EXIF fields of an original, one for each of `Photo`'s typed +// methods. Each is absent when the file lacks it. export interface PhotoExif { make?: string; model?: string; @@ -80,30 +108,51 @@ const asDate = (v: unknown): Date | undefined => { return Number.isNaN(date.getTime()) ? undefined : date; }; -// The common fields of an original's EXIF: `{}` when the file has no EXIF, -// exifreader cannot read its EXIF, or it is not an image exifreader reads. -export const readPhotoExif = (bytes: Uint8Array): PhotoExif => { - const tags = readExifTags(bytes); - const exif = tags?.exif; - const gps = tags?.gps; - const altitude = asNumber(exif?.GPSAltitude?.computed); +// GPSLatitude and GPSLongitude hold degrees, minutes and seconds, computed as +// three numbers. This is them in decimal degrees, negative when `ref`, the +// GPSLatitudeRef or GPSLongitudeRef tag, is `negativeRef` ("S" or "W"). +// Without that tag the hemisphere is unknown, so it is undefined. +const asDegrees = ( + dms: unknown, + ref: unknown, + negativeRef: string, +): number | undefined => { + if (!Array.isArray(dms) || ref === undefined) return undefined; + const [d, m, s] = dms.map(asNumber); + if (d === undefined || m === undefined || s === undefined) return undefined; + const degrees = d + m / 60 + s / 3600; + return ref === negativeRef ? -degrees : degrees; +}; + +// The common fields picked from an original's EXIF tags, `readAllExifTags`'s +// result: `{}` when there are none. +export const readPhotoExif = (tags: ExifTags): PhotoExif => { + const altitude = asNumber(tags.GPSAltitude?.computed); const fields: PhotoExif = { - make: asString(exif?.Make?.computed), - model: asString(exif?.Model?.computed), - lensModel: asString(exif?.LensModel?.computed), - dateTimeOriginal: asDate(exif?.DateTimeOriginal?.computed), - offsetTimeOriginal: asString(exif?.OffsetTimeOriginal?.computed), - exposureTime: asNumber(exif?.ExposureTime?.computed), - fNumber: asNumber(exif?.FNumber?.computed), + make: asString(tags.Make?.computed), + model: asString(tags.Model?.computed), + lensModel: asString(tags.LensModel?.computed), + dateTimeOriginal: asDate(tags.DateTimeOriginal?.computed), + offsetTimeOriginal: asString(tags.OffsetTimeOriginal?.computed), + exposureTime: asNumber(tags.ExposureTime?.computed), + fNumber: asNumber(tags.FNumber?.computed), // Only when the tag holds a single number, as most cameras write it. - iso: asNumber(exif?.ISOSpeedRatings?.computed), - focalLength: asNumber(exif?.FocalLength?.computed), - orientation: asNumber(exif?.Orientation?.computed), - gpsLatitude: asNumber(gps?.Latitude), - gpsLongitude: asNumber(gps?.Longitude), + iso: asNumber(tags.ISOSpeedRatings?.computed), + focalLength: asNumber(tags.FocalLength?.computed), + orientation: asNumber(tags.Orientation?.computed), + gpsLatitude: asDegrees( + tags.GPSLatitude?.computed, + tags.GPSLatitudeRef?.computed, + "S", + ), + gpsLongitude: asDegrees( + tags.GPSLongitude?.computed, + tags.GPSLongitudeRef?.computed, + "W", + ), // A GPSAltitudeRef of 1 means the altitude is below sea level. gpsAltitude: - altitude !== undefined && exif?.GPSAltitudeRef?.value === 1 + altitude !== undefined && tags.GPSAltitudeRef?.value === 1 ? -altitude : altitude, }; diff --git a/src/index.ts b/src/index.ts index d237d91..1e8b631 100644 --- a/src/index.ts +++ b/src/index.ts @@ -85,7 +85,7 @@ export type { LibrarySnapshot, LibraryChange, } from "./library/records.js"; -export type { PhotoExif } from "./exif.js"; +export type { ExifTags, PhotoExif } from "./exif.js"; export { decryptCollection, decryptFile } from "./model/index.js"; export { downloadFile, downloadThumbnail } from "./download/index.js"; export type { diff --git a/src/library/read.ts b/src/library/read.ts index 3aac9ce..b676b05 100644 --- a/src/library/read.ts +++ b/src/library/read.ts @@ -13,14 +13,19 @@ // // A `Photo` also fetches its own bytes: `original()`, `thumbnail()`, // `download()`, `content()`, `exif()` and the methods that each return one -// field of `exif()` go through the on-disk content cache (issue #46), and are +// EXIF field go through the on-disk content cache (issue #46), and are // the one place in this module that may touch the network. A library opened // without a content source leaves that cache absent, and those methods then // throw. `savePath` and `isLocal` look only at the disk and need no cache. import { readFile } from "node:fs/promises"; -import { readPhotoExif, type PhotoExif } from "../exif.js"; +import { + readAllExifTags, + readPhotoExif, + type ExifTags, + type PhotoExif, +} from "../exif.js"; import type { CollectionType, EnteFile, FileType } from "../model/types.js"; import type { ContentOptions, ContentResult, PhotoContent } from "./content.js"; import type { AlbumRecord, PhotoRecord, DerivedRecords } from "./records.js"; @@ -156,74 +161,75 @@ export class Photo implements PhotoExifMethods { return readFile(path); } - // The common EXIF fields of the original, read from `content()`, so this - // may download it. EXIF is read from any image format exifreader reads, - // JPEG and HEIC/HEIF among them; any other file gives `{}`, and a video - // gives it without fetching anything. Like the other content methods, it - // throws when there is no content cache, video or not. - async exif(opts?: ContentOptions): Promise { + // Every EXIF tag of the original, keyed by name (see `ExifTags`), read + // from `content()`, so this may download it. EXIF is read from any image + // format exifreader reads, JPEG and HEIC/HEIF among them; any other file + // gives `{}`, and a video gives it without fetching anything. Like the + // other content methods, it throws when there is no content cache, video + // or not. + async exif(opts?: ContentOptions): Promise { this.cacheOrThrow(); if (this.rec.fileType === "video") return {}; - return readPhotoExif(await this.content(opts)); + return readAllExifTags(await this.content(opts)); } - // One field of `exif()` each, named and typed as in `PhotoExif`, and - // undefined when the file lacks it. Each call runs `exif()`, which reads - // the original again. + // One field each, named and typed as in `PhotoExif`, picked from the tags + // `exif()` returns, and undefined when the file lacks it. Each call runs + // `exif()`, which reads the original again. async make(opts?: ContentOptions): Promise { - return (await this.exif(opts)).make; + return readPhotoExif(await this.exif(opts)).make; } async model(opts?: ContentOptions): Promise { - return (await this.exif(opts)).model; + return readPhotoExif(await this.exif(opts)).model; } async lensModel(opts?: ContentOptions): Promise { - return (await this.exif(opts)).lensModel; + return readPhotoExif(await this.exif(opts)).lensModel; } async dateTimeOriginal( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).dateTimeOriginal; + return readPhotoExif(await this.exif(opts)).dateTimeOriginal; } async offsetTimeOriginal( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).offsetTimeOriginal; + return readPhotoExif(await this.exif(opts)).offsetTimeOriginal; } async exposureTime( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).exposureTime; + return readPhotoExif(await this.exif(opts)).exposureTime; } async fNumber(opts?: ContentOptions): Promise { - return (await this.exif(opts)).fNumber; + return readPhotoExif(await this.exif(opts)).fNumber; } async iso(opts?: ContentOptions): Promise { - return (await this.exif(opts)).iso; + return readPhotoExif(await this.exif(opts)).iso; } async focalLength( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).focalLength; + return readPhotoExif(await this.exif(opts)).focalLength; } async orientation( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).orientation; + return readPhotoExif(await this.exif(opts)).orientation; } async gpsLatitude( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).gpsLatitude; + return readPhotoExif(await this.exif(opts)).gpsLatitude; } async gpsLongitude( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).gpsLongitude; + return readPhotoExif(await this.exif(opts)).gpsLongitude; } async gpsAltitude( opts?: ContentOptions, ): Promise { - return (await this.exif(opts)).gpsAltitude; + return readPhotoExif(await this.exif(opts)).gpsAltitude; } private cacheOrThrow(): PhotoContent { diff --git a/test/cli/metadata-exif.test.ts b/test/cli/metadata-exif.test.ts index 273181c..509f1d8 100644 --- a/test/cli/metadata-exif.test.ts +++ b/test/cli/metadata-exif.test.ts @@ -3,14 +3,18 @@ * `quak backup-metadata --exif` records. * * The originals come from users' libraries, so a truncated or corrupt file - * must neither hang the read nor throw out of it: `readPhotoExif` gives `{}`, + * must neither hang the read nor throw out of it: `readAllExifTags` gives `{}`, * and `backup-metadata` tells an EXIF block it cannot read apart from a file * that simply has no EXIF, carrying the reason in `exifError`. Each JPEG below * is a short hand-built byte array; the HEIC is a real file. */ import { describe, expect, it } from "vitest"; -import { readPhotoExif } from "../../src/exif.js"; +import { + readAllExifTags, + readExifTags, + readPhotoExif, +} from "../../src/exif.js"; import { extractImageMetadata } from "../../src/metadata-backup.js"; import { HEIC_WITH_EXIF } from "../exif-heic.js"; @@ -63,6 +67,51 @@ const TIFF_ALTITUDE_WITHOUT_REF = [ ...[0x00, 0x00, 0x00, 0x19, 0x00, 0x00, 0x00, 0x02], // 25/2, at 44 ]; +// A big-endian TIFF block holding a GPSLatitude of 33° 30' 0" and a +// GPSLatitudeRef of "S". +const TIFF_SOUTHERN_LATITUDE = [ + ...[0x4d, 0x4d, 0x00, 0x2a, 0x00, 0x00, 0x00, 0x08], // the first IFD at 8 + // The first IFD, at 8: one entry, then no next IFD. + ...[0x00, 0x01], + // The GPS IFD's offset (0x8825), LONG, 26. + ...[0x88, 0x25, 0x00, 0x04, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x1a], + ...[0x00, 0x00, 0x00, 0x00], + // The GPS IFD, at 26: two entries, then no next IFD. + ...[0x00, 0x02], + // GPSLatitudeRef (0x0001), 2 ASCII bytes: "S". + ...[0x00, 0x01, 0x00, 0x02, 0x00, 0x00, 0x00, 0x02, 0x53, 0x00, 0x00, 0x00], + // GPSLatitude (0x0002), three RATIONALs at 56. + ...[0x00, 0x02, 0x00, 0x05, 0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x38], + ...[0x00, 0x00, 0x00, 0x00], + ...[0x00, 0x00, 0x00, 0x21, 0x00, 0x00, 0x00, 0x01], // 33/1, at 56 + ...[0x00, 0x00, 0x00, 0x1e, 0x00, 0x00, 0x00, 0x01], // 30/1 + ...[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01], // 0/1 +]; + +// A big-endian TIFF block holding a GPSLatitude of 40° 26' 46" and a +// GPSLongitude of 79° 58' 56", and neither GPSLatitudeRef nor GPSLongitudeRef. +const TIFF_POSITION_WITHOUT_REFS = [ + ...[0x4d, 0x4d, 0x00, 0x2a, 0x00, 0x00, 0x00, 0x08], // the first IFD at 8 + // The first IFD, at 8: one entry, then no next IFD. + ...[0x00, 0x01], + // The GPS IFD's offset (0x8825), LONG, 26. + ...[0x88, 0x25, 0x00, 0x04, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x1a], + ...[0x00, 0x00, 0x00, 0x00], + // The GPS IFD, at 26: two entries, then no next IFD. + ...[0x00, 0x02], + // GPSLatitude (0x0002), three RATIONALs at 56. + ...[0x00, 0x02, 0x00, 0x05, 0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x38], + // GPSLongitude (0x0004), three RATIONALs at 80. + ...[0x00, 0x04, 0x00, 0x05, 0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x50], + ...[0x00, 0x00, 0x00, 0x00], + ...[0x00, 0x00, 0x00, 0x28, 0x00, 0x00, 0x00, 0x01], // 40/1, at 56 + ...[0x00, 0x00, 0x00, 0x1a, 0x00, 0x00, 0x00, 0x01], // 26/1 + ...[0x00, 0x00, 0x00, 0x2e, 0x00, 0x00, 0x00, 0x01], // 46/1 + ...[0x00, 0x00, 0x00, 0x4f, 0x00, 0x00, 0x00, 0x01], // 79/1, at 80 + ...[0x00, 0x00, 0x00, 0x3a, 0x00, 0x00, 0x00, 0x01], // 58/1 + ...[0x00, 0x00, 0x00, 0x38, 0x00, 0x00, 0x00, 0x01], // 56/1 +]; + // A big-endian TIFF block holding Orientation 6 and a Make whose value lies // past the end of the file. const TIFF_MAKE_PAST_END = [ @@ -87,6 +136,27 @@ const TIFF_UNNAMED_TAG = [ ...[0x00, 0x00, 0x00, 0x00], ]; +// A big-endian TIFF block holding Orientation 6, and a thumbnail IFD holding +// its own Orientation 1 and a 4-byte JPEG thumbnail. +const TIFF_WITH_THUMBNAIL = [ + ...[0x4d, 0x4d, 0x00, 0x2a, 0x00, 0x00, 0x00, 0x08], // the first IFD at 8 + // The first IFD, at 8: one entry, then the thumbnail IFD at 26. + ...[0x00, 0x01], + // Orientation (0x0112), SHORT, 6. + ...[0x01, 0x12, 0x00, 0x03, 0x00, 0x00, 0x00, 0x01, 0x00, 0x06, 0x00, 0x00], + ...[0x00, 0x00, 0x00, 0x1a], + // The thumbnail IFD, at 26: three entries, then no next IFD. + ...[0x00, 0x03], + // Orientation (0x0112), SHORT, 1. + ...[0x01, 0x12, 0x00, 0x03, 0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00], + // JPEGInterchangeFormat (0x0201), LONG: the thumbnail is at 68. + ...[0x02, 0x01, 0x00, 0x04, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x44], + // JPEGInterchangeFormatLength (0x0202), LONG: 4 bytes. + ...[0x02, 0x02, 0x00, 0x04, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x04], + ...[0x00, 0x00, 0x00, 0x00], + ...[0xff, 0xd8, 0xff, 0xd9], // the thumbnail, at 68: an empty JPEG +]; + // An APP1 segment whose length field matches its data. const app1 = (data: number[]): number[] => { const len = data.length + 2; @@ -96,31 +166,90 @@ const app1 = (data: number[]): number[] => { const bytes = (...parts: number[][]): Uint8Array => new Uint8Array(parts.flat()); +describe("readAllExifTags", () => { + it("keys a tag exifreader has no name for by its number", () => { + const data = [...EXIF_HEADER, ...TIFF_UNNAMED_TAG]; + expect(readAllExifTags(bytes(SOI, app1(data), SOS))).toStrictEqual({ + "undefined-49152": { + id: 49152, + value: 7, + description: 7, + computed: 7, + }, + }); + }); + + it("puts the thumbnail's tags under Thumbnail, without its image", () => { + const input = bytes( + SOI, + app1([...EXIF_HEADER, ...TIFF_WITH_THUMBNAIL]), + SOS, + ); + // exifreader finds the thumbnail's image. + expect(readExifTags(input)?.Thumbnail?.type).toBe("image/jpeg"); + const tags = readAllExifTags(input); + expect(tags.Orientation?.value).toBe(6); + expect(Object.keys(tags.Thumbnail ?? {}).sort()).toEqual([ + "JPEGInterchangeFormat", + "JPEGInterchangeFormatLength", + "Orientation", + ]); + expect(tags.Thumbnail?.Orientation?.value).toBe(1); + expect(readPhotoExif(tags)).toStrictEqual({ orientation: 6 }); + }); +}); + describe("readPhotoExif", () => { it("reads the common fields of a valid JPEG", () => { const data = [...EXIF_HEADER, ...TIFF_ORIENTATION_6]; - expect(readPhotoExif(bytes(SOI, app1(data), SOS))).toStrictEqual({ + expect( + readPhotoExif(readAllExifTags(bytes(SOI, app1(data), SOS))), + ).toStrictEqual({ orientation: 6, }); }); it("gives no dateTimeOriginal for a DateTimeOriginal of 0000:00:00 00:00:00", () => { const data = [...EXIF_HEADER, ...TIFF_UNSET_DATE]; - expect(readPhotoExif(bytes(SOI, app1(data), SOS))).toStrictEqual({ + expect( + readPhotoExif(readAllExifTags(bytes(SOI, app1(data), SOS))), + ).toStrictEqual({ orientation: 6, }); }); it("reads a GPSAltitude without GPSAltitudeRef as above sea level", () => { const data = [...EXIF_HEADER, ...TIFF_ALTITUDE_WITHOUT_REF]; - expect(readPhotoExif(bytes(SOI, app1(data), SOS))).toStrictEqual({ + expect( + readPhotoExif(readAllExifTags(bytes(SOI, app1(data), SOS))), + ).toStrictEqual({ gpsAltitude: 12.5, }); }); + it("reads a GPSLatitude with GPSLatitudeRef S as south of the equator", () => { + const data = [...EXIF_HEADER, ...TIFF_SOUTHERN_LATITUDE]; + expect( + readPhotoExif(readAllExifTags(bytes(SOI, app1(data), SOS))), + ).toStrictEqual({ + gpsLatitude: -33.5, + }); + }); + + it("gives no gpsLatitude or gpsLongitude without their reference tags", () => { + const data = [...EXIF_HEADER, ...TIFF_POSITION_WITHOUT_REFS]; + const tags = readAllExifTags(bytes(SOI, app1(data), SOS)); + // The position is read; only its hemisphere is unknown. + expect(tags.GPSLatitude?.computed).toStrictEqual([40, 26, 46]); + expect(tags.GPSLongitude?.computed).toStrictEqual([79, 58, 56]); + expect(readPhotoExif(tags)).toStrictEqual({}); + }); + it("gives no make for a Make whose value lies past the end of the file", () => { const data = [...EXIF_HEADER, ...TIFF_MAKE_PAST_END]; - expect(readPhotoExif(bytes(SOI, app1(data), SOS))).toStrictEqual({ + expect( + readPhotoExif(readAllExifTags(bytes(SOI, app1(data), SOS))), + ).toStrictEqual({ orientation: 6, }); }); @@ -175,8 +304,9 @@ describe("readPhotoExif", () => { "an EXIF block that cannot be parsed", bytes(SOI, app1([...EXIF_HEADER, 0x58, 0x58]), SOS), ], - ])("returns no fields for %s", (_, input) => { - expect(readPhotoExif(input)).toStrictEqual({}); + ])("returns no tags and no fields for %s", (_, input) => { + expect(readAllExifTags(input)).toStrictEqual({}); + expect(readPhotoExif(readAllExifTags(input))).toStrictEqual({}); }); }); diff --git a/test/examples/download-albums.test.ts b/test/examples/download-albums.test.ts index 8607b03..ac130a7 100644 --- a/test/examples/download-albums.test.ts +++ b/test/examples/download-albums.test.ts @@ -29,6 +29,7 @@ import { downloadAlbums } from "../../examples/download-albums.js"; import { Library, type ContentSource } from "../../src/index.js"; import type { CollectionsPage, FilesPage } from "../../src/client.js"; import type { Collection, EnteFile } from "../../src/model/types.js"; +import { readAllExifTags } from "../../src/exif.js"; import { HEIC_WITH_EXIF } from "../exif-heic.js"; import { asLivePhoto, @@ -201,11 +202,10 @@ describe("examples/download-albums.ts", () => { Buffer.from(VIDEO), ); - // The metadata is the photo's record and its EXIF fields. The - // originals of photos 1 and 2 are not image data, so they have no - // EXIF fields. Photo 3's image holds a camera, an exposure and a - // position, and the date it was taken is written as an ISO 8601 - // string. `record` holds the fields the three records share. + // The metadata is the photo's record and its EXIF tags. The originals + // of photos 1 and 2 are not image data, so they have no EXIF tags. + // Photo 3's are every tag of its image, as `photo.exif()` returns + // them. `record` holds the fields the three records share. const record = { takenAt: TAKEN_MS, modifiedAt: TAKEN_MS, @@ -234,21 +234,7 @@ describe("examples/download-albums.ts", () => { title: "file-3.jpg", fileType: "livePhoto", hash: livePhotoHash(HEIC_WITH_EXIF, VIDEO), - exif: { - make: "Canon", - model: "EOS R5", - lensModel: "RF50mm F1.8 STM", - dateTimeOriginal: "2021-07-15T14:30:00.000Z", - offsetTimeOriginal: "+02:00", - exposureTime: 1 / 250, - fNumber: 2.8, - iso: 400, - focalLength: 50, - orientation: 6, - gpsLatitude: 40 + 26 / 60 + 46 / 3600, - gpsLongitude: -(79 + 58 / 60 + 56 / 3600), - gpsAltitude: -12.5, - }, + exif: readAllExifTags(HEIC_WITH_EXIF), }); // Each album's photos, newest first, by save path relative to `dir`. diff --git a/test/library/content-library.test.ts b/test/library/content-library.test.ts index d5976a4..a8a139f 100644 --- a/test/library/content-library.test.ts +++ b/test/library/content-library.test.ts @@ -7,7 +7,7 @@ * a cached path shows up on the projected record. A library opened without a * content source leaves those methods throwing rather than silently doing * nothing. It also covers a `Photo`'s `savePath`, `isLocal`, `download()`, - * `content()`, `exif()` and the methods that each return one field of `exif()`. + * `content()`, `exif()` and the methods that each return one EXIF field. */ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; @@ -27,7 +27,7 @@ import { Library, type LibraryOptions } from "../../src/library/index.js"; import type { ContentSource } from "../../src/library/content.js"; import type { CollectionsPage, FilesPage } from "../../src/client.js"; import type { Collection, EnteFile } from "../../src/model/types.js"; -import type { PhotoExif } from "../../src/exif.js"; +import { readPhotoExif, type PhotoExif } from "../../src/exif.js"; import { HEIC_WITH_EXIF } from "../exif-heic.js"; import { asLivePhoto, @@ -273,10 +273,10 @@ const entry = ( value: number[], ): number[] => [...u16(tag), ...u16(type), ...u32(count), ...value]; -// The TIFF block of a JPEG's EXIF segment, holding every field `exif()` picks: -// the camera in the first IFD, the exposure in the Exif IFD, and a GPS position -// of 40°26'46" N, 79°58'56" W, 12.5 m below sea level. Offsets count from the -// start of this block. +// The TIFF block of a JPEG's EXIF segment, holding every field `Photo`'s typed +// methods return: the camera in the first IFD, the exposure in the Exif IFD, +// and a GPS position of 40°26'46" N, 79°58'56" W, 12.5 m below sea level. +// Offsets count from the start of this block. const TIFF = [ ...[0x4d, 0x4d, 0x00, 0x2a], // big-endian TIFF ...u32(8), // the first IFD's offset @@ -637,9 +637,72 @@ describe("Photo save path, local copy, content and EXIF", () => { await lib.close(); }); - it("reads the common EXIF fields of a JPEG original", async () => { + // Every tag in JPEG_WITH_EXIF, by name, in the order of its IFDs. + const jpegTags = [ + "Make", + "Model", + "Orientation", + "Exif IFD Pointer", + "GPS Info IFD Pointer", + "ExposureTime", + "FNumber", + "ISOSpeedRatings", + "DateTimeOriginal", + "OffsetTimeOriginal", + "FocalLength", + "LensModel", + "GPSLatitudeRef", + "GPSLatitude", + "GPSLongitudeRef", + "GPSLongitude", + "GPSAltitudeRef", + "GPSAltitude", + ]; + // HEIC_WITH_EXIF holds those and the tags exiftool adds to every file. + const heicTags = [ + ...jpegTags, + "YCbCrPositioning", + "ExifVersion", + "ComponentsConfiguration", + "ColorSpace", + "GPSVersionID", + ]; + + it.each([ + [ + "JPEG", + JPEG_WITH_EXIF, + jpegTags, + { + "Exif IFD Pointer": { value: 88 }, + GPSLatitudeRef: { value: ["N"], description: "North latitude" }, + }, + ], + [ + "HEIC", + HEIC_WITH_EXIF, + heicTags, + { + ColorSpace: { value: 0xffff, description: "Uncalibrated" }, + ExifVersion: { description: "0232" }, + }, + ], + ])( + "returns every EXIF tag of a %s original, by name", + async (_, bytes, names, others) => { + const lib = await open({ contentSource: stubSource(bytes) }); + const exif = await lib.photos.byID({ fileID: 1 })!.exif(); + expect(Object.keys(exif).sort()).toEqual([...names].sort()); + // Tags outside the thirteen fields, as exifreader decodes them. + expect(exif).toMatchObject(others); + await lib.close(); + }, + ); + + it("picks the common EXIF fields from a JPEG original's tags", async () => { const lib = await open({ contentSource: stubSource(JPEG_WITH_EXIF) }); - expect(await lib.photos.byID({ fileID: 1 })!.exif()).toStrictEqual({ + const exif = await lib.photos.byID({ fileID: 1 })!.exif(); + expect(readPhotoExif(exif)).toStrictEqual({ make: "Canon", model: "EOS R5", lensModel: "RF50mm F1.8 STM", @@ -658,8 +721,8 @@ describe("Photo save path, local copy, content and EXIF", () => { await lib.close(); }); - // What exif() returns for HEIC_WITH_EXIF, and for JPEG_WITH_EXIF, which - // holds the same values. + // The fields picked from HEIC_WITH_EXIF's tags, and from JPEG_WITH_EXIF's, + // which hold the same values. const heicFields: PhotoExif = { make: "Canon", model: "EOS R5", @@ -676,11 +739,10 @@ describe("Photo save path, local copy, content and EXIF", () => { gpsAltitude: -12.5, }; - it("reads the same common EXIF fields from a HEIC original", async () => { + it("picks the same common EXIF fields from a HEIC original's tags", async () => { const lib = await open({ contentSource: stubSource(HEIC_WITH_EXIF) }); - expect(await lib.photos.byID({ fileID: 1 })!.exif()).toStrictEqual( - heicFields, - ); + const exif = await lib.photos.byID({ fileID: 1 })!.exif(); + expect(readPhotoExif(exif)).toStrictEqual(heicFields); await lib.close(); }); @@ -694,28 +756,27 @@ describe("Photo save path, local copy, content and EXIF", () => { client: new FilesClient([live]), contentSource: cdnSource(new Map([[1, body]])), }); - expect(await lib.photos.byID({ fileID: 1 })!.exif()).toStrictEqual( - heicFields, - ); + const exif = await lib.photos.byID({ fileID: 1 })!.exif(); + expect(readPhotoExif(exif)).toStrictEqual(heicFields); await lib.close(); }); // The build's type check, not this test, makes sure `Photo` has a method // for every `PhotoExif` field, whatever the fixtures hold: `Photo` // implements a type with one method per field. This test checks that each - // method gives the same value as exif(). + // method gives the field picked from the tags exif() returns. it.each([ ["JPEG", JPEG_WITH_EXIF], ["HEIC", HEIC_WITH_EXIF], ])( - "has a method for each field exif() returns, giving the same value, for a %s", + "has a method for each field, agreeing with the tags exif() returns, for a %s", async (_, bytes) => { const lib = await open({ contentSource: stubSource(bytes) }); const photo = lib.photos.byID({ fileID: 1 })!; - const exif = await photo.exif(); + const fields = readPhotoExif(await photo.exif()); // The file holds every field, so every method is checked. - expect(exif).toStrictEqual(heicFields); - for (const [field, value] of Object.entries(exif)) { + expect(fields).toStrictEqual(heicFields); + for (const [field, value] of Object.entries(fields)) { expect(await photo[field as keyof PhotoExif]()).toStrictEqual( value, ); @@ -724,7 +785,7 @@ describe("Photo save path, local copy, content and EXIF", () => { }, ); - it("returns no EXIF fields for an original that is not an image", async () => { + it("returns no EXIF tags for an original that is not an image", async () => { const lib = await open(); const photo = lib.photos.byID({ fileID: 1 })!; expect(await photo.exif()).toStrictEqual({}); @@ -732,7 +793,7 @@ describe("Photo save path, local copy, content and EXIF", () => { await lib.close(); }); - it("returns no EXIF fields for a JPEG whose EXIF cannot be parsed", async () => { + it("returns no EXIF tags for a JPEG whose EXIF cannot be parsed", async () => { const lib = await open({ contentSource: stubSource(JPEG_WITH_BAD_EXIF), }); @@ -753,7 +814,7 @@ describe("Photo save path, local copy, content and EXIF", () => { await lib.close(); }); - it("returns no EXIF fields for a video, without fetching it", async () => { + it("returns no EXIF tags for a video, without fetching it", async () => { const video = file(1, 1); video.metadata.fileType = "video"; const source = stubSource(JPEG_WITH_EXIF);