ponolock 0.3.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ponolock/__init__.py +93 -0
- ponolock/_docs/README.md +13 -0
- ponolock/_docs/africadrive_and_redundancy.md +101 -0
- ponolock/_docs/africadrive_integration_note.md +71 -0
- ponolock/_docs/africadrive_integration_prompt.md +149 -0
- ponolock/_docs/api.md +118 -0
- ponolock/_docs/architecture.md +40 -0
- ponolock/_docs/benchmarks/2026-11-18-linux-2vcpu.json +1239 -0
- ponolock/_docs/benchmarks.md +92 -0
- ponolock/_docs/configuration.md +104 -0
- ponolock/_docs/development/plan-0.3.md +81 -0
- ponolock/_docs/embedding.md +117 -0
- ponolock/_docs/gnss.md +90 -0
- ponolock/_docs/hardware_validation.md +114 -0
- ponolock/_docs/headless.md +69 -0
- ponolock/_docs/implementation_jobs.md +22 -0
- ponolock/_docs/installation.md +62 -0
- ponolock/_docs/lifecycle.md +104 -0
- ponolock/_docs/live_gnss_map.md +44 -0
- ponolock/_docs/local_database.md +27 -0
- ponolock/_docs/media_pipeline.md +77 -0
- ponolock/_docs/migration.md +45 -0
- ponolock/_docs/operations.md +89 -0
- ponolock/_docs/operator-tools.md +92 -0
- ponolock/_docs/physical_acceptance.md +99 -0
- ponolock/_docs/plugin_development.md +35 -0
- ponolock/_docs/quickstart.md +64 -0
- ponolock/_docs/release.md +67 -0
- ponolock/_docs/session_format.md +126 -0
- ponolock/_docs/studio_api.md +29 -0
- ponolock/_docs/synchronization.md +48 -0
- ponolock/_docs/timestamps.md +78 -0
- ponolock/_docs/troubleshooting.md +58 -0
- ponolock/_docs/verification.md +57 -0
- ponolock/_version.py +3 -0
- ponolock/api/__init__.py +1 -0
- ponolock/api/app.py +427 -0
- ponolock/api/launch.py +78 -0
- ponolock/api/media.py +206 -0
- ponolock/api/research.py +184 -0
- ponolock/api/runtime.py +89 -0
- ponolock/auth/__init__.py +3 -0
- ponolock/auth/accounts.py +177 -0
- ponolock/benchmarks/__init__.py +3 -0
- ponolock/benchmarks/recording.py +318 -0
- ponolock/benchmarks/synthetic.py +399 -0
- ponolock/cli.py +518 -0
- ponolock/clock/__init__.py +5 -0
- ponolock/clock/models.py +185 -0
- ponolock/config.py +26 -0
- ponolock/documentation.py +47 -0
- ponolock/errors.py +66 -0
- ponolock/metrics/__init__.py +29 -0
- ponolock/metrics/quality.py +35 -0
- ponolock/metrics/resources.py +40 -0
- ponolock/models.py +90 -0
- ponolock/plugins/__init__.py +36 -0
- ponolock/preflight.py +256 -0
- ponolock/profiles.py +110 -0
- ponolock/progress.py +120 -0
- ponolock/py.typed +0 -0
- ponolock/recording/__init__.py +3 -0
- ponolock/recording/inspection.py +312 -0
- ponolock/recording/lifecycle.py +174 -0
- ponolock/recording/mkv.py +118 -0
- ponolock/recording/playback.py +175 -0
- ponolock/recording/preview.py +196 -0
- ponolock/recording/recorder.py +1083 -0
- ponolock/recording/verification.py +342 -0
- ponolock/recording/writer.py +367 -0
- ponolock/reporting.py +82 -0
- ponolock/sources/__init__.py +6 -0
- ponolock/sources/base.py +22 -0
- ponolock/sources/camera.py +224 -0
- ponolock/sources/discovery.py +301 -0
- ponolock/sources/ffmpeg_probe.py +161 -0
- ponolock/sources/gnss.py +405 -0
- ponolock/sources/identity.py +79 -0
- ponolock/sources/simulated.py +108 -0
- ponolock/status.py +99 -0
- ponolock/storage/__init__.py +3 -0
- ponolock/storage/database.py +132 -0
- ponolock/storage/importer.py +124 -0
- ponolock/storage/session.py +215 -0
- ponolock/studio/static/assets/mark.svg +1 -0
- ponolock/studio/static/css/studio.css +31 -0
- ponolock/studio/static/js/api.js +16 -0
- ponolock/studio/static/js/app.js +142 -0
- ponolock/studio/static/js/gnss-map-core.js +45 -0
- ponolock/studio/static/js/gnss-map.js +78 -0
- ponolock/studio/static/js/media.js +288 -0
- ponolock/studio/static/js/research.js +79 -0
- ponolock/studio/static/js/ui.js +72 -0
- ponolock/studio/static/js/views.js +157 -0
- ponolock/studio/static/vendor/leaflet/LICENSE +26 -0
- ponolock/studio/static/vendor/leaflet/images/layers-2x.png +0 -0
- ponolock/studio/static/vendor/leaflet/images/layers.png +0 -0
- ponolock/studio/static/vendor/leaflet/leaflet.css +661 -0
- ponolock/studio/static/vendor/leaflet/leaflet.js +6 -0
- ponolock/studio/templates/index.html +33 -0
- ponolock/sync/__init__.py +20 -0
- ponolock/sync/association.py +212 -0
- ponolock/sync/diagnostics.py +185 -0
- ponolock/sync/interpolation.py +64 -0
- ponolock/sync/registry.py +44 -0
- ponolock/timing.py +160 -0
- ponolock-0.3.1.dist-info/METADATA +181 -0
- ponolock-0.3.1.dist-info/RECORD +111 -0
- ponolock-0.3.1.dist-info/WHEEL +4 -0
- ponolock-0.3.1.dist-info/entry_points.txt +7 -0
- ponolock-0.3.1.dist-info/licenses/LICENSE +21 -0
ponolock/__init__.py
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
"""PonoLock: dependable multicamera and GNSS recording with explicit timing evidence.
|
|
2
|
+
|
|
3
|
+
The public API is everything listed in ``__all__``. Importing ``ponolock`` loads only the
|
|
4
|
+
standard library and Pydantic; camera, serial and Studio backends load on demand.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from ponolock._version import __version__
|
|
10
|
+
from ponolock.errors import (
|
|
11
|
+
ConfigurationError,
|
|
12
|
+
DeviceIdentityError,
|
|
13
|
+
LifecycleError,
|
|
14
|
+
PonoLockError,
|
|
15
|
+
PreflightError,
|
|
16
|
+
SessionFormatError,
|
|
17
|
+
ShutdownTimeoutError,
|
|
18
|
+
SourceError,
|
|
19
|
+
WriterError,
|
|
20
|
+
)
|
|
21
|
+
from ponolock.models import Observation, SensorConfig, Timestamp
|
|
22
|
+
from ponolock.recording import Recorder
|
|
23
|
+
from ponolock.recording.lifecycle import EventSubscription, RecorderState, RecordingOptions
|
|
24
|
+
from ponolock.storage import Session, load_session
|
|
25
|
+
|
|
26
|
+
_LAZY = {
|
|
27
|
+
"RecordingProfile": "ponolock.profiles",
|
|
28
|
+
"load_profile": "ponolock.profiles",
|
|
29
|
+
"save_profile": "ponolock.profiles",
|
|
30
|
+
"setup_profile": "ponolock.profiles",
|
|
31
|
+
"ProgressEvent": "ponolock.progress",
|
|
32
|
+
"generate_report": "ponolock.reporting",
|
|
33
|
+
"DeviceInfo": "ponolock.sources.discovery",
|
|
34
|
+
"list_cameras": "ponolock.sources.discovery",
|
|
35
|
+
"list_serial_ports": "ponolock.sources.discovery",
|
|
36
|
+
"list_devices": "ponolock.sources.discovery",
|
|
37
|
+
"probe_camera": "ponolock.sources.discovery",
|
|
38
|
+
"verify_session": "ponolock.recording.verification",
|
|
39
|
+
"inspect_session": "ponolock.recording.inspection",
|
|
40
|
+
"recover_session": "ponolock.recording.inspection",
|
|
41
|
+
"PreflightReport": "ponolock.preflight",
|
|
42
|
+
"RecorderStatus": "ponolock.status",
|
|
43
|
+
"SourceStatus": "ponolock.status",
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def __getattr__(name: str) -> Any:
|
|
48
|
+
module = _LAZY.get(name)
|
|
49
|
+
if module is None:
|
|
50
|
+
raise AttributeError(f"module 'ponolock' has no attribute {name!r}")
|
|
51
|
+
import importlib
|
|
52
|
+
|
|
53
|
+
return getattr(importlib.import_module(module), name)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
__all__ = [
|
|
57
|
+
"RecordingProfile",
|
|
58
|
+
"load_profile",
|
|
59
|
+
"save_profile",
|
|
60
|
+
"setup_profile",
|
|
61
|
+
"ProgressEvent",
|
|
62
|
+
"generate_report",
|
|
63
|
+
"ConfigurationError",
|
|
64
|
+
"DeviceIdentityError",
|
|
65
|
+
"DeviceInfo",
|
|
66
|
+
"EventSubscription",
|
|
67
|
+
"LifecycleError",
|
|
68
|
+
"Observation",
|
|
69
|
+
"PonoLockError",
|
|
70
|
+
"PreflightError",
|
|
71
|
+
"PreflightReport",
|
|
72
|
+
"Recorder",
|
|
73
|
+
"RecorderState",
|
|
74
|
+
"RecorderStatus",
|
|
75
|
+
"RecordingOptions",
|
|
76
|
+
"SensorConfig",
|
|
77
|
+
"Session",
|
|
78
|
+
"SessionFormatError",
|
|
79
|
+
"ShutdownTimeoutError",
|
|
80
|
+
"SourceError",
|
|
81
|
+
"SourceStatus",
|
|
82
|
+
"Timestamp",
|
|
83
|
+
"WriterError",
|
|
84
|
+
"__version__",
|
|
85
|
+
"inspect_session",
|
|
86
|
+
"list_cameras",
|
|
87
|
+
"list_devices",
|
|
88
|
+
"list_serial_ports",
|
|
89
|
+
"load_session",
|
|
90
|
+
"probe_camera",
|
|
91
|
+
"recover_session",
|
|
92
|
+
"verify_session",
|
|
93
|
+
]
|
ponolock/_docs/README.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# PonoLock documentation
|
|
2
|
+
|
|
3
|
+
Start with [configuration, progress, reports and offline docs](operator-tools.md).
|
|
4
|
+
|
|
5
|
+
| For | Read |
|
|
6
|
+
|---|---|
|
|
7
|
+
| Getting started | [Installation](installation.md) · [Quickstart](quickstart.md) |
|
|
8
|
+
| Integrating | [Embedding](embedding.md) · [API reference](api.md) · [Configuration and device identity](configuration.md) · [Lifecycle and concurrency](lifecycle.md) |
|
|
9
|
+
| Understanding data | [Timestamps](timestamps.md) · [GNSS](gnss.md) · [Session format](session_format.md) · [Synchronization methods](synchronization.md) |
|
|
10
|
+
| Operating | [Long sessions, durability, recovery, troubleshooting](operations.md) · [Studio troubleshooting](troubleshooting.md) · [Benchmarks](benchmarks.md) · [Physical acceptance](physical_acceptance.md) |
|
|
11
|
+
| Maintaining | [Architecture](architecture.md) · [Migration from 0.2](migration.md) · [Release and versioning](release.md) · [AfricaDrive integration note](africadrive_integration_note.md) · [0.3 plan](development/plan-0.3.md) |
|
|
12
|
+
| Studio | [Studio API](studio_api.md) · [Local database](local_database.md) · [Live GNSS map](live_gnss_map.md) · [Media pipeline](media_pipeline.md) |
|
|
13
|
+
| History | [Hardware validation (0.1–0.2)](hardware_validation.md) · [Headless notes (0.2)](headless.md) · [Verification record (0.1)](verification.md) · [AfricaDrive and redundancy](africadrive_and_redundancy.md) |
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# AfricaDrive, data integrity and accessible sensor redundancy
|
|
2
|
+
|
|
3
|
+
AfricaDrive's need for dependable sensor data motivated PonoLock. AfricaDrive is an
|
|
4
|
+
application and scientific dataset consumer; PonoLock is the reusable, application-
|
|
5
|
+
independent instrument for recording and evaluating heterogeneous sensor networks.
|
|
6
|
+
Their work is complementary: credible AfricaDrive data depends on explicit acquisition
|
|
7
|
+
evidence, and real AfricaDrive failures inform PonoLock's research. Neither project
|
|
8
|
+
can substitute a working UI or plausible route for measured integrity.
|
|
9
|
+
|
|
10
|
+
## Where operators start
|
|
11
|
+
|
|
12
|
+
Normal AfricaDrive discovery, recording, calibration when requested, import and dataset
|
|
13
|
+
work start in the **AfricaDrive repository**. It installs Core from a tested exact Git
|
|
14
|
+
commit in an isolated capture environment; neither this checkout nor Studio is needed
|
|
15
|
+
to record. AfricaDrive owns its physical role bindings, final mounts, calibration and
|
|
16
|
+
acceptance protocol, GNSS coverage-only policy and dataset provenance. Its current
|
|
17
|
+
contract is two stereo rigs and one USB GNSS receiver.
|
|
18
|
+
|
|
19
|
+
Maintain reusable sources, capture/writer isolation, timestamp semantics, timing methods
|
|
20
|
+
and general redundancy research here. A Core code change returns to AfricaDrive only
|
|
21
|
+
after verification and an explicit dependency-pin update. Documentation/test changes
|
|
22
|
+
here do not automatically replace AfricaDrive's installed package. See
|
|
23
|
+
[AfricaDrive's operator entry](https://github.com/DeepsMoseli/AfricaDrive_V2/blob/ponoLock-integration/START_HERE.md)
|
|
24
|
+
and [GNSS plan](https://github.com/DeepsMoseli/AfricaDrive_V2/blob/ponoLock-integration/docs/gnss-improvement-plan.md).
|
|
25
|
+
|
|
26
|
+
## Research remit: multiple accessible sensors
|
|
27
|
+
|
|
28
|
+
Investigate whether multiple affordable, locally obtainable cameras and GNSS receivers
|
|
29
|
+
can improve useful observation availability and expose failures within limited CPU,
|
|
30
|
+
memory, USB, disk and energy budgets. Test mixed device quality and repairable local
|
|
31
|
+
equipment; include setup burden and total deployed cost. Do not assume Africa has
|
|
32
|
+
uniform prices, infrastructure or GNSS conditions. Affordability and geographic
|
|
33
|
+
accessibility are measured deployment properties, not substitutes for data quality.
|
|
34
|
+
|
|
35
|
+
Current infrastructure supports N-camera/M-GNSS configuration, per-source capture and
|
|
36
|
+
writer workers, bounded queues, identity resolution, raw GNSS and per-source timing/
|
|
37
|
+
quality/event evidence. A synthetic four-camera/three-receiver integration test checks
|
|
38
|
+
concurrent persistence. A separate two-GNSS synthetic test injects one writer failure
|
|
39
|
+
and checks that the other continues and the failed session remains visibly erroneous.
|
|
40
|
+
These are software isolation tests, not physical reliability or spatial accuracy results.
|
|
41
|
+
|
|
42
|
+
Do not describe this as completed fusion, trustworthy automatic failover, independent
|
|
43
|
+
receiver errors or exposure synchronization. Multi-source collection is implemented;
|
|
44
|
+
scientifically validated redundancy benefit is an open research result.
|
|
45
|
+
|
|
46
|
+
## Proposed redundancy protocol (not yet a validated field capability)
|
|
47
|
+
|
|
48
|
+
1. Freeze source identities, roles, firmware/configuration, antenna/mount geometry,
|
|
49
|
+
USB/power sharing, local cost/availability and intended failure assumptions. Archive
|
|
50
|
+
original source streams; any fusion/selection result is a separate derivative.
|
|
51
|
+
2. Distinguish redundant views from complementary views. Front/rear coverage alone is
|
|
52
|
+
not redundant observation of the same scene. Define what another camera can actually
|
|
53
|
+
replace and how reduced observability affects downstream eligibility.
|
|
54
|
+
3. Compare GNSS observations at matched receiver epochs with declared timing tolerances,
|
|
55
|
+
reference frame/datum, antenna offsets and missing-data rules. Keep receipt time
|
|
56
|
+
separate from receiver UTC. Preserve checksums, raw bytes and available quality
|
|
57
|
+
fields; DOP/satellite count is not a metre-level confidence certificate.
|
|
58
|
+
4. Test individual source/cable/writer faults and common USB-controller, disk, host and
|
|
59
|
+
power faults. Independent workers do not make shared hardware independent. Preserve
|
|
60
|
+
failure events and loss counts; measure healthy-source progress after a fault.
|
|
61
|
+
5. Predeclare disagreement/freshness thresholds and future selection rules. A switch
|
|
62
|
+
must retain its source, reason, epoch and uncertainty. Agreement is not ground truth;
|
|
63
|
+
disagreement between two sources alone cannot identify the correct one. Do not
|
|
64
|
+
average correlated errors under an independence assumption or invent missing fixes.
|
|
65
|
+
6. Evaluate against held-out independent reference measurements. Report availability,
|
|
66
|
+
longest outages, error distributions, timing uncertainty coverage, false acceptance/
|
|
67
|
+
rejection, native resource use, measured energy and deployed cost. Retain negative
|
|
68
|
+
results where extra sources add load without improving trustworthy observations.
|
|
69
|
+
|
|
70
|
+
These steps specify research and acceptance work. Automatic GNSS fusion, correlated-
|
|
71
|
+
error estimation and automatic quality-certified switching are not implemented by this
|
|
72
|
+
documentation. A downstream application must explicitly support any expanded profile
|
|
73
|
+
and preserve its own scientific policy. Better GNSS does not override AfricaDrive's
|
|
74
|
+
prohibition on GPS-derived metric trajectory labels or split assignment.
|
|
75
|
+
|
|
76
|
+
## Shared evidence without overstating it
|
|
77
|
+
|
|
78
|
+
The earlier local indoor one-camera tests remain limited to their stated conditions.
|
|
79
|
+
AfricaDrive subsequently reported a roughly 20-second stationary two-rig/one-GNSS trial:
|
|
80
|
+
599 and 600 saved/decoded frames, no reported application queue drops, and about 1 Hz
|
|
81
|
+
independent position epochs. It was nighttime, both cameras faced forward, the rear
|
|
82
|
+
mount was provisional and front-board strain was subsequently reported. No physical
|
|
83
|
+
camera rerun followed that report. This is neither a validated mounting geometry nor
|
|
84
|
+
an outdoor/moving accuracy, exposure-sync, endurance or energy result. See the
|
|
85
|
+
[versioned downstream report](https://github.com/DeepsMoseli/AfricaDrive_V2/blob/931fb529/docs/sensor-check-2026-11-11.md).
|
|
86
|
+
|
|
87
|
+
Improve antenna placement and inventory actual receiver capabilities before treating
|
|
88
|
+
an extra cheap receiver as an accuracy upgrade. Shared obstruction/multipath can affect
|
|
89
|
+
both receivers; this motivates measuring common errors rather than presuming independent
|
|
90
|
+
evidence. [GPS.gov](https://www.gps.gov/gps-accuracy) explains those accuracy factors.
|
|
91
|
+
Specialized moving-base heading requires suitable receiver hardware and configuration,
|
|
92
|
+
not merely two ordinary position strings; see
|
|
93
|
+
[u-blox's application note](https://content.u-blox.com/sites/default/files/documents/ZED-F9P-MovingBase_AppNote_UBX-19009093.pdf).
|
|
94
|
+
|
|
95
|
+
A later [ten-minute downstream diagnostic](https://github.com/DeepsMoseli/AfricaDrive_V2/blob/b1dc5872/docs/sensor-check-2026-11-12.md)
|
|
96
|
+
retained 36,002 decodable camera frames with zero reported application drops and 3,805
|
|
97
|
+
checksum-valid NMEA sentences, but no valid positions. That negative result is part
|
|
98
|
+
of the integrity evidence: transport success does not establish a usable GNSS fix.
|
|
99
|
+
Covered parking was confirmed initially; subsequent open-sky exposure was not timed
|
|
100
|
+
or confirmed. Diagnose actual placement/conditions before attributing the result to
|
|
101
|
+
software or promising that a second inexpensive receiver will solve it.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# AfricaDrive integration note (PonoLock 0.3.1 candidate)
|
|
2
|
+
|
|
3
|
+
AfricaDrive's field capture environment still pins Core 0.2.3 at commit `05e4478`.
|
|
4
|
+
Do not use an editable sibling checkout for field recording. Install and test an
|
|
5
|
+
immutable wheel or commit, then update the application pin and setup version check
|
|
6
|
+
together. Publication of 0.3.1 is pending; do not assume it is available on PyPI.
|
|
7
|
+
|
|
8
|
+
## Software evidence
|
|
9
|
+
|
|
10
|
+
The Windows review on 18 November 2026 used Python 3.11 and GUI OpenCV 4.14.0.94
|
|
11
|
+
in a separate candidate environment. It did not open physical cameras or GNSS.
|
|
12
|
+
|
|
13
|
+
* PonoLock suite: **107 passed, 3 skipped**. Skips require POSIX shell syntax,
|
|
14
|
+
privileged Windows symlinks, or Linux udev fixtures.
|
|
15
|
+
* AfricaDrive capture/import/profile/doctor/guidance/survey/epoch/evidence checks:
|
|
16
|
+
**38 passed**, including batched NMEA records with identical read receipts.
|
|
17
|
+
* Both AfricaDrive capture and live-preview simulation programs passed with
|
|
18
|
+
the application disk reserve intact.
|
|
19
|
+
* Studio browser checks passed: setup/login, simulated previews, recording,
|
|
20
|
+
playback, alignment, benchmark artifacts, diagnostics, themes and mobile layout.
|
|
21
|
+
* A fresh wheel install outside the repository passed setup/config, simulated
|
|
22
|
+
recording, verify/inspect, reports, offline documentation and a consumer app.
|
|
23
|
+
Windows Application Control blocked the consumer's generated console launcher;
|
|
24
|
+
its documented `python -m trip_logger.app` entry point passed instead. Host
|
|
25
|
+
application policy was not changed.
|
|
26
|
+
|
|
27
|
+
The earlier 0.3.0 candidate also passed simulations on a Linux VM with a reduced
|
|
28
|
+
disk reserve in the copied test fixture. That does not establish Linux results
|
|
29
|
+
for 0.3.1; the release CI must test the exact release commit on both platforms.
|
|
30
|
+
|
|
31
|
+
## Compatibility and migration
|
|
32
|
+
|
|
33
|
+
Public recorder APIs and schema version 1 remain supported. The default muxer
|
|
34
|
+
still creates one AVI master per camera. Session statuses include `partial`,
|
|
35
|
+
`aborted`, `failed` and derived `interrupted`; only accepted complete sessions
|
|
36
|
+
should enter AfricaDrive's normal import path.
|
|
37
|
+
|
|
38
|
+
1. GNSS sentences delivered by a single serial read legitimately share
|
|
39
|
+
`receipt_monotonic_ns`. AfricaDrive's importer must allow equal GNSS receipts,
|
|
40
|
+
retain stable row order for ties, and still reject decreasing receipts. Camera
|
|
41
|
+
receipt checks remain strict. A focused importer change and regression test
|
|
42
|
+
were prepared in AfricaDrive during this review.
|
|
43
|
+
2. The default free-space reserve is 200 MB. AfricaDrive applies its own stricter
|
|
44
|
+
reserve. Do not lower that application reserve for a field run.
|
|
45
|
+
3. Empty sources produce a partial session. Snapshot source state may be `stalled`
|
|
46
|
+
with no exception: handle the `stalled` flag as well as `error`.
|
|
47
|
+
4. A normal GNSS stop now archives bytes already read, including an incomplete
|
|
48
|
+
final sentence as an invalid raw record. This is preservation, not a new fix.
|
|
49
|
+
5. Rollover fsyncs each closed master before advertising it as closed. Recovery
|
|
50
|
+
matches timing rows by `media_file` and local `media_index`; an ambiguous
|
|
51
|
+
truncated segment is withheld rather than assigned invented correspondence.
|
|
52
|
+
|
|
53
|
+
Keep rollover off in AfricaDrive until its importer and playback support several
|
|
54
|
+
masters per camera and have been tested with missing middle segments. Keep the
|
|
55
|
+
current muxer until receipt-based playback/proxy handling is checked for MKV.
|
|
56
|
+
OpenCV masters use configured-FPS presentation times; `stream_mkv` uses
|
|
57
|
+
receipt-relative milliseconds forced strictly increasing. Neither proves exposure
|
|
58
|
+
synchronization, and the CSV remains the association record.
|
|
59
|
+
|
|
60
|
+
New applications can use versioned JSON profiles, `setup`, `config validate`,
|
|
61
|
+
`doctor`, progress callbacks, `report` and offline `docs` without depending on
|
|
62
|
+
Studio. See [operator tools](operator-tools.md) and the consumer example.
|
|
63
|
+
|
|
64
|
+
## Physical acceptance still required
|
|
65
|
+
|
|
66
|
+
No physical recording, synchronization measurement, calibration, receiver-accuracy
|
|
67
|
+
test or power-loss test was performed in this review. Use the existing field SOP
|
|
68
|
+
and [independent acceptance gates](physical_acceptance.md). The changed mounts and
|
|
69
|
+
pending calibrations need fresh evidence. Local reconciliation and host receipt
|
|
70
|
+
association cannot establish exposure alignment or GNSS accuracy. AfricaDrive's
|
|
71
|
+
coverage-only GNSS policy remains in force; no motion labels are derived here.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Prompt: integrate PonoLock into AfricaDrive without losing existing work
|
|
2
|
+
|
|
3
|
+
Copy everything below the separator into the AfricaDrive coding-agent conversation.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Implement a lightweight, scientifically defensible recording, calibration, and GNSS workflow in AfricaDrive by integrating PonoLock as a reusable package. Preserve the existing dataset, portal, calibration tools, processing pipeline, and historical provenance. This is an implementation request: inspect both repositories, make the necessary reversible changes, run meaningful checks, and document the result. Do not stop at an architecture proposal. Identify physical validation that still requires the operator and hardware, and provide runnable procedures for it.
|
|
8
|
+
|
|
9
|
+
My priorities are laptop battery life during recording, reliable original recordings, defensible timing and calibration, and evidence I can explain to a technically demanding advisor. Calibration has been our biggest failure point: implement real-time help during calibration capture so I can correct poor footage immediately. Include explicit extrinsic calibration this time. A library choice alone does not establish scientific validity. Build an auditable method and expose limitations rather than promising publication acceptance.
|
|
10
|
+
|
|
11
|
+
The new production setup is exactly **two physical stereo cameras/rigs and one USB GNSS receiver**: front stereo (FL/FR), rear stereo (BL/BR), and one GNSS module. This means two side-by-side video streams, four optical views, and one serial GNSS stream. Bind these roles to discovered persistent device identities; do not guess device indexes or COM ports. Build and validate this default profile without removing historical layouts for other configurations.
|
|
12
|
+
|
|
13
|
+
## Repository context to verify
|
|
14
|
+
|
|
15
|
+
- AfricaDrive checkout: `C:\Users\mosel\OneDrive\Documents\Research\AfricaDrive_V2`.
|
|
16
|
+
- PonoLock checkout: sibling directory `..\PonoLock`, remote `Mind-Forge-AI/PonoLock`.
|
|
17
|
+
- Read applicable `AGENTS.md` files and preserve unrelated local changes.
|
|
18
|
+
- AfricaDrive currently ingests an OBS composite and derives views from immutable layouts. Inspect `ingest.py`, `sampling.py`, `camera_split.py`, capture epochs, scene segmentation, calibration source mappings, and downstream timestamp consumers.
|
|
19
|
+
- AfricaDrive's GPS map currently uses browser-location logs, route edits, and OBS filename timing. Its documented policy keeps GPS out of metric motion, trajectory labels, and split decisions. Preserve that policy unless a separately justified research protocol explicitly changes it.
|
|
20
|
+
- PonoLock exposes `Recorder`, `SensorConfig`, and `load_session` without Studio. Inspect the actual implementation, not just its README. Its present camera timestamps are host receipt times; video FPS is a playback timebase, and frame CSVs contain authoritative receipt timing.
|
|
21
|
+
- Earlier inspection found Python 3.11 in both environments, OpenCV 5 in AfricaDrive, and PonoLock camera dependencies constrained below OpenCV 5. Verify current state. Resolve packaging deliberately; do not mix incompatible OpenCV distributions or downgrade the processing environment blindly.
|
|
22
|
+
- PonoLock's previous suite had 34 passing tests. Its recorded physical validation was short, stationary, indoors, with one camera and a receiver without valid fixes. Those results do not establish outdoor GNSS accuracy, multi-rig timing, battery savings, or long-drive reliability.
|
|
23
|
+
|
|
24
|
+
## 1. Keep capture small and independent
|
|
25
|
+
|
|
26
|
+
Build a standalone recording command and simple Windows launcher with two explicit modes. **Drive recording** is headless: no browser, Next.js, FastAPI server, authentication service, learned-model loading/inference, rectification, or calibration fitting. Terminal status at a modest rate is sufficient. **Guided calibration capture** adds a small local view and bounded board-analysis workers for immediate feedback; it must also work with both portals closed. Keep the two modes distinct so calibration assistance does not add work to ordinary drive capture.
|
|
27
|
+
|
|
28
|
+
Use PonoLock Core as a versioned dependency. Keep sensor acquisition, recorder lifecycle, generic media backends, and timing improvements reusable in PonoLock. Put AfricaDrive-specific rig mappings, calibration bindings, ingestion, and dataset policy in AfricaDrive. Do not copy PonoLock internals into AfricaDrive. If upstream changes are needed, make them in the sibling repository and document dependency installation and version pinning. A separate capture environment/process is acceptable and may be preferable to changing the existing model-processing environment.
|
|
29
|
+
|
|
30
|
+
Default drive recording to preview fully disabled. Avoid preview workers, frame decoding for display, JPEG preview encoding, thumbnail generation, and unnecessary allocations in this mode. Allow an optional brief setup preview; disabling it must leave recording unaffected. Guided calibration may enable the low-rate feedback path described below. Do not assume removing the browser eliminates the main power cost: measure capture, encoding, storage, and USB-device power together where possible.
|
|
31
|
+
|
|
32
|
+
Provide device discovery, persistent identity binding, profile validation, preflight, record, status, stop, and post-record verification. Preflight should check actual mode, rig/eye identity, output writability, disk budget, GNSS freshness/fix state, and required calibration bindings. Handle unsupported modes and missing devices clearly. Make degraded capture an explicit, recorded choice; it must never silently qualify as an accepted production session.
|
|
33
|
+
|
|
34
|
+
Calibration mode must bootstrap without an existing fitted calibration. Mark intrinsics/extrinsics as pending instead of substituting guesses or refusing to collect the footage needed to estimate them. Define mode-specific preflight requirements so a stationary board session without a GNSS fix is identified accurately and is not confused with a drive that passed production GNSS checks.
|
|
35
|
+
|
|
36
|
+
## 2. Choose the media path using evidence
|
|
37
|
+
|
|
38
|
+
Use FFmpeg/ffprobe where they provide a supported, reproducible capture, muxing, probing, decoding, or extraction path. Inspect the installed build and actual Windows DirectShow device modes. Record executable versions, build configuration, commands, and negotiated settings. Prefer upstream documentation over recipes from arbitrary blogs.
|
|
39
|
+
|
|
40
|
+
Evaluate native compressed stream copying first when the camera/backend/container combination supports it. Saving the camera's original MJPEG packets without decoding and re-encoding could reduce work and preserve the supplied bitstream. Prove that the selected path actually does this. Do not call camera-generated MJPEG uncompressed or lossless sensor data. If passthrough is unavailable, report the actual decode/re-encode path and justify its quality and resource costs.
|
|
41
|
+
|
|
42
|
+
Keep each physical stereo rig's original side-by-side stream and native geometry. Do not resize, stretch, composite front/rear, burn overlays, or rectify acquisition masters. Generate viewing derivatives offline. Benchmark lossless FFV1 only as a candidate; do not force it if it causes drops or unacceptable battery/storage demand. Document color/pixel-format conversions and distinguish packet preservation from decoded-pixel preservation.
|
|
43
|
+
|
|
44
|
+
Preserve available source timestamps with declared semantics. Prevent unintended frame duplication/drop or timestamp rewriting by frame-rate conversion. Check the chosen muxer's actual timestamp behavior. Container selection and FFmpeg flags must follow measured requirements, not a blanket claim that one format or tool guarantees scientific quality.
|
|
45
|
+
|
|
46
|
+
Critically, a subprocess's log-line arrival time is not a camera frame timestamp. Do not open a second camera handle to manufacture timestamps for the first handle's recording. Every timing record must identify the actual saved frame/packet through the same acquisition path. Preserve PTS, DTS, timebase, host receipt timing, and their mappings where available; explicitly mark unavailable fields. If a backend cannot supply a trustworthy mapping to the common clock, retain that limitation and do not claim cross-sensor synchronization from its PTS alone.
|
|
47
|
+
|
|
48
|
+
## 3. Make timing and GNSS claims precise
|
|
49
|
+
|
|
50
|
+
Distinguish camera exposure time, driver/device timestamps, host monotonic receipt time, host UTC, GNSS fix UTC, and serial receipt time. Record clock domains, units, timestamp source, mappings, and uncertainty evidence. Nanosecond representation does not imply nanosecond accuracy. Unknown uncertainty stays unknown.
|
|
51
|
+
|
|
52
|
+
Keep source sequence and saved-frame index separate. Account for gaps, late arrivals, queue drops, writer failures, reconnects, clock jumps, and reset segments. Publish explicit association tolerances, signed time deltas, missing associations, and target reuse policy. Keep both eyes of a pair from the same rig observation, while acknowledging that one USB composite does not itself prove simultaneous physical exposure. Separately associate front/rear observations using declared timing evidence.
|
|
53
|
+
|
|
54
|
+
Use direct serial USB GNSS and preserve original NMEA plus structured observations. Retain receiver identity/configuration, sentence type, validity, fix-quality indicators, satellites, HDOP, available fix UTC, and host receipt time. Validate checksums and missing fields. Do not invent dates, coordinates, altitude, speed, or measured spatial uncertainty. HDOP is not an accuracy measurement in metres. Multiple sentence types describing one fix must not be counted as independent position measurements.
|
|
55
|
+
|
|
56
|
+
Document receiver update rate, message configuration, buffering/serial latency, antenna placement, dropouts, and time-to-fix. Keep raw observations distinct from interpolation and manually edited map routes. Interpolation needs a justified common timeline, maximum-gap and validity rules, and a derived-data label. Preserve historical coverage-only routes with their original provenance.
|
|
57
|
+
|
|
58
|
+
NMEA receipt association alone cannot establish camera-exposure-to-GNSS-fix alignment. Define a feasible independent timing-validation procedure, such as independently logged visible timing events and a suitable clock reference. Measure repeatability, offset, drift, and tail errors across the relevant session duration and conditions. Reserve independent validation events before fitting. State which part of the chain each reference measures. Do not claim PPS, triggering, RTK accuracy, exposure synchronization, or calibrated error bounds unless the hardware and measurements support them.
|
|
59
|
+
|
|
60
|
+
Derive acceptable temporal and spatial error budgets from intended driving tasks, speed ranges, frame rates, and downstream sensitivity. Freeze justified acceptance thresholds before evaluating final validation runs. If available hardware cannot support the intended claim, identify the gap and minimum additional measurement/hardware needed. Software cannot remove unobserved physical uncertainty.
|
|
61
|
+
|
|
62
|
+
## 4. Reuse and strengthen geometric calibration
|
|
63
|
+
|
|
64
|
+
Reuse AfricaDrive's ChArUco tools, quality reports, separate-rig source mappings, rectification, and immutable calibration sets. Inspect `calibration_capture.py`, `calibration_quality.py`, and the existing calibration workflow before adding duplicate logic. Extend them for PonoLock sessions and native per-rig recordings. Calibration capture uses the same recorder, with live assistance in its dedicated mode. Final fitting, full-resolution verification, and approval remain separate from the live capture-quality indicator.
|
|
65
|
+
|
|
66
|
+
### 4a. Give actionable help during calibration recording
|
|
67
|
+
|
|
68
|
+
Implement the actual interactive tool, not just a checklist or a retrospective report. Use a small native/local calibration window and concise status, without requiring either portal. Show the selected rig's two eyes with detected corners and accumulated coverage maps. Keep separate progress and quality state for all four eyes and both stereo pairs. Let me calibrate the front and rear sequentially; a board need not be visible to both opposing rigs simultaneously. Continue recording the two configured video streams and the GNSS stream, showing their acquisition health independently of board visibility.
|
|
69
|
+
|
|
70
|
+
Provide immediate guidance for:
|
|
71
|
+
|
|
72
|
+
- Correct board identity and sufficient identifiable, well-distributed corners in each eye; reject collinear or otherwise degenerate selections. For stereo, require enough shared corner IDs in the same rig observation, not merely a detection in each eye.
|
|
73
|
+
- Blur, motion, clipped/underexposed board regions, glare, occlusion, and board size in the image. Use documented, resolution-aware heuristics; expose unavailable diagnostics rather than implying precise optical measurements.
|
|
74
|
+
- Coverage of corners, edges, and centre for each eye, board scale/near-far variation, and useful tilt/orientation variation. Do not let a large number of nearly identical central views satisfy a diversity requirement. Before intrinsics are available, label pose/diversity estimates as image-space heuristics or provisional estimates.
|
|
75
|
+
- Concrete next actions such as "hold still", "move the board toward the upper-left edge", "bring it closer", "tilt the board", "rear-right image is blurred", or "both eyes need more shared corners". Base each instruction on the measured deficiency.
|
|
76
|
+
|
|
77
|
+
Automatically mark useful observations after a stability interval and enough new information. Keep the original master recording intact. Persist selected/rejected observation IDs, corner coordinates, diagnostic values, active thresholds, selection rationale, and coverage/pose progress so the session is reproducible offline. Provide a useful progress checklist that does not equate a frame count or coverage percentage with calibration accuracy. Include undo/review of sample selections without deleting source footage.
|
|
78
|
+
|
|
79
|
+
Run analysis through a bounded latest-frame path at a configurable measured rate. Slow detection, display, or provisional fitting must skip analysis frames instead of blocking acquisition or dropping master frames. Reuse the recorder's acquisition stream; do not open another camera handle. Downsample for display/coarse detection where useful, but map coordinates correctly and perform final corner refinement/measurement at the native calibration resolution. Record those transformations. A new snapshot or provisional fit must carry the observation-set/version identifier so stale results cannot appear current.
|
|
80
|
+
|
|
81
|
+
Once sufficient diverse samples exist, allow a bounded background or operator-triggered provisional fit and rectification preview. Show fit residuals, stereo epipolar diagnostics, and missing evidence as provisional; avoid repeatedly solving a large optimization for every frame. Distinguish **capture coverage sufficient**, **provisional fit available**, and **independent validation passed**. If held-out checks fail, tell me which additional poses or measurements are needed. Keep held-out data separate from repeated fit tuning, and collect a fresh final validation set after using validation feedback to change the fit or acquisition protocol. Never auto-confirm calibration because the live indicator turned green.
|
|
82
|
+
|
|
83
|
+
Record board identity and independently measured printed dimensions, camera identities, native per-eye geometry, lens/focus/exposure configuration, relevant optical path, stereo baseline evidence, and mount/vehicle identity. Fit an appropriate documented distortion model using diverse board poses and image coverage. Preserve selected/rejected observations and exclusion reasons.
|
|
84
|
+
|
|
85
|
+
Report fit residuals separately from held-out validation. Use distinct board poses or recording sequences for validation; a random split of nearly identical adjacent frames is weak evidence. Include per-eye reprojection distributions, rectified vertical-error distributions, coverage, baseline plausibility/measurement, and independent checks on real driving imagery. Evaluate depth/scale against independently measured targets where metric accuracy is claimed; a fitted baseline or agreement between algorithms is insufficient by itself.
|
|
86
|
+
|
|
87
|
+
Bind each session immutably to its exact calibration/profile. The old OBS eye size and the native PonoLock eye size may differ; never attach an old calibration blindly or silently resize inputs to make them fit. A documented intrinsic transformation is acceptable only when the image transformation is known and validated. Changes in recorder software alone do not necessarily change geometry. Distinguish stereo intrinsics/extrinsics from camera-to-vehicle extrinsics, which need separate attention after remounting.
|
|
88
|
+
|
|
89
|
+
Preserve quality failures and explicit historical overrides. A button saying "trusted" must not turn a failed or provisional calibration into independent scientific evidence.
|
|
90
|
+
|
|
91
|
+
### 4b. Calibrate the complete mounted geometry explicitly
|
|
92
|
+
|
|
93
|
+
Reuse AfricaDrive's `configs/vehicle_geometry/README.md`, `bev_geometry.py`, and existing measurement/PnP tools. Preserve its established vehicle-frame convention and document transform direction, units, axes, origin, and composition. Cover each of these separately:
|
|
94
|
+
|
|
95
|
+
1. **Within each stereo rig:** estimate and validate left-to-right rotation/translation and baseline. Preserve the association with the intrinsics and image mode used to estimate them.
|
|
96
|
+
2. **Each rig to the vehicle:** measure/estimate front and rear rig poses in the same vehicle frame, then derive all four raw-eye and rectified-eye transforms using the calibrated stereo and rectification chains. Do not type independent plausible eye matrices or forget the rectification rotations.
|
|
97
|
+
3. **Front to rear:** derive the relative transform from their common vehicle-frame bindings and validate it with independent survey/check measurements. These cameras may have no overlapping field of view. Separate observations of a hand-moved board do not establish its intervening motion or a common frame. Use targets or board placements surveyed into the shared vehicle frame, or another justified observable procedure. Provide an operator-friendly measurement sheet and guided collection/solve workflow.
|
|
98
|
+
4. **GNSS antenna to vehicle:** measure and record the antenna reference-point offset (lever arm) in vehicle coordinates, its measurement method/error evidence, and the physical reference point represented by the receiver output. A single ordinary GNSS antenna does not independently measure a full orientation or vehicle attitude. Do not invent an antenna rotation, heading, or calibrated phase-centre location. Treat absent manufacturer reference information as a limitation.
|
|
99
|
+
|
|
100
|
+
For surveyed targets, preserve target IDs, vehicle-frame coordinates, survey measurements, image correspondences, and their uncertainty evidence. The guided tool should show the correspondences, conditioning warnings, projected checks, and residuals. Support the existing planar approach only with its documented assumptions and ambiguity checks; prefer stronger target geometry where feasible. Check positive depth, physically plausible orientation, transform inverses/composition, and independent targets or placements excluded from fitting. Report rotation/translation repeatability and measurement limitations, not only training-point reprojection RMS.
|
|
101
|
+
|
|
102
|
+
Bind extrinsics to vehicle identity, mount version, exact stereo-calibration hashes, image/rectification conventions, and explicit validity. A moved or re-aimed rig needs a new mount calibration/validation. Show separate statuses for camera intrinsics, stereo extrinsics, vehicle extrinsics, antenna lever arm, and temporal calibration. Calibrating spatial transforms does not establish temporal synchronization, and measuring an antenna offset does not justify GPS-based metric labels under the existing dataset policy.
|
|
103
|
+
|
|
104
|
+
## 5. Integrate without discarding historical data
|
|
105
|
+
|
|
106
|
+
Add a versioned PonoLock session importer alongside the OBS path. Preserve all original recordings, annotations, route logs, calibration sets, manifests, and useful processing outputs. Keep old capture epochs readable. Create a new epoch/profile for new acquisition. Audit eligibility for each intended use rather than assigning every historical recording a blanket pass or fail.
|
|
107
|
+
|
|
108
|
+
Map sensor identities to physical rigs and canonical FL/FR/BL/BR views explicitly. Create the established downstream artifacts where appropriate and extend schemas compatibly when necessary. Keep source session, source file/stream, source sequence, saved index, original timestamps, association deltas, calibration hashes, and transformations traceable.
|
|
109
|
+
|
|
110
|
+
Audit sampling, scene segmentation, rectification, SLAM adapters, trajectory windows, export, portal playback, and GPS playback. Do not derive new-session elapsed time from filename, configured FPS, encoded duration, or summed segment durations. Use the authoritative timeline, including segment offsets and gaps. Sampling onto a nominal grid must retain actual selected observation times and selection error. Missing/duplicated samples require explicit treatment; synthesized regular-grid timestamps must not masquerade as measurements.
|
|
111
|
+
|
|
112
|
+
Allow old and new data to coexist with documented capabilities and limits. Historical footage can remain useful for appropriate visual tasks even when metric geometry or synchronization is unavailable. Exclude unsupported metric labels from eligible exports without deleting the underlying evidence. Do not fabricate missing timing/GNSS or silently recalibrate every old session with the newest set.
|
|
113
|
+
|
|
114
|
+
## 6. Verify reliability, power, and research suitability
|
|
115
|
+
|
|
116
|
+
Add meaningful tests for session import, legacy compatibility, actual frame-index/timestamp mapping, irregular frame rates, gaps, cross-rig association, invalid/stale GNSS, reset segments, calibration mismatches, writer failures, and interrupted recordings. Exercise the actual two-stereo-rig/one-GNSS profile. Test that slow live calibration assistance cannot block master recording, that repeated/blurred/degenerate board views do not falsely satisfy readiness, that stereo selections use the same observation and shared corner IDs, and that native-resolution coordinate mapping is correct. Verify extrinsic transform direction/composition, remount invalidation, and rejection of underconstrained front/rear estimates. Verify output by decoding/counting frames and reconciling them with timing records and accounting. Packet-preservation claims require packet checks; lossless decoded-image claims require pixel checks.
|
|
117
|
+
|
|
118
|
+
Provide a physical validation runner and operator protocol for staged 1-, 10-, and 60-minute runs, plus representative drive-duration runs with all actual sensors. Include shared USB bandwidth, thermal behavior, representative exposure/lighting, disk pressure, controlled disconnects, graceful shutdown, unexpected interruption, and tested rollover/recovery behavior. Do not automatically start long camera/battery experiments. Run safe automated checks now and identify operator-run tests explicitly.
|
|
119
|
+
|
|
120
|
+
Measure actual captured/recorded rates, gap distributions, queue drops, reconnects, corrupt/undecodable media, GNSS coverage/latency evidence, CPU, native process memory, disk throughput, and storage per hour. Account for losses inside the driver/backend when observable; zero application queue drops is not proof of zero sensor-side losses. Record unobservable loss as a limitation.
|
|
121
|
+
|
|
122
|
+
Compare the selected headless profile against relevant existing capture baselines under matched hardware, mode, lighting, and settings, using repeated runs and recording ambient workload. Separately measure the guided-calibration mode's analysis/display overhead and verify that its workers are absent during ordinary headless recording. Measure whole-system watts or Wh per recorded minute where instrumentation allows, separating battery discharge from AC measurements. Include USB devices. If only battery telemetry is available, report that method and its limits. Do not invent energy savings from CPU percentages. Set up the measurements even when hardware access prevents collecting them now.
|
|
123
|
+
|
|
124
|
+
Create a reproducible session audit and release-eligibility report. Proposed thresholds must have rationale, be versioned, and be fixed before final validation; do not loosen them to turn failures into passes. Separate software test status, physical acquisition health, geometric validation, temporal validation, and spatial positioning evidence. Permit legitimate missing data under a declared protocol, and preserve failed/aborted sessions and exclusions. "Complete" must not imply every scientific quality criterion passed.
|
|
125
|
+
|
|
126
|
+
Archive configuration, hardware/firmware inventory, code commits, dependency and FFmpeg versions, calibration/reference identifiers, methods, validation artifacts, and exclusion records. Hash finalized master files outside the critical capture path where practical. Track parent recordings/sessions so train/validation/test splits cannot leak adjacent scenes or duplicates across partitions; preserve the existing GPS policy. Document image/location privacy and release transformations with traceability to the originals.
|
|
127
|
+
|
|
128
|
+
## Deliverables and completion report
|
|
129
|
+
|
|
130
|
+
Deliver the working headless recorder and launcher, the verified two-stereo-rig/one-GNSS profile, a lightweight real-time calibration assistant, the measured/surveyed extrinsic workflow and records, pinned package setup, session importer, timing-aware downstream path, offline verification, and backward compatibility. Reuse existing tools and extend them where justified; avoid a new portal or wholesale rewrite.
|
|
131
|
+
|
|
132
|
+
Also deliver:
|
|
133
|
+
|
|
134
|
+
1. An advisor-facing architecture decision explaining the chosen capture/backend/codec/container, alternatives considered, power/storage tradeoffs, and timestamp limitations.
|
|
135
|
+
2. A field SOP covering preflight, guided calibration capture, independent geometric validation, vehicle/extrinsic target survey and antenna-offset measurement, timing-reference capture, recording, shutdown, verification, and recovery. Include a practical two-rig checklist and examples of live corrective instructions.
|
|
136
|
+
3. A paper-ready methods outline and evidence table separating completed measurements, software-only tests, planned experiments, failures, and unsupported claims.
|
|
137
|
+
4. Exact commands for installation, discovery, preflight, headless recording, guided calibration capture, final calibration processing/validation, extrinsic collection/solve/validation, import, and audit. Clearly identify any commands that are proposed rather than implemented.
|
|
138
|
+
5. A final report of actual changes, checks run, evidence produced, preserved legacy behavior, and remaining physical validation. No fabricated results, automatic scientific certification, or guarantee of paper acceptance.
|
|
139
|
+
|
|
140
|
+
Proceed autonomously with authorized implementation and verification. Ask only for information that genuinely blocks progress, such as a missing physical measurement or an unresolved hardware identity; continue independent work while awaiting it. Keep the default recording workflow small enough to use with both portals closed.
|
|
141
|
+
|
|
142
|
+
## Primary references to consult
|
|
143
|
+
|
|
144
|
+
- FFmpeg stream copying and timestamp/frame-rate behavior: https://ffmpeg.org/ffmpeg.html
|
|
145
|
+
- FFmpeg DirectShow devices and timestamp-source options: https://ffmpeg.org/ffmpeg-devices.html#dshow
|
|
146
|
+
- OpenCV camera calibration and reconstruction: https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html
|
|
147
|
+
- OpenCV interactive calibration (concepts; use APIs compatible with the selected installed version): https://docs.opencv.org/5.0/tutorials/calib3d/interactive_calibration/interactive_calibration.html
|
|
148
|
+
- Existing PonoLock `docs/timestamps.md`, `docs/media_pipeline.md`, `docs/hardware_validation.md`, and `research/experiment_protocol.md`.
|
|
149
|
+
- Existing AfricaDrive calibration contracts, capture/quality modules, vehicle-geometry conventions and survey/PnP tools, capture epochs, GPS policy, legacy-data handling, and stereo/SLAM investigation records.
|
ponolock/_docs/api.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Public API reference
|
|
2
|
+
|
|
3
|
+
Everything below is importable from `ponolock` and covered by the
|
|
4
|
+
[versioning policy](release.md#versioning). Modules not listed here (for example
|
|
5
|
+
`ponolock.api`, the Studio web application) are internal.
|
|
6
|
+
|
|
7
|
+
## Discovery (read-only)
|
|
8
|
+
|
|
9
|
+
| Name | Description |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `list_cameras() -> list[DeviceInfo]` | Cameras from sysfs/udev (Linux) or DirectShow monikers (Windows). Opens nothing. |
|
|
12
|
+
| `list_serial_ports() -> list[DeviceInfo]` | Serial ports via pyserial. Opens nothing. |
|
|
13
|
+
| `list_devices() -> list[DeviceInfo]` | Both. |
|
|
14
|
+
| `probe_camera(device, backend="auto") -> dict` | **Opens** a camera briefly and reports the backend's default mode. |
|
|
15
|
+
| `DeviceInfo` | `kind`, `device`, `description`, `persistent_id`, `identity_basis`, `identity_stable`, `vid`, `pid`, `backend`, `limitations`, `to_dict()` |
|
|
16
|
+
| `ponolock.sources.discovery.discover_cameras(limit=6, probe=False)` / `discover_gnss()` | 0.2-compatible dict forms |
|
|
17
|
+
|
|
18
|
+
## Configuration
|
|
19
|
+
|
|
20
|
+
`RecordingProfile`, `load_profile(path)`, `save_profile(profile, path, overwrite=False)`
|
|
21
|
+
and `setup_profile(simulate=False)` provide strict versioned profiles, legacy list
|
|
22
|
+
migration and guided read-only device selection. See [operator tools](operator-tools.md).
|
|
23
|
+
|
|
24
|
+
Long operations accept `progress=callback`: `verify_session`, `inspect_session`,
|
|
25
|
+
`recover_session`, and `generate_report(session, output, include_private=False)`.
|
|
26
|
+
Callbacks receive frozen `ProgressEvent` values from `ponolock.progress`. CLI rendering
|
|
27
|
+
is separate; embedding callers own their event delivery and UI. `generate_report`
|
|
28
|
+
produces privacy-redacted JSON, HTML and a ZIP bundle by default.
|
|
29
|
+
|
|
30
|
+
| Name | Description |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `SensorConfig` | One source (Pydantic model). See [configuration](configuration.md). |
|
|
33
|
+
| `RecordingOptions` | Durability, disk, rollover and timeout policy. |
|
|
34
|
+
| `Recorder.preflight(duration_s=None, *, bytes_per_second=None, freshness_s=2, minimum_rate_fraction=0.8, check_encoders=True) -> PreflightReport` | Checks; never records. |
|
|
35
|
+
| `PreflightReport` | `passed`, `checks` (`PreflightCheck(name, status, detail, source, data)`), `errors`, `warnings`, `raise_for_errors()`, `to_dict()` |
|
|
36
|
+
|
|
37
|
+
## Recorder
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
Recorder(output_dir="./recordings", *, preview_enabled=True, options=None)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
| Member | Description |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `add_source(config, source=None)` | Register; `source` overrides the built-in driver. `idle` only. |
|
|
46
|
+
| `add_camera(device=0, name=None, stereo="none", **fields)` / `add_gps(port="COM3", name=None, **fields)` | Shorthands |
|
|
47
|
+
| `connect()` / `disconnect()` / `close()` | Open / release all sources |
|
|
48
|
+
| `start() -> Path` | Create a session and start saving (connects if needed) |
|
|
49
|
+
| `stop(*, keep_connected=False) -> Path \| None` | Drain, finalize, optionally keep streaming |
|
|
50
|
+
| `abort(reason="aborted_by_caller", *, keep_connected=False)` | Finalize as `aborted` |
|
|
51
|
+
| `state -> RecorderState`, `connected`, `recording`, `session_path`, `sources` | Properties |
|
|
52
|
+
| `status() -> RecorderStatus` | Typed live status (`state`, `recording`, `session_path`, `elapsed_s`, `sources`, `healthy`, `source(name)`) |
|
|
53
|
+
| `snapshot() -> dict` | JSON-compatible status; 0.2 keys preserved |
|
|
54
|
+
| `events(after=0) -> list[dict]` | Bounded in-memory history |
|
|
55
|
+
| `subscribe(maxsize=1024) -> EventSubscription` | `get(timeout)`, `drain()`, `missed`, `close()`; context manager |
|
|
56
|
+
| `preview_frame(name, view="composite", *, after_sequence=None, timeout=0) -> PreviewFrame \| None` | `sequence`, `receipt_monotonic_ns`, `jpeg`; views `composite`, `left`, `right` |
|
|
57
|
+
| `preview(name, view="composite") -> bytes \| None` | Latest JPEG |
|
|
58
|
+
| `latest_observation(name) -> Observation \| None` | Read-only tap from the same handle |
|
|
59
|
+
| context manager | `__exit__` calls `stop()` |
|
|
60
|
+
|
|
61
|
+
`SourceStatus` fields: `name`, `kind`, `state`, `error`, `stalled`, `acquisition_hz`,
|
|
62
|
+
`saved_hz`, `preview_hz`, `captured`, `acquired`, `written`, `queue_dropped`,
|
|
63
|
+
`writer_dropped`, `queue_depth`, `queue_capacity`, `reconnects`,
|
|
64
|
+
`last_observation_age_s`, `handoff_latency_ms_p95`, `preview_latency_ms_p50`,
|
|
65
|
+
`workers_alive`.
|
|
66
|
+
|
|
67
|
+
## Observations
|
|
68
|
+
|
|
69
|
+
`Observation(sequence, timing: Timestamp, payload, metadata, encoded_payload)`.
|
|
70
|
+
`Timestamp` fields are documented in [timestamps](timestamps.md); new 0.3 fields are
|
|
71
|
+
appended with defaults so positional construction from 0.2 still works.
|
|
72
|
+
|
|
73
|
+
## Saved sessions
|
|
74
|
+
|
|
75
|
+
| Name | Description |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `load_session(path) -> Session` | Raises `SessionFormatError` for unknown major versions |
|
|
78
|
+
| `Session.status` | `complete`, `partial`, `aborted`, `failed`, `recording`, `interrupted` |
|
|
79
|
+
| `Session.finalized` / `incomplete` / `schema_minor` / `sensors` / `sensor(name)` | |
|
|
80
|
+
| `Session.observations(name) -> list[dict]` | Timing CSV rows |
|
|
81
|
+
| `Session.media_files(name) -> list[Path]` | Camera masters in order |
|
|
82
|
+
| `Session.raw_gnss_path(name)`, `timing_path(name)`, `file(relative)` | Safe paths inside the session |
|
|
83
|
+
| `Session.align(algorithm, source=..., target=...)` | Offline association ([synchronization](synchronization.md)) |
|
|
84
|
+
| `Session.export(destination)` | ZIP archive |
|
|
85
|
+
| `verify_session(path, *, ffprobe=None) -> dict` | Offline reconciliation; read-only |
|
|
86
|
+
| `inspect_session(path) -> dict` | What the files contain; read-only |
|
|
87
|
+
| `recover_session(path, *, ffmpeg=None, remux=True) -> dict` | Writes `recovery/<stamp>/` only |
|
|
88
|
+
| `ponolock.sync.diagnostics.session_diagnostics(path)` | Timing diagnostics |
|
|
89
|
+
| `ponolock.sync.diagnostics.holdout_split`, `evaluate_mapping` | Held-out clock evaluation |
|
|
90
|
+
|
|
91
|
+
## Errors
|
|
92
|
+
|
|
93
|
+
`PonoLockError` ← `ConfigurationError` (ValueError), `DeviceIdentityError` (OSError),
|
|
94
|
+
`SourceError` (OSError), `LifecycleError` (RuntimeError), `PreflightError`
|
|
95
|
+
(RuntimeError, `.report`), `WriterError` (OSError), `ShutdownTimeoutError`
|
|
96
|
+
(TimeoutError), `SessionFormatError` (ValueError).
|
|
97
|
+
|
|
98
|
+
## Command line
|
|
99
|
+
|
|
100
|
+
```text
|
|
101
|
+
ponolock --version | doctor | devices [--probe]
|
|
102
|
+
ponolock camera test --device 0 --duration 5
|
|
103
|
+
ponolock gps test --device COM5 --baudrate 9600 --duration 10
|
|
104
|
+
ponolock preflight --config rig.json [--connect] [--duration S]
|
|
105
|
+
ponolock record [--config rig.json] [--camera N] [--gps PORT] [--simulate] [--duration S]
|
|
106
|
+
[--muxer stream_mkv] [--segment-seconds S] [--disk-reserve-mb MB] [--preflight]
|
|
107
|
+
ponolock verify SESSION [--ffprobe ffprobe] # exit 3 on discrepancies
|
|
108
|
+
ponolock inspect SESSION | recover SESSION [--no-remux] | diagnose SESSION
|
|
109
|
+
ponolock sessions [DIR] | align SESSION ... | evaluate SESSION | import VIDEO ...
|
|
110
|
+
ponolock benchmark-recording [--cameras 1 2 4] [--modes ...] [--preview]
|
|
111
|
+
ponolock benchmark --config configs/benchmarks/low_resource.json # synthetic timing research
|
|
112
|
+
ponolock studio | users setup|list|reset
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Studio HTTP API
|
|
116
|
+
|
|
117
|
+
Studio's routes are documented in [Studio API](studio_api.md). They are not part of the
|
|
118
|
+
library's semantic-versioning promise.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
```text
|
|
4
|
+
┌──────────── consumers (no extra device handles) ────────────┐
|
|
5
|
+
CLI Studio (FastAPI, optional) your application AfricaDrive, ...
|
|
6
|
+
└──────────────── ponolock.Recorder (one per rig) ───────────┘
|
|
7
|
+
│ per source: capture thread ─► bounded queue ─► writer thread ─► session files
|
|
8
|
+
│ └► latest observation ─► preview thread (cameras) / taps
|
|
9
|
+
└ monitor thread: stalls, disk reserve
|
|
10
|
+
Sources (lazy): CameraSource (OpenCV) · NMEASource (pyserial) · SimulatedSource · plugins
|
|
11
|
+
Offline: load_session · verify_session · inspect/recover · sync diagnostics · clock models
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
| Package | Responsibility | Imports at `import ponolock` |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| `ponolock` (core) | Recorder, config, lifecycle, sessions, verification, timing semantics | stdlib + Pydantic only |
|
|
17
|
+
| `ponolock.sources` | Discovery, identity resolution, camera/NMEA/simulated sources | lazily (OpenCV, pyserial) |
|
|
18
|
+
| `ponolock.recording` | Recorder, writers, streaming MKV, previews, inspection | lazily (OpenCV, numpy) |
|
|
19
|
+
| `ponolock.sync`, `ponolock.clock` | Association, diagnostics, evidence-gated clock mapping | stdlib |
|
|
20
|
+
| `ponolock.api`, `ponolock.studio`, `ponolock.auth` | Studio workstation (optional extra) | only when Studio starts |
|
|
21
|
+
| `ponolock.benchmarks` | Recording benchmark, synthetic timing research | on demand |
|
|
22
|
+
|
|
23
|
+
Design decisions and their evidence:
|
|
24
|
+
|
|
25
|
+
* **Threads, not processes** for acquisition, encoding and previews: OpenCV releases the
|
|
26
|
+
GIL; measured scaling in [benchmarks](benchmarks.md). See [lifecycle](lifecycle.md).
|
|
27
|
+
* **Bounded queues, drop newest, count everything**: memory is bounded by configuration;
|
|
28
|
+
every loss is visible in status, events, the manifest and the saved sequence.
|
|
29
|
+
* **Original evidence first**: camera MJPEG packets and every GNSS byte are stored as
|
|
30
|
+
received; decoded or re-encoded media is labelled by `recording_mode`.
|
|
31
|
+
* **Streaming MKV muxer**: added after a fault-injection test showed OpenCV's AVI writer can
|
|
32
|
+
leave an empty file after a crash ([operations](operations.md)).
|
|
33
|
+
* **Application policy outside the engine**: GNSS-fix requirements, calibration acceptance
|
|
34
|
+
and dataset rules belong to consumers; `preflight()` reports facts.
|
|
35
|
+
* **Additive session format**: the major version stays 1 so 0.2 readers (including
|
|
36
|
+
AfricaDrive's importer) keep working ([session format](session_format.md)).
|
|
37
|
+
|
|
38
|
+
Studio owns one Recorder and a SQLite metadata store, uses only the public Core API, binds
|
|
39
|
+
to loopback by default and requires local accounts. See [Studio API](studio_api.md) and
|
|
40
|
+
[local database](local_database.md).
|