ViewerGL: Batching Capsules with Different Sizes by jumyungc · Pull Request #1469 · newton-physics/newton

jumyungc · 2026-01-28T08:04:49Z

Description

Previously, capsule-based instancing was used, which created separate instances whenever the capsule size changed. This change allows batching capsules of different sizes.

Newton Migration Guide

Please ensure the migration guide for warp.sim users is up-to-date with the changes made in this PR.

The migration guide in docs/migration.rst is up-to date

Before your PR is "Ready for review"

Necessary tests have been added and new examples are tested (see newton/tests/test_examples.py)
Documentation is up-to-date
Code passes formatting and linting checks with pre-commit run -a

Summary by CodeRabbit

New Features
- Added capsule geometry rendering using instanced body+end meshes with automatic batching across per-instance scales.
- Introduced backend extensibility for specialized capsule rendering and improved geometry-type propagation for per-batch decisions.
Tests
- Added tests validating capsule batching, per-instance scale handling, cached-geometry reuse, and correct routing of capsule vs. non-capsule logging.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Signed-off-by: JC <jumyungc@nvidia.com>

coderabbitai · 2026-01-28T08:05:10Z

📝 Walkthrough

Walkthrough

Dispatches capsule geometries to a new capsule-specific rendering path, adds a backend hook log_capsules(), propagates geometry-type via ShapeInstances.geo_type, and implements GPU Warp kernels and batching updates to render capsules as instanced cylinder bodies + sphere caps.

Changes

Cohort / File(s)	Summary
Core viewer API `newton/_src/viewer/viewer.py`	Added `log_capsules(...)` hook on `ViewerBase` (defaults to `log_instances`) and added `geo_type` field to `ViewerBase.ShapeInstances` for per-batch geometry-type routing.
GL viewer + instancing `newton/_src/viewer/viewer_gl.py`	Added Warp kernels (`_capsule_duplicate_vec3/vec4`, `_capsule_build_body_scales`, `_capsule_build_cap_xforms_and_scales`), capsule-aware `_hash_geometry`, per-instance scale conversion in `set_model()`, and `log_capsules()` implementations to emit capsule bodies and caps as instanced meshes.
Tests `newton/tests/test_viewer_geometry_batching.py`	New tests and `_ViewerGeometryBatchingProbe` validating capsule batching across scales, geometry cache behavior, per-instance scale rewriting, and `log_state()` dispatch to `log_capsules`.

Sequence Diagrams

sequenceDiagram
    participant Client
    participant ViewerBase
    participant Batching
    participant GPU
    participant Renderer

    Client->>ViewerBase: log_state(model,...)
    ViewerBase->>Batching: group shapes (uses geo_type)
    alt capsule batch
        Batching->>GPU: _capsule_build_body_scales(shape_scale, indices)
        GPU-->>Batching: body_scales (r,r,half_h)
        Batching->>GPU: _capsule_build_cap_xforms_and_scales(xforms, scales)
        GPU-->>Batching: cap_xforms, cap_scales
        Batching->>GPU: _capsule_duplicate_vec3/vec4(colors,materials)
        GPU-->>Batching: duplicated attributes
        Batching->>Renderer: emit capsule_body instancer + capsule_caps instancer
        Renderer->>Renderer: draw cylinder bodies and sphere caps (instanced)
    else non-capsule
        Batching->>Renderer: emit standard instancer data
        Renderer->>Renderer: draw standard instanced geometry
    end
    Renderer-->>Client: frame rendered

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Fix ViewerGL to handle dynamic number of transforms and points #1217: Touches ViewerGL/instancer paths related to instancing behavior that this PR extends for capsule batching.
Viewer refactor #522: Prior viewer subsystem changes in ViewerBase/ViewerGL that this PR builds upon for capsule rendering.

Suggested reviewers

eric-heiden

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.46% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: enabling batching of capsules with different sizes in ViewerGL, which is the core objective of the PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-01-28T08:14:07Z

Codecov Report

