Create heightfield from wp.Mesh

[StafaH]

Description

Downstream in IsaacLab, Terrain-based tasks handed the Newton MuJoCo solver a single huge terrain mesh (626k verts / 1.19M faces for AnymalD Rough). MuJoCo's spec.compile runs qhull / inertia / BVH over every face, dominating solver initialization.

The correct behaviour is to pass to newton a Heightfield as a Heightfield and not a mesh. This requires rasterizing the mesh terrain from USD into the correct heightfield data. This PR adds the option to create newton Heightfields from wp.Mesh inputs as an alternative construction mechanism.

Gains (Isaac-Velocity-Rough-AnymalD, warm, 64 envs)

Metric	Before (mesh)	After (heightfield)	Change
Terrain in MuJoCo	nmesh=1, 626k v	nmesh=0, nhfield=1	—
MuJoCo spec.compile	963 ms	5.5 ms	175×
Initialize solver	1.94 s	0.86 s	−56%
env_creation	8.8 s	7.35 s	−1.45 s

Summary by CodeRabbit

• New Features
  • Added a heightfield build workflow that converts a triangle mesh into a sampled heightfield on a regular XY grid with configurable resolution.
  • Introduced a rasterization utility to generate height samples, using the mesh minimum Z when rays miss.
  • Exposed the new rasterization utility via the public API.
  • Added a Heightfield factory that returns both the heightfield and a placement transform that centers the grid over the mesh.
• Documentation
  • Documented the new utility and updated the changelog.
• Tests
  • Added unit tests for sloped-plane accuracy, placement, missed-ray fallback, bounds behavior, and input validation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 763f5888-cdd7-4765-bcf9-000d06d4313b

📥 Commits

Reviewing files that changed from the base of the PR and between 349577b and c1a411b.

📒 Files selected for processing (1)

• newton/_src/utils/heightfield.py

💤 Files with no reviewable changes (1)

• newton/_src/utils/heightfield.py

---

📝 Walkthrough

Walkthrough

The PR adds Warp-based mesh-to-heightfield rasterization, a Heightfield.create_from_mesh factory returning a centered transform, public utility exports, tests for sampling and floor fallback, and API/changelog documentation.

Changes

Mesh heightfield construction

Layer / File(s)	Summary
Mesh rasterization kernel and utility newton/_src/utils/heightfield.py	A grid kernel casts downward rays into a mesh, storing hit elevations or the minimum-Z floor; the utility computes bounds, resolution, allocation, and launches the kernel. Existing local heightfield intersection helpers are removed.
Heightfield factory and public API newton/_src/geometry/types.py, newton/utils.py	Heightfield.create_from_mesh constructs heightfield data and a centered placement transform, and rasterize_mesh_to_heightfield is publicly exported.
Validation and API documentation newton/tests/test_heightfield.py, docs/api/newton_utils.rst, CHANGELOG.md	Tests cover sloped-plane sampling, placement, bounds, input validation, and missed-ray floor values; documentation lists the new utility and changelog entry.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Heightfield.create_from_mesh
  participant rasterize_mesh_to_heightfield
  participant _rasterize_mesh_kernel
  participant wp.Mesh
  Client->>Heightfield.create_from_mesh: provide mesh and resolution
  Heightfield.create_from_mesh->>rasterize_mesh_to_heightfield: rasterize mesh
  rasterize_mesh_to_heightfield->>wp.Mesh: read bounds and device
  rasterize_mesh_to_heightfield->>_rasterize_mesh_kernel: launch sampling grid
  _rasterize_mesh_kernel->>wp.Mesh: cast downward rays
  _rasterize_mesh_kernel-->>rasterize_mesh_to_heightfield: write hit or floor heights
  rasterize_mesh_to_heightfield-->>Heightfield.create_from_mesh: return heights and XY bounds
  Heightfield.create_from_mesh-->>Client: return Heightfield and centered transform

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding support to create a heightfield from a wp.Mesh.
Docstring Coverage	✅ Passed	Docstring coverage is 90.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@newton/_src/geometry/types.py`:
- Around line 2223-2237: Update the public docstring for the rasterization
method around the terrain description and arguments: describe supported terrain
as single-valued in Z, including sloped planes, rather than requiring constant
elevation per cell. Add “[m]” units to the mesh coordinate and placement
translation descriptions, while preserving the existing resolution and grid
behavior documentation.

In `@newton/_src/utils/heightfield.py`:
- Around line 119-120: Validate max_cells_per_axis is at least 2 before the ncol
and nrow calculations in the heightfield dimension logic, rejecting smaller
values instead of allowing the max(2, ...) expressions to exceed the configured
upper bound. Keep the existing dimension calculations unchanged for valid
inputs.

In `@newton/utils.py`:
- Around line 35-37: Remove the redundant “heightfield utils” banner comment
near the top of newton/utils.py, leaving the following import and surrounding
code unchanged.

🪄 Autofix (Beta)

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 89ea7a1f-de42-4479-97c9-e5bcc5ed9462

📥 Commits

Reviewing files that changed from the base of the PR and between ff9b71d and d9f41e2.

📒 Files selected for processing (6)

• CHANGELOG.md
• docs/api/newton_utils.rst
• newton/_src/geometry/types.py
• newton/_src/utils/heightfield.py
• newton/tests/test_heightfield.py
• newton/utils.py

[codecov]

Codecov Report

❌ Patch coverage is 96.55172% with 1 line in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
newton/_src/utils/heightfield.py	94.73%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

An unexpected error occurred while generating fixes: Not Found - https://docs.github.com/rest/git/refs#get-a-reference

[eric-heiden]

Thanks!