[Docs] Unify volume, surface, and cable deformables into one guide - #7576
Draft
mmichelis wants to merge 2 commits into
Draft
[Docs] Unify volume, surface, and cable deformables into one guide#7576mmichelis wants to merge 2 commits into
mmichelis wants to merge 2 commits into
Conversation
Deformable documentation was split by solver rather than by concept. Volume and surface deformables were documented inside the Newton VBD solver guide, cables had their own Newton backend page, and the only crisp definition of the volume and surface split lived in the 3.0 migration guide. Add a single Core Concepts > Deformables page covering the three kinds at the asset level: what each one is, how it is authored, how volume and surface are resolved from the physics material, tetrahedralization, runtime state, kinematic targets, and the cable material, collision, and rendering contracts. Solver configuration, tuning, and coupling stay in the Newton VBD solver guide and the coupled solvers page, which the new page links to instead of restating. Reduce the cable page to a pointer, keeping its label so existing references resolve, and repoint the Newton index, the showroom, and the Newton asset preparation skill at the new guide. Also correct two inherited errors in the cable material documentation. Stiffness is discretized per rod joint using that joint's dual rest length rather than once for the whole cable from the mean segment length, so the uniform point spacing caveat no longer applies. The twist fallback reuses the bend structural stiffness rather than the bend modulus, so setting twist_stiffness equal to bend_stiffness gives twice the fallback value.
Add the seven side-by-side animations referenced by the deformables guide, one per material parameter, each sweeping three values with everything else held fixed: Young's modulus, Poisson's ratio, and particle radius for volume, stretch and bend stiffness for surface, and bend and twist stiffness for cables. Kept as a separate commit so the media can be dropped or replaced with externally hosted files without touching the prose.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Deformable documentation is currently split by solver rather than by concept. Volume and surface deformables are documented inside the Newton VBD solver guide, cables have their own page under the Newton backend, and the only crisp definition of the volume/surface split lives in the 3.0 migration guide. A reader asking "what is a deformable in Isaac Lab, and how do I author one" has no single place to look.
This adds a single Core Concepts > Deformables page covering the three kinds at the asset level:
Solver configuration, tuning, and coupling deliberately stay where they are. The new page links to the Newton VBD solver guide and the coupled solvers page rather than restating them, and
using-vbd-solver.rstis unchanged. MPM is explicitly out of scope and cross-linked so readers are not left guessing.using-cables.rstis reduced to a pointer, keeping itsnewton-using-cableslabel so existing references still resolve. The Newton index, the showroom, and the Newton asset preparation skill are repointed at the new guide.Corrections to inherited content
Two errors in the existing cable material documentation surfaced while verifying the text against the importer, and are fixed here:
0.5 * (L_parent + L_child), not once for the whole cable from the mean segment length. The "uniform point spacing assumed" caveat and its associated warning were therefore incorrect and have been removed.E * I / L, whereas an explicitly authoredtwist_stiffnessis applied to the polar momentJ = 2 * I. Settingtwist_stiffness = bend_stiffnessgives twice the fallback stiffness, not the same value. This asymmetry with the shear fallback is now documented.Note on the media
The animations are added as a separate commit so they can be dropped or swapped for externally hosted files without touching the prose. They are GIFs, routed through Git LFS by the existing
*.gifrule, so history stores 132-byte pointers rather than binaries. Re-encoded mp4s of the same clips come to 644 KB total against 13 MB of GIF, so I am happy to switch if reviewers prefer.Type of change
Release backport
developChecklist
pre-commitchecks with./isaaclab.sh --formatsource/<pkg>/changelog.d/for every touched package (do not editCHANGELOG.rstor bumpextension.toml— CI handles that)CONTRIBUTORS.mdor my name already exists thereNotes on the two unchecked items: this change touches only
docs/andskills/, so there is no source package to add a changelog fragment for and nothing to unit test.sphinx-buildsucceeds on the branch with one warning, a pre-existing duplicateRigidBodyMaterialCfgautoclass shared betweenisaaclab.sim.spawners.rstandisaaclab_physx.sim.spawners.rst, both untouched here.