❌ Patch coverage is 17.91045% with 55 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
newton/_src/viewer/viewer_gl.py	5.26%	54 Missing ⚠️
newton/_src/viewer/viewer.py	90.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@newton/_src/viewer/viewer_gl.py`:
- Around line 416-497: The override method log_capsules has an unused parameter
mesh causing a Ruff ARG002 warning; rename the parameter to _mesh in the
log_capsules signature (and update any internal references if present) so the
unused argument is intentionally ignored, leaving all other logic (including
calls to log_instances and creation of sphere_mesh/cylinder_mesh, cap_xforms,
cap_scales, cap_colors, cap_materials) unchanged.

In `@newton/tests/test_viewer_geometry_batching.py`:
- Around line 69-71: The test stub method log_instances currently accepts
parameters (name, mesh, xforms, scales, colors, materials, hidden=False) but
doesn't use them, triggering Ruff ARG002; update the signature of log_instances
to silence unused-argument warnings by either prefixing unused parameter names
with an underscore (e.g., _name, _mesh, etc.) or replacing the parameters with a
catch-all (*args, **kwargs), and keep the body as self.log_instances_calls += 1
so the call count remains unchanged.

eric-heiden

Why do capsules have the scale (r, r, half_height) here? They should be (r, h, 0) (the last entry is ignored).

jumyungc · 2026-01-28T20:46:51Z

Why do capsules have the scale (r, r, half_height) here? They should be (r, h, 0) (the last entry is ignored).

Thank you @eric-heiden for the feedback!

As you mentioned, model-side capsule shape_scale is stored as (radius, half_height, 0).
But for better batching in ViewerGL (instancing different-sized capsules together), capsules are now rendered using one shared unit cylinder (body) and one shared unit sphere (cap), with per-instance transforms/scales.

So the (cylinder) body’s per-instance scale in the viewer is (radius, radius, half_height), following the viewer's cylinder convention.

Signed-off-by: JC <jumyungc@nvidia.com>

eric-heiden · 2026-01-28T22:43:11Z

Why do capsules have the scale (r, r, half_height) here? They should be (r, h, 0) (the last entry is ignored).

Thank you @eric-heiden for the feedback!

As you mentioned, model-side capsule shape_scale is stored as (radius, half_height, 0). But for better batching in ViewerGL (instancing different-sized capsules together), capsules are now rendered using one shared unit cylinder (body) and one shared unit sphere (cap), with per-instance transforms/scales.

So the (cylinder) body’s per-instance scale in the viewer is (radius, radius, half_height), following the viewer's cylinder convention.

Thanks @jumyungc for clarifying and adding these comments! I can see the scale refers to the xyz mesh scaling now.

Signed-off-by: JC <jumyungc@nvidia.com>

Batching capsules with different sizes.

6f8057c

Signed-off-by: JC <jumyungc@nvidia.com>

jumyungc self-assigned this Jan 28, 2026

jumyungc linked an issue Jan 28, 2026 that may be closed by this pull request

Slow capsule visualization when different capsule dimensions are used. #1465

Closed

coderabbitai Bot reviewed Jan 28, 2026

View reviewed changes

Comment thread newton/_src/viewer/viewer_gl.py

Comment thread newton/tests/test_viewer_geometry_batching.py Outdated

eric-heiden reviewed Jan 28, 2026

View reviewed changes

Comment thread newton/_src/viewer/viewer_gl.py

eric-heiden reviewed Jan 28, 2026

View reviewed changes

Comment thread newton/_src/viewer/viewer_gl.py Outdated

eric-heiden requested changes Jan 28, 2026

View reviewed changes

jumyungc added 2 commits January 29, 2026 09:48

Applied feedback.

eaa52b9

Signed-off-by: JC <jumyungc@nvidia.com>

Merge branch 'main' into viewergl-capsule

d4d69d3

eric-heiden approved these changes Jan 28, 2026

View reviewed changes

eric-heiden added this pull request to the merge queue Jan 28, 2026

Merged via the queue into newton-physics:main with commit 12e796d Jan 28, 2026
22 checks passed

jumyungc deleted the viewergl-capsule branch January 28, 2026 23:22

coderabbitai Bot mentioned this pull request Feb 6, 2026

Fix log_shapes broadcasting for length-1 warp arrays #1550

Merged

3 tasks

coderabbitai Bot mentioned this pull request Feb 17, 2026

Viewer gl optimizations #1656

Merged

4 tasks

mmacklin pushed a commit to mmacklin/newton that referenced this pull request Apr 7, 2026

ViewerGL: Batching Capsules with Different Sizes (newton-physics#1469)

2ce5dd6

Signed-off-by: JC <jumyungc@nvidia.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ViewerGL: Batching Capsules with Different Sizes#1469

ViewerGL: Batching Capsules with Different Sizes#1469
eric-heiden merged 3 commits into
newton-physics:mainfrom
jumyungc:viewergl-capsule

jumyungc commented Jan 28, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jan 28, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagrams

Estimated code review effort

Possibly related PRs

Suggested reviewers

Uh oh!

codecov Bot commented Jan 28, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eric-heiden left a comment

Uh oh!

jumyungc commented Jan 28, 2026 •

edited

Loading

Uh oh!

eric-heiden commented Jan 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jumyungc commented Jan 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Newton Migration Guide

Before your PR is "Ready for review"

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagrams

Estimated code review effort

Possibly related PRs

Suggested reviewers

Uh oh!

codecov Bot commented Jan 28, 2026

Codecov Report

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eric-heiden left a comment

Choose a reason for hiding this comment

Uh oh!

jumyungc commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eric-heiden commented Jan 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jumyungc commented Jan 28, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jan 28, 2026 •

edited

Loading

jumyungc commented Jan 28, 2026 •

edited

Loading