[Shannon Bradshaw (shannonbradshaw)]

Updates the kinematics reference for two changes in RDK v1.15.0: a third kinematics file format (the kinematic model's JSON encoding), and how GetKinematics responds when a request sets include_collision_meshes or include_visual_meshes.

Source changes

• RSDK-14749 — RSDK-14749: read the kinematic model file with its meshes beside it rdk#6709: a .json kinematics file can be the proto JSON of KinematicModel (links with pose, collision, visual; joints with limits and JOINT_TYPE_ types) as well as SVA or DH. Mesh files are read relative to the model file (forward slashes, no absolute paths or URI schemes, .. allowed). Collision meshes must be STL or PLY. The parse is strict and names the file in every error. The reader tells the formats apart by fields, as the PR describes.
• RSDK-14750 — RSDK-14750: one GetKinematics transport for arm, gantry and gripper rdk#6733: arm, gantry and gripper servers honor include_collision_meshes and include_visual_meshes. A request that sets either flag gets the typed model alone, with mesh bytes only for the roles it asked for (referenceframe.KinematicsResponse at v1.15.0). A request with neither flag still gets every mesh plus the deprecated fields. This finishes the follow-up Update kinematics reference for GetKinematics mesh contents #5490 left for release.

Both are in RDK v1.15.0 (published 2026-11-03; git merge-base --is-ancestor for 1d8a97962 and 64dd03d7e).

Documents: no open DOCS ticket. The matched ticket, DOCS-4890 (shares parent RSDK-14232 with RSDK-14749 and RSDK-14750), is closed.

Docs changes

• docs/motion-planning/reference/kinematics.md:
  • "Kinematics file formats" table gains a Kinematic model row.
  • The GetKinematics paragraph adds the per-flag rule for v1.15.0 and later.
  • New "Kinematic model format" subsection under step 2: how the format is detected, an example built from referenceframe/testfiles/ur5e_kinematic_model.json (first link and joint), the main fields, mesh path rules, and the strict-parse failures.

Left out on purpose: limits.max_velocity and limits.max_acceleration. The proto has them, but the motion service does not enforce them yet; see the closed #5274.

How I found these

• Xref lookup: component-api-xref.md (arm GetKinematics) → docs/motion-planning/reference/kinematics.md.
• Grep matches: include_collision_meshes, include_visual_meshes, KinematicModel, kinematic model, kinematic_param_type, JOINT_TYPE_, Kinematics file formats, URDF across docs/, static/, data/, layouts/. Only this page lists the file formats or describes the mesh flags.

---

Generated by daily docs change agent

---

Generated by Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	f62b51c
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6aecde36e16f390346530be4
😎 Deploy Preview	https://deploy-preview-5498--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 32 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Eliza Farley (elizafarley)]

Docs review: Ready to merge

This PR documents the kinematic model JSON file format and the v1.15.0 GetKinematics mesh-flag behavior. cd4f95e resolves all four findings from the previous review. I checked each new claim against viamrobotics/rdk at v1.15.0. Leaving out the frame-system kinematics case is correct: that UnmarshalModelJSON call (referenceframe/frame_system.go:1336) decodes a FrameSystemConfig received over the wire, not a config field that users write.

CI: All required checks passing. Pending, not required: Check Markdown files

Docs health: No regressions

Verified against source (20 claims)

All in viamrobotics/rdk at v1.15.0. Both source commits (1d8a97962, 64dd03d7e) are ancestors of the tag.

New in cd4f95e

• Deprecated fields hold the SVA/URDF file itself; a kinematic-model file is served there converted to SVA, without visual geometry: referenceframe/model.go:90-116, 136-140
• Format detection: kinematic-model markers (top-level properties, link pose/collision/visual, joint limits, JOINT_TYPE_) win; a file with neither set of markers is read as a kinematic model: referenceframe/model_file.go:63-101
• Visual meshes accept any format with an extension, because they're never parsed: model_file.go:222-226, 286
• Mesh file references resolve only when the file is loaded by path; bytes-only loading fails with mesh "<path>" cannot be read without the directory of the model file: model_file.go:297-298, model_json.go:47-50, 262-275
• Fake arm model-path loads by path: components/arm/fake/fake.go:32, 44

From the first pass, unchanged

• .json files can be kinematic-model proto JSON as well as SVA/DH: model_json.go:61-66, model.go:191-194
• Example matches referenceframe/testfiles/ur5e_kinematic_model.json (lines 1-24, 147-159)
• Joint types and continuous = revolute with no limits: model_proto.go:311-319, 369-373
• Limits in degrees/mm; orientation in degrees: model_proto.go:354-356, 389-390
• Visual geometry kept separate from collision geometry: model.go:554-566, model_transport.go:73-107
• Content type from extension: model_file.go:265-277
• Mesh path rules (relative, forward slashes, no absolute/URI, .. allowed): model_file.go:300, 311-322
• Collision meshes STL or PLY: model_file.go:286-288
• Strict-parse failures: model_file.go:43-56, 116-149, 155-219, 302-305
• Error names the file: model_file.go:33, model_json.go:271-273
• Either flag set: model alone, mesh bytes only for requested roles: model_transport.go:29-47
• Other meshes keep path and content type: model_transport.go:60-66
• Neither flag set: every mesh plus deprecated fields: model_transport.go:49-50, model.go:90-108
• Arm, gantry, and gripper servers share the response builder: components/arm/server.go:386-396
• Python sample unaffected (flags default to False): viam-python-sdk src/viam/components/arm/client.py:271-291

Automated review by Claude. Rerunning the review updates this comment.

[Shannon Bradshaw (shannonbradshaw)]

Thanks, I checked each point against rdk at v1.15.0. All four are addressed in cd4f95e:

• Deprecated fields (line 81): Now says they hold the file itself when it's SVA or URDF, and that a kinematic model file is served there converted to SVA, without its visual geometry (KinematicModelToProtobuf → legacyKinematicsResponse). "The same JSON file format" is now "The SVA format".
• Mesh file references: Added that they resolve only when the kinematics file is loaded from disk by path (for example a fake arm's model-path). A model read from bytes, such as a file embedded in a module's binary, must carry its mesh contents. I quoted the cannot be read without the directory of the model file error. The table row now says "from a kinematics file loaded by path". I left out the frame-system kinematics case. That UnmarshalModelJSON call (frame_system.go:1336) decodes a FrameSystemConfig received over the wire, not a field users write in their config.
• Format detection (nit): Rewritten to lead with the kinematic-model markers (properties, link pose/collision/visual, joint limits, JOINT_TYPE_), then the SVA/DH markers. A file with neither is read as a kinematic model, matching isKinematicModelDocument's message || !legacy.
• Visual mesh formats (nit): Now "visual meshes can be any format with a file extension, such as GLB", which matches loadMeshes never parsing visual meshes. I didn't claim GLB is the only format the 3D scene renders, because I couldn't verify that.

prettier, markdownlint, vale, frontmatter_rules.py and make build-prod pass.

---

Generated by Claude Code

[Jeremy Rose (jeremyrose-viam)]

Eliza Farley (@elizafarley) could you rerun the docs review on f62b51c? Since cd4f95e, the kinematics page is restructured as a reference page with no steps:

• Sections: Concepts; Kinematics file formats (SVA, kinematic model, URDF); The GetKinematics method, with a Response subsection; Provide a kinematics file.
• SVA wording: no longer called "native". The page says each format is a way to write the same model.
• Deprecated response fields: format, kinematics_data and meshes_by_urdf_filepath are listed with what each holds. The mesh-flag behavior is described without naming flags.
• Snippets: the Python snippet prints the format name and reads the model from kinematics[3]. The URDF example now has box geometry, a defined upper_arm link and a joint <origin>, which the old version lacked. add-an-arm.md now lists the kinematic model format.
• Diataxis: this clarifies the page's Diataxis mode. The frontmatter already says diataxis: reference, but the old "Steps" section mixed step-by-step instructions into a reference page. The content now matches the declared mode, and the description is updated to match.

I ran both snippets and the page's SVA, kinematic model and URDF examples against viam-server v1.15.0 (Python SDK 0.85.2, RDK v1.15.0 Go). Worth re-checking in particular: a DH file reports format SVA, meshes_by_urdf_filepath is filled only for URDF files, and a kinematic model file's kinematics_data is a derived SVA without visual geometry.