fd0568caa1
Lands the first chunk of P2: PyO3 bindings for `Keypoint` and
`KeypointType` from `wifi_densepose_core`. Bound types surface to
Python as `wifi_densepose.Keypoint` / `wifi_densepose.KeypointType`.
## Design choices that affect the API surface
1. **`Confidence` is NOT bound as a separate class.** Users hate
wrapping a float in a constructor. Python-side, confidence is just
a `float in [0.0, 1.0]`; the binding validates on construction
(`ValueError` for out-of-range, matching the Rust core error).
2. **`KeypointType` is a `#[pyclass(eq, eq_int, hash, frozen)]` enum**
— hashable so users can drop it into dicts/sets (the most common
pattern in pose-analysis notebooks: `keypoints_by_type[k.type] = k`).
3. **`Keypoint.__init__` keyword-only `z`** so 2D users don't have to
write `None` and 3D users get a clear named arg:
`Keypoint(KeypointType.LeftWrist, 0.2, 0.4, 0.8, z=0.1)`.
4. **`Keypoint` is `#[pyclass(frozen)]`** — no in-place mutation. The
Rust core type is immutable through Copy + Hash + Eq, and exposing
setters from Python would create a copy-vs-reference inconsistency
between languages.
## Files
- `python/src/bindings/keypoint.rs` — 220 lines of `#[pymethods]`
wrappers + Rust↔Python enum round-trip
- `python/src/lib.rs` — `mod bindings { pub mod keypoint; }` +
`bindings::keypoint::register(m)?` call from `#[pymodule]`
- `python/wifi_densepose/__init__.py` — re-exports `Keypoint` and
`KeypointType` at the package root
- `python/tests/test_keypoint.py` — 23 tests covering:
- 17-element COCO ordering of `KeypointType.all()`
- index→type mapping for every variant
- snake_name matches COCO spec
- `is_face()` / `is_upper_body()` predicates
- hashability (the bug I caught when I added the set-based face
test — fixed by adding `hash` to the `#[pyclass]` attribute)
- 2D + 3D constructor variants
- position_2d / position_3d tuples
- is_visible threshold
- confidence validation (Err on out-of-range)
- distance_to (2D Euclidean, 3D Euclidean, fallback when one is 2D
and the other is 3D)
- __repr__ + __eq__
- the new `p2-keypoint-bindings` feature marker landed
## Local validation
\`\`\`
$ cd python && .venv/Scripts/python -m pytest tests/ -v
tests/test_smoke.py::test_package_imports PASSED
tests/test_smoke.py::test_version_string_well_formed PASSED
tests/test_smoke.py::test_rust_version_surfaced PASSED
tests/test_smoke.py::test_build_features_listed PASSED
tests/test_smoke.py::test_hello_returns_ok PASSED
tests/test_smoke.py::test_native_module_private PASSED
tests/test_keypoint.py::test_keypoint_type_all_returns_17 PASSED
…
======================== 29 passed in 0.06s =========================
\`\`\`
Wheel size after both bindings: still well under the 5 MB ADR §5.4
budget (release build with --strip on Windows: ~340 KB).
Also adds `python/.gitignore` to prevent the `.venv/` + `target/` +
`_native.abi3.pyd` artifacts from getting committed.
## What's left in P2
CsiFrame + PoseEstimate bindings land in the next iteration. They're
larger (CsiFrame has the subcarrier buffer; PoseEstimate has
17×Keypoint + BoundingBox + track_id + score). Pattern is now proven
so they go faster.
Refs #785, ADR-117 §6.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|---|---|---|
| .. | ||
| src | ||
| tests | ||
| wifi_densepose | ||
| .gitignore | ||
| Cargo.toml | ||
| README.md | ||
| pyproject.toml | ||
README.md
wifi-densepose v2.x — PyO3 bindings for the Rust core
This directory contains the source for the wifi-densepose PyPI wheel
(v2.0+). It's a PyO3 + maturin build that wraps the Rust crates in
v2/crates/ and replaces the legacy pure-Python
wifi-densepose==1.1.0 (released 2025-06-07).
See ADR-117 for the full modernization plan.
Build locally
# Install maturin + dev deps
pip install maturin pytest
# Develop-install — builds the Rust extension in-place
cd python
maturin develop
# Run the smoke tests
pytest tests/
The maturin develop command produces a debug-build wheel installed
into your current Python environment. For release builds:
maturin build --release --strip
The wheel lands under python/target/wheels/.
Layout
python/
├── Cargo.toml # PyO3 + abi3-py310 + Rust deps
├── pyproject.toml # maturin backend + Python metadata
├── README.md # this file
├── src/
│ └── lib.rs # #[pymodule] — Rust binding glue
├── wifi_densepose/ # pure-Python facade (the user-facing API)
│ ├── __init__.py # re-exports compiled module symbols
│ └── py.typed # PEP 561 typed-package marker
└── tests/
└── test_smoke.py # P1 acceptance tests
Phase status (per ADR-117 §6)
- ✅ P1 — Scaffold (this commit): module loads, version constant
exposed, 6 smoke tests pass via
maturin develop. - ⏳ P2 — Core type bindings:
CsiFrame,Keypoint,PoseEstimate. - ⏳ P3 — Vitals + signal DSP: 4-stage HR/BR pipeline +
CsiProcessorPhaseSanitizer, withallow_threadsGIL release on hot loops.
- ⏳ P4 — WS/MQTT client: pure-Python
wifi_densepose.clientextra. - ⏳ P5 — cibuildwheel + PyPI publish: Linux/macOS/Windows × abi3-py310.
Each phase ends with a checkbox PR. Tests are additive — every phase's smoke tests must still pass after later phases land.
Migrating from v1.x
The v1 line was a separate pure-Python implementation. v2 is a hard break (semver-justified by 11.5 months of stack drift). Migration guide ships in docs/migrations/wifi-densepose-1-to-2.md (landing in P5).