Add conveyor Franka tasks with Newton and CPU PhysX

[maxkra15]

Description

Adds two contributed Franka conveyor tasks using the same pretrained policy and shared manipulation code: the original four-cube racetrack transfer task and a 24-parcel warehouse sorter. Both run on Newton GPU; the original task also has a native CPU PhysX reference.

• Racetrack transfer (IsaacContrib-Conveyor-Franka-Newton-v0): four numbered 40 mm cubes, counter-rotating belts at 0.35 m/s, phase-balanced resets, and continuous transfer commands. Both backends retain the same ordered 123 observations and eight actions at 120 Hz physics / 60 Hz policy rates.
• Warehouse sorting (IsaacContrib-Conveyor-Franka-Newton-Play-v0): textured cartons, lighting, racks, compact elevated returns, and gravity infeeds authored in USD. Twenty-four physical parcels reuse four policy slots with stable identity during grasps. Blue/green route to one circulating conveyor; orange/purple to the other. The original manipulation straights and adjoining 90-degree bends stay fixed.
• Shared infrastructure: custom triangle-mesh spawning, backend-neutral surface-velocity controls, Newton contact-force feedback and lifecycle hooks, and native PhysX surface-velocity authoring. Imported warehouse dressing has no physics ownership; additional background cartons are visual-only.

Native PhysX is intentionally CPU-only: GPU contact modification can drop belt contacts in the supported runtime, so CUDA configurations fail with an actionable error. Backend-compatible tensor shapes do not imply identical dynamics. The unchanged policy can also miss grasps and reset in the larger warehouse batch; reliable complete-batch sorting is not established.

Conveyor user guide · Task and asset details

Preview

Watch/download the 22-second warehouse preview. Captured from the merged branch on September 24, 2026, using the documented Kit recording configuration. It is not evidence of a completed batch. The video is hosted separately, and the repository contains only a small JPG for documentation.

Pretrained policy

Audited the online conveyor W&B runs. Iteration 7998 remains the latest completed continuation and highest reported final reward among the available trained runs examined. This is a run-summary comparison, not an exhaustive checkpoint evaluation.

The W&B model_7998.pt, canonical Isaac dev artifact, and public download match byte for byte: 5,505,205 bytes, SHA-256 361d1881f9abc2405eeebd7cf23f7967d142187d021b04417c8ab2dc213c1631. The existing publication is current; no replacement upload was needed.

IsaacContrib-Conveyor-Franka-Newton-v0_newtonmjwarp_none_rsl_rl.pt

The compact Newton task uses --checkpoint pretrained. The warehouse guide supplies the same public checkpoint URL explicitly; the PhysX task uses an explicit checkpoint path. Assets and checkpoints are downloaded on first use.

Validation

Merged current develop (e3a825f73) and adapted the conveyor lifecycle hooks and configuration imports to the current backend interfaces.

• 87 focused conveyor contract, geometry, slot identity, sorting, backend configuration, and surface-velocity tests passed.
• 267 Newton manager and visualizer-adapter tests passed.
• Native PhysX consolidated Contrib smoke test passed with two CPU environments; custom-mesh integration test passed.
• Published Newton checkpoint: 1,200 policy steps, four transfers, zero terminations/truncations, and zero non-finite observations.
• Warehouse Kit/RTX recording, CUDA graphs disabled: 1,440 policy steps, seven transfers, zero terminations/truncations, and zero non-finite observations. Nineteen of 24 parcels were sorted at the end of this bounded check.
• Verified table materials and live warehouse rendering. The guide disables experimental Kit geometry streaming, which hid meshes with a saved local preference. Graph-enabled Kit recording stalled in a local probe; the documented recording command disables graphs.
• Formatting, lint, changelog, and Git LFS checks passed. The built task wheel contains all nine USD assets.
• Sphinx documentation built with warnings treated as errors. Checked desktop/mobile rendering, all three environment-browser entries, the GitHub-rendered README table, and preview media.

