85 lines
4.8 KiB
Markdown
85 lines
4.8 KiB
Markdown
# PROJECT KNOWLEDGE BASE
|
|
|
|
**Generated:** 2026-02-11T10:53:29Z
|
|
**Commit:** f754f6f
|
|
**Branch:** master
|
|
|
|
## OVERVIEW
|
|
OpenGait is a research-grade, config-driven gait analysis framework centered on distributed PyTorch training/testing.
|
|
Core runtime lives in `opengait/`; `configs/` and `datasets/` are first-class operational surfaces, not just support folders.
|
|
|
|
## STRUCTURE
|
|
```text
|
|
OpenGait/
|
|
├── opengait/ # runtime package (train/test, model/data/eval pipelines)
|
|
├── configs/ # model- and dataset-specific experiment specs
|
|
├── datasets/ # preprocessing/rearrangement scripts + partitions
|
|
├── docs/ # user workflow docs
|
|
├── train.sh # launch patterns (DDP)
|
|
└── test.sh # eval launch patterns (DDP)
|
|
```
|
|
|
|
## WHERE TO LOOK
|
|
| Task | Location | Notes |
|
|
|------|----------|-------|
|
|
| Train/test entry | `opengait/main.py` | DDP init + config load + model dispatch |
|
|
| Model registration | `opengait/modeling/models/__init__.py` | dynamic class import/registration |
|
|
| Backbone/loss registration | `opengait/modeling/backbones/__init__.py`, `opengait/modeling/losses/__init__.py` | same dynamic pattern |
|
|
| Config merge behavior | `opengait/utils/common.py::config_loader` | merges into `configs/default.yaml` |
|
|
| Data loading contract | `opengait/data/dataset.py`, `opengait/data/collate_fn.py` | `.pkl` only, sequence sampling modes |
|
|
| Evaluation dispatch | `opengait/evaluation/evaluator.py` | dataset-specific eval routines |
|
|
| Dataset preprocessing | `datasets/pretreatment.py` + dataset subdirs | many standalone CLI tools |
|
|
|
|
## CODE MAP
|
|
| Symbol / Module | Type | Location | Refs | Role |
|
|
|-----------------|------|----------|------|------|
|
|
| `config_loader` | function | `opengait/utils/common.py` | high | YAML merge + default overlay |
|
|
| `get_ddp_module` | function | `opengait/utils/common.py` | high | wraps modules with DDP passthrough |
|
|
| `BaseModel` | class | `opengait/modeling/base_model.py` | high | canonical train/test lifecycle |
|
|
| `LossAggregator` | class | `opengait/modeling/loss_aggregator.py` | medium | consumes `training_feat` contract |
|
|
| `DataSet` | class | `opengait/data/dataset.py` | high | dataset partition + sequence loading |
|
|
| `CollateFn` | class | `opengait/data/collate_fn.py` | high | fixed/unfixed/all sampling policy |
|
|
| `evaluate_*` funcs | functions | `opengait/evaluation/evaluator.py` | medium | metric/report orchestration |
|
|
| `models` package registry | dynamic module | `opengait/modeling/models/__init__.py` | high | config string → model class |
|
|
|
|
## CONVENTIONS
|
|
- Launch pattern is DDP-first (`python -m torch.distributed.launch ... opengait/main.py --cfgs ... --phase ...`).
|
|
- DDP Constraints: `world_size` must equal number of visible GPUs; test `evaluator_cfg.sampler.batch_size` must equal `world_size`.
|
|
- Model/loss/backbone discoverability is filesystem-driven via package-level dynamic imports.
|
|
- Experiment config semantics: custom YAML overlays `configs/default.yaml` (local key precedence).
|
|
- Outputs are keyed by config identity: `output/${dataset_name}/${model}/${save_name}`.
|
|
|
|
## ANTI-PATTERNS (THIS PROJECT)
|
|
- Do not feed non-`.pkl` sequence files into runtime loaders (`opengait/data/dataset.py`).
|
|
- Do not violate sampler shape assumptions (`trainer_cfg.sampler.batch_size` is `[P, K]` for triplet regimes).
|
|
- Do not ignore DDP cleanup guidance; abnormal exits can leave zombie processes (`misc/clean_process.sh`).
|
|
- Do not add unregistered model/loss classes outside expected directories (`opengait/modeling/models`, `opengait/modeling/losses`).
|
|
|
|
## UNIQUE STYLES
|
|
- `datasets/` is intentionally script-heavy (rearrange/extract/pretreat), not a pure library package.
|
|
- Research model zoo is broad; many model files co-exist as first-class references.
|
|
- Recent repo trajectory includes scoliosis screening models (ScoNet lineage), not only person-ID gait benchmarks.
|
|
|
|
## COMMANDS
|
|
```bash
|
|
# install (uv)
|
|
uv sync --extra torch
|
|
|
|
# train (uv)
|
|
CUDA_VISIBLE_DEVICES=0,1 uv run python -m torch.distributed.launch --nproc_per_node=2 opengait/main.py --cfgs ./configs/baseline/baseline.yaml --phase train
|
|
|
|
# test (uv)
|
|
CUDA_VISIBLE_DEVICES=0,1 uv run python -m torch.distributed.launch --nproc_per_node=2 opengait/main.py --cfgs ./configs/baseline/baseline.yaml --phase test
|
|
|
|
# ScoNet 1-GPU eval
|
|
CUDA_VISIBLE_DEVICES=0 uv run python -m torch.distributed.launch --nproc_per_node=1 opengait/main.py --cfgs ./configs/sconet/sconet_scoliosis1k_local_eval_1gpu.yaml --phase test
|
|
|
|
# preprocess (generic)
|
|
python datasets/pretreatment.py --input_path <raw_or_rearranged> --output_path <pkl_root>
|
|
```
|
|
|
|
## NOTES
|
|
- LSP symbol map can be enabled via uv dev dependency `basedpyright`; `basedpyright` and `basedpyright-langserver` are available in `.venv` after `uv sync`.
|
|
- `train.sh` / `test.sh` are canonical launch examples across datasets/models.
|
|
- Academic-use-only restriction is stated in repository README.
|