{"id":26903638,"url":"https://github.com/ethanmclark1/biped_locomotion","last_synced_at":"2025-10-03T17:45:55.535Z","repository":{"id":284001880,"uuid":"902582637","full_name":"ethanmclark1/biped_locomotion","owner":"ethanmclark1","description":"Imitation learning approach for generating natural and robust bipedal locomotion using phase manifolds","archived":false,"fork":false,"pushed_at":"2025-03-23T15:15:38.000Z","size":297,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T10:37:46.754Z","etag":null,"topics":["biped","humanoid","imitation-learning","kinematics","locomotion"],"latest_commit_sha":null,"homepage":"https://dl.acm.org/doi/10.1145/3528223.3530178","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethanmclark1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-12T21:17:14.000Z","updated_at":"2025-03-23T15:18:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"1f169aeb-f9d4-462c-b045-7257870599bf","html_url":"https://github.com/ethanmclark1/biped_locomotion","commit_stats":null,"previous_names":["ethanmclark1/biped_locomotion"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ethanmclark1/biped_locomotion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanmclark1%2Fbiped_locomotion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanmclark1%2Fbiped_locomotion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanmclark1%2Fbiped_locomotion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanmclark1%2Fbiped_locomotion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethanmclark1","download_url":"https://codeload.github.com/ethanmclark1/biped_locomotion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanmclark1%2Fbiped_locomotion/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266962179,"owners_count":24012994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biped","humanoid","imitation-learning","kinematics","locomotion"],"created_at":"2025-04-01T10:36:17.900Z","updated_at":"2025-10-03T17:45:50.479Z","avatar_url":"https://github.com/ethanmclark1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Biped Locomotion: Deep Phase Motion Generation Framework\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0) ![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg) ![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n## Overview\n\nBiped Locomotion is a robot-agnostic framework that adapts the [DeepPhase](https://github.com/sebastianstarke/AI4Animation/tree/master/AI4Animation/SIGGRAPH_2022) motion generation system ([Starke et al., 2022](https://github.com/sebastianstarke/AI4Animation/blob/master/Media/SIGGRAPH_2022/Paper.pdf)) for practical robotics applications. This implementation transforms the original animation-focused approach into a flexible framework for generating fluid, natural motions for various robot platforms.\n\nKey contributions of this repo include:\n\n* Pure Python-based data processing pipeline (removing Unity dependency)\n* Robot-agnostic architecture supporting various robot configurations\n* Streamlined data processing and training workflow\n* Flexible deployment options for robotics applications\n\n## Technical Architecture\n\nThe framework consists of two main components:\n\n### 1. Periodic Autoencoder (PAE)\n\nThe PAE learns to encode motion data into a compact, periodic representation:\n\n* **Input** : Joint states (positions and velocities) with window-based normalization\n* **Output** : Periodic phase parameters (shift, frequency, amplitude)\n\n### 2. Mode-Adaptive Neural Network (MANN)\n\nThe MANN uses the phase representation to predict motion:\n\n* **Input** : Command velocities, robot state, and phase space representation\n* **Output** : Next robot state, joint positions/velocities, contact states, and phase updates\n\n## Installation\n\n### Prerequisites\n\n* Python 3.9\n* CUDA-compatible GPU (recommended)\n* Git LFS (for managing large data files)\n\n### Clone the Repository\n\n```bash\n# Install Git LFS first if you haven't\napt-get install git-lfs  # Ubuntu/Debian\n# OR\nbrew install git-lfs  # macOS\n\n# Clone and initialize LFS\ngit clone https://github.com/ethanmclark1/biped_locomotion.git\ncd biped_locomotion\ngit lfs install\ngit lfs pull\n```\n\n### Environment Setup\n\n```bash\n# Create and activate conda environment\nconda env create -f environment.yml\nconda activate biped_locomotion\n\n# Verify installation\npython -c \"import torch; import numpy as np; import quaternion; import scipy\"\n```\n\n### Directory Structure\n\nThe repository is organized as follows:\n\n```\nbiped_locomotion/\n├── data/                # Motion capture data (LFS tracked)\n├── scripts/             # Core implementation\n│   ├── mann/            # Mode-Adaptive Neural Network\n│   ├── pae/             # Periodic Autoencoder\n│   ├── test/            # Test utilities\n│   └── utils/           # Helper functions\n├── ckpt/                # Model checkpoints (created during training)\n└── img/                 # Output visualizations (created during training)\n```\n\n## Usage\n\n\u003e **Important** : All scripts should be run from the project root directory to avoid import errors!\n\n### Data Preparation\n\nPlace your motion data in the `biped_locomotion/data/sequence_X/` directories with:\n\n* `walking_joint_states.npy`: Joint angles in degrees\n* `walking_root_states.npy`: Root position, orientation and velocities\n* `walking_foot_contacts.npy`: Contact states\n\n### Training Pipeline\n\n#### 1. Train the Periodic Autoencoder (PAE)\n\n```bash\n# Run from project root\npython -m biped_locomotion.scripts.pae.trainer\n```\n\nThis learns to encode joint motions into periodic phase parameters.\n\n#### 2. Train the Mode-Adaptive Neural Network (MANN)\n\n```bash\n# Run from project root \npython -m biped_locomotion.scripts.mann.trainer\n```\n\nThis learns to predict motion based on command inputs and phase representation.\n\n### Inference\n\nTo run inference and generate motion:\n\n```bash\npython -m biped_locomotion.scripts.mann.inference\n```\n\n### Configuration\n\nModify `biped_locomotion/scripts/config.yaml` to adjust:\n\n* Network architecture parameters\n* Training hyperparameters\n* Data processing settings\n\n## Troubleshooting\n\n### Import Errors\n\nIf you encounter `ModuleNotFoundError: No module named 'biped_locomotion'`, ensure you're running scripts from the project root:\n\n```bash\n# Correct way to run scripts\ncd /path/to/biped_locomotion\npython -m biped_locomotion.scripts.pae.trainer\n```\n\n### CUDA Issues\n\nIf you encounter CUDA errors, verify your PyTorch installation matches your CUDA version:\n\n```bash\npython -c \"import torch; print(f'CUDA available: {torch.cuda.is_available()}, Version: {torch.version.cuda}')\"\n```\n\n## Model Configuration\n\n### PAE Configuration\n\n* `phase_channels`: Number of phase channels (default: 8)\n* `intermediate_channels`: Dimension of latent space (default: 40)\n* `full_joint_state`: Whether to use both positions and velocities (default: False)\n\n### MANN Configuration\n\n* `gating_hidden`: Hidden layer size for gating network\n* `main_hidden`: Hidden layer size for main network\n* `n_experts`: Number of expert networks in mixture\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nThis project is licensed under the Apache 2.0 License - see [LICENSE](https://claude.ai/chat/LICENSE) file for details.\n\n## Citation\n\nIf you use this implementation in your research, please cite the original DeepPhase paper:\n\n```bibtex\n@inproceedings{starke2022deepphase,\n  title={DeepPhase: Periodic Autoencoders for Learning Motion Phase Manifolds},\n  author={Starke, Sebastian and Mason, Ian and Komura, Taku},\n  booktitle={ACM SIGGRAPH 2022 Conference Proceedings},\n  year={2022},\n  organization={ACM}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethanmclark1%2Fbiped_locomotion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethanmclark1%2Fbiped_locomotion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethanmclark1%2Fbiped_locomotion/lists"}