Update COMPASS training doc#6135
Conversation
sameerchavan0027
requested review from
Mayankm96,
jtigue-bdai and
kellyguo11
as code owners
github-actions
Bot
added
the
documentation
Greptile SummaryThis PR rewrites the COMPASS navigation policy documentation page, expanding it from a short redirect stub into a full overview with NuRec asset descriptions, embedded GIF demos, and updated links pointing to the
Confidence Score: 3/5The page will render with two broken image placeholders until the missing GIF assets are added. Two GIF files (galileo.gif and galileo_g1_training.gif) are referenced in the document but absent from the repository. Every build of the docs will produce empty image cells in the Real2Sim Assets and Training Examples tables until those files are committed. The CSS and the three included GIFs are correct. docs/source/policy_deployment/03_compass_with_NuRec/compass_navigation_policy_with_NuRec.rst — the two missing GIF assets need to be added before this page renders correctly. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[compass_navigation_policy_with_NuRec.rst] --> B[NuRec Assets section]
A --> C[XGRIDS Assets section]
A --> D[COMPASS Workflow section]
A --> E[Training Examples section]
B --> B1[galileo.gif ❌ MISSING]
B --> B2[living_room.gif ✅]
C --> C1[wormhole_with_sim_objects.gif ✅]
E --> E1[galileo_g1_training.gif ❌ MISSING]
E --> E2[xgrid_wormhole_carter_training.gif ✅]
D --> D2["COMPASS handbook link (real2sim/isaaclab_3.0)"]
Reviews (1): Last reviewed commit: "Update compass docs with assets and prop..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| :widths: 50 50 | ||
| :class: nurec-gif-grid | ||
|
|
||
| * - .. figure:: ../../_static/policy_deployment/03_compass_with_NuRec/galileo.gif |
There was a problem hiding this comment.
Two GIF files referenced in this page do not exist in the repository: galileo.gif (line 37) and galileo_g1_training.gif (line 102). The PR adds only living_room.gif, wormhole_with_sim_objects.gif, and xgrid_wormhole_carter_training.gif. When the docs are built, these two .. figure:: directives will produce broken image placeholders — the "Real2Sim Assets" table will show an empty cell and the "Training Examples" table will be asymmetric.
| **Wormhole** | ||
|
|
||
| | Embodiment: Hand-Held | ||
| | Sensor Rig: `XGRIDS PortalCam <https://www.xgrids.com/intl/portalcamp>`_ [2 x fish-eye cameras, 2 x front cameras, 1 x LiDAR] |
There was a problem hiding this comment.
portalcamp should likely be portalcam to match the product name "PortalCam". A broken link here would send readers to a 404 page.
| | Sensor Rig: `XGRIDS PortalCam <https://www.xgrids.com/intl/portalcamp>`_ [2 x fish-eye cameras, 2 x front cameras, 1 x LiDAR] | |
| | Sensor Rig: `XGRIDS PortalCam <https://www.xgrids.com/intl/portalcam>`_ [2 x fish-eye cameras, 2 x front cameras, 1 x LiDAR] |
![isaaclab-review-bot[bot]](https://avatars.githubusercontent.com/u/157846462?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation Review — PR #6135
Thanks for the expanded COMPASS + NuRec documentation, @sameerchavan0027! The restructured page with asset descriptions, training examples, and embedded GIFs is a big improvement over the previous stub.
Summary
This PR rewrites the COMPASS navigation policy tutorial with NuRec asset descriptions, embedded demonstration GIFs, and custom CSS for a responsive grid layout. The changes are well-structured, but there are two CI-blocking issues and one build-breaking problem that need attention before merge.
CI Failures
| Check | Status | Root Cause |
|---|---|---|
pre-commit (codespell) |
❌ | segway flagged as typo — needs allowlist entry |
Check for Broken Links |
❌ | COMPASS handbook URL returns 404 |
Findings
See inline comments for details.
| stays in sync with the NuRec support branch. | ||
| This page gives a short overview of the supported NuRec assets and example COMPASS training clips. For | ||
| installation, asset registration, training, evaluation, export, and ROS 2 deployment instructions, see the | ||
| `COMPASS handbook <https://github.com/NVlabs/COMPASS/blob/real2sim/isaaclab_3.0/docs/handbook/workflows/nurec_real2sim.md>`_. |
There was a problem hiding this comment.
🔴 CI Blocker — Broken Link (404)
The Check for Broken Links CI job fails because this URL returns HTTP 404:
https://github.com/NVlabs/COMPASS/blob/real2sim/isaaclab_3.0/docs/handbook/workflows/nurec_real2sim.md
Possible causes:
- The branch
real2sim/isaaclab_3.0may not exist yet on the public repo (private or not yet pushed) - The path inside the repo may have changed
Please verify the branch/path exist on the public NVlabs/COMPASS repo, or exclude this URL from the link checker config until the branch is published. This same URL appears again on line 87.
| :widths: 50 50 | ||
| :class: nurec-gif-grid | ||
|
|
||
| * - .. figure:: ../../_static/policy_deployment/03_compass_with_NuRec/galileo.gif |
There was a problem hiding this comment.
🔴 Build Breaker — Missing Asset: galileo.gif
This .. figure:: directive references galileo.gif, but that file is not included in this PR. The files added are:
living_room.gif✅wormhole_with_sim_objects.gif✅xgrid_wormhole_carter_training.gif✅
Missing:
galileo.gif❌ (referenced here)galileo_g1_training.gif❌ (referenced on line 102)
Sphinx will emit a warning or broken image. Please add these two GIFs to the PR or remove the figures that reference them.
|
|
||
| **Galileo** | ||
|
|
||
| | Embodiment: `Nova Carter [wheeled robot] <https://robotics.segway.com/nova-carter/>`_ |
There was a problem hiding this comment.
🟡 CI Blocker — Codespell false positive on segway
The pre-commit job fails because codespell flags segway (in the Segway Robotics URL) as a misspelling of segue. This is a brand name and a false positive.
Fix: Add segway to the project's codespell ignore list. Typically this is done in setup.cfg, pyproject.toml, or .codespellrc:
# pyproject.toml
[tool.codespell]
ignore-words-list = "segway"Or in the .pre-commit-config.yaml args:
args: ["--ignore-words-list", "segway"]
There was a problem hiding this comment.
🤖 Isaac Lab Review Bot
Summary
This PR updates the COMPASS training documentation with new content, NuRec asset GIFs, and improved CSS styling. The documentation overhaul looks good overall, but there are critical issues that will cause the documentation build to fail.
Design Assessment
Design is sound — The restructuring of the COMPASS documentation to focus on NuRec assets with visual examples is a good approach. The CSS additions follow existing patterns.
Findings
🔴 Critical: Missing GIF assets referenced in RST — compass_navigation_policy_with_NuRec.rst:34, :99
The RST file references two GIF files that are not included in this PR:
../../_static/policy_deployment/03_compass_with_NuRec/galileo.gif(line 34)../../_static/policy_deployment/03_compass_with_NuRec/galileo_g1_training.gif(line 99)
Only three GIFs are added (living_room.gif, wormhole_with_sim_objects.gif, xgrid_wormhole_carter_training.gif), but the documentation expects five. This will cause broken images in the built documentation.
Fix: Add the missing galileo.gif and galileo_g1_training.gif files to the PR.
🔴 Critical: Broken external link (404) — compass_navigation_policy_with_NuRec.rst:12, :64
The link to the COMPASS handbook returns 404:
https://github.com/NVlabs/COMPASS/blob/real2sim/isaaclab_3.0/docs/handbook/workflows/nurec_real2sim.md
The branch real2sim/isaaclab_3.0 does not exist. The correct branch appears to be samc/support_nurec_assets_isaaclab_3.0.
Fix: Update both link references (lines 12 and 64) to use the correct branch name, or ensure the real2sim/isaaclab_3.0 branch exists on the COMPASS repository before merging.
🟡 Warning: False positive in codespell CI check — compass_navigation_policy_with_NuRec.rst:45
The pre-commit CI fails because codespell flags segway (in the Segway Robotics URL) as a misspelling of segue. This is a false positive — "Segway" is the correct name of the robotics company (the Nova Carter robot link).
Fix: Either:
- Add
segwayto the codespell ignore list in the repo config, or - Restructure the line to avoid the word (e.g., use the full URL without the company name in surrounding text)
Test Coverage
- Documentation-only PR: No runtime tests required.
- The documentation build CI (
Build Latest Docs) is still pending and will likely fail due to the missing GIF assets.
CI Status
| Check | Status |
|---|---|
| pre-commit | ❌ Failed (codespell false positive on "segway") |
| Check for Broken Links | ❌ Failed (404 on COMPASS handbook link) |
| Build Latest Docs | ⏳ Pending |
| Check changelog fragments | ✅ Passed |
| Build Wheel | ✅ Passed |
Verdict
Significant concerns
This PR has two critical issues that must be fixed before it can be merged:
- Missing GIF files (
galileo.gif,galileo_g1_training.gif) — will cause broken images - Broken external link — the COMPASS handbook URL returns 404
Additionally, the codespell CI failure needs to be addressed (false positive on "Segway" company name).
Update (0cfb0c6): New commits add the two previously missing GIF assets:
- ✅ Fixed:
galileo.gifadded (10.9 MB, LFS) - ✅ Fixed:
galileo_g1_training.gifadded (1.6 MB, LFS) - CSS selectors refined from
.nurec-gif-covertofigure.nurec-gif-cover img— correctly targets the<img>inside the figure element.
Remaining unresolved:
- 🔴 Broken external link (COMPASS handbook URL still returns 404)
- 🟡 Codespell false positive on "segway" still needs to be addressed
Update (ddcc577): Major simplification — GIF-based visual grids replaced with plain-text bullet lists containing hyperlinks.
- ✅ Fixed: Missing GIF assets issue is now moot — all
.. figure::directives and GIF references removed entirely - ✅ Fixed: Custom
.nurec-gif-gridCSS removed (no longer needed) - All 5 GIF files (galileo.gif, galileo_g1_training.gif, living_room.gif, wormhole_with_sim_objects.gif, xgrid_wormhole_carter_training.gif) deleted from LFS
Remaining unresolved:
- 🔴 Broken external link —
real2sim/isaaclab_3.0branch URL still returns 404 (lines 11 and 58) - 🟡
portalcamptypo in XGRIDS URL (line 49) — should beportalcam - 🟡 Codespell "segway" false positive likely still present
Update (f69be8e): Incremental commit adds segway to the codespell ignore-words-list in pyproject.toml.
- ✅ Fixed: Codespell false positive on "segway" — added to ignore list
- ✅ Fixed: Broken external link — the
real2sim/isaaclab_3.0branch now exists on NVlabs/COMPASS (returns 200)
Remaining unresolved:
- 🟡
portalcamptypo in XGRIDS URL (line 50) — should beportalcam
Update (63a59e0): Minor refinements — added stereo camera datasheet hyperlink for the Living Room asset description, and removed the placeholder "Training Examples" section (Galileo/Wormhole bullet points). No new issues introduced.
Remaining unresolved:
- 🟡
portalcamptypo in XGRIDS URL (line 50) — should beportalcam
| scenes produced with this workflow; two examples are shown below. | ||
|
|
||
| .. list-table:: | ||
| :widths: 50 50 |
There was a problem hiding this comment.
🔴 Critical: Missing asset
This figure references galileo.gif but the file is not included in this PR. The PR adds living_room.gif, wormhole_with_sim_objects.gif, and xgrid_wormhole_carter_training.gif — but not galileo.gif.
Please add the missing galileo.gif file to the PR.
| This page gives a short overview of the supported NuRec assets and example COMPASS training clips. For | ||
| installation, asset registration, training, evaluation, export, and ROS 2 deployment instructions, see the | ||
| `COMPASS handbook <https://github.com/NVlabs/COMPASS/blob/real2sim/isaaclab_3.0/docs/handbook/workflows/nurec_real2sim.md>`_. | ||
|
|
There was a problem hiding this comment.
🔴 Critical: Broken link (404)
This URL returns 404 — the branch real2sim/isaaclab_3.0 does not exist in the COMPASS repository.
The existing branch is samc/support_nurec_assets_isaaclab_3.0. Either:
- Update this link to the correct branch, or
- Ensure the new branch is created before merging
| `COMPASS handbook <https://github.com/NVlabs/COMPASS/blob/samc/support_nurec_assets_isaaclab_3.0/docs/handbook/workflows/nurec_real2sim.md>`_. |
| COMPASS also supports compatible assets reconstructed with XGRIDS. These assets are post-processed into the | ||
| NuRec format used by the COMPASS workflow, including mesh alignment and augmentation with simulation-ready | ||
| assets available in Isaac Sim. | ||
|
|
There was a problem hiding this comment.
🔴 Critical: Broken link (404)
Same issue as line 12 — this link also needs to be updated to the correct branch.
| - **Guide:** `NuRec asset workflow <https://github.com/NVlabs/COMPASS/blob/samc/support_nurec_assets_isaaclab_3.0/docs/handbook/workflows/nurec_real2sim.md>`_ |
| The following clips show COMPASS training with different robot embodiments in NuRec scenes. | ||
|
|
||
| .. list-table:: | ||
| :widths: 50 50 |
There was a problem hiding this comment.
🔴 Critical: Missing asset
This figure references galileo_g1_training.gif but the file is not included in this PR.
Please add the missing galileo_g1_training.gif file to the PR.
|
|
||
| **Galileo** | ||
|
|
||
| | Embodiment: `Nova Carter [wheeled robot] <https://robotics.segway.com/nova-carter/>`_ |
There was a problem hiding this comment.
🟡 Warning: codespell false positive
The pre-commit CI fails because codespell flags "segway" (in the URL) as a misspelling of "segue". This is a false positive since Segway is a proper noun (the robotics company that makes Nova Carter).
Consider adding segway to the project's codespell ignore list, or this CI check will continue to fail.
GIFs will be added in a later release. Replace list-table/figure blocks with plain bullet lists and remove nurec-gif-* CSS rules that were only needed to style the GIF grid.
"segway" in robotics.segway.com was flagged as a misspelling of "segue". Segway is the brand name for the Nova Carter robot platform.
1 participant
Update compass docs with assets and proper links