droboticflow/docs/capture-layout-compatibility.md

31 lines
5.2 KiB
Markdown

# Capture layout compatibility
- Flat legacy directories keep the existing filename requirements and one Run per directory. Nested files cannot satisfy root requirements. Multiple candidates for a required type block admission rather than selecting the first file.
- A direct `part[0-9]+` child selects segmented layout. Each part is an independent unit, identified by workflow + parent prefix + part. Capture names are not restricted to FYLX or a date pattern.
- Part video names must contain the actual Capture name, camera side and actual part name. Original `.mp4/.mov/.mkv` and suffixed variants such as `_silent_480p_wm.mp4` are recognized. Multiple variants block intake as ambiguous.
- Part PTS and IMU names must match the Capture and part exactly. Video-specific `<video-stem>_pts.csv` takes precedence over raw part PTS when present. Only the parent's two `<capture>_calibration_camera.yaml` / `<capture>_calibration_imu.yaml` files are shared. Audio remains optional. Metadata requirements for raw-human and v4 intake are defined below; other legacy workflows keep meta optional.
- Root sensor data plus part directories is a structural conflict. Missing/empty files block only their unit; missing shared calibration blocks all affected parts. Custom required patterns remain supported for flat layouts; for part layouts they add constraints within the selected unit, never permit cross-part matching.
- A directory reference records the parent `prefix`, explicit `objectKeys` and display `captureUnit`. Both directory reading and normalization enforce the selection, including on retry. Missing selected files fail closed. Each part's fingerprint includes only its selected files and shared calibration/meta.
- Existing admitted parent records retain their Run association and are not split/relaunched by scanning. Discarded or launching parents also prevent child admissions. No completion manifest is required; non-empty required files and the existing stability window still apply.
- Once a part has been admitted, the parent cannot later be admitted as a flat unit by moving/removing source files.
## Data-quality boundary
Filename compatibility does not prove frame correspondence. In particular, a transcoded `_silent_480p_wm.mp4` plus raw `_part0001_pts.csv` is recognized by intake but remains subject to the existing normalizer rejection when a matching transformed-video PTS/frame mapping is absent. This change must not invent timestamps or silently bypass that safety check.
### 2026-11-02: raw-human source admission
For newly launched workflows whose Orbbec normalizer uses `PROCESSING_PROFILE=raw_human`, the selected files must include exactly one nonempty `meta_<capture>.json` at the capture root. A same-name file inside a part or another capture does not satisfy this requirement. Discovery checks presence and size; launch repeats the frozen-selection check. V4's existing eight-file selection remains required independently. Already-created Runs keep their bindings and annotation history; this does not migrate or relaunch them.
The normalizer remains the authority for meta content: `streams.color_left.segments` and `streams.color_right.segments` provide the relevant camera's records; the selected record requires `index` matching the current part and a positive integer `frame_count` (legacy digit strings accepted). The count must match the actual decoded video frames and PTS rows. Optional `file` / `pts_file` identities must agree with capture, camera and part; matching must be unique. Legacy index/count-only records remain supported when that part has no explicit filename identities. No additional device, scene or business fields are invented as mandatory metadata. Existing admitted legacy inputs without meta retain their previous normalization path; present metadata is always checked.
Raw-human normalization checks IMU headers `timestamp_us,x,y,z,type`, positive timestamps, finite coordinates, monotonic timestamps, and exactly one `accel` / `gyro` pair per timestamp. Invalid types such as `gyr`, incomplete final pairs, duplicate samples and empty data fail before normalization publishes the task input. This restores content validation without the previous full-video endpoint coverage requirement: legal part boundaries can end a few milliseconds beyond the local IMU samples. Source bytes are never repaired, renamed or truncated by validation.
File completeness only permits normalization to start; it is not a content-validation certificate or permission to claim an annotation task. The source validation and claim gate must also pass. Ingestion changes require the worker and normalizer runtime image together; local tests do not update deployed operator image digests.
## Validation
Go tests cover flat/part grouping, independent identities/fingerprints, shared calibration, missing/empty/wrong-part files, duplicate videos, mixed layouts, historical-parent protection, Run binding/de-duplication and retry references. Python tests cover scope enforcement in both readers, parent calibration pairing and unchanged PTS safety.
Deploy worker, API and both directory-scan / Orbbec-normalization operator images together. Do not enable a new scanner with old operators that ignore `objectKeys`. No live deployment or business replay is performed by unit tests.