Skip to content

Add InteractiveScene camera debug helpers (S5) - #180

Merged
KraHsu merged 1 commit into
dev/bump-genesis-1.0from
feat/genesis-1.0-s5-xacro-imgui
May 29, 2026
Merged

KraHsu merged 1 commit into
dev/bump-genesis-1.0from
feat/genesis-1.0-s5-xacro-imgui

Conversation

@KraHsu

@KraHsu KraHsu commented May 29, 2026

Copy link
Copy Markdown
Owner

Summary

Phase S5 of the Genesis 1.0 migration (ADR-0001). Ships the camera
debug helpers — the slot in the S5 scope with a clean v1.0 implementation —
and explicitly carves the other two sub-tasks (full xacro support on
ArticulationCfg, ImGui slider bridge) as post-migration polish.
Neither is on the critical path for the dev/bump-genesis-1.0 → main
promotion.

Changes

  • src/genelab/scene/interactive_scene.py — two thin wrappers over
    Genesis 1.0's scene.draw_debug_frustum / scene.draw_debug_trajectory:
    • draw_camera_frustums(camera_names=None, color=...) resolves
      names against the scene's CameraSensor set; returns the number
      drawn so callers can detect mis-named selections.
    • draw_camera_trajectory(positions, radius, color) is a verbatim
      pass-through.
      Both raise RuntimeError if called pre-build().
  • src/genelab/sensor/camera.py — added a public gs_camera
    property so external debug code reaches the Genesis handle through
    the same surface instead of _cam.
  • tests/test_scene_camera_debug.py — 7 new tests via a
    _FakeGsScene that records every debug-draw call; a monkeypatch
    routes isinstance(s, CameraSensor) through fakes so no real
    Genesis env is needed.
  • docs/concepts/scene.{en,zh}.md — new Camera debug helpers
    section.
  • CHANGELOG.md — ### Added entry.

v1.0 inspection notes (other S5 sub-tasks)

ADR S5 sub-task v1.0 reality Decision
Extend Articulation to dispatch on .xacro Genesis 1.0 already auto-preprocesses .xacro / .urdf.xacro files when loaded via gs.morphs.URDF (the parser is invoked at URDF morph build time). GeneLab's Articulation is still MJCF-only — adding URDF/xacro is a real surface change to ArticulationCfg (parallel urdf_path field + dispatch in spawn() + asset_zoo updates). Carved to post-migration polish. Users who need xacro today can call gs.morphs.URDF(file="...xacro", xacro_args={...}) directly; promoting it to ArticulationCfg is a follow-up after the migration lands on main.
Add a sample .xacro robot under asset_zoo Hinges on the ArticulationCfg URDF support landing first. Carved with the parent sub-task.
draw_camera_frustums() + draw_camera_trajectory() Genesis 1.0 exposes both via scene.draw_debug_frustum(camera, color) and scene.draw_debug_trajectory(poss, radius, color). Shipped in this PR.
Wire --debug-cameras CLI flag Trivial follow-up once the helpers exist; needs an InteractiveSceneCfg.debug_cameras flag and a one-line call from the step hook. Carved to a future commit on this branch or a separate PR — non-blocking for promotion.
ImGui slider bridge mapping ImGui sliders to joint targets Genesis's viewer ImGui hook can't be probed headlessly; needs a display-equipped environment to validate the callback API. Existing bridges/dearpygui.py already provides a working twist-bridge (over DearPyGui's own loop), so the ImGui-native equivalent is an additive, not a blocker. Carved to post-migration polish. The S1-added SimulationCfg.viewer_imgui flag already plumbs Genesis's ImGui overlay; the slider bridge is a separate (display-required) feature.

Test plan

  • ruff check
  • ruff format --check
  • pyright — 0 errors, 0 warnings
  • pytest — 605 passed (+7 scene-debug), 0 failed
  • mkdocs build --strict

Risks

  • Pre-build call sequencing. Both helpers raise if called before
    build(). Play-time hooks (e.g. a custom EnvHook or a
    RecorderBridge extension) need to register after the env's
    build phase — same constraint every sensor wrapper already obeys.
  • Camera name resolution is by sensor name, not link name. The
    helpers walk scene._sensors. A scene with multiple cameras
    attached to the same link works fine; mistyping the name surfaces
    with a KeyError listing the available sensor names.

Notes

  • After this merges, the remaining S5 sub-tasks are deferred to
    post-migration polish. The integration branch is then ready for the
    promotion PR dev/bump-genesis-1.0 → main. At ~22 commits
    ahead of main, the diff is reviewable in one pass.
  • S3.3 (registered tactile example task) is also still parked as
    parallel housekeeping; carving it the same way unless you want it
    before promotion.

Two thin wrappers over Genesis 1.0's
``scene.draw_debug_frustum(camera, color=...)`` and
``scene.draw_debug_trajectory(poss, radius, color)`` for inspecting
attached cameras at play time:

- ``draw_camera_frustums(camera_names=None, color=...)`` resolves names
  against the scene's ``CameraSensor`` set and forwards each handle to
  ``draw_debug_frustum``. Returns the number drawn so callers can
  detect mis-named selections without poking the viewer. A name that
  resolves to a non-camera sensor raises ``TypeError``; an unknown
  name raises ``KeyError``.
- ``draw_camera_trajectory(positions, radius, color)`` is a verbatim
  pass-through to ``draw_debug_trajectory`` — the caller owns the
  positions buffer so no history sits on the scene side.

Both helpers raise ``RuntimeError`` if called before ``build()`` since
Genesis allocates the camera handles in ``CameraSensor.pre_build_genesis``.

Added a public ``gs_camera`` property on ``CameraSensor`` so the scene
helper reads the underlying handle through the same surface external
debug code uses, rather than reaching into ``_cam``.

Tests use a synthetic ``_FakeGsScene`` that records every debug-draw
call plus a ``_FakeCameraSensor`` that exposes ``gs_camera``; a
monkeypatch routes ``isinstance(s, CameraSensor)`` through the fake
class so no real Genesis env is needed.

Bilingual ``Camera debug helpers`` section added to
``docs/concepts/scene.{en,zh}.md``.

This ships **S5.1** of the Genesis 1.0 migration; the remaining S5
sub-tasks (full xacro support on ``ArticulationCfg``, ImGui slider
bridge) are deliberately carved as post-migration polish — neither is
on the critical path for the ``dev/bump-genesis-1.0 → main`` promotion.
@KraHsu
KraHsu merged commit 33c80b5 into dev/bump-genesis-1.0 May 29, 2026
3 checks passed
@KraHsu
KraHsu deleted the feat/genesis-1.0-s5-xacro-imgui branch May 29, 2026 06:07
KraHsu added a commit that referenced this pull request Jun 5, 2026
Add InteractiveScene camera debug helpers (S5)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant