feat: GPU-accelerated FrameView local poses + a new xform_space_writer API

[pv-nvidia]

Fast GPU pose/scale ops on Fabric + a new writer-scope API

What this does

Two things:

1. Local-space pose and scale ops are now GPU-fast on the Fabric backend.
   They go through the same Warp-kernel path that world-space ops already used.
   The old USD fallback for local-space is ~100× slower (see the table below).

2. All transform writes go through a small context manager. You open a
   scope, do your writes inside it, and the scope handles the cleanup:

   with view.xform_world_space_writer() as writer:
       writer.set_poses(positions=p, orientations=o)
       writer.set_scales(scales=s)

   Use view.xform_local_space_writer() for local-space writes.

Builds on Piotr's prototype at
bareya/pbarejko/camera-update.

Why a scope?

A FrameView keeps two copies of each prim's transform in Fabric storage:
the omni:fabric:worldMatrix and omni:fabric:localMatrix attributes.
When you write one, the other has to be recomputed so they stay
consistent.

Without a scope, that recompute has to run after every single write. With
a scope, it runs once, when the scope closes. You can call set_poses
and set_scales as many times as you want inside the scope; on exit, one
Warp kernel derives the other space and one wp.synchronize() runs.
Empty scopes cost nothing.

The scope also pauses Fabric Hierarchy's transform-change tracking
while you're writing, then restores it on exit. (Fabric itself is just
the data store; Fabric Hierarchy, exposed through USDRT's
IFabricHierarchy, is the plugin that watches writes to
omni:fabric:localMatrix / omni:fabric:worldMatrix and keeps them
mutually consistent across the hierarchy.) Its tracking is pull-based:
a per-attribute listener records writes into a changelog, and the
plugin drains and processes that changelog on the next call to
IFabricHierarchy::update_world_xforms(). Pausing the listener does
not block the writes themselves — they still land in Fabric storage —
it just keeps them out of the changelog. With the changelog empty, the
next tick has nothing to "catch up on" for these prims, and can't
decide one of the two spaces is canonical and derive the other from
it. See the next section for why that matters.

Rules:

• Only one writer can be open on a view at a time. Opening a second one
  raises RuntimeError.
• While a writer is open, the view's own getters (get_world_poses, etc.)
  raise. Read through the writer (writer.get_poses()) inside the scope,
  or close the scope first.
• Do not advance the simulation or render from inside the scope.
  No sim.step(), no world.render(), no SimulationApp.update().
  The matrices are mid-write until exit, and rendering against that state
  would read torn data. Keep scopes short and close them before stepping.
• If something raises inside the scope (a user-code bug, a notebook
  cell interrupt, etc.), the scope still runs the opposite-space recompute
  on exit so the world and local matrices stay consistent prim-by-prim.
  The partial write itself is not rolled back — if you need
  all-or-nothing, snapshot the matrices yourself before entering.

Why we have to coordinate with Fabric Hierarchy (renderer correctness)

A writer scope is synchronous Python code, so the renderer can't see
anything mid-scope — no tick runs until we exit. The risk is on the
next render/sim tick after the scope closes.

On that next tick, Fabric Hierarchy runs its
IFabricHierarchy::update_world_xforms() step, which can recompute
omni:fabric:worldMatrix from omni:fabric:localMatrix (or vice
versa). If it thinks one of the two was the user's most recent edit,
it derives the other from it; the derived value — not what we wrote —
is then what the Fabric Scene Delegate (FSD) hands to RTX on the
render path.

Three things in this PR keep that next-tick recompute from clobbering our
work:

1. Opposite-space derive at scope exit. By the time the scope closes,
   omni:fabric:worldMatrix and omni:fabric:localMatrix are mutually
   consistent prim-by-prim, so any recompute Fabric Hierarchy does is a
   no-op.

2. Fabric-Hierarchy change tracking is paused for the whole scope.
   The writer calls track_local_xform_changes(False) and
   track_world_xform_changes(False) on enter (saving the prior state)
   and restores them on exit. While tracking is paused, the listeners
   don't record our writes in their changelog, so when the next tick
   runs there's nothing for update_world_xforms() to "catch up on".

3. Two persistent selections with explicit read-only / read-write
   flags. Outside the scope, the view's selection is fully read-only —
   both omni:fabric:worldMatrix and omni:fabric:localMatrix are
   flagged RO. Inside the scope, the writer flips to a fully read-write
   selection.

   _sel_ro :  worldMatrix=RO, localMatrix=RO   (steady state, between writes)
   _sel_rw :  worldMatrix=RW, localMatrix=RW   (active during a writer scope)
   

   Both selections are built once when the view is initialized and kept
   alive for its lifetime. The writer scope flips a single flag (_is_rw)
   on enter/exit; nothing is rebuilt. The RO steady state tells Fabric
   Hierarchy's next-tick update_world_xforms() that no attribute is
   user-authored, so it leaves both alone.

