💚 End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
[docs] Focus EXIF README on usage and policy
laurenspriem3d853a43edcd
diff --git a/rust/crates/exif/README.md b/rust/crates/exif/README.mdindex 3726d53954..ef83a30920 100644--- a/rust/crates/exif/README.md+++ b/rust/crates/exif/README.md@@ -1,109 +1,37 @@# ente-exif-Reads EXIF, XMP and IPTC with bounded reads and owned results, without decoding-image pixels. Supports JPEG, TIFF, HEIF/AVIF, PNG, WebP, GIF, JPEG XL and explicitly-supplied XMP sidecars. It does not discover adjacent files or write metadata.--```rust,no_run-use ente_exif::{Limits, Mode};-use std::{fs::File, io::BufReader};--let mut file = BufReader::with_capacity(16 * 1024, File::open("photo.heic")?);-let metadata = ente_exif::read(&mut file, Mode::Summary, Limits::default())?;-if let Some(size) = metadata.display_dimensions() {- println!("display size: {} × {}", size.width, size.height);-}-println!("camera: {:?} {:?}", metadata.camera_make(), metadata.camera_model());-println!("location: {:?}", metadata.exif_location());-if let Some(date) = metadata.capture_date_time() {- println!("photo time: {}; offset: {:?}; epoch µs: {:?}; source: {:?}",- date.date_time, date.offset_time, date.timestamp_micros, date.source);-}-println!("panorama: {}", metadata.is_panorama());-if let Some(video) = metadata.motion_video {- println!("motion video: [{}..{})", video.start, video.end);-}-# Ok::<(), Box<dyn std::error::Error>>(())-```--Use `Cursor<&[u8]>` for bytes already in memory. `Summary` retains common photo-fields; `Details` adds general tags and properties. Use `read_structured()` when-nested XMP annotations need parent/list relationships.--## Photo metadata--- `display_dimensions()` applies container crops and orientation. `width()` and- `height()` return stored dimensions. Use decoder output dimensions directly- when available; do not orient them again.-- `capture_date_time()` selects a date across XMP/IPTC/EXIF and keeps local time,- embedded offset and epoch microseconds separate. Full timestamps without an- offset remain unresolved. `capture_date_time_with()` accepts application- timezone/rejection policy; `date_time(source)` reads a single source.-- Camera, lens, exposure, GPS and description helpers derive values on demand.- Location/caption source precedence and upload storage mapping belong to callers.-- `is_panorama()` recognizes GPano projections or EXIF panorama metadata.- `motion_video` gives an appended video's half-open byte range. It may include- vendor trailer bytes and does not establish playback support. Pairing separate- live-photo files belongs to the caller.--## API contracts--Dates retain local components: offsets are minutes east of UTC, capture output-normalizes them to `±HH:MM`, and epoch timestamps use microseconds. Local text-retains nanoseconds. Unknown offsets stay unknown. Partial dates normalize to-period-start midnight UTC without inventing an embedded offset; source-specific-`date_time()` preserves precision without this normalization. Epoch zero is valid.--Capture selection uses the first parseable candidate, in this order:--| Family | Sources |-| --- | --- |-| Original | XMP `exif:DateTimeOriginal`, IPTC 2:55/60, EXIF Original, XMP `photoshop:DateCreated` |-| Digitized | XMP `exif:DateTimeDigitized`, IPTC 2:62/63, EXIF Digitized, XMP `xmp:CreateDate` |-| Metadata change | XMP `xmp:MetadataDate` |-| Modified | XMP `tiff:DateTime`, EXIF Modified, XMP `xmp:ModifyDate` |--EXIF families use their own subsecond/offset tags; inline values win. Blank-auxiliary fields mean unknown; malformed values used for conversion fail.-`capture_date_time_with()` can resolve the epoch using host timezone/DST rules or-reject a candidate with `false`. An assumed offset must not replace `offset_time`.--Display size prefers container/EXIF dimensions, then a complete XMP pair.-Native transforms apply in order. Nonzero HEIF rotation or any mirror suppresses-EXIF/XMP orientation; otherwise valid EXIF wins over XMP. XMP-only sizes use XMP-orientation. JPEG XL orientation always wins. Crops must be positive, integral,-pixel-aligned and in bounds; otherwise size is `None`. Display resampling and-pixel aspect ratio are excluded. Rotations are counterclockwise quarter turns;-mirror axes are 0 = vertical, 1 = horizontal; EXIF orientations 5–8 swap axes.--GPS helpers preserve `(0, 0)` and reject invalid/incomplete coordinates. EXIF-signed D/M/S values supply the sign only when both hemisphere references are-absent; XMP requires a suffix or reference for each axis. Camera text is trimmed;-exposure is exact rational seconds, focal length is millimetres, and legacy ISO-ratings preserve the 65535 sentinel. Text decoding requires an explicit encoding;-IPTC's declared UTF-8 overrides the fallback. Raw collections retain duplicates;-`tag()`/`property()` return the first. XMP descriptions prefer the requested-language, then `x-default`, then the first value. Structured XMP parent indices-align with properties; node parents identify enclosing structures/list items.--Motion extraction chooses the largest candidate, ending at the next video or-EOF. Explicit `MotionPhoto` values other than `1` disable detection. Panorama-means GPano cylindrical/equirectangular projection or EXIF `CustomRendered = 6`.--## Limits--`Limits::default()` bounds logical reads to 8 MiB, individual values to 64 KiB,-retained metadata accounting to 512 KiB, entries to 16,384, TIFF directories to-64 per block and nesting to 32. Expanded text has a separate cumulative budget-equal to the read limit. These account for parser work, not exact process memory.--I/O errors and exhausted budgets stop parsing. Recoverable malformed metadata-appears in `issues`; inspect it before treating a result as complete.--BigTIFF, manufacturer MakerNotes, non-TIFF RAW adapters and metadata writing are-unsupported. JPEG scanning ends at the first image scan. PNG CRCs and extended-XMP-GUID digests are not authenticated. Structured XMP is not a complete RDF graph-or a typed face-region API.+Reads EXIF, XMP and IPTC metadata without decoding image pixels. XMP sidecars must+be supplied explicitly; the crate does not discover adjacent files or write+metadata.++## Intended usage and policy++- Use decoder output dimensions directly when available; do not apply metadata+ orientation to them again.+- Callers choose location and caption source precedence, upload storage mapping,+ and how to pair separate live-photo files.+- Extracted motion-video byte ranges may include vendor trailer bytes. Finding a+ range does not establish playback support.+- Keep local capture time, embedded timezone offset and resolved epoch separate.+ Unknown offsets remain unknown. Applications may resolve local times using+ their timezone and daylight-saving rules, or reject a capture-date candidate.+ An assumed offset must not replace the embedded offset.+- Capture-date selection normalizes partial dates to the start of their period at+ midnight UTC without inventing an embedded offset. Reading an individual date+ source preserves its precision without this normalization.+- Choose a fallback text encoding explicitly when metadata does not declare one.++## Limitations++Read, decompression and retention budgets constrain parser work, not exact+process memory. I/O errors and exhausted budgets stop parsing. Recoverable+malformed metadata is reported separately; inspect reported issues before+treating a result as complete.++BigTIFF, manufacturer MakerNotes and non-TIFF RAW adapters are unsupported. JPEG+scanning ends at the first image scan. PNG CRCs and extended-XMP GUID digests are+not authenticated. Structured XMP is not a complete RDF graph or a typed+face-region API.## Development