lightcraft/docs/focus-points.md

Focus points

Most cameras record where they focused. LightCraft reads that point from the file, draws it over the photo and zooms to it, so checking whether the subject is sharp takes one key while culling. Lightroom shows no focus points (photographers add plug-ins for it); this goes beyond parity (tracker row LR-VIEW-FOCUSPOINT).

Using it

• View ▸ Show Focus Point (⌥F; view.focusPoint {on?}) draws the camera's AF frame as green corner brackets in Detail, Compare and Survey. It follows Rotate, flips and the crop; a point cropped away is not drawn. Off by default; the choice is saved with the app's settings.
• View ▸ Zoom to Focus Point (view.zoomToFocus {on?}, on by default): Toggle Zoom (Z or Space) zooms in centred on the focus point instead of the last position. A click on the photo still zooms where you click, and a photo without a focus point zooms as before. On by default because it changes nothing for photos without a point, and for those with one the focus point is what a 1:1 check is for. In Compare the two panes share one pan, so Z centres on the active photo's point; per-pane focus zoom is a follow-up.
• Info panel: a Focus row says how the camera focused, e.g. AF-C · Wide · Animal Eye Tracking (focus mode, the AF area set on the camera, and what it tracked when the camera says).
• Agents: photo.inspect (and the MCP lightcraft://photo/active resource) returns it as meta.focus: {rect: {x0, y0, x1, y1}, mode?, area?, tracking?}, the box normalized to the upright (EXIF-oriented) photo, y down. Photos without one have no focus key. view.zoomToggle replies {focus: [x, y]} (the pan it centred on) when it zoomed to one.

The point is read when a photo is imported. Photos imported earlier get it in the background (below). It is read-only camera data: never written to XMP, and absent from the catalog JSON when unknown, so older catalogs read unchanged (no catalog format change).

Photos imported earlier

A library imported before focus points were read gets them by itself: when a library opens and some of its photos from a supported body have no point and haven't been looked at, LightCraft reads them in the background, with a Reading focus points row in the activity stack (n of N; ✕ stops it). Photo ▸ Read Focus Points (photo.readFocusPoints) starts the same job by hand. Photo ▸ Reload from Disk still fills a missing point too, but it re-reads and hashes whole files and runs while you wait, so it is for a few photos, not a library.

• What is opened: only photos whose stored camera is a supported body (SONY ILCE-1, SONY ILCE-7SM3), whose file is an ARW or JPEG, that are in the library and have no point yet. Nothing else is opened.
• What is read: the few kilobytes that hold the focus data, not the file (lightcraft_meta::focus::read_header). It walks the file's structure as the decoder does — the TIFF header and IFD0 (Make, Model), the Exif IFD (the MakerNote entry), the maker note's IFD and the values of the focus tags; in a JPEG, the segments up to the Exif one — asking only for the ranges the bytes read so far point at, and decodes them with the same code as a whole-file read. On the α1 and the A7S III everything sits in the first 16 KB, so one 32 KB read per photo does it (instead of 50–120 MB). Rounds (12), bytes (2 MB) and the file size are bounded; a file that wants more is treated as having no point. On 109 real α1 / A7S III ARWs (83 with a point) the header read gave the same point as the whole-file read for every file.
• Pace: one file at a time on one worker thread (the drive may be a spinning disk), in path order so neighbouring files are read together. Nothing new is read while you drag, type or scroll, and it rests briefly between files while you are around, so your own previews come first. Measured on a 5400 rpm USB drive, cold cache, 200 α1 / A7S III ARWs: 1.9 s (about 100 photos a second, 32 KB each), so a library of 58,796 raws takes about ten minutes at full pace instead of re-reading 2.25 TB.
• Saving: what was read is committed every 200 photos (or every 3 seconds) as LightCraft's own bookkeeping: no undo step, no sidecar written, and only meta.focus changes, on a photo that still has none and still points at the file that was read (a photo deleted, moved or relinked meanwhile is left for another run). Photos that turned out to have no point (manual focus, a centre-only Wide report) are listed in focus-scanned.bin beside the library, so they are not read again at every launch. The list is headed by the decoder's tag (the bodies it knows): when a body is added, the list starts afresh and those photos are looked at again. A file that can't be read (an offline drive, a file gone or replaced during the read) is not listed, and is tried again the next time the library opens.
• Resuming: quitting mid-run keeps what was committed; the next launch reads the rest.
• Agents: photo.readFocusPoints {ids?, wait?} — without ids, every photo not looked at yet; with ids, those photos, looked at again even if listed. wait: true returns when done with {last: {total, done, found, none, unavailable, bytesRead, seconds, cancelled}} (lightcraft-cli run --library DIR photo.readFocusPoints wait=true). The app's frame loop calls focus.pump {pace}, which also starts the job once per library opening.

Cameras

Sony first, on bodies whose files have been checked: ILCE-1 (α1) and ILCE-7SM3 (A7S III) (lightcraft_meta::focus::SONY_MODELS). Other Sony bodies store the same tags, but a body is added only after its files are checked, so an unchecked one shows nothing rather than a misleading box. Fujifilm, Canon, Nikon, OM System and Panasonic record similar data and are later steps.

Sony layout and evidence

Tag identities and value names come from the public ExifTool tag-name documentation (Sony MakerNotes table). No third-party code was read or ported. Every field was confirmed on real files by comparing LightCraft's decoder with ExifTool's output, run as a black box: 333 ARWs sampled across four years of a photographer's library (180 α1, 153 A7S III; 12 portrait or upside-down, 54 in APS-C crop or reduced-size modes), with no mismatch in the point, frame or names.

MakerNote tag	Layout	Notes
0x2027 FocusLocation	4 × int16u: frame width, frame height, focus x, focus y	in the sensor's landscape frame (a portrait shot still says 8640 × 5760); the frame is the image size (5616 × 3744 in α1 APS-C mode)
0x2037 FocusFrameSize	6 bytes: int16u width, int16u height, then 2 bytes that are zero when no frame was shown	zero in manual focus; one AF-C α1 file had no frame (a small box is drawn: 3 % of the short side)
0x201b FocusMode	int8u: 0 Manual, 2 AF-S, 3 AF-C, 4 AF-A, 6 DMF, 7 AF-D
0x201c AFAreaModeSetting	int8u: 0 Wide, 1 Center, 3 Flexible Spot, 11 Zone, 12 Expanded Flexible Spot, 13 Custom AF Area
0x2021 AFTracking	int8u: 0 Off, 1 Face tracking, 2 Lock On AF
0x9402 bytes 0x16 / 0x17	enciphered: focus mode (low 7 bits) and the AF area mode used (0 Multi, 2 Spot, 3 Flexible Spot, 11 Zone, 14 Tracking, 15 Face Tracking, 20 Animal Eye Tracking, 21 Human Eye Tracking, 255 Manual…)	read only when its focus mode equals 0x201b's

The documentation says the 0x94xx blocks use "a simple substitution cipher". On the files each byte p < 249 is stored as p³ mod 249 (bytes 249–255 unchanged): ExifTool's decoded AFAreaMode 20 is stored as 0x20, a decoded 0x83 as 0x77. Cubing is a bijection modulo 249 (= 3 × 83), so the inverse is a table lookup.

On the α1 files the box sits on the subject: drawn on the embedded previews, it lands on the bird's eye in eye-AF shots and follows spot, zone, wide and tracking shots, in portrait and landscape.

When there is no real point

Nothing is stored (so nothing is drawn and Z zooms as before) when:

• the body is not one of the checked ones, the tags are missing or malformed, the frame size is zero, or the centre lies outside its frame;
• manual focus (0x201b = 0, or the block's area mode is Manual). The camera still records where the AF frame was parked: 83 of the 91 sampled manual-focus files carry an off-centre location that says nothing about focus;
• the location is the exact frame centre while the area used was Multi (Wide with nothing tracked; without the block, Wide with tracking off). The wide area reports the centre when it picked no particular spot; 7 of the 34 sampled autofocus Multi files did. A centred Spot, Zone or Flexible Spot frame is a choice the photographer made, and is kept (49 of the 111 sampled spot and zone files were centred, the camera's default position).

DMF (AF, then manual touch-up) keeps its point.

Code

• crates/meta/src/focus.rs: the decoder (bounded; hostile values give no point, never a panic) and its tests, including an opt-in test over real files (LIGHTCRAFT_FOCUS_SAMPLES=<photo folder>).
• crates/meta/src/focus_read.rs: the header-only read; its tests check it against the whole-file read on intact, truncated and corrupted files and count what it reads.
• crates/engine/src/focus_scan.rs: the background job (photo.readFocusPoints, focus.pump) and crates/engine/src/tests_focus_scan.rs, with an opt-in comparison over real files (LIGHTCRAFT_FOCUS_FILES=<a list of paths>); crates/ui-egui/src/focus_scan.rs drives it from the frame loop.
• crates/ui-egui/src/panels/detail.rs (focus_box, focus_pan, draw_focus_point): mapping through the user's rotation and crop, the overlay, and the zoom target; crates/ui-egui/src/tests_focus_point.rs.