Unify primitive mesh refinement controls

[mmichelis]

Description

• Add MeshCfg.edge_refinement, defaulting to 4.0, to control surface subdivision for all primitive mesh spawners using a bounding-box-diagonal target.
• Forward 1.0 / edge_refinement to automatic tetrahedralization for volume deformables spawned through MeshCfg primitive spawners. Direct callers of define_deformable_body_properties retain its existing default factor of 0.1.
• Document that values near 1.0 should be avoided for volume deformables because they can make TetWild tetrahedralization significantly slower.
• Replace MeshRectangleCfg.resolution with scalar edge_refinement. This removes independent per-axis resolution control, and subdivision counts can be discontinuous for non-power-of-two factors.
• Migrate existing cloth callsites and examples, and set the Franka soft-lift cuboid refinement to 8.0.

This is a breaking change. Unconfigured primitive surfaces now use an edge-refinement factor of 4.0, and unconfigured volume primitive spawners use a tetrahedralization factor of 0.25 instead of 0.1. Rectangles now use the common recursive edge-length subdivision instead of the previous per-axis grid.

Type of change

• Breaking change
• New feature

Release backport

• Backport this pull request to the active release branch after it merges into develop

Testing

• Ruff, format, compilation, and diff checks
• Mesh-spawner integration suite: 21 tests
• Newton surface-deformable initialization and freefall integration test
• PhysX deformables demo: completed setup and simulation
• Franka cloth environment: 20 steps each on Newton, PhysX, and OvPhysX
• Franka cloth camera environment: 5 PhysX/RTX steps with image observations
• Scripted Franka cloth lift: 50 steps each on Newton and PhysX
• Franka soft lift with refinement 8.0: 10 steps each on Newton and Isaac Sim PhysX
• Seed-42 RSL-RL scratch smoke at 2,048 environments: 55 soft updates and 11 cloth updates with finite losses
• Seed-42 matched checkpoint continuation at 2,048 environments: 52 updates each on develop and the PR mesh; final-20 success was 67.1% versus 81.5% for soft and 85.3% versus 87.6% for cloth
• TetWild timing check for all five volume primitives at the default factor of 0.25

PhysX reports an invalid surface-deformable-view warning in the demo and cloth environment. The same warning is present on untouched develop with the same runtime and is not introduced by this change.

Checklist

• Changelog fragments added
• Existing callsites migrated

[greptile-apps]

Greptile Summary

The PR unifies primitive mesh surface subdivision around MeshCfg.edge_refinement and forwards its reciprocal to automatic tetrahedralization for primitive volume deformables.

• Moves edge refinement from cuboid-specific configuration to the common primitive mesh configuration with a default of 4.0.
• Replaces rectangle per-axis grid resolution with generic diagonal-based recursive subdivision.
• Migrates cloth examples, tests, and Franka soft-object configurations to the unified control.
• Preserves the direct schema API’s existing tetrahedralization default of 0.1.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking issue identified.

The common refinement path validates the documented lower bound, applies subdivision consistently to primitive meshes, preserves direct schema-call defaults, and forwards the new tetrahedralization factor only on the existing volume-deformable path.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/sim/spawners/meshes/meshes.py	Centralizes primitive surface subdivision and forwards the reciprocal refinement factor for volume tetrahedralization; no actionable defect was established.
source/isaaclab/isaaclab/sim/spawners/meshes/meshes_cfg.py	Adds the common refinement field and removes rectangle resolution and the cuboid-specific override as an intentional breaking API change.
source/isaaclab/isaaclab/sim/schemas/schemas.py	Adds an optional tetrahedralization factor while retaining the existing direct-caller default.
source/isaaclab/test/sim/test_spawn_meshes.py	Extends integration coverage across all primitive spawners, invalid refinement, and volume-factor forwarding.
source/isaaclab_tasks/isaaclab_tasks/core/lift/config/franka_soft/franka_cloth_env_cfg.py	Migrates cloth configurations from per-axis resolution to the unified refinement factor.
source/isaaclab_tasks/isaaclab_tasks/core/lift/config/franka_soft/franka_soft_env_cfg.py	Raises cuboid refinement for both configured deformable backends consistently.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  C[MeshCfg.edge_refinement] --> S[Primitive surface mesh]
  S --> R[subdivide_to_size using bbox diagonal / refinement]
  R --> D{Deformable?}
  D -- No --> U[Write USD mesh]
  D -- Surface --> P[Apply surface deformable properties]
  D -- Volume --> T[Automatic tetrahedralization using 1 / refinement]
  P --> U
  T --> U

Loading

_{Reviews (1): Last reviewed commit: "Refine Franka soft lift cuboid mesh" | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The shared edge_refinement implementation is internally consistent, but the PR removes the public MeshRectangleCfg.resolution API without deprecation and does not document the changed primitive defaults as breaking changes with migration guidance in the changelog.

• Design and architecture: Centralizing primitive subdivision in _spawn_mesh_geom_from_mesh and forwarding the normalized target to volume tetrahedralization is coherent. However, the public rectangle configuration transition must retain a deprecation path rather than deleting resolution immediately.
• API: MeshCfg.edge_refinement is documented and validated, and direct callers of define_deformable_body_properties retain the existing 0.1 default. Existing rectangle callers using resolution will now fail during configuration construction, contrary to the repository rule requiring deprecation before public API removal. The changed surface-refinement and tetrahedralization defaults also need a major changelog entry with explicit migration guidance.
• Implementation: The changed spawner path consistently applies subdivision across primitive meshes and forwards 1.0 / edge_refinement only for volume deformables. The required fixes are compatibility handling for MeshRectangleCfg.resolution and release-note coverage for the changed defaults; no separate implementation defect was established.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🟡 Warning · Api — Default behavior changes filed as minor addition

This fragment records only the new field, but the change also alters existing behavior: cuboid refinement default moves 1.0 -> 4.0, all other primitives gain subdivision they never had, and primitive volume deformables now tetrahedralize at 0.25 instead of 0.1. Unmodified user configs silently produce different render and simulation meshes. Record these default changes in a major fragment with migration guidance (e.g. set edge_refinement=1.0).

[isaaclab-review-bot]

🟡 Warning · Api — Public resolution field removed without deprecation

Introducing edge_refinement here deletes MeshRectangleCfg.resolution, so existing configurations passing resolution=(nx, ny) now fail at construction with a TypeError. Repository guidelines forbid removing a public API without a prior deprecation and migration path. Keep resolution for one release, warn when it is set, and map it onto edge_refinement (with defined precedence) before deleting it.

[kellyguo11]

run-ci

[kellyguo11]

rendering test seems to have failed twice - do we need a golden image update for this?

[mmichelis]

rendering test seems to have failed twice - do we need a golden image update for this?

Ah yes that could very well be! I changed the default resolution so maybe there is some slight differences. Let me regenerate them!

[AntoineRichard]

run-ci

[isaaclab-bot]

Backported to release/3.0.0 as 51642ea.