- name
- source-observe
- description
- Use when cataloging or annotating visible construction in photographs or scan RGB, especially before registration or while the base model may be replaced.
Build a bounded, source-linked inventory that remains useful without a house coordinate system. Read [source-observations.md](../../references/source-observations.md) for the observation, identity, endpoint and placement records. Apply [model selection](../../references/work-packets.md#model-selection), including actual image capability for visual review.
1. Select a coherent photographic scope and inspect the original images. Preserve source bytes, extraction provenance and the mapping between displayed and native pixels.
For native capture frames, derive ordinals programmatically from the declared source inventory and record the index basis; for Polycam use `polycam.capture_inventory(root)["frame_ids"]`. Verify each immutable frame ID to native ordinal mapping. Keep contact-sheet/display positions separate, and never copy native ordinals from narrative or contact labels.
For stills derived from video, bind each output to the frame actually written: record its presentation timestamp, time base, decoded-frame index and exact native pixel/crop mapping. A decoder or filter may log read-ahead frames that never become output, so do not select the last logged `showinfo` entry as the output frame. Prefer a direct output-index/PTS binding and verify it against an independently known extraction. In a one-output pipeline with no downstream frame selection, dropping or timestamp changes, the first emitted `showinfo n=0` record is the relevant binding; this rule does not generalize to arbitrary filter graphs.
2. Record visible member faces, pipe/cable spans, boxes, fittings and candidate hardware as individually identified observations. Separate visible facts, tentative classification, endpoint meaning and present-day survival.
3. Produce annotated source sheets from the stored pixel marks. Use [`scripts/observations.py`](../../scripts/observations.py) when the source is a standalone JPEG or PNG and the record matches the documented contract; add `--coordinate-inspections` when exact authored pixels need enlarged review. Treat the whole-source sheet as orientation and context, then open each generated native-scale assertion crop and confirm the full mark lies on the claimed construction. Use the optional unmarked/located coordinate sheet to check exact vertices without treating it as physical classification. Verify its generated display coordinates equal the original review picks; round-tripping an upright pick that was already recorded as native proves only internal consistency. For every polyline endpoint, inspect its dedicated crop and check that the authored endpoint kind and basis match the visible transition. A plausible overview or valid coordinate transform is not this review.
4. Record the checked assertion-crop path and hash, mark status and finding, plus every endpoint-crop path/hash, checked status, kind and finding. Finalizers may bind explicit per-mark and per-endpoint image-review decisions; never synthesize `checked`/`accepted` statuses or findings from author labels, successful rendering, coordinate replay or uniform auto-pass loops. Keep the observation pending when the feature or transition is ambiguous. Correct misplaced marks, downgrade unsupported endpoint meanings to `unknown` or `annotation boundary`, regenerate into a fresh directory and repeat review before using the observation to support identity or geometry.
5. Link observations to a bounded physical feature or group only with stated correspondence evidence. Record construction-state differences and occlusions alongside matches; assess capture chronology and current survival separately. Keep later depth measurements, registrations and candidate placements in separately referenced records.
A useful inventory can have no depth, no physical dimensions and no accepted placement. Continue supported observation work while those questions remain open. Use `depth-inspect`, `scan-register` and `blender-reconstruct` when advancing to their respective evidence stages.
View on GitHub