flow_badminton

Imported from yangfeiyang-123/flow_badminton (AGENTS.md). Install upstream with npx skills add yangfeiyang-123/flow_badminton. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

The active codebase is under WHAM/.

• WHAM/lib/: core implementation (core/, models/, data/, data_utils/, eval/, vis/, utils/).
• WHAM/configs/yamls/: run configs such as demo.yaml, stage1.yaml, and stage2.yaml.
• WHAM/docs/: setup and usage docs (INSTALL.md, DOCKER.md, API.md, DATASET.md).
• WHAM/examples/: sample videos and calibration files for demo runs.
• WHAM/dataset/, WHAM/checkpoints/, WHAM/output/: data, model weights, and generated outputs.
• WHAM/third-party/ and WHAM/chumpy/: vendored dependencies; avoid changing unless syncing upstream fixes.

Build, Test, and Development Commands

Run commands from WHAM/.

• pip install -r requirements.txt: install Python dependencies.
• pip install -v -e third-party/ViTPose: install ViTPose in editable mode.
• bash fetch_demo_data.sh: download demo assets, body models, and checkpoints.
• python demo.py --video examples/IMG_9732.mov --visualize: end-to-end local inference smoke test.
• python train.py --cfg configs/yamls/stage1.yaml: stage-1 training run.
• python -m lib.eval.evaluate_3dpw --cfg configs/yamls/demo.yaml TRAIN.CHECKPOINT checkpoints/wham_vit_w_3dpw.pth.tar: baseline 3DPW evaluation.

Coding Style & Naming Conventions

• Target Python 3.9 with 4-space indentation and PEP 8-aligned style.
• Use snake_case for functions/variables/files, PascalCase for classes, and UPPER_CASE for constants.
• Keep YAML config patterns consistent with existing keys (for example TRAIN.CHECKPOINT).
• Follow local style in touched files (import grouping, logging, argument parsing) since no formatter/linter is enforced in-repo.

Testing Guidelines

• There is no dedicated first-party unit test suite under WHAM/ today.
• Validate changes with workflow-aligned smoke checks.
• Inference: run demo.py on files in examples/.
• Data/training: run the relevant lib.data_utils.* preprocessing module plus a short train/eval pass.
• When adding tests, use pytest and place them under WHAM/tests/ with names like test_<module>.py.

Commit & Pull Request Guidelines

• Existing history favors short imperative subjects (for example: fix bug, update loss, training stage 1).
• Prefer clearer scoped messages: <area>: <change> (example: data: fix bbox augment).
• Each PR should include a concise problem/solution summary.
• Include exact commands used for verification.
• List dataset/checkpoint prerequisites.
• Add visual evidence or metric deltas for demo/evaluation-impacting changes.