refactor(soma): rename handedness to hand side

[nv-mhaselton]

Description

Follow-up to #1207.

Rename SomaHandedness to SomaHandSide and handedness to hand_side to distinguish anatomical left/right hand selection from coordinate-system handedness. This also aligns with existing IC retargeters and examples.

Update the schemas, Python bindings and exports, sources, publishers, viewer, tests, and documentation. Regenerate the affected schema goldens.

This is a direct API rename within unreleased SOMA support. Coordinate conventions and pose behavior are unchanged.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Testing

Validated native schema tests, Python schema/source tests, body and hand publisher/viewer tests with SOMA-X v0.3.1 assets, mypy, documentation, and formatting checks.

To reproduce the automated checks from a configured development checkout:

.venv/bin/cmake --build build \
  --target schema_tests python_package -j4

.venv/bin/ctest --test-dir build \
  -R '^(schema_|retargeting_test_soma_|retargeting_mypy_type_check|deviceio_live_view_test_soma_viewer|soma_(body|hand)_publisher_test_publisher)' \
  --output-on-failure

make -C docs current-docs

SKIP=check-copyright-year pre-commit run --all-files

Checklist

• I have read and understood the contribution guidelines
• I have run the linter and formatter with SKIP=check-copyright-year pre-commit run --all-files
• I have made corresponding changes to the documentation
• I have added tests that prove my fix/feature works (or explained why not)
• I have signed off all my commits (git commit -s) per the DCO

Summary by CodeRabbit

• API Updates
  • SOMA hand data now identifies left or right hands using SomaHandSide and the hand_side field across schemas, Python interfaces, examples, and documentation.
  • Hand sources validate that incoming payloads match the configured hand side.
• Documentation
  • Clarified how standalone hand streams are identified and that Isaac Teleop does not automatically combine them with hand controls in a body payload.

[github-actions]

📝 Docs preview is not auto-deployed for fork PRs.

A maintainer with write access to NVIDIA/IsaacCapture can deploy a preview by
commenting /preview-docs on this PR. Once deployed, the preview
will live at:

https://nvidia.github.io/IsaacCapture/preview/pr-1246/

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/IsaacCapture/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: c4439d3f-705b-4514-9c8c-8ac4371b3a3d

---

📥 Commits

Reviewing files that changed from the base of the PR and between 9aee765 and 2db47c3.

---

📒 Files selected for processing (22)

• docs/source/device/soma.rst
• docs/source/device/trackers.rst
• examples/deviceio_live_view/python/isaaccapture_examples/deviceio_live_view/soma_hand.py
• examples/soma_hand_publisher/python/isaaccapture_examples/soma_hand_publisher/publisher.py
• src/core/schema/fbs/soma_common.fbs
• src/core/schema/fbs/soma_hand_joint_poses.fbs
• src/core/schema/fbs/soma_hand_joint_rotations.fbs
• src/core/schema/golden/soma_common.bfbs
• src/core/schema/golden/soma_hand_joint_poses.bfbs
• src/core/schema/golden/soma_hand_joint_rotations.bfbs
• src/core/schema/python/soma_common_bindings.h
• src/core/schema/python/soma_hand_joint_poses_bindings.h
• src/core/schema/python/soma_hand_joint_rotations_bindings.h
• src/python/isaaccapture/retargeting_engine/deviceio_source_nodes/soma_hand_source.py
• src/python/isaaccapture/schema/__init__.py
• tests/cpp/core/schema/test_soma_hand_joint_poses.cpp
• tests/cpp/core/schema/test_soma_hand_joint_rotations.cpp
• tests/python/core/retargeting_engine/test_soma_hand_source.py
• tests/python/core/schema/test_soma_hand_joint_poses.py
• tests/python/core/schema/test_soma_hand_joint_rotations.py
• tests/python/examples/deviceio_live_view/test_soma_viewer.py
• tests/python/examples/soma_hand_publisher/test_publisher.py

---

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The SOMA hand-side enum and payload fields now use SomaHandSide and hand_side instead of SomaHandedness and handedness. Python bindings, SomaHandSource, examples, tests, and documentation use the renamed terms. The side values and payload field defaults remain unchanged.

Priority: ⬇️ Low

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

---

Merge Risk: ⚪ Minimal · up to 2db47

The intended rename updates the in-tree SOMA API consumers, and the schema goldens match the renamed definitions. No actionable merge risk is evident.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 2.27% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 44 functions across 14 files. (5 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: renaming handedness to hand side across SOMA schemas, APIs, examples, tests, and documentation.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 2.27% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 44 functions across 14 files. (5 skipped: 5 unsupported.)

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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