Backend support

• Fabric (PhysX): the fast GPU path described above.
• USD, Newton, OVPhysX: the writer is a thin wrapper. Writes go straight
  to the backend's existing storage. No batching, no extra recompute (there
  is no second matrix to keep in sync). Same API across all four backends.

Newton has two different "scale" ideas, and the API keeps them apart:

• NewtonSiteFrameView.set_scales(...) (deprecated) writes the Newton
  collision-shape geometry size.
• The writer's set_scales(...) writes per-site transform scale,
  matching what USD FrameView does.

They operate on different state and are not merged.

API changes

New (recommended):

• view.xform_world_space_writer() / view.xform_local_space_writer() —
  a context manager with set_poses, set_scales, get_poses,
  get_scales.

Deprecated (still works, warns once per class on first use):

• set_world_poses / set_local_poses — use the writer scope.
• get_scales / set_scales — use get_local_scales /
  get_world_scales, or the writer's set_scales.

Benchmark (1024 prims, 50 iterations, Blackwell RTX PRO 5000)

Per-iteration timings (lower is better):

Operation	USD (ms)	Fabric (ms)	Newton Site (ms)
Get World Poses	8.6148	0.0375	0.0307
Set World Poses	19.1357	0.1090	0.0368
Get Local Poses	5.9556	0.0374	0.0497
Set Local Poses	7.9794	0.0979	0.0790
Get World Scales	13.1193	0.0371	0.0015
Set World Scales	21.4571	0.1014	0.0612
Get Local Scales	3.2544	0.0375	0.0022
Set Local Scales	3.8350	0.0937	0.0587
Get Both (World+Local)	14.7506	0.0738	0.1302
Interleaved World Set→Get	28.1046	0.1432	0.1588
Per-iter total	126.2	0.77	0.61

Speedup vs USD (per-iter ops; one-time view construction excluded):

Operation	Fabric ×	Newton Site ×
Get World Poses	229.6×	280.2×
Set World Poses	175.6×	519.8×
Get Local Poses	159.0×	119.9×
Set Local Poses	81.5×	101.0×
Get World Scales	353.9×	8911.5×
Set World Scales	211.6×	350.4×
Get Local Scales	86.8×	1489.9×
Set Local Scales	40.9×	65.4×
Get Both (World+Local)	200.0×	113.3×
Interleaved World Set→Get	196.2×	177.0×
Overall (per-iter)	164×	207×

One-time view construction (reported separately, not part of the per-iter total): USD 4.6 ms, Fabric 4.4 ms, Newton Site 1013 ms — the Newton number is dominated by stage population on the first call. Steady-state per-iteration cost is what the speedup row reflects.

Notes for reviewers

• Getters call wp.synchronize() before returning, so the returned
  ProxyArray is always immediately readable from both GPU and host
  code — no caller-side sync needed. (Both the cached and the
  per-indices paths sync; this used to be asymmetric.)

[isaaclab-review-bot]

🔍 Code Review Update

Review of new commits: PR was rebased and expanded since last review.
Previously reviewed: b15d6235 | Now reviewing: 80838c00

Summary

The PR has been expanded from 5 to 6 commits, adding Fabric-accelerated get/set_local_poses:

1. Service locator infrastructure on SimulationContext
2. Service locator tests + changelog
3. Indexed Fabric transform kernels in isaaclab.utils.warp.fabric
4. FabricStageCache as a shared hierarchy handle
5. (NEW) Merge commit to consolidate branches
6. (NEW) FabricFrameView rewrite with get/set_local_poses + dirty tracking

✅ New Additions Since Last Review

• Fabric-accelerated local poses: set_local_poses / get_local_poses now use wp.indexedfabricarray to read/write omni:fabric:localMatrix directly on the GPU
• Bidirectional world↔local sync:
  • set_world_poses → recomputes localMatrix via _sync_local_from_world()
  • set_local_poses → marks _world_dirty, world recomputed on next get_world_poses
• Per-view dirty tracking: _world_dirty flag is instance-scoped, so concurrent views on the same stage don't clear each other's flag
• Parent matrix handling: _build_parent_indexed_array() + _compute_parent_fabric_indices() for parent world matrix lookups
• Topology-adaptive: PrepareForReuse() calls + _rebuild_trans_ro_arrays() for automatic recovery
• Comprehensive tests: 13 new integration tests covering local/world consistency, rotated/scaled parents, multi-view isolation

🔧 Remaining Observations

[Minor] Index array dtype mismatch still present

The kernels declare indices: ArrayUInt32, but _compute_fabric_indices() returns dtype=wp.int32:

# fabric_frame_view.py
return wp.array(indices, dtype=wp.int32, device=self._device)

