Integrate dexsim gizmo controllers

[yuecideng]

Description

Summary

• Delegate world-level rigid-body and articulation manipulation to dexsim's EntityGizmoManipulator.
• Enable entity gizmos by default when a viewer window opens, keep headless simulations disabled, and expose explicit enable/disable/query APIs.
• Register EmbodiChain's built-in default_plane as a static external target so it cannot be manipulated.
• Bind robot TCP gizmos to dexsim's IKGizmoController and NewtonChainIK, while adapting joint state reads and writes through EmbodiChain's Robot abstraction.
• Update gizmo examples and documentation, and add lifecycle, exclusion, and robot-controller tests.

Dependency / merge gate

This PR requires the next dexsim release and must not be merged or released before that version is published and EmbodiChain's dexsim requirement is updated.

The required dexsim release must include:

• World.enable_entity_gizmo(), World.disable_entity_gizmo(), and World.get_entity_gizmo();
• multi-target EntityGizmoManipulator support, including register_external_target();
• dexsim.kit.ik.IKGizmoController and dexsim.kit.ik.NewtonChainIK.

The dependency file is intentionally unchanged because that dexsim version has not been released yet.

Related: #420

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation update

Screenshots

Not applicable; behavior is covered by automated tests and interactive dexsim smoke tests.

Validation

• black .
• git diff --check
• python -m compileall on changed Python modules
• pytest -q tests/sim/test_cfg.py tests/sim/test_sim_manager.py tests/sim/objects/test_gizmo.py — 28 passed
• pytest -q tests/sim/objects/test_robot_cfg.py -k 'not pk_dof' — 20 passed
• pytest -q tests/sim/objects/test_robot_cfg.py -k 'pk_dof' — 8 passed
• Interactive smoke checks for entity attach/detach, window reopen/config restore, headless behavior, default-plane exclusion, and robot IK on CPU/CUDA

Checklist

• I have run the black . command to format the code base.
• I have made corresponding changes to the documentation.
• I have added tests that prove my feature works.
• Dependencies have been updated — pending the next dexsim release described above.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Greptile Summary

The PR integrates DexSim entity and robot IK Gizmo controllers across native-window, Viser, and preview workflows.

• Adds world-level entity Gizmo lifecycle APIs and default-plane exclusion.
• Adds Newton IK-backed robot Gizmos and EmbodiChain robot-state adapters.
• Adds Viser click-to-pick interaction, preview controls, documentation, and lifecycle tests.

Confidence Score: 4/5

The PR is not yet safe to merge because picker ownership and manifest/frame synchronization failures remain outstanding.

Picking an entity can still claim and later destroy a pre-existing user Gizmo, while a topology-changing manifest can still pair new node IDs with old picker transforms until the next matching frame.

Files Needing Attention: embodichain/lab/sim/sim_manager.py; embodichain/lab/visualization/backends/viser.py

Important Files Changed

Filename	Overview
embodichain/lab/sim/sim_manager.py	Adds entity-Gizmo lifecycle management, picker integration, and simulation-thread Gizmo command processing.
embodichain/lab/sim/objects/gizmo.py	Reworks robot Gizmos around DexSim Newton IK while retaining rigid-object and camera control paths.
embodichain/lab/visualization/backends/viser.py	Adds browser click-to-pick controls, ray-cast state, and pick-command publication.
embodichain/lab/visualization/picker.py	Introduces backend-neutral ray-to-triangle selection for static scene meshes.
embodichain/lab/scripts/run_env.py	Adds native single-environment preview setup and visibility controls for robot IK Gizmos.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Native window] --> B[DexSim EntityGizmoManipulator]
    C[Viser click] --> D[ScenePicker]
    D --> E[PickCommand queue]
    E --> F[SimulationManager]
    F --> G[Target Gizmo]
    H[Robot TCP target] --> I[IKGizmoController]
    I --> J[NewtonChainIK]
    J --> K[Robot joint drive targets]

Loading

_{Reviews (2): Last reviewed commit: "wip" | Re-trigger Greptile}

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

Suppressed comments (2)

embodichain/lab/visualization/runtime.py:168

• PickCommandQueue.put() replaces an existing command in-place, which breaks the stated “arrival order” semantics when a client clicks again after other clients (e.g., A, B, A drains as A, B instead of B, A). To keep only the latest command per client while preserving correct ordering of the retained commands, remove any previous entry for the client and append the new command at the end.

            for index in range(len(self._commands) - 1, -1, -1):
                if self._commands[index].client_id == command.client_id:
                    self._commands[index] = command
                    return

embodichain/lab/sim/sim_manager.py:2367

• process_pick_commands() is driven by the Viser backend, but enable_gizmo() defaults to creating a native DexSim gizmo whenever sim_config.headless is False. If a user configures Viser with headless=False (native window suppressed by Viser), this call can raise because no native window exists. For click-to-pick, force enable_native=False so the picker always uses the backend-neutral (Viser) gizmo path.

            self._release_picker_gizmo()
            gizmo = self.enable_gizmo(uid=uid)
            if gizmo is not None:

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated no new comments.

Suppressed comments (1)

embodichain/lab/sim/sim_manager.py:2358

• Click-to-pick currently clears the existing picker-owned Gizmo when the clicked node resolves to an unsupported kind (e.g., articulation/soft/camera). The docs state these are ignored by the picker, and clearing here also makes accidental clicks on non-pickable nodes unexpectedly detach the current pick.

Suggestion: keep the warning (or drop it), but do not call _release_picker_gizmo() for unsupported kinds—just continue processing the next command.

                logger.log_warning(
                    f"Pick target kind {kind!r} (uid {uid!r}) is not gizmo-able; "
                    "only rigid objects and robots can be picked."
                )
                self._release_picker_gizmo()