OpenGait/AGENTS.md

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

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

# 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.