Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-exif

Source of release 0.1.1

0.1.1 / README.md

# luce-exif

Photo metadata for Luce and Luce Base. It reads what a photo library shows and sorts
by: the camera and lens, when the picture was taken, how it was exposed, where it was
taken, the orientation and size, and the rating and color label an editor stored in
XMP. Fujifilm files also report their film simulation. It is written in pure Luce
Base with no platform libraries.

```luce
from luce_exif import exif
from luce_std import files

let m = exif.read(files.read(path))     # a Luce value; its texts are its own
print(f"{m.make} {m.model}, {m.lens}: {m.shutter} f/{m.f_number} ISO {m.iso}")
print(f"taken {m.captured}{m.offset}, rated {m.rating}")
```

From Base, `read` returns an `interop.Owned[Metadata]`. Read `.value`, then call
`release()` when you are done with it.

## API (module `luce_exif.exif`)

`read(data: const u8[]) -> interop.Owned[Metadata]!`: the metadata of the file
`data`. It fails with `exif.unrecognized` when the bytes are not a supported
container, and with `exif.truncated` when the file ends before its first metadata
directory. Anything damaged after that point is skipped, and the affected fields
keep their zero values. Every offset is checked, so no input can make it trap
(`tests/fuzz.py`).

`Metadata`. Texts are `""` and numbers `0` when the file does not say:

| field | meaning |
| --- | --- |
| `format` | `"DNG"`, `"TIFF"`, `"NEF"`, `"ARW"`, `"CR2"`, `"CR3"`, `"ORF"`, `"RW2"`, `"PEF"`, `"RAF"`, `"JPEG"`, `"HEIF"`, `"AVIF"`, `"PNG"` |
| `make`, `model` | as the camera writes them, trimmed |
| `lens` | LensModel; otherwise built from the lens's range (DNG LensInfo, EXIF LensSpecification): `"35mm f/1.4"`, `"18-55mm f/2.8-4"` |
| `serial`, `software` | BodySerialNumber (or DNG CameraSerialNumber), Software |
| `captured` | `"YYYY-MM-DDTHH:MM:SS"`, local time, from DateTimeOriginal, else DateTimeDigitized, else DateTime |
| `subseconds`, `offset` | SubSecTimeOriginal digits; OffsetTimeOriginal `"+02:00"` (or OffsetTime) |
| `captured_unix` | seconds since 1970 UTC when the offset is known, otherwise the local time read as UTC; 0 without a date |
| `exposure_time`, `shutter` | seconds, and `"1/250"`, `"0.3s"`, `"30s"` |
| `f_number`, `iso`, `exposure_bias`, `focal_length`, `focal_length_35` | as EXIF states them; APEX values stand in for a missing exposure time or f-number |
| `flash` | whether the flash fired |
| `metering`, `exposure_program` | the EXIF codes (`5` multi-segment, `3` aperture priority, ...) |
| `orientation` | 1–8, defaulting to 1 |
| `width`, `height` | the main image's size: a DNG's default crop, a RAF's cropped raw size, a JPEG's frame, otherwise the largest full-resolution directory or PixelX/YDimension |
| `has_gps`, `latitude`, `longitude`, `altitude` | signed degrees and metres; a GPS directory without a fix (void status, no hemisphere, 0/0) does not count |
| `rating`, `label` | XMP `xmp:Rating` (−1 rejected, 0–5) and `xmp:Label` (also IFD0 Rating) |
| `film_simulation` | Fujifilm's menu name: `"Classic Chrome"`, `"Acros+R Filter"`, `"Provia/Standard"`, ... |

## Containers

| container | where the metadata is |
| --- | --- |
| TIFF and TIFF raws (DNG, NEF, ARW, CR2, PEF, ORF, RW2, TIFF) | the TIFF stream from byte 0; IFD0, its chain and SubIFDs; the EXIF and GPS directories; RW2's embedded JpgFromRaw |
| JPEG | the APP1 `Exif` segment and the APP1 XMP packet; the frame header for the size |
| Fujifilm RAF | the embedded JPEG's EXIF and maker note; the RAF header's model and the RAF directory's raw size |
| Canon CR3 | Canon's uuid box in `moov`: CMT1 (IFD0), CMT2 (EXIF), CMT4 (GPS); the XMP uuid box |
| HEIF / HEIC / AVIF | the `Exif` item and an `application/rdf+xml` mime item, located by `meta/iinf` and `meta/iloc` (construction method 0, first extent) |
| PNG | the `eXIf` chunk and the `XML:com.adobe.xmp` iTXt chunk (uncompressed) |

Not read yet:
- maker notes other than Fujifilm's, so no lens name from Canon, Nikon or Sony maker
  notes when the EXIF LensModel is missing;
- XMP that writes the `xmp` namespace under another prefix, or compressed PNG iTXt;
- HEIF items split over several extents or stored in `idat`;
- Sigma X3F, Canon CRW and other non-TIFF legacy raws.

## Tests

```sh
./test.sh                    # module tests, fixtures, the Luce crossing; native and C
tools/fetch_exiftool.sh      # optional: ExifTool into build/, for the sample comparison
```

`tests/run.py` runs the module's own tests: hand-built TIFF and JPEG files, every
truncation and byte flip of a TIFF, and the date, shutter and lens texts. It
compares the dump of `tests/fixtures` (a JPEG, PNG and HEIC made by
`tools/make_fixtures.py`) with `expected.txt`, and builds a Luce program that reads
a fixture. When ExifTool and luce-raw's camera samples are present, it also checks
every sample against ExifTool: make, model, lens, serial, date, offset, subseconds,
exposure time, f-number, ISO, focal lengths, orientation, GPS, rating and film
simulation. That covers 32 samples: Leica M240 DNG, five Fujifilm RAFs (X-Trans
and Bayer, GFX), Canon CR2/CR3, Nikon, Sony, Olympus, Panasonic, Pentax, and
iPhone/Pixel DNGs. `tests/fuzz.py DUMP` mutates their metadata heads and requires
that nothing traps.

Licensed MIT or Apache-2.0, at your option.