Warp will silently cast, so this works in practice. Suggestion: switch to dtype=wp.uint32 for consistency with the kernel signatures. Not blocking.

[Minor] Undefined buffer references in get_local_poses

get_local_poses references self._fabric_local_translations_buf and self._fabric_local_orientations_buf:

if use_cached:
    translations_wp = self._fabric_local_translations_buf
    orientations_wp = self._fabric_local_orientations_buf

These don't appear to be initialized in _initialize_fabric(). Verify these buffers are created alongside the existing world-pose buffers.

📋 Architecture Notes

The world↔local propagation design is clean:

• Write world → update local: _sync_local_from_world() runs update_indexed_local_matrix_from_world kernel immediately after world writes
• Write local → lazy world update: _world_dirty flag defers update_indexed_world_matrix_from_local until the next world read

This asymmetry makes sense: world writes are typically followed by physics steps (which don't need locals), while local writes are often followed by world reads for rendering.

📋 Verdict

LGTM — the new local-pose acceleration is a significant feature addition. The bidirectional sync logic is well-designed, and the test coverage is comprehensive (33 test functions across all new modules). The minor dtype observation from the previous review remains, plus one potential undefined buffer issue to double-check.

---

Automated review by isaaclab-review-bot • Reviewed at 80838c00

[isaaclab-review-bot]

🔍 Code Review Update

Review of new commits: PR was rebased and expanded since last review.
Previously reviewed: eb5582ec | Now reviewing: 9ff3155

Summary

This PR delivers a well-architected feature: GPU-accelerated local-pose operations for FabricFrameView. The implementation is comprehensive and addresses the core limitation where local poses previously fell back to USD round-trips.

✅ Strengths

1. Clean Architecture

• FabricStageCache provides shared hierarchy handles via the service locator pattern, avoiding per-view duplication
• Three persistent selections (trans_sel_ro, world_sel_rw, local_sel_rw) cleanly separate read vs. write access patterns
• Factory dispatch in FrameView._get_backend() correctly routes to UsdFrameView when Fabric is unavailable

2. Robust World↔Local Consistency

• Bidirectional dirty tracking: set_local_poses marks _world_dirty, deferred until next world read
• _sync_local_from_world() / _sync_world_from_local_if_dirty() keep matrices consistent
• Per-view dirty flags prevent concurrent views from clearing each other's pending syncs

3. Topology-Adaptive Design

• PrepareForReuse() + lazy array rebuild in _get_*_array() handles Fabric memory layout changes
• _rebuild_trans_ro_arrays() consolidates index and indexed-array refresh

4. Excellent Test Coverage

• 13+ new integration tests covering rotated parents, scaled parents, multi-view isolation
• test_set_local_then_get_world_with_rotated_parent validates transpose-convention correctness
• test_multi_view_per_view_dirty_isolation catches per-stage vs. per-view flag bugs

🔧 Minor Observations

[Minor] Index array dtype mismatch

_compute_fabric_indices() returns dtype=wp.int32, but kernels declare indices: ArrayUInt32:

return wp.array(indices, dtype=wp.int32, device=self._device)

Warp silently casts, so this works. Suggestion: use dtype=wp.uint32 for consistency with kernel signatures. Not blocking.

[Nit] Docstring transpose-convention note

The docstrings for update_indexed_local_matrix_from_world and update_indexed_world_matrix_from_local explain the transpose identity well. Consider adding a brief note that this relies on Fabric's row-major storage convention for future maintainers.

[Style] Empty sentinel shape

_fabric_empty_2d_array_sentinel uses shape (0, 0):

self._fabric_empty_2d_array_sentinel = wp.zeros((0, 0), dtype=wp.float32, device=self._device)

This is fine since the kernels gate on shape[0] > 0, but (0, 3) or (0, 4) might be slightly more self-documenting for unused position/quaternion slots.

📋 Architecture Notes

The asymmetric sync strategy is well-reasoned:

• Write world → sync local immediately: _sync_local_from_world() runs right after world writes because downstream code (e.g., rendering) typically reads locals soon after
• Write local → lazy world sync: _world_dirty flag defers the world = parent * local kernel until the next world read, avoiding unnecessary computation when multiple local writes occur before a world read

📋 CI Status

CI checks are currently pending. The pre-commit and changelog checks have passed.

📋 Verdict

LGTM — This is a significant feature addition that completes the Fabric acceleration story for FabricFrameView. The bidirectional sync logic is sound, test coverage is thorough, and the codebase is well-documented. The minor dtype observation is non-blocking.

---

Automated review by isaaclab-review-bot • Reviewed at 9ff31550

---

Update (d13ed99→7f1a012c): Reviewed large incremental batch (50+ files changed). This batch contains no changes to the core FabricFrameView implementation — the Fabric local-poses feature code is identical to the previously reviewed state.

Key changes in this batch (all outside the PR's core feature scope):

1. isaaclab_ppisp made fully optional: All packages (isaaclab_physx, isaaclab_newton, isaaclab_ov, isaaclab_ovphysx) removed hard isaaclab_ppisp from dependencies. Lazy try/except ModuleNotFoundError with _raise_missing_ppisp_error() helper provides actionable install hints only when isp_cfg is actually set. Clean pattern, consistently applied.

2. Cloner refactoring to ReplicateContext classes: physx_replicate, newton_physics_replicate, and ovphysx_replicate legacy functions now delegate to new PhysxReplicateContext, NewtonReplicateContext, and OvPhysxReplicateContext classes. Asset constructors call queue_*_replication(cfg) to register on REPLICATION_QUEUE. Well-structured — separates queueing from execution, enables batched replication.

3. MJWarp ls_parallel deprecated: Config field emits DeprecationWarning via __post_init__(), _build_solver() ignores it. Removed from all test configurations.

4. Newton manager lifecycle fix: close() now calls super().close() before cls.clear(), ensuring sensor invalidation callbacks fire while Newton state is still alive, preventing stale registrations leaking.

5. OvPhysX/OVRTX runtime guards: import_ovphysx() helper with actionable install messages, ovphysx==0.4.13 pin.

6. PhysxManager rigid body view: Now detects name collisions between rigid and non-rigid prims (e.g., JointWrenchSensor frame prim vs. rigid link with same name) and uses exact paths for ambiguous names.

7. Version bumps and changelog consolidation: All changelog fragment files moved into proper versioned CHANGELOG.rst entries.

Previous inline comments status:

• ⏳ P1 (Missing wp.synchronize() in indexed getter paths): Still present — no changes to fabric_frame_view.py in this batch. Remains non-blocking per previous assessment.
• ✅ P2 (Redundant kernel launch): Fixed in earlier commits (confirmed).

No new issues found in the incremental changes. All additions are well-implemented and follow established patterns. LGTM.

---

Automated incremental review by isaaclab-review-bot • Reviewed at 7f1a012c

---

Update (7f1a012→999cf3c6): Major architectural refactor reviewed.

Changes in this batch

The lazy dirty-flag mechanism (_DirtyFlag enum, _dirty field, _sync_*_if_dirty helpers, interleaved-write warning) has been removed entirely and replaced with a context-managed writer scope API (FrameViewSpaceWriterBase). This is a substantial and well-executed improvement:

1. New xform_space_writer() context manager: Opens a scoped write session ("world" or "local"). On __exit__, derives the opposite-space matrices once via a single Warp kernel and calls wp.synchronize() once. Clean, predictable, no more subtle interleaving bugs.

2. Single-active-writer invariant: Per-view lock prevents concurrent scopes — RuntimeError on double-entry. Well-tested.

3. Hierarchy listener pause/restore: _FabricWriterMixin._enter_impl() pauses track_local_xform_changes / track_world_xform_changes during writes, restoring prior state on exit. Correctly handles pre-paused listeners (no accidental re-enable).

4. Deprecated shims preserved: set_world_poses() / set_local_poses() remain as thin wrappers that open one-shot writer scopes internally + emit DeprecationWarning. Clean migration path.

5. set_world_scales / set_local_scales removed (breaking): Since these were introduced in this release cycle without stable downstream users, removal without deprecation is appropriate. Changelog documents it.

6. Test coverage: Comprehensive new tests for the writer contract — single-active invariant, derive-on-exit counting, empty-scope no-op, getter-raises-inside-scope, hierarchy tracking restore.

Previous comments status

• ✅ P2 (Redundant kernel launch): Fixed — the _sync_fabric_from_usd_initial() path now only composes localMatrix then calls _recompute_world_from_local_all(). The redundant world compose is gone.
• ⏳ P1 (Missing wp.synchronize() in indexed getter paths): Still present in the non-cached decompose paths. Remains non-blocking per previous assessment (callers on the same CUDA stream see correct ordering; only cross-stream or immediate .numpy() usage is affected).
• ✅ Minor observations (dtype, docstring, sentinel shape): These were non-blocking nits and remain unchanged. The sentinel shape (0, 0) is now less relevant since it is only used internally by the writer compose kernel.

New observations

No new issues found. The architectural shift from lazy dirty-flag tracking to eager derive-on-scope-exit is a clear improvement in correctness and readability. The _FabricWriterMixin pattern cleanly separates Fabric lifecycle management from the write logic. LGTM.

---

Automated incremental review by isaaclab-review-bot • Reviewed at 999cf3c6

[pv-nvidia]

Superseded by the consolidated PR #5728 (pv/fabric-full-stack).