ponolock 0.3.1__tar.gz
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-0.3.1/.gitignore +194 -0
- ponolock-0.3.1/CHANGELOG.md +75 -0
- ponolock-0.3.1/CITATION.cff +18 -0
- ponolock-0.3.1/CONTRIBUTING.md +40 -0
- ponolock-0.3.1/LICENSE +21 -0
- ponolock-0.3.1/PKG-INFO +181 -0
- ponolock-0.3.1/README.md +104 -0
- ponolock-0.3.1/SECURITY.md +22 -0
- ponolock-0.3.1/benchmarks/scalability.py +13 -0
- ponolock-0.3.1/configs/benchmarks/clock_reset.json +9 -0
- ponolock-0.3.1/configs/benchmarks/low_resource.json +20 -0
- ponolock-0.3.1/configs/mmlove_vk162.json +4 -0
- ponolock-0.3.1/docs/README.md +13 -0
- ponolock-0.3.1/docs/africadrive_and_redundancy.md +101 -0
- ponolock-0.3.1/docs/africadrive_integration_note.md +71 -0
- ponolock-0.3.1/docs/africadrive_integration_prompt.md +149 -0
- ponolock-0.3.1/docs/api.md +118 -0
- ponolock-0.3.1/docs/architecture.md +40 -0
- ponolock-0.3.1/docs/benchmarks/2026-11-18-linux-2vcpu.json +1239 -0
- ponolock-0.3.1/docs/benchmarks.md +92 -0
- ponolock-0.3.1/docs/configuration.md +104 -0
- ponolock-0.3.1/docs/development/plan-0.3.md +81 -0
- ponolock-0.3.1/docs/embedding.md +117 -0
- ponolock-0.3.1/docs/gnss.md +90 -0
- ponolock-0.3.1/docs/hardware_validation.md +114 -0
- ponolock-0.3.1/docs/headless.md +69 -0
- ponolock-0.3.1/docs/implementation_jobs.md +22 -0
- ponolock-0.3.1/docs/installation.md +62 -0
- ponolock-0.3.1/docs/lifecycle.md +104 -0
- ponolock-0.3.1/docs/live_gnss_map.md +44 -0
- ponolock-0.3.1/docs/local_database.md +27 -0
- ponolock-0.3.1/docs/media_pipeline.md +77 -0
- ponolock-0.3.1/docs/migration.md +45 -0
- ponolock-0.3.1/docs/operations.md +89 -0
- ponolock-0.3.1/docs/operator-tools.md +92 -0
- ponolock-0.3.1/docs/physical_acceptance.md +99 -0
- ponolock-0.3.1/docs/plugin_development.md +35 -0
- ponolock-0.3.1/docs/quickstart.md +64 -0
- ponolock-0.3.1/docs/release.md +67 -0
- ponolock-0.3.1/docs/session_format.md +126 -0
- ponolock-0.3.1/docs/studio_api.md +29 -0
- ponolock-0.3.1/docs/synchronization.md +48 -0
- ponolock-0.3.1/docs/timestamps.md +78 -0
- ponolock-0.3.1/docs/troubleshooting.md +58 -0
- ponolock-0.3.1/docs/verification.md +57 -0
- ponolock-0.3.1/examples/camera_only.py +7 -0
- ponolock-0.3.1/examples/consumer_app/README.md +16 -0
- ponolock-0.3.1/examples/consumer_app/pyproject.toml +16 -0
- ponolock-0.3.1/examples/consumer_app/src/trip_logger/__init__.py +1 -0
- ponolock-0.3.1/examples/consumer_app/src/trip_logger/app.py +92 -0
- ponolock-0.3.1/examples/custom_algorithm.py +17 -0
- ponolock-0.3.1/examples/gps_only.py +7 -0
- ponolock-0.3.1/examples/mmlove_vk162.py +19 -0
- ponolock-0.3.1/examples/multi_camera_multi_gnss.py +10 -0
- ponolock-0.3.1/examples/offline_alignment.py +10 -0
- ponolock-0.3.1/examples/simulated_recording.py +11 -0
- ponolock-0.3.1/pyproject.toml +106 -0
- ponolock-0.3.1/research/charter.md +46 -0
- ponolock-0.3.1/research/experiment_protocol.md +30 -0
- ponolock-0.3.1/research/methodology.md +36 -0
- ponolock-0.3.1/research/paper_outline.md +29 -0
- ponolock-0.3.1/research/questions.md +36 -0
- ponolock-0.3.1/src/ponolock/__init__.py +93 -0
- ponolock-0.3.1/src/ponolock/_version.py +3 -0
- ponolock-0.3.1/src/ponolock/api/__init__.py +1 -0
- ponolock-0.3.1/src/ponolock/api/app.py +427 -0
- ponolock-0.3.1/src/ponolock/api/launch.py +78 -0
- ponolock-0.3.1/src/ponolock/api/media.py +206 -0
- ponolock-0.3.1/src/ponolock/api/research.py +184 -0
- ponolock-0.3.1/src/ponolock/api/runtime.py +89 -0
- ponolock-0.3.1/src/ponolock/auth/__init__.py +3 -0
- ponolock-0.3.1/src/ponolock/auth/accounts.py +177 -0
- ponolock-0.3.1/src/ponolock/benchmarks/__init__.py +3 -0
- ponolock-0.3.1/src/ponolock/benchmarks/recording.py +318 -0
- ponolock-0.3.1/src/ponolock/benchmarks/synthetic.py +399 -0
- ponolock-0.3.1/src/ponolock/cli.py +518 -0
- ponolock-0.3.1/src/ponolock/clock/__init__.py +5 -0
- ponolock-0.3.1/src/ponolock/clock/models.py +185 -0
- ponolock-0.3.1/src/ponolock/config.py +26 -0
- ponolock-0.3.1/src/ponolock/documentation.py +47 -0
- ponolock-0.3.1/src/ponolock/errors.py +66 -0
- ponolock-0.3.1/src/ponolock/metrics/__init__.py +29 -0
- ponolock-0.3.1/src/ponolock/metrics/quality.py +35 -0
- ponolock-0.3.1/src/ponolock/metrics/resources.py +40 -0
- ponolock-0.3.1/src/ponolock/models.py +90 -0
- ponolock-0.3.1/src/ponolock/plugins/__init__.py +36 -0
- ponolock-0.3.1/src/ponolock/preflight.py +256 -0
- ponolock-0.3.1/src/ponolock/profiles.py +110 -0
- ponolock-0.3.1/src/ponolock/progress.py +120 -0
- ponolock-0.3.1/src/ponolock/py.typed +0 -0
- ponolock-0.3.1/src/ponolock/recording/__init__.py +3 -0
- ponolock-0.3.1/src/ponolock/recording/inspection.py +312 -0
- ponolock-0.3.1/src/ponolock/recording/lifecycle.py +174 -0
- ponolock-0.3.1/src/ponolock/recording/mkv.py +118 -0
- ponolock-0.3.1/src/ponolock/recording/playback.py +175 -0
- ponolock-0.3.1/src/ponolock/recording/preview.py +196 -0
- ponolock-0.3.1/src/ponolock/recording/recorder.py +1083 -0
- ponolock-0.3.1/src/ponolock/recording/verification.py +342 -0
- ponolock-0.3.1/src/ponolock/recording/writer.py +367 -0
- ponolock-0.3.1/src/ponolock/reporting.py +82 -0
- ponolock-0.3.1/src/ponolock/sources/__init__.py +6 -0
- ponolock-0.3.1/src/ponolock/sources/base.py +22 -0
- ponolock-0.3.1/src/ponolock/sources/camera.py +224 -0
- ponolock-0.3.1/src/ponolock/sources/discovery.py +301 -0
- ponolock-0.3.1/src/ponolock/sources/ffmpeg_probe.py +161 -0
- ponolock-0.3.1/src/ponolock/sources/gnss.py +405 -0
- ponolock-0.3.1/src/ponolock/sources/identity.py +79 -0
- ponolock-0.3.1/src/ponolock/sources/simulated.py +108 -0
- ponolock-0.3.1/src/ponolock/status.py +99 -0
- ponolock-0.3.1/src/ponolock/storage/__init__.py +3 -0
- ponolock-0.3.1/src/ponolock/storage/database.py +132 -0
- ponolock-0.3.1/src/ponolock/storage/importer.py +124 -0
- ponolock-0.3.1/src/ponolock/storage/session.py +215 -0
- ponolock-0.3.1/src/ponolock/studio/static/assets/mark.svg +1 -0
- ponolock-0.3.1/src/ponolock/studio/static/css/studio.css +31 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/api.js +16 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/app.js +142 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/gnss-map-core.js +45 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/gnss-map.js +78 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/media.js +288 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/research.js +79 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/ui.js +72 -0
- ponolock-0.3.1/src/ponolock/studio/static/js/views.js +157 -0
- ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/LICENSE +26 -0
- ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/images/layers-2x.png +0 -0
- ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/images/layers.png +0 -0
- ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/leaflet.css +661 -0
- ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/leaflet.js +6 -0
- ponolock-0.3.1/src/ponolock/studio/templates/index.html +33 -0
- ponolock-0.3.1/src/ponolock/sync/__init__.py +20 -0
- ponolock-0.3.1/src/ponolock/sync/association.py +212 -0
- ponolock-0.3.1/src/ponolock/sync/diagnostics.py +185 -0
- ponolock-0.3.1/src/ponolock/sync/interpolation.py +64 -0
- ponolock-0.3.1/src/ponolock/sync/registry.py +44 -0
- ponolock-0.3.1/src/ponolock/timing.py +160 -0
- ponolock-0.3.1/tests/browser_check.py +168 -0
- ponolock-0.3.1/tests/compat/test_africadrive_contract.py +176 -0
- ponolock-0.3.1/tests/compat/test_legacy_sessions.py +57 -0
- ponolock-0.3.1/tests/conftest.py +5 -0
- ponolock-0.3.1/tests/docs/test_doc_examples.py +41 -0
- ponolock-0.3.1/tests/faults.py +113 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/cameras/front.avi +0 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/cameras/front_frames.csv +16 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/configuration.json +54 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/events/system_events.jsonl +2 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/gnss/gnss_fixes.csv +9 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/gnss/gnss_raw.nmea +8 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/manifest.json +97 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/quality/recording_quality.json +20 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/timing/clock_domains.json +18 -0
- ponolock-0.3.1/tests/fixtures/legacy_0_2_3/timing/clock_mappings.json +4 -0
- ponolock-0.3.1/tests/gnss-map.test.cjs +66 -0
- ponolock-0.3.1/tests/integration/__init__.py +0 -0
- ponolock-0.3.1/tests/integration/conftest.py +20 -0
- ponolock-0.3.1/tests/integration/helpers.py +14 -0
- ponolock-0.3.1/tests/integration/test_api.py +133 -0
- ponolock-0.3.1/tests/integration/test_device_identity.py +27 -0
- ponolock-0.3.1/tests/integration/test_headless.py +195 -0
- ponolock-0.3.1/tests/integration/test_interrupted_recovery.py +86 -0
- ponolock-0.3.1/tests/integration/test_lifecycle_integrity.py +368 -0
- ponolock-0.3.1/tests/integration/test_media.py +240 -0
- ponolock-0.3.1/tests/integration/test_release_regressions.py +71 -0
- ponolock-0.3.1/tests/integration/test_reliability.py +197 -0
- ponolock-0.3.1/tests/integration/test_stream_mkv.py +173 -0
- ponolock-0.3.1/tests/release/inspect_artifacts.py +91 -0
- ponolock-0.3.1/tests/release/smoke.py +185 -0
- ponolock-0.3.1/tests/synthetic/test_benchmarks.py +44 -0
- ponolock-0.3.1/tests/unit/test_core.py +105 -0
- ponolock-0.3.1/tests/unit/test_discovery_identity.py +174 -0
- ponolock-0.3.1/tests/unit/test_gnss.py +244 -0
- ponolock-0.3.1/tests/unit/test_operator_tools.py +102 -0
- ponolock-0.3.1/tests/unit/test_sync_diagnostics.py +56 -0
- ponolock-0.3.1/tests/unit/test_synchronization.py +84 -0
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
share/python-wheels/
|
|
24
|
+
*.egg-info/
|
|
25
|
+
.installed.cfg
|
|
26
|
+
*.egg
|
|
27
|
+
MANIFEST
|
|
28
|
+
|
|
29
|
+
# PyInstaller
|
|
30
|
+
# Usually these files are written by a python script from a template
|
|
31
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
32
|
+
*.manifest
|
|
33
|
+
*.spec
|
|
34
|
+
|
|
35
|
+
# Installer logs
|
|
36
|
+
pip-log.txt
|
|
37
|
+
pip-delete-this-directory.txt
|
|
38
|
+
|
|
39
|
+
# Unit test / coverage reports
|
|
40
|
+
htmlcov/
|
|
41
|
+
.tox/
|
|
42
|
+
.nox/
|
|
43
|
+
.coverage
|
|
44
|
+
.coverage.*
|
|
45
|
+
.cache
|
|
46
|
+
nosetests.xml
|
|
47
|
+
coverage.xml
|
|
48
|
+
*.cover
|
|
49
|
+
*.py,cover
|
|
50
|
+
.hypothesis/
|
|
51
|
+
.pytest_cache/
|
|
52
|
+
cover/
|
|
53
|
+
|
|
54
|
+
# Translations
|
|
55
|
+
*.mo
|
|
56
|
+
*.pot
|
|
57
|
+
|
|
58
|
+
# Django stuff:
|
|
59
|
+
*.log
|
|
60
|
+
local_settings.py
|
|
61
|
+
db.sqlite3
|
|
62
|
+
db.sqlite3-journal
|
|
63
|
+
|
|
64
|
+
# Flask stuff:
|
|
65
|
+
instance/
|
|
66
|
+
.webassets-cache
|
|
67
|
+
|
|
68
|
+
# Scrapy stuff:
|
|
69
|
+
.scrapy
|
|
70
|
+
|
|
71
|
+
# Sphinx documentation
|
|
72
|
+
docs/_build/
|
|
73
|
+
|
|
74
|
+
# PyBuilder
|
|
75
|
+
.pybuilder/
|
|
76
|
+
target/
|
|
77
|
+
|
|
78
|
+
# Jupyter Notebook
|
|
79
|
+
.ipynb_checkpoints
|
|
80
|
+
|
|
81
|
+
# IPython
|
|
82
|
+
profile_default/
|
|
83
|
+
ipython_config.py
|
|
84
|
+
|
|
85
|
+
# pyenv
|
|
86
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
87
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
88
|
+
# .python-version
|
|
89
|
+
|
|
90
|
+
# pipenv
|
|
91
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
92
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
93
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
94
|
+
# install all needed dependencies.
|
|
95
|
+
#Pipfile.lock
|
|
96
|
+
|
|
97
|
+
# UV
|
|
98
|
+
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
|
|
99
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
100
|
+
# commonly ignored for libraries.
|
|
101
|
+
#uv.lock
|
|
102
|
+
|
|
103
|
+
# poetry
|
|
104
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
105
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
106
|
+
# commonly ignored for libraries.
|
|
107
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
108
|
+
#poetry.lock
|
|
109
|
+
|
|
110
|
+
# pdm
|
|
111
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
112
|
+
#pdm.lock
|
|
113
|
+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
|
|
114
|
+
# in version control.
|
|
115
|
+
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
|
|
116
|
+
.pdm.toml
|
|
117
|
+
.pdm-python
|
|
118
|
+
.pdm-build/
|
|
119
|
+
|
|
120
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
121
|
+
__pypackages__/
|
|
122
|
+
|
|
123
|
+
# Celery stuff
|
|
124
|
+
celerybeat-schedule
|
|
125
|
+
celerybeat.pid
|
|
126
|
+
|
|
127
|
+
# SageMath parsed files
|
|
128
|
+
*.sage.py
|
|
129
|
+
|
|
130
|
+
# Environments
|
|
131
|
+
.env
|
|
132
|
+
.venv
|
|
133
|
+
env/
|
|
134
|
+
venv/
|
|
135
|
+
ENV/
|
|
136
|
+
env.bak/
|
|
137
|
+
venv.bak/
|
|
138
|
+
|
|
139
|
+
# Spyder project settings
|
|
140
|
+
.spyderproject
|
|
141
|
+
.spyproject
|
|
142
|
+
|
|
143
|
+
# Rope project settings
|
|
144
|
+
.ropeproject
|
|
145
|
+
|
|
146
|
+
# mkdocs documentation
|
|
147
|
+
/site
|
|
148
|
+
|
|
149
|
+
# mypy
|
|
150
|
+
.mypy_cache/
|
|
151
|
+
.dmypy.json
|
|
152
|
+
dmypy.json
|
|
153
|
+
|
|
154
|
+
# Pyre type checker
|
|
155
|
+
.pyre/
|
|
156
|
+
|
|
157
|
+
# pytype static type analyzer
|
|
158
|
+
.pytype/
|
|
159
|
+
|
|
160
|
+
# Cython debug symbols
|
|
161
|
+
cython_debug/
|
|
162
|
+
|
|
163
|
+
# PyCharm
|
|
164
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
165
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
166
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
167
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
168
|
+
#.idea/
|
|
169
|
+
|
|
170
|
+
# Ruff stuff:
|
|
171
|
+
.ruff_cache/
|
|
172
|
+
|
|
173
|
+
# PyPI configuration file
|
|
174
|
+
.pypirc
|
|
175
|
+
|
|
176
|
+
# Cursor
|
|
177
|
+
# Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to
|
|
178
|
+
# exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
|
|
179
|
+
# refer to https://docs.cursor.com/context/ignore-files
|
|
180
|
+
.cursorignore
|
|
181
|
+
.cursorindexingignore
|
|
182
|
+
|
|
183
|
+
# Local research data and credentials (never commit locations or sessions)
|
|
184
|
+
recordings/
|
|
185
|
+
.ponolock/
|
|
186
|
+
artifacts/
|
|
187
|
+
*.sqlite3
|
|
188
|
+
*.sqlite3-*
|
|
189
|
+
*.db
|
|
190
|
+
*.db-*
|
|
191
|
+
playwright-report/
|
|
192
|
+
test-results/
|
|
193
|
+
.venv311/
|
|
194
|
+
*.local.json
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
|
|
5
|
+
[Semantic Versioning](https://semver.org/) as described in `docs/release.md`.
|
|
6
|
+
|
|
7
|
+
## [0.3.1] - 2026-11-18
|
|
8
|
+
|
|
9
|
+
- Recover per media file/index; preserve gaps when segments are missing. Withhold
|
|
10
|
+
ambiguous mappings instead of assigning the wrong timestamps to surviving frames.
|
|
11
|
+
- Fsync each rollover segment before publishing it closed; propagate flush failures.
|
|
12
|
+
- Preserve already-received GNSS shutdown tails and their actual receipt times.
|
|
13
|
+
- Add strict versioned profiles, guided read-only setup, migration and schema commands.
|
|
14
|
+
- Add consumer-owned progress events and CLI bars/JSON progress for recording,
|
|
15
|
+
verification, hashing, inspection, recovery, reporting and benchmarks.
|
|
16
|
+
- Add redacted JSON/HTML/ZIP diagnostic reports and bundled offline documentation.
|
|
17
|
+
- Gate publication on the full Linux/Windows checks; isolate TestPyPI project downloads.
|
|
18
|
+
- Fix a Studio map renderer teardown race detected by the real-browser workflow.
|
|
19
|
+
- AfricaDrive must allow tied GNSS receipts from serial batches; do not synthesize times.
|
|
20
|
+
Hardware timing/accuracy/endurance acceptance remains separate and unrun.
|
|
21
|
+
|
|
22
|
+
## [0.3.0] - 2026-11-18
|
|
23
|
+
|
|
24
|
+
Unpublished release candidate. Session format 1.1 (additive over 1.0).
|
|
25
|
+
See `docs/migration.md` for behaviour changes.
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
- Read-only discovery (`list_cameras`, `list_serial_ports`, `list_devices`, `DeviceInfo`)
|
|
29
|
+
with identity basis, stability and limitations; explicit `probe_camera`.
|
|
30
|
+
- Identity resolution on every open/reconnect with no fallback (`DeviceIdentityError`).
|
|
31
|
+
- Typed exception hierarchy subclassing the builtin types raised by 0.2.
|
|
32
|
+
- Explicit lifecycle state machine (`RecorderState`), `abort()`, `close()`, `status()`
|
|
33
|
+
(`RecorderStatus`/`SourceStatus`), bounded `subscribe()` event queues, `preflight()`.
|
|
34
|
+
- `RecordingOptions`: disk reserve with live monitor, opt-in rollover, flush/fsync
|
|
35
|
+
policy, drain/join/stall timeouts.
|
|
36
|
+
- Session states `partial`, `aborted`, `failed` and derived `interrupted` (recording lock).
|
|
37
|
+
- Per-source accounting (`acquired = written + queue_dropped + writer_dropped`).
|
|
38
|
+
- `muxer="stream_mkv"`: crash-tolerant streaming Matroska for MJPEG packets, byte-exact.
|
|
39
|
+
- `inspect_session` / `recover_session` (non-destructive, hash-proven) and CLI
|
|
40
|
+
`verify`, `inspect`, `recover`, `diagnose`, `preflight`, `benchmark-recording`.
|
|
41
|
+
- Byte-exact NMEA framing, solution-epoch grouping, GNSS time segments, course over
|
|
42
|
+
ground, passive receiver adapter interface.
|
|
43
|
+
- Timestamp provenance (`timing/timestamp_semantics.json`), capability-gated Linux V4L2
|
|
44
|
+
driver timestamps, read-start times, serial first/last-byte receipt times.
|
|
45
|
+
- Synchronization diagnostics and held-out clock-mapping evaluation.
|
|
46
|
+
- Preview decoding of undecoded MJPEG packets on the preview thread at reduced scale.
|
|
47
|
+
- `camera-headless` extra; OpenCV 5 support (tested in CI).
|
|
48
|
+
- Recording-pipeline benchmark harness and published measurements.
|
|
49
|
+
- Documentation set (installation, quickstarts, embedding, API, configuration, lifecycle,
|
|
50
|
+
timing, GNSS, session format, operations, benchmarks, physical acceptance, migration,
|
|
51
|
+
release) with executed examples; example consumer application.
|
|
52
|
+
- AfricaDrive contract tests and a 0.2.3 legacy-session fixture.
|
|
53
|
+
- Trusted-publishing release workflow with TestPyPI stage and artifact inspection.
|
|
54
|
+
|
|
55
|
+
### Changed
|
|
56
|
+
- `discover_cameras()` no longer opens camera streams by default.
|
|
57
|
+
- `complete_with_errors` is now written as `partial` (old value still read).
|
|
58
|
+
- Timing rows are handed to the OS every row (was every 20 rows).
|
|
59
|
+
- CLI `record` disables unused previews and exits 3 unless the session is `complete`.
|
|
60
|
+
- Simulated GNSS emits RMC+GGA epochs at a synthetic open-ocean location.
|
|
61
|
+
- Single-sourced version; fixed stale versions in CLI, manifests and Studio.
|
|
62
|
+
|
|
63
|
+
### Fixed
|
|
64
|
+
- Partial serial reads split one NMEA sentence into two malformed records.
|
|
65
|
+
- GNSS time-of-day parsing ignored values with a UTC offset suffix.
|
|
66
|
+
- CI formatting/mypy failures on Linux.
|
|
67
|
+
|
|
68
|
+
## [0.2.3] - 2026-11-12
|
|
69
|
+
Downstream physical-test corrections (see `docs/headless.md`). Not published to PyPI.
|
|
70
|
+
|
|
71
|
+
## [0.2.0] – [0.2.2]
|
|
72
|
+
Headless taps, offline reconciliation, raw serial bytes, NMEA validation. Not published.
|
|
73
|
+
|
|
74
|
+
## [0.1.0] - 2026-11-07
|
|
75
|
+
Initial research release (Core, Studio, Research). Not published to PyPI.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: Please cite the software version and commit used in your experiments.
|
|
3
|
+
title: 'PonoLock: Uncertainty-Aware Temporal Alignment of Low-Cost Camera and GNSS Networks'
|
|
4
|
+
type: software
|
|
5
|
+
authors:
|
|
6
|
+
- family-names: Motsoehli
|
|
7
|
+
given-names: Moseli
|
|
8
|
+
- name: PonoLock contributors
|
|
9
|
+
version: 0.1.0
|
|
10
|
+
date-released: '2026-11-07'
|
|
11
|
+
repository-code: 'https://github.com/Mind-Forge-AI/PonoLock'
|
|
12
|
+
license: MIT
|
|
13
|
+
keywords:
|
|
14
|
+
- synchronization
|
|
15
|
+
- GNSS
|
|
16
|
+
- uncertainty
|
|
17
|
+
- sensor networks
|
|
18
|
+
- African research
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
PonoLock welcomes research, engineering, documentation and hardware-validation
|
|
4
|
+
contributions. Begin with a reproducible problem or a falsifiable experimental question.
|
|
5
|
+
Follow the [research charter](research/charter.md) and preserve application independence.
|
|
6
|
+
|
|
7
|
+
```powershell
|
|
8
|
+
py -3.11 -m venv .venv
|
|
9
|
+
.venv\Scripts\python -m pip install -e ".[all,dev]"
|
|
10
|
+
.venv\Scripts\python -m pytest -q
|
|
11
|
+
.venv\Scripts\python -m ruff check src tests examples benchmarks
|
|
12
|
+
.venv\Scripts\python -m ruff format --check src tests examples benchmarks
|
|
13
|
+
.venv\Scripts\python -m mypy src/ponolock
|
|
14
|
+
.venv\Scripts\python -m build
|
|
15
|
+
.venv\Scripts\python tests\release\inspect_artifacts.py dist
|
|
16
|
+
.venv\Scripts\python tests\release\smoke.py (Get-Item dist\*.whl)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Tests are organised as `tests/unit` (pure logic), `tests/integration` (real recorder
|
|
20
|
+
threads, files and decoding with simulated or fault-injecting sources from
|
|
21
|
+
`tests/faults.py`), `tests/compat` (0.2.3 sessions and the AfricaDrive contract),
|
|
22
|
+
`tests/docs` (executes documentation examples marked `<!-- doctest -->`), `tests/synthetic`
|
|
23
|
+
(research benchmarks) and `tests/release` (artifact inspection and clean-environment
|
|
24
|
+
smoke tests). Assertions must check saved content (decoded pixels, raw bytes, rows), not
|
|
25
|
+
only the recorder's own counters. Simulations are never presented as hardware evidence.
|
|
26
|
+
|
|
27
|
+
Real-browser verification: `python -m playwright install chromium`, then
|
|
28
|
+
`python tests/browser_check.py`. It uses temporary accounts and simulated devices.
|
|
29
|
+
`--executable PATH` can use an existing Chromium installation.
|
|
30
|
+
|
|
31
|
+
Keep optional dependencies lazy, respect public interfaces, validate configuration, and
|
|
32
|
+
test meaningful lifecycle/failure cases. New drivers and algorithms must state their
|
|
33
|
+
timing evidence, unknowns, boundedness and failure behavior. Do not replace missing
|
|
34
|
+
historical observations with current timestamps. Review UI keyboard access and test
|
|
35
|
+
backend authorization independently of navigation visibility.
|
|
36
|
+
|
|
37
|
+
Pull requests should explain the concrete problem and resulting behavior, validation,
|
|
38
|
+
scientific limits and any hardware-specific assumptions. Do not commit recordings,
|
|
39
|
+
credentials, raw positions, private images, personal databases or machine-specific device
|
|
40
|
+
identifiers. Release process and versioning: see `docs/release.md`. Existing MIT licensing applies to contributions unless separately agreed.
|
ponolock-0.3.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Moseli Motsoehli
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
ponolock-0.3.1/PKG-INFO
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ponolock
|
|
3
|
+
Version: 0.3.1
|
|
4
|
+
Summary: Dependable multicamera and GNSS recording with explicit timestamp provenance, loss accounting and offline verification
|
|
5
|
+
Project-URL: Homepage, https://github.com/Mind-Forge-AI/PonoLock
|
|
6
|
+
Project-URL: Documentation, https://pypi.org/project/ponolock/#description
|
|
7
|
+
Project-URL: Repository, https://github.com/Mind-Forge-AI/PonoLock
|
|
8
|
+
Project-URL: Changelog, https://github.com/Mind-Forge-AI/PonoLock/blob/main/CHANGELOG.md
|
|
9
|
+
Project-URL: Issues, https://github.com/Mind-Forge-AI/PonoLock/issues
|
|
10
|
+
Author: Moseli Motsoehli, PonoLock contributors
|
|
11
|
+
Maintainer: Mindforge AI
|
|
12
|
+
License-Expression: MIT
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Keywords: camera,data-acquisition,gnss,gps,nmea,recording,stereo,synchronization,timestamps
|
|
15
|
+
Classifier: Development Status :: 3 - Alpha
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Intended Audience :: Science/Research
|
|
18
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
19
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Topic :: Multimedia :: Video :: Capture
|
|
26
|
+
Classifier: Topic :: Scientific/Engineering
|
|
27
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
28
|
+
Classifier: Typing :: Typed
|
|
29
|
+
Requires-Python: >=3.11
|
|
30
|
+
Requires-Dist: pydantic<3,>=2.10
|
|
31
|
+
Provides-Extra: all
|
|
32
|
+
Requires-Dist: argon2-cffi<26,>=23.1; extra == 'all'
|
|
33
|
+
Requires-Dist: cv2-enumerate-cameras<2,>=1.1; extra == 'all'
|
|
34
|
+
Requires-Dist: fastapi<1,>=0.115; extra == 'all'
|
|
35
|
+
Requires-Dist: markdown<4,>=3.7; extra == 'all'
|
|
36
|
+
Requires-Dist: matplotlib<4,>=3.9; extra == 'all'
|
|
37
|
+
Requires-Dist: numpy<3,>=1.26; extra == 'all'
|
|
38
|
+
Requires-Dist: opencv-python<6,>=4.10; extra == 'all'
|
|
39
|
+
Requires-Dist: pynmea2<2,>=1.19; extra == 'all'
|
|
40
|
+
Requires-Dist: pyserial<4,>=3.5; extra == 'all'
|
|
41
|
+
Requires-Dist: uvicorn<1,>=0.32; extra == 'all'
|
|
42
|
+
Requires-Dist: websockets<17,>=14; extra == 'all'
|
|
43
|
+
Provides-Extra: camera
|
|
44
|
+
Requires-Dist: cv2-enumerate-cameras<2,>=1.1; extra == 'camera'
|
|
45
|
+
Requires-Dist: numpy<3,>=1.26; extra == 'camera'
|
|
46
|
+
Requires-Dist: opencv-python<6,>=4.10; extra == 'camera'
|
|
47
|
+
Provides-Extra: camera-headless
|
|
48
|
+
Requires-Dist: cv2-enumerate-cameras<2,>=1.1; extra == 'camera-headless'
|
|
49
|
+
Requires-Dist: numpy<3,>=1.26; extra == 'camera-headless'
|
|
50
|
+
Requires-Dist: opencv-python-headless<6,>=4.10; extra == 'camera-headless'
|
|
51
|
+
Provides-Extra: dev
|
|
52
|
+
Requires-Dist: build<2,>=1.2; extra == 'dev'
|
|
53
|
+
Requires-Dist: httpx<1,>=0.28; extra == 'dev'
|
|
54
|
+
Requires-Dist: mypy<2,>=1.14; extra == 'dev'
|
|
55
|
+
Requires-Dist: pip-audit<3,>=2.7; extra == 'dev'
|
|
56
|
+
Requires-Dist: playwright<2,>=1.50; extra == 'dev'
|
|
57
|
+
Requires-Dist: pytest<10,>=8.3; extra == 'dev'
|
|
58
|
+
Requires-Dist: ruff<1,>=0.11; extra == 'dev'
|
|
59
|
+
Requires-Dist: twine<8,>=6.1; extra == 'dev'
|
|
60
|
+
Requires-Dist: types-markdown<4,>=3.7; extra == 'dev'
|
|
61
|
+
Provides-Extra: docs
|
|
62
|
+
Requires-Dist: markdown<4,>=3.7; extra == 'docs'
|
|
63
|
+
Provides-Extra: gnss
|
|
64
|
+
Requires-Dist: pynmea2<2,>=1.19; extra == 'gnss'
|
|
65
|
+
Requires-Dist: pyserial<4,>=3.5; extra == 'gnss'
|
|
66
|
+
Provides-Extra: parquet
|
|
67
|
+
Requires-Dist: pyarrow<24,>=18; extra == 'parquet'
|
|
68
|
+
Provides-Extra: research
|
|
69
|
+
Requires-Dist: matplotlib<4,>=3.9; extra == 'research'
|
|
70
|
+
Requires-Dist: numpy<3,>=1.26; extra == 'research'
|
|
71
|
+
Provides-Extra: studio
|
|
72
|
+
Requires-Dist: argon2-cffi<26,>=23.1; extra == 'studio'
|
|
73
|
+
Requires-Dist: fastapi<1,>=0.115; extra == 'studio'
|
|
74
|
+
Requires-Dist: uvicorn<1,>=0.32; extra == 'studio'
|
|
75
|
+
Requires-Dist: websockets<17,>=14; extra == 'studio'
|
|
76
|
+
Description-Content-Type: text/markdown
|
|
77
|
+
|
|
78
|
+
# PonoLock
|
|
79
|
+
|
|
80
|
+
**Dependable multicamera and GNSS recording that tells you exactly what its timestamps
|
|
81
|
+
mean, what it lost, and what it cannot know.**
|
|
82
|
+
|
|
83
|
+
PonoLock records any number of USB cameras (including side-by-side stereo) and serial
|
|
84
|
+
NMEA GNSS receivers concurrently, from one Python library. It preserves original camera
|
|
85
|
+
MJPEG packets and every received GNSS byte, keeps each kind of timestamp separate with
|
|
86
|
+
its provenance, accounts for every observation it acquired, and verifies sessions
|
|
87
|
+
offline. The same engine powers the command line, an optional local Studio and your own
|
|
88
|
+
applications.
|
|
89
|
+
|
|
90
|
+
[](https://pypi.org/project/ponolock/)
|
|
91
|
+
[](https://pypi.org/project/ponolock/)
|
|
92
|
+
[](https://github.com/Mind-Forge-AI/PonoLock/actions/workflows/ci.yml)
|
|
93
|
+
|
|
94
|
+
```console
|
|
95
|
+
pip install "ponolock[camera,gnss]"
|
|
96
|
+
ponolock record --simulate --duration 5 --muxer stream_mkv
|
|
97
|
+
ponolock verify recordings/session_*
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Embed it
|
|
101
|
+
|
|
102
|
+
<!-- doctest -->
|
|
103
|
+
```python
|
|
104
|
+
import tempfile, time
|
|
105
|
+
from ponolock import Recorder, RecordingOptions, SensorConfig, verify_session
|
|
106
|
+
|
|
107
|
+
recorder = Recorder(tempfile.mkdtemp(), preview_enabled=False,
|
|
108
|
+
options=RecordingOptions(disk_reserve_bytes=0))
|
|
109
|
+
recorder.add_source(SensorConfig(name="front", kind="camera", simulated=True,
|
|
110
|
+
width=320, height=240, fps=15, muxer="stream_mkv"))
|
|
111
|
+
recorder.add_source(SensorConfig(name="gnss", kind="gnss", simulated=True))
|
|
112
|
+
with recorder:
|
|
113
|
+
session = recorder.start()
|
|
114
|
+
time.sleep(1)
|
|
115
|
+
print(verify_session(session)["software_reconciliation_passed"]) # True
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
For real devices, bind identities from `ponolock devices` (which opens nothing) with
|
|
119
|
+
`SensorConfig(persistent_id=...)`. PonoLock never silently switches to another camera or
|
|
120
|
+
receiver when indexes or COM numbers change.
|
|
121
|
+
|
|
122
|
+
## What is supported
|
|
123
|
+
|
|
124
|
+
| Capability | Status |
|
|
125
|
+
|---|---|
|
|
126
|
+
| N cameras + M GNSS receivers, one acquisition owner per device | Implemented |
|
|
127
|
+
| UVC cameras via OpenCV (DirectShow/MSMF on Windows, V4L2 on Linux); side-by-side stereo | Implemented |
|
|
128
|
+
| MJPEG packet passthrough; JPEG re-encode; lossless FFV1 | Implemented (FFV1 is CPU-bound, see benchmarks) |
|
|
129
|
+
| Crash-tolerant streaming MKV, rollover, disk reserve, recovery of interrupted sessions | Implemented |
|
|
130
|
+
| Serial NMEA with byte-exact raw logs, epoch grouping, validity/staleness | Implemented |
|
|
131
|
+
| Host receipt timestamps (all sources); Linux V4L2 driver timestamps | Implemented; V4L2 hardware-unvalidated |
|
|
132
|
+
| Exposure timestamps, hardware triggering, PPS capture | **Not implemented** |
|
|
133
|
+
| Exposure synchronization, positioning accuracy, sensor fusion | **Not claimed** |
|
|
134
|
+
| Python 3.11–3.13 on Windows and Linux | Tested in CI (software only) |
|
|
135
|
+
|
|
136
|
+
Physical validation status and procedures: [physical acceptance](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/physical_acceptance.md).
|
|
137
|
+
Measured software throughput: [benchmarks](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/benchmarks.md).
|
|
138
|
+
|
|
139
|
+
## Documentation
|
|
140
|
+
|
|
141
|
+
Full documentation ships in the package, including when the source repository is private:
|
|
142
|
+
|
|
143
|
+
```console
|
|
144
|
+
pip install "ponolock[docs]"
|
|
145
|
+
ponolock docs --output ponolock-manual
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Open `ponolock-manual/index.html`. Guided configuration: `ponolock setup`.
|
|
149
|
+
Progress bars are enabled by default; `--progress-json` supports integrations.
|
|
150
|
+
`ponolock report SESSION --output REPORT_DIR` writes redacted JSON, HTML and ZIP.
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
* [Installation and extras](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/installation.md) ·
|
|
154
|
+
[Quickstart (simulation and real devices)](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/quickstart.md)
|
|
155
|
+
* [Embedding in Python](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/embedding.md) ·
|
|
156
|
+
[API reference](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/api.md) ·
|
|
157
|
+
[Configuration and device identity](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/configuration.md)
|
|
158
|
+
* [Lifecycle, ownership and concurrency](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/lifecycle.md) ·
|
|
159
|
+
[Timestamps and synchronization evidence](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/timestamps.md) ·
|
|
160
|
+
[GNSS semantics](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/gnss.md)
|
|
161
|
+
* [Session format](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/session_format.md) ·
|
|
162
|
+
[Long sessions, durability, recovery, troubleshooting](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/operations.md)
|
|
163
|
+
* [Migration from 0.2](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/migration.md) ·
|
|
164
|
+
[Release and versioning policy](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/release.md) ·
|
|
165
|
+
[Changelog](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CHANGELOG.md) ·
|
|
166
|
+
[Contributing](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CONTRIBUTING.md)
|
|
167
|
+
* Studio and research: [Studio](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/studio_api.md),
|
|
168
|
+
[synchronization research methods](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/synchronization.md),
|
|
169
|
+
[research charter](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/research/charter.md)
|
|
170
|
+
|
|
171
|
+
## Honest limits
|
|
172
|
+
|
|
173
|
+
A common host clock, configured FPS, nearest-neighbour matching or visually aligned
|
|
174
|
+
previews do not prove exposure synchronization. Host receipt time follows exposure by an
|
|
175
|
+
unknown delay. HDOP and satellite count are not accuracy. Zero queue drops is not zero
|
|
176
|
+
device-side loss. Unknown uncertainty is recorded as unknown, never zero, and gaps are
|
|
177
|
+
never filled by interpolation.
|
|
178
|
+
|
|
179
|
+
PonoLock was motivated by data-integrity needs in the AfricaDrive dataset project and is
|
|
180
|
+
developed independently of it. Images, positions and credentials stay local; PonoLock has
|
|
181
|
+
no telemetry. MIT licensed.
|
ponolock-0.3.1/README.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# PonoLock
|
|
2
|
+
|
|
3
|
+
**Dependable multicamera and GNSS recording that tells you exactly what its timestamps
|
|
4
|
+
mean, what it lost, and what it cannot know.**
|
|
5
|
+
|
|
6
|
+
PonoLock records any number of USB cameras (including side-by-side stereo) and serial
|
|
7
|
+
NMEA GNSS receivers concurrently, from one Python library. It preserves original camera
|
|
8
|
+
MJPEG packets and every received GNSS byte, keeps each kind of timestamp separate with
|
|
9
|
+
its provenance, accounts for every observation it acquired, and verifies sessions
|
|
10
|
+
offline. The same engine powers the command line, an optional local Studio and your own
|
|
11
|
+
applications.
|
|
12
|
+
|
|
13
|
+
[](https://pypi.org/project/ponolock/)
|
|
14
|
+
[](https://pypi.org/project/ponolock/)
|
|
15
|
+
[](https://github.com/Mind-Forge-AI/PonoLock/actions/workflows/ci.yml)
|
|
16
|
+
|
|
17
|
+
```console
|
|
18
|
+
pip install "ponolock[camera,gnss]"
|
|
19
|
+
ponolock record --simulate --duration 5 --muxer stream_mkv
|
|
20
|
+
ponolock verify recordings/session_*
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Embed it
|
|
24
|
+
|
|
25
|
+
<!-- doctest -->
|
|
26
|
+
```python
|
|
27
|
+
import tempfile, time
|
|
28
|
+
from ponolock import Recorder, RecordingOptions, SensorConfig, verify_session
|
|
29
|
+
|
|
30
|
+
recorder = Recorder(tempfile.mkdtemp(), preview_enabled=False,
|
|
31
|
+
options=RecordingOptions(disk_reserve_bytes=0))
|
|
32
|
+
recorder.add_source(SensorConfig(name="front", kind="camera", simulated=True,
|
|
33
|
+
width=320, height=240, fps=15, muxer="stream_mkv"))
|
|
34
|
+
recorder.add_source(SensorConfig(name="gnss", kind="gnss", simulated=True))
|
|
35
|
+
with recorder:
|
|
36
|
+
session = recorder.start()
|
|
37
|
+
time.sleep(1)
|
|
38
|
+
print(verify_session(session)["software_reconciliation_passed"]) # True
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
For real devices, bind identities from `ponolock devices` (which opens nothing) with
|
|
42
|
+
`SensorConfig(persistent_id=...)`. PonoLock never silently switches to another camera or
|
|
43
|
+
receiver when indexes or COM numbers change.
|
|
44
|
+
|
|
45
|
+
## What is supported
|
|
46
|
+
|
|
47
|
+
| Capability | Status |
|
|
48
|
+
|---|---|
|
|
49
|
+
| N cameras + M GNSS receivers, one acquisition owner per device | Implemented |
|
|
50
|
+
| UVC cameras via OpenCV (DirectShow/MSMF on Windows, V4L2 on Linux); side-by-side stereo | Implemented |
|
|
51
|
+
| MJPEG packet passthrough; JPEG re-encode; lossless FFV1 | Implemented (FFV1 is CPU-bound, see benchmarks) |
|
|
52
|
+
| Crash-tolerant streaming MKV, rollover, disk reserve, recovery of interrupted sessions | Implemented |
|
|
53
|
+
| Serial NMEA with byte-exact raw logs, epoch grouping, validity/staleness | Implemented |
|
|
54
|
+
| Host receipt timestamps (all sources); Linux V4L2 driver timestamps | Implemented; V4L2 hardware-unvalidated |
|
|
55
|
+
| Exposure timestamps, hardware triggering, PPS capture | **Not implemented** |
|
|
56
|
+
| Exposure synchronization, positioning accuracy, sensor fusion | **Not claimed** |
|
|
57
|
+
| Python 3.11–3.13 on Windows and Linux | Tested in CI (software only) |
|
|
58
|
+
|
|
59
|
+
Physical validation status and procedures: [physical acceptance](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/physical_acceptance.md).
|
|
60
|
+
Measured software throughput: [benchmarks](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/benchmarks.md).
|
|
61
|
+
|
|
62
|
+
## Documentation
|
|
63
|
+
|
|
64
|
+
Full documentation ships in the package, including when the source repository is private:
|
|
65
|
+
|
|
66
|
+
```console
|
|
67
|
+
pip install "ponolock[docs]"
|
|
68
|
+
ponolock docs --output ponolock-manual
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Open `ponolock-manual/index.html`. Guided configuration: `ponolock setup`.
|
|
72
|
+
Progress bars are enabled by default; `--progress-json` supports integrations.
|
|
73
|
+
`ponolock report SESSION --output REPORT_DIR` writes redacted JSON, HTML and ZIP.
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
* [Installation and extras](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/installation.md) ·
|
|
77
|
+
[Quickstart (simulation and real devices)](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/quickstart.md)
|
|
78
|
+
* [Embedding in Python](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/embedding.md) ·
|
|
79
|
+
[API reference](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/api.md) ·
|
|
80
|
+
[Configuration and device identity](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/configuration.md)
|
|
81
|
+
* [Lifecycle, ownership and concurrency](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/lifecycle.md) ·
|
|
82
|
+
[Timestamps and synchronization evidence](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/timestamps.md) ·
|
|
83
|
+
[GNSS semantics](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/gnss.md)
|
|
84
|
+
* [Session format](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/session_format.md) ·
|
|
85
|
+
[Long sessions, durability, recovery, troubleshooting](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/operations.md)
|
|
86
|
+
* [Migration from 0.2](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/migration.md) ·
|
|
87
|
+
[Release and versioning policy](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/release.md) ·
|
|
88
|
+
[Changelog](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CHANGELOG.md) ·
|
|
89
|
+
[Contributing](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CONTRIBUTING.md)
|
|
90
|
+
* Studio and research: [Studio](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/studio_api.md),
|
|
91
|
+
[synchronization research methods](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/synchronization.md),
|
|
92
|
+
[research charter](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/research/charter.md)
|
|
93
|
+
|
|
94
|
+
## Honest limits
|
|
95
|
+
|
|
96
|
+
A common host clock, configured FPS, nearest-neighbour matching or visually aligned
|
|
97
|
+
previews do not prove exposure synchronization. Host receipt time follows exposure by an
|
|
98
|
+
unknown delay. HDOP and satellite count are not accuracy. Zero queue drops is not zero
|
|
99
|
+
device-side loss. Unknown uncertainty is recorded as unknown, never zero, and gaps are
|
|
100
|
+
never filled by interpolation.
|
|
101
|
+
|
|
102
|
+
PonoLock was motivated by data-integrity needs in the AfricaDrive dataset project and is
|
|
103
|
+
developed independently of it. Images, positions and credentials stay local; PonoLock has
|
|
104
|
+
no telemetry. MIT licensed.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
Studio binds `127.0.0.1` by default. Authentication is entirely local. First-run setup
|
|
4
|
+
uses a one-time token delivered in a browser fragment (not a request URL), or an
|
|
5
|
+
interactive local CLI. No shipped passwords, cloud identity, analytics or uploads exist.
|
|
6
|
+
|
|
7
|
+
Password hashes use Argon2id. Browser sessions use random tokens stored hashed in
|
|
8
|
+
SQLite, absolute expiration, HttpOnly/SameSite=Strict cookies, CSRF checks and role
|
|
9
|
+
authorization. Login is limited per client. SQLite connections use parameterized values;
|
|
10
|
+
recording identifiers and file paths are constrained. The frontend has a self-only CSP.
|
|
11
|
+
HTTP loopback cookies deliberately omit Secure because the default transport is local
|
|
12
|
+
HTTP. Explicit remote access requires TLS certificate/key, secure cookies and
|
|
13
|
+
`--allow-remote`. Remote hosting has not been penetration-tested or deployed.
|
|
14
|
+
|
|
15
|
+
Operating-system access to the data directory permits account recovery and access to
|
|
16
|
+
recordings. Protect OS accounts, disks and backups accordingly. Account recovery revokes
|
|
17
|
+
existing sessions. Keep credentials, session cookies, setup fragments, images and location
|
|
18
|
+
logs out of issues, screenshots and public artifacts.
|
|
19
|
+
|
|
20
|
+
Report vulnerabilities privately to the repository maintainers using GitHub private
|
|
21
|
+
security reporting when available. Include a minimal reproduction without private data.
|
|
22
|
+
Do not disclose live credentials or tokens in a public issue.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""Run independently reproducible scaling conditions; compare artifacts across runs."""
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
|
|
5
|
+
from ponolock.benchmarks import SyntheticConfig, run_benchmark
|
|
6
|
+
|
|
7
|
+
if __name__ == "__main__":
|
|
8
|
+
for count in (1, 2, 4, 8):
|
|
9
|
+
result = run_benchmark(
|
|
10
|
+
SyntheticConfig(sensor_count=count, seed=42),
|
|
11
|
+
Path("artifacts/scalability") / f"cameras_{count}",
|
|
12
|
+
)
|
|
13
|
+
print(count, result["resources"])
|