72 lines
3.6 KiB
Markdown
72 lines
3.6 KiB
Markdown
# NeuroPose (rewrite)
|
|
|
|
Ground-up rewrite of the prior NeuroPose internal prototype.
|
|
|
|
## Target layout
|
|
|
|
```text
|
|
neuropose/
|
|
├── .github/workflows/ # CI on the GitHub mirror (ruff + pyright + pytest)
|
|
├── src/neuropose/
|
|
│ ├── __init__.py # version only
|
|
│ ├── config.py # pydantic-settings Settings class
|
|
│ ├── io.py # prediction schema, load/save helpers
|
|
│ ├── estimator.py # per-video MeTRAbs worker (ported, cleaned)
|
|
│ ├── interfacer.py # filesystem-polling daemon (ported, cleaned)
|
|
│ ├── cli.py # typer app (`neuropose run|watch|analyze`)
|
|
│ ├── _model.py # MeTRAbs model load + local cache
|
|
│ └── analyzer/ # rewrite of the prior analyzer.py
|
|
│ ├── dtw.py # FastDTW helpers
|
|
│ ├── features.py # normalization, padding, joint angles
|
|
│ └── classification.py # sktime classifier wrappers
|
|
├── tests/
|
|
│ ├── unit/ # fast, no model download
|
|
│ ├── integration/ # marked @slow, downloads the model
|
|
│ └── fixtures/ # synthetic video + reference predictions
|
|
├── docs/ # mkdocs-material site
|
|
├── notebooks/ # getting_started.ipynb, tested in CI via nbval
|
|
├── config/default.yaml # example runtime config
|
|
├── scripts/download_model.py
|
|
├── pyproject.toml # hatchling build, typer + pydantic + TF stack
|
|
├── Dockerfile # CPU, pinned deps
|
|
├── AUTHORS.md
|
|
├── CITATION.cff
|
|
└── LICENSE # MIT
|
|
```
|
|
## Architecture
|
|
|
|
Three stages, one module each:
|
|
|
|
- **`estimator`** — per-video worker. Extracts frames from an input video,
|
|
runs MeTRAbs on each frame, and writes per-frame predictions (`boxes`,
|
|
`poses3d`, `poses2d`) to JSON. No daemon logic; usable directly from Python.
|
|
- **`interfacer`** — filesystem-polling daemon. Watches the configured input
|
|
directory for new job subdirectories, dispatches each to an `Estimator`,
|
|
and persists job state (`status.json`) across crashes and restarts. Owns
|
|
the input → output → failed directory lifecycle.
|
|
- **`analyzer`** — post-processing subpackage. FastDTW-based motion
|
|
comparison, joint-angle feature extraction, and sktime classifier wrappers.
|
|
Operates on the JSON output of the estimator.
|
|
|
|
Configuration is centralized in `src/neuropose/config.py` (a
|
|
pydantic-settings `Settings` class). The runtime data directory defaults to
|
|
`$XDG_DATA_HOME/neuropose/jobs/` and never lives inside the repository.
|
|
|
|
## Commit plan
|
|
|
|
| # | Scope | State |
|
|
|---|---|---|
|
|
| 1 | Scaffolding: package layout, MIT license, authors, citation, policy-aware `.gitignore` | in review |
|
|
| 2 | Dev tooling: pre-commit, ruff, pyright, gitleaks | planned |
|
|
| 3 | CI workflow on the GitHub mirror | planned |
|
|
| 4 | `config.py`, `io.py`, unit tests | planned |
|
|
| 5 | Port `estimator.py` with typing and audit §6 fixes | planned |
|
|
| 6 | Port `interfacer.py` with audit §7 fixes | planned |
|
|
| 7 | Typer CLI (`neuropose run|watch|analyze`) | planned |
|
|
| 8 | mkdocs-material docs site | planned |
|
|
| 9 | Data-handling policy (gates going public) | blocked on IRB prose |
|
|
| 10 | `analyzer/` subpackage rewrite | planned |
|
|
| 11 | MeTRAbs model loader + integration smoke test | blocked on upstream URL + TF pin |
|
|
| 12 | Dockerfile | blocked on 11 |
|
|
| 13 | Comprehensive `CHANGELOG.md` retroactive entry | blocked on 12 |
|