These are bounded compatibility checks, not a guarantee of indefinite recovery or complete-batch sorting. The tests emit existing compatibility/deprecation warnings from the current simulation APIs.

Type of change

• New feature (non-breaking)
• Documentation update

Checklist

• I have read and understood the contribution guidelines.
• I have run the repository formatting and pre-commit checks with uv run isaaclab -f.
• I have updated the documentation and environment browser.
• I have added focused tests and run the relevant simulation checks.
• I have added changelog fragments for each changed source package.
• My name already exists in CONTRIBUTORS.md.

[greptile-apps]

Greptile Summary

The PR adds checkpoint-compatible Newton GPU and CPU PhysX conveyor-manipulation tasks, along with reusable custom-mesh spawning and Newton lifecycle hooks.

• Adds the Franka conveyor environment, backend adapters, MDP terms, PPO configuration, geometry, and focused tests.
• Adds custom triangular USD mesh configuration and spawning support.
• Extends Newton with solver-initialization and post-substep callback lifecycle APIs.
• Preserves configured environment devices when parse_env_cfg receives device=None.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
source/isaaclab_tasks/isaaclab_tasks/contrib/conveyor_franka/conveyor_franka_env_cfg.py	Defines the Newton conveyor scene and manager-based task contract; its required Newton package is now declared.
source/isaaclab_tasks/isaaclab_tasks/contrib/conveyor_franka/conveyor_force_driver.py	Implements batched Newton contact-force feedback and lifecycle-safe conveyor control.
source/isaaclab_tasks/isaaclab_tasks/contrib/conveyor_franka/conveyor_franka_physx_env_cfg.py	Defines the CPU-only native PhysX task variant and its backend constraints.
source/isaaclab_newton/isaaclab_newton/physics/newton_manager.py	Adds symmetric solver-initialization and post-substep callback registration and cleanup.
source/isaaclab/isaaclab/sim/spawners/meshes/meshes.py	Adds validated custom triangular-mesh spawning and configurable collision/subdivision behavior.
source/isaaclab_tasks/pyproject.toml	Declares the Newton and PhysX packages required by the newly registered conveyor tasks.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Registry["Gym task registry"] --> Env["ConveyorFrankaEnv"]
    Env --> Shared["ConveyorBeltView"]
    Shared --> Newton["Newton force driver"]
    Shared --> PhysX["PhysX surface-velocity adapter"]
    Newton --> Hooks["Newton solver lifecycle hooks"]
    PhysX --> CPU["CPU PhysX simulation"]
    Env --> MDP["Actions, observations, rewards, resets"]

Loading

_{Reviews (3): Last reviewed commit: "Localize conveyor task interfaces" | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The public custom-mesh spawner and Newton conveyor task are coherently structured, but three scoped fixes are needed before merge: limit the new displayColor behavior so existing mesh spawners do not change rendering semantics, preserve supported environment constructor keywords such as render_mode, and apply the repository-mandated copyright header to the new task files.

• Design and architecture: The separation between procedural geometry, the Warp force driver, environment configuration, and the reusable MeshCustomCfg spawner is sound. However, renderer-independent color authoring was added to the shared mesh helper, unintentionally extending the behavior beyond custom meshes and creating inconsistent color/material handling for existing spawners.
• API: MeshCustomCfg and spawn_mesh_custom are consistently exported and documented through the public stubs and changelog. The task environment constructor currently discards all Gym-provided keyword arguments, narrowing the base ManagerBasedRLEnv constructor contract and breaking paths that rely on render_mode; supported arguments should be forwarded.
• Implementation: The custom-mesh validation, collision configuration, racetrack generation, and force-driver organization are internally coherent. Required corrections are to scope displayColor authoring appropriately, retain the kitless warning when material properties remain unapplied, and update the new files to the required 2022-2026 copyright header.

Minor fixes needed. Posted 3 actionable findings inline.

Automated review; human maintainers own approval decisions.

[maxkra15]

@greptileai check again