Document viewer debugging workflows

[jcarius-nv]

Description

Rename the visualization guide to Viewers and Debugging and make Newton's
current viewer-based debugging workflows easier to discover.

The updated guide:

• helps users choose between live visualization, timeline inspection,
  state-snapshot recording, and persistent visual or scene export;
• explains that viewer diagnostics use explicit log_*() calls;
• documents exactly what ViewerFile captures and what it does not;
• distinguishes visual state playback from deterministic simulation replay;
• adds a copy-paste recording and playback workflow using the existing examples;
• links the workflow from the FAQ, overview, and simulation tuning guidance.

This gives users an accurate entry point for Newton's current debugging
capabilities without promising future diagnostic functionality.

Closes #3295

Checklist

• New or existing tests cover these changes
• The documentation is up to date with these changes
• CHANGELOG.md has been updated (not required for this documentation-only change)

Test plan

uv run --extra docs --extra sim sphinx-build -j auto -W -D nbsphinx_execute=never -b html docs docs/_build/html
uvx --python 3.12 pre-commit run -a
git diff --check upstream/main...HEAD

Summary by CodeRabbit

• Documentation
  • Strengthened the “Validate the model” checklist to explicitly inspect both collision geometry and contact normals using viewer debugging tools.
  • Replaced the visualization FAQ with a more detailed “How can I visualize and debug Newton simulations?” entry, covering live inspection, overlays/diagnostics, timeline inspection, and recording with visual playback.
  • Reworked the visualization guide around “Viewers and debugging,” including a “Choosing a Viewer” comparison and expanded “Recording to File (ViewerFile)” documentation and examples.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9a800121-3296-4ffd-8ca6-d2450e263e24

📥 Commits

Reviewing files that changed from the base of the PR and between befbda8 and 62dcb9a.

📒 Files selected for processing (1)

• docs/guide/visualization.rst

---

📝 Walkthrough

Walkthrough

Documentation updates rename and expand viewer debugging guidance, describe ViewerFile recording and replay behavior, improve navigation and FAQ references, and clarify collision geometry and contact-normal validation.

Changes

Viewer debugging documentation

Layer / File(s)	Summary
Viewer debugging guidance docs/guide/visualization.rst, docs/guide/overview.rst, docs/faq.rst, docs/concepts/simulation_tuning.rst	Introduces viewer debugging workflows, viewer selection guidance, expanded FAQ content, updated navigation wording, and explicit contact-normal validation instructions.
ViewerFile recording details docs/guide/visualization.rst	Documents ViewerFile contents and omissions, recording and replay examples, history retention, capture limitations, and a custom-visualization anchor.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• newton-physics/newton#3224 — Updates related simulation-tuning validation guidance.

Suggested reviewers: dylanturpin

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main change: adding viewer debugging workflow documentation.
Linked Issues check	✅ Passed	The docs add a dedicated debugging-focused section for ViewerFile and related workflows, matching issue #3295.
Out of Scope Changes check	✅ Passed	The extra FAQ, overview, and tuning cross-links still support the same documentation goal and are not unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/guide/visualization.rst (1)

341-346: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Advance the state in the recording example.

The loop only increments sim_time; it logs the same state five times. Playback therefore contains identical snapshots and does not demonstrate recorded simulation motion. Step a solver/update state between frames, or explicitly label this as a static snapshot example.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guide/visualization.rst` around lines 341 - 346, Update the recording
loop in the visualization example to advance or mutate state between calls to
viewer.log_state, using the existing solver or state-update mechanism if
available, so each frame records a distinct simulation snapshot; only label it
static if no state update is intended.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/guide/visualization.rst`:
- Around line 382-386: Update the recording/replay workflow in the visualization
guide around the `uv run -m newton.examples recording` and `replay_viewer`
commands so it installs or otherwise includes the required `cbor2` dependency
before creating `humanoid_recording.bin`; keep the binary recording workflow
consistent with the documented prerequisite.

---

Outside diff comments:
In `@docs/guide/visualization.rst`:
- Around line 341-346: Update the recording loop in the visualization example to
advance or mutate state between calls to viewer.log_state, using the existing
solver or state-update mechanism if available, so each frame records a distinct
simulation snapshot; only label it static if no state update is intended.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: ccb00aa1-263c-4d74-bc05-b8a6a8421a57

📥 Commits

Reviewing files that changed from the base of the PR and between 0a3e9e1 and e386d6b.

📒 Files selected for processing (4)

• docs/concepts/simulation_tuning.rst
• docs/faq.rst
• docs/guide/overview.rst
• docs/guide/visualization.rst

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[gyeomannvidia]

Looks good! I made a couple of really nit-picky comments. You can decide whether to modify or not.

[jcarius-nv]

@gyeomannvidia Thanks again for the review. I addressed the review comments in 62dcb9a, replied in each thread, and resolved the remaining threads. The latest push dismissed the earlier approval; could you please re-approve when convenient?