Access per-photo quality codes not in the centroid layer (tilt, crab, overlap)

[NewGraphEnvironment]

Corrected 2026-08-29. The premise below was wrong. This issue was filed on the
belief that the centroid layer exposes only nine simplified fields, and proposed OCR
of scanned flight-log PDFs or a bulk provincial data request to recover focal length
and flying height. Both fields are in fact already in the layer and fully populated.
The expensive approaches are not needed for them. Scope reduced and retitled; the
original framing is kept below so the reasoning is auditable.

What is actually in the centroid layer

Measured on 680 centroids in southeast BC (#30), and confirmed against the 20-photo
bundled test data in this repo:

Field	Populated	Note
FOCAL_LENGTH	680/680	153 / 305 mm film, 92 / 100 mm digital
FLYING_HEIGHT	680/680	metres
SCALE	680/680	string, "1:15000". Not PHOTO_SCALE, which returns all NULL
GROUND_SAMPLE_DISTANCE	560/680	digital only; absent on film
MEDIA	680/680	film vs digital
camera_calibration_url	sparse	NA across the 1968 film sample
patb_georef_url	sparse	NA across the 1968 film sample

The last two are columns this issue did not know about. camera_calibration_url is the
natural route to camera type and recording format, and fly_fetch(type = "calibration")
already downloads it.

What that closes

• Focal length — available, no PDF parsing required
• Flying height per flight line — available; combined with focal length this gives
  true scale at terrain rather than reported nominal scale
• Negative / sensor format — not solved by the above, but moved to Establish sensor dimensions for digital frames and ship them as a camera format table #32, which uses
  camera_calibration_url and the pixel_pitch = GSD / scale identification lever
  rather than OCR. v0.4.0 already ships the format_size slot the answer drops into
• Flight line azimuth — fly_bearing() computes bearing from consecutive centroids
  per roll, which has served as a working proxy since v0.3.0

What is genuinely still missing

These are Type 04 per-photo codes with no counterpart in the centroid layer, so the
original approaches still apply to them:

• Tilt / crab / verticality codes — needed for the terrain work in DEM-based terrain-adjusted footprints #9
• Scale-off code
• Forward overlap code — the database already flags substandard overlap, which
  would be useful validation for fly_overlap()

Whether these justify PDF parsing or a bulk data request is now a much smaller question
than the one this issue was filed to ask, because the two fields that motivated it are
no longer in question.

Acceptance criteria

• Establish which fields the centroid layer actually exposes (fly_footprint() assumes a 9-inch negative, but 20% of catalogue frames are digital #30)
• Decide whether tilt / crab / overlap codes are worth pursuing at all, given DEM-based terrain-adjusted footprints #9 can
  begin without them
• If yes: assess flight-log PDF structure and parseability for those codes only
• If viable, create a helper to enrich centroid data with the missing codes

Reference

• BC Air Photo Database Specs (PDF)
• newgraphiti blog post
• bcdata record: WHSE_IMAGERY_AND_BASE_MAPS.AIMG_PHOTO_CENTROIDS_SP

Relates to #9 — DEM-based terrain-adjusted footprints, now unblocked for focal length
and flying height
Relates to #32 — sensor widths, which took over the recording-format half of this issue

---

Original issue body as filed 2026-03-05 (premise since disproved)

Context

The BC Air Photo Database spec (April 2008, CRGB) defines rich per-roll and per-flight-line metadata:

• Type 02 (Roll): camera focal length code, film emulsion code
• Type 03 (Line): average flying height (m), requested flying height (m), flight line azimuth
• Type 04 (Photo): tilt/crab/verticality codes, scale-off code, forward overlap code

However, the centroid layer available from BC Data Catalogue (AIMG_PHOTO_CENTROIDS_SP) only exposes simplified fields: airp_id, photo_year, photo_date, scale, film_roll, frame_number, media, photo_tag, nts_tile.

What IS available programmatically

The centroid layer has two URL columns not currently used by fly:

• thumbnail_image_url — photo thumbnails at openmaps.gov.bc.ca/thumbs/
• flight_log_url — flight log PDFs at openmaps.gov.bc.ca/thumbs/logbooks/

The flight log PDFs likely contain camera type, focal length, negative format, flying height, and other metadata from the full database spec. These are grouped by roll, so one PDF covers many photos.

Potential approaches

1. Parse flight log PDFs — download unique flight_log_url values, extract text (many may be scanned so OCR needed), pull camera/focal length/flying height per roll. Join back to centroids by film_roll.

2. Request bulk database export — the province may provide the full Air Photo System database (or relevant tables) as a data release or FOI request. This would give machine-readable access to all Type 01-04 fields.

3. WIMSI web scraping — the Web Imagery Search Interface may expose additional fields per photo not available in the WFS layer.

What this unlocks

• Accurate negative size — confirm 9x9 or identify non-standard formats per roll (currently hardcoded as default)
• Flying height per flight line — combined with focal length, gives true scale at terrain rather than reported nominal scale
• Tilt/crab angles — for future terrain-adjusted footprints (issue DEM-based terrain-adjusted footprints #9)
• Forward overlap codes — the database already flags substandard overlap, useful for fly_overlap() validation

Acceptance criteria

• Investigate flight log PDF structure and parseability
• Prototype extraction of focal length and flying height from a sample of flight log PDFs
• Evaluate which approach (PDF parsing vs bulk data request) is viable
• If viable, create helper to enrich centroid data with flight metadata