gear-sonic

Author: ZhengyiLuo

.gitattributes

@@ -21,3 +21,5 @@
 *.dae filter=lfs diff=lfs merge=lfs -text
 *.so filter=lfs diff=lfs merge=lfs -text
 *.so.* filter=lfs diff=lfs merge=lfs -text
+# Docs static assets must NOT use LFS — GitHub Pages can't serve LFS pointers
+docs/source/_static/** filter= diff= merge=

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - gear-sonic
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+      - ".gitattributes"
+  workflow_dispatch:
+
+# Allow only one concurrent deployment; cancel in-flight runs
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Sphinx Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Restore docs static assets (bypass git-lfs smudge)
+        run: |
+          # git-lfs on the runner rewrites files tracked by *.png/*.gif
+          # even when our .gitattributes override removes filter=lfs.
+          # Use git cat-file to write real binary content directly from
+          # the object store, bypassing all smudge filters.
+          git ls-tree -r HEAD -- docs/source/_static \
+            | awk '{print $3, $4}' \
+            | while IFS=" " read -r hash path; do
+                git cat-file blob "$hash" > "$path"
+              done
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip"
+          cache-dependency-path: "docs/requirements.txt"
+
+      - name: Install documentation dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build HTML documentation
+        run: sphinx-build -b html docs/source docs/build/html
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/gear-sonic'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/gear-sonic'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -67,7 +67,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+
 
 # PyBuilder
 .pybuilder/
@@ -166,10 +166,29 @@ outputs/
 
 .DS_Store
 
+# Hugging Face upload/maintenance scripts (internal use only)
+huggingface/
+
+# Model checkpoints (download via download_from_hf.py)
+*.onnx
+!decoupled_wbc/sim2mujoco/resources/robots/g1/policy/GR00T-WholeBodyControl-Balance.onnx
+!decoupled_wbc/sim2mujoco/resources/robots/g1/policy/GR00T-WholeBodyControl-Walk.onnx
+
 
 # Mujoco
 MUJOCO_LOG.TXT
 
 # IsaacDeploy
 external_dependencies/isaac_teleop_app/isaac-deploy
+external_dependencies/doc/
+
+# XRoboToolkit pybind (cloned locally on aarch64 by install_pico.sh)
+external_dependencies/XRoboToolkit-PC-Service-Pybind/
+
+# UV
+uv.lock
 
+# XRoboToolkit-PC-Service-Pybind
+xrobotoolkit_sdk.cpython-*-*-*.so
+teleop_vids/
+*.code-workspace

CITATION.cff

@@ -0,0 +1,93 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "GR00T Whole-Body Control"
+authors:
+  - family-names: "Luo"
+    given-names: "Zhengyi"
+  - family-names: "Yuan"
+    given-names: "Ye"
+  - family-names: "Wang"
+    given-names: "Tingwu"
+  - family-names: "Li"
+    given-names: "Chenran"
+  - family-names: "Chen"
+    given-names: "Sirui"
+  - family-names: "Castañeda"
+    given-names: "Fernando"
+  - family-names: "Cao"
+    given-names: "Zi-Ang"
+  - family-names: "Li"
+    given-names: "Jiefeng"
+  - family-names: "Zhu"
+    given-names: "Yuke"
+url: "https://github.com/NVlabs/GR00T-WholeBodyControl"
+repository-code: "https://github.com/NVlabs/GR00T-WholeBodyControl"
+type: software
+keywords:
+  - humanoid-robotics
+  - reinforcement-learning
+  - whole-body-control
+  - motion-tracking
+  - teleoperation
+  - robotics
+  - pytorch
+license: Apache-2.0
+preferred-citation:
+  type: article
+  title: "SONIC: Supersizing Motion Tracking for Natural Humanoid Whole-Body Control"
+  authors:
+    - family-names: "Luo"
+      given-names: "Zhengyi"
+    - family-names: "Yuan"
+      given-names: "Ye"
+    - family-names: "Wang"
+      given-names: "Tingwu"
+    - family-names: "Li"
+      given-names: "Chenran"
+    - family-names: "Chen"
+      given-names: "Sirui"
+    - family-names: "Castañeda"
+      given-names: "Fernando"
+    - family-names: "Cao"
+      given-names: "Zi-Ang"
+    - family-names: "Li"
+      given-names: "Jiefeng"
+    - family-names: "Minor"
+      given-names: "David"
+    - family-names: "Ben"
+      given-names: "Qingwei"
+    - family-names: "Da"
+      given-names: "Xingye"
+    - family-names: "Ding"
+      given-names: "Runyu"
+    - family-names: "Hogg"
+      given-names: "Cyrus"
+    - family-names: "Song"
+      given-names: "Lina"
+    - family-names: "Lim"
+      given-names: "Edy"
+    - family-names: "Jeong"
+      given-names: "Eugene"
+    - family-names: "He"
+      given-names: "Tairan"
+    - family-names: "Xue"
+      given-names: "Haoru"
+    - family-names: "Xiao"
+      given-names: "Wenli"
+    - family-names: "Wang"
+      given-names: "Zi"
+    - family-names: "Yuen"
+      given-names: "Simon"
+    - family-names: "Kautz"
+      given-names: "Jan"
+    - family-names: "Chang"
+      given-names: "Yan"
+    - family-names: "Iqbal"
+      given-names: "Umar"
+    - family-names: "Fan"
+      given-names: "Linxi"
+    - family-names: "Zhu"
+      given-names: "Yuke"
+  journal: "arXiv preprint"
+  year: 2025
+  url: "https://arxiv.org/abs/2511.07820"