Trail

[fjenelten-bdai]

Description

This PR adds a modular framework for generating parameterizable mountain-bike trails. Each terrain patch comprises four components: a starting platform, a final platform, a connecting trail segment, and distinct skill elements. The resulting terrain is represented as a single mesh using the trimesh library, which models geometry as triangles and stores visual information within the RGB channels.

A trail segment is generated by first defining a cross-section polygon with counter-clockwise ordered vertices. This polygon is then swept along a sweeping path, a sequence of knot-points (x, y, z and yaw) connecting the two platforms. To form a simple ground floor around the trail, the vertices on the left and right borders are expanded outward. Each trail segment may contain one or more skill elements of a unique type, such as ramps, skinnies, roots, rocks, or waves. Each element is parameterized by a uniform distribution over its dimensions.

The generated terrains can easily be embedded into the existing Terrain Generator. The parameterization of the skill elements scales linearly (other maps may be defined) with the terrain level, allowing to employ a classical terrain curriculum.

The terrain mesh is systematically randomized by overlaying the vertices with a sequence of geometric disturbances. Additionally, decorative elements such as trees, roots, or stones can be procedurally placed adjacent to the trail. These perturbations break predictable structural patterns, preventing overfitting to specific procedural patterns.

Semantic information is explicitly stored in the vertex colors. The exact RGB values can be chosen arbitrarily, provided the mapping from RGB to semantic label remains bijective.

As training environment we have generate more than 1000 unique terrain patches and trained behaviors on a single NVIDIA L4 GPU.

This PR is part of an upcoming publication from the Robotics and AI (RAI) institute.

Type of change

• non breaking feature

Screenshots

trail_library_short.mp4

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[greptile-apps]

Greptile Summary

This PR introduces a modular mountain-bike trail terrain generator for Isaac Lab, producing parameterizable terrain patches (start platform → trail with skill elements → end platform) as trimesh meshes with semantic vertex coloring and curriculum-aware difficulty scaling.

• Core pipeline (trail_terrains.py, trail_cfg.py): sweeps a 2D cross-section polygon along a sampled path, applies roll, terrain deformation functions, and optional decorative objects, then assembles platforms and a surrounding floor into one merged mesh.
• Skill elements and helpers: separate modules for object profiles (ramps, waves, roots, stairs), sweeping paths, roll functions, and terrain deformation primitives; utility modules for math, color, NumPy, and trimesh operations.
• Three bugs need attention before merging: two silent no-ops in HSV color randomization that leave hue unwrapped and saturation unclamped; an inverted/incomplete boundary guard in the decoration placement loop that can place objects outside the terrain patch; and a = vs += mistake in delta_z_sin_xy that discards all but the last wave pass when N > 1.

Confidence Score: 3/5

Not safe to merge as-is: incorrect vertex colors on all decorated objects, potential out-of-bounds decoration placement, and a broken N-pass accumulation in a terrain deformation function.

Three independent logic bugs affect the generated terrain output. The no-op HSV modifications silently produce wrong colors on every decorated object. The boundary check in add_decoration is logically inverted on the x-axis, so decorations can be placed outside the patch. The delta_z_sin_xy accumulation bug means any configuration with N > 1 computes the wrong deformation. All are straightforward one-line fixes.

decoration_functions.py (HSV no-ops and annotation), trail_terrains.py (boundary guard in add_decoration), terrain_functions.py (delta_z_sin_xy accumulation).

Important Files Changed

