[AlanZhu2006]

Summary

Add viser.extras.BatchedViserUrdf for a fixed-size group of robots that share
one URDF's visual geometry and have independent joint values and base poses.
Each visual mesh is exported once and rendered through the existing batched GLB
API. ViserUrdf and the frontend/message protocol remain unchanged.

Motivation

Addresses #658. This follows
the batched-URDF approach in
Chung Min Kim's Pyroki prototype,
referenced by @brentyi in the issue. FK uses NumPy and the existing optional
yourdfpy dependency; there is no JAX or Pyroki runtime dependency.

from pathlib import Path

import numpy as np
import viser
from viser.extras import BatchedViserUrdf

server = viser.ViserServer()
server.scene.add_frame("/robots", show_axes=False)
robots = BatchedViserUrdf(
    server, Path("examples/assets/batched_arm.urdf"),
    num_robots=16, root_node_name="/robots",
)
i = np.arange(16)
robots.update_base_poses(
    batched_wxyzs=np.tile([1.0, 0.0, 0.0, 0.0], (16, 1)),
    batched_positions=np.column_stack([i % 4, i // 4, np.zeros(16)]) * 1.2,
)
robots.update_cfg(
    np.array([[0.4, 0.1], [-0.2, 0.2]]), robot_indices=np.array([7, 2]),
)

Changes

• Full and indexed joint/base updates, with ordered unique robot_indices.
  Indexed joint updates evaluate FK for the selected rows; base edits reuse FK.
  Changed visual properties still send complete N-row arrays via public dense
  setters. This does not introduce sparse transport.
• Copied input state, finite real-array validation (including complex values
  inside object arrays), visibility, removal, and safe same-root replacement.
• A bundled two-joint robot, documentation, and a 16-robot animated demo:
  python examples/04_demos/06_batched_urdf.py --num-robots 16.
  --record demo.html exports a self-contained three-second animation.

Test plan

On macOS arm64 / Python 3.12.13, with runtime sources at 59bd950 and the
submission's documentation-only heading correction in 9a5f5e7:

• Final review: pytest --ignore=tests/e2e — 855 passed, 8 warnings in unchanged
  camera/lifecycle/deprecated-API cases. CI-scope Ruff lint/format, full src
  Pyright and the new example's Pyright passed. Earlier 155 targeted checks,
  including 95 helper cases, are retained separately.
• Wheel/sdist builds include the exact helper, public export and py.typed;
  installed-wheel indexed API and missing-urdf-extra smoke passed. The actual
  new RST/literalinclude and helper autodoc passed a focused Sphinx -W build.
  Examples/assets remain repository files under the existing packaging policy.
• Actual Playwright 1.63.0 / Chromium 153.0.8010.12 acceptance passed ten live
  scenarios, playback rewind, and a bounded 20-minute update/recreate/reconnect
  run, with zero page or console errors. Screenshots and exact commands are
  retained in the local review deliverable.
• Current main is 56712d3. The cumulative patch applied cleanly; the subsequent
  one-character RST heading fix changes no Python/frontend/protocol bytes.

The full E2E suite, multi-Python CI matrix and complete themed/notebook docs
site were not run locally. Browser observations are functional acceptance,
with no FPS/GPU or total-client-memory claim. Initial image-test/type-check
failures in an incomplete local environment also reproduced on upstream; the
corrected isolated environment passed without weakening tests or changing
unrelated source.

Limits

Visual meshes only, fixed instance count, and existing batched GLB limitations.
FK remains a Python/yourdfpy loop. Floating/planar joints and additional global
scaling are unsupported. Dense array traffic can cost more than independent
ViserUrdf updates when only a few robots change; this is an optional helper,
with no universal speedup claim.