Filename	Overview
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/elements/decoration_functions.py	Two silent no-ops in load_object_mesh leave hue unwrapped and saturation unclamped, producing incorrect vertex colors; also uses invalid dict() call syntax for type annotation.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/trail_terrains.py	Boundary check in add_decoration only guards against y-axis overflow; objects with x outside [0, max_x] are not filtered and can be placed outside the terrain patch.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/elements/terrain_functions.py	delta_z_sin_xy uses assignment (=) instead of accumulation (+=) inside its N-pass loop, so only the last wave pass is retained when N > 1.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/trail_cfg.py	Comprehensive configuration dataclasses for all terrain parameters; docstring typo and invalid dict() annotation syntax.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/utils/math.py	Well-implemented math utilities (interp, sample, in_limits) with good validation; straightforward and correct.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/utils/trimesh_utils.py	Clean mesh utilities using open3d for simplification and cKDTree for color interpolation; straightforward and correct.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/elements/sweeping_paths.py	Collection of parameterized sweeping path generators; well-structured and consistent.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/terrain_parameter_interface.py	Small interface class exposing shared terrain geometry parameters to MDP components; correct and straightforward.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/utils/colors.py	HSV/RGB conversion utilities with torch and numpy implementations; consistent with usage patterns.
source/isaaclab_contrib/isaaclab_contrib/terrains/trail/elements/object_profiles.py	2D profile generators for ramps, waves, roots, boxes, and stairs; all correct.
source/isaaclab_contrib/isaaclab_contrib/test/terrains/test_trail.py	Unit tests covering core utility functions; reasonable coverage.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[mesh_trail_segment] --> B[Interpolate curriculum params]
    B --> C{Object loop}
    C -->|fits on trail| D[object_function]
    D --> E[sweep_polygon]
    E --> F[Apply transform + color]
    F --> C
    C -->|no more room| G[trail_profile polygon]
    G --> H[down_sample_to_enforce_min_res]
    H --> I[Compute trail_roll]
    I --> J[Apply roll to objects]
    J --> K[sweep_polygon trail along full path]
    K --> L{extrude_trail_objects?}
    L -->|yes| M[Ray-cast objects into trail mesh]
    L -->|no| N[Merge object meshes]
    M --> O[color_mesh]
    N --> O
    O --> P[process_floor]
    P --> Q[add_platforms P0 + P1]
    Q --> R[Apply terrain_functions]
    R --> S[add_decoration]
    S --> T{ride_direction}
    T -->|uphill| U[origin = P0]
    T -->|downhill| V[Flip mesh, origin = P1]
    U --> W[Translate to world frame]
    V --> W
    W --> X[Return mesh + origin]

Loading

_{Reviews (1): Last reviewed commit: "improve readme" | Re-trigger Greptile}

[kellyguo11]

could we put the details in its own doc page under https://isaac-sim.github.io/IsaacLab/develop/source/experimental-features/bleeding-edge.html

[fjenelten-bdai]

I have added a trail.rst file with the same infomration as the current readme. I have also enriched the documentation with 4 fpeg images. I have added the compiled dock below for a quick visual check.

Regarding the README file: Do you recommend to completely remove the changes there, or support both readme and web doc as currently the case?

trail_doc.pdf

[kellyguo11]

maybe this could become a demo script?

[fjenelten-bdai]

Thats a good idea. As this probably makes most sense in combination with the terrain importer, I have added new task called "IsaacContrib-Velocity-Trail-AnymalC" in isaaclab_tasks_contrib/trail. Below a small snapshot of how it looks like.

[kellyguo11]

could you add license files for these under https://github.com/isaac-sim/IsaacLab/tree/develop/docs/licenses/dependencies?

[fjenelten-bdai]

the shapely packages seems to be already installed, hence I have removed it. I have now added the manifold3d package to pyproject.toml, which was missing. The license for this package appears to be already present within the linked directory.

[kellyguo11]

we've updated our dev workflow to add changelog fragments now instead of modifying the changelog file directly to avoid conflicts between PRs

[fjenelten-bdai]

I have added two rst files, both names fjenelten-feature-trail_library_migration.rst, one placed in isaaclab_tasks/changelog.d and the other in isaaclab_contrib/changelog.d.

[fjenelten-bdai]

@kellyguo11 Thanks a lot for the review! Addressing your feedback led to the following updates:

Changes made:

• Added three .jpeg images to docs/source/_static/experimental-features/trail/.
• Added docs/source/experimental-features/trail.rst for the web page documentation.
• Added changelog fragments to source/isaaclab_contrib/changelog.d/ and source/isaaclab_tasks/changelog.d/ following the guidelines for updating the changelog.
• Addressed the smaller code feedback in isaaclab_contrib/terrains/trail.
• Added an __init__.py and anymal_trail_env_cfg.py inside source/isaaclab_tasks/isaaclab_tasks/contrib/trail/ to provide a ready-to-use training environment for testing.
• Updated pyproject.toml file with all missing dependencies .

To verify everything works, I have done the following:

• Tore down and rebuilt the Docker container.
• Ran the newly added unit tests.
• Built and verified the docs (./isaaclab.sh --docs).
• Ran the test task: ./isaaclab.sh -p scripts/environments/zero_agent.py --task IsaacContrib-Velocity