Spec 1.12: link_state, joint_state changes #1461

scpeters · 2024-07-20T00:29:42Z

🎉 New feature

Summary

This makes several changes to the specification for the <state/> element in SDFormat 1.12. It does not include DOM objects, which will be implemented in a future pull request. Note that part of the motivation for these changes is to allow specification of initial model state in gz-sim (see prototype in gazebosim/gz-sim#2359).

Link state changes

Use pairs of vector3 datatypes to represent twist, spatial acceleration, and wrenches instead of a pose datatype, which distorts the angular values by interpreting them as Euler angles. This resolves link_state velocity, acceleration, and wrench data should not use pose type #1366. The new elements for velocity and acceleration have names starting with linear_ or angular_, while the replacement for wrench is force and torque:
- //link_state/linear_velocity
- //link_state/angular_velocity
- //link_state/linear_acceleration
- //link_state/angular_acceleration
- //link_state/force
- //link_state/torque
Alternative considered: add support for a vector6 type and rename velocity to twist, acceleration to spatial_acceleration. While this could allow for shorter XML files, it would require features to be added to gz-math to support math::Vector6 and has the potential for error in remembering which order to specify the angular and linear coefficients. Using a pair of vector3 types is more verbose but more clear and is already supported by gz-math and libsdformat.

Joint state changes

Refactor //joint_state/angle and //joint_state/angle/@axis to //joint_state/axis_state/position and //joint_state/axis2_state/position. This more closely matches the structure of //joint/axis and //joint/axis2, and the rename from angle to position was suggested in add joint velocity and joint acceleration to state structure #83 (comment).

Add velocity, acceleration, and effort to //joint_state. The addition of velocity and acceleration was requested by add joint velocity and joint acceleration to state structure #83, and effort is added to match wrench used in link states.

Link and Joint states: add boolean `@degrees` attribute to some angular types

Add a boolean @degrees attribute to the following elements:
- //link_state/angular_velocity
- //link_state/angular_acceleration
- //joint_state/axis_state/position
- //joint_state/axis_state/velocity
- //joint_state/axis_state/acceleration
- //joint_state/axis2_state/position
- //joint_state/axis2_state/velocity
- //joint_state/axis2_state/acceleration
When true, this attribute causes the data to be interpreted in deg instead of rad, deg/s instead of rad/s, or deg/s^2 instead of rad/s^2. The attribute is not added to joint effort and link wrench types.

Allow specification of model state within a model

Currently states are only specified at the world level via the //world/state element. To allow a model to specify a default initial configuration or initial velocity, the //model/model_state element is added. If a world contains both a //world/state and a model that specifies its own state, I think the world state should take precedence.
To allow a model state to be overridden when being <include>d, the //model/include/model_state and //world/include/model_state elements are added as well.

Test it

The INTEGRATION_nested_model test has been updated to use some of the new //link_state elements, but there are not yet any tests using the new //joint_state or //model/model_state elements.

Checklist

Signed all commits for DCO
Added tests
Added example and/or tutorial
Updated documentation (as needed)
Updated migration guide (as needed)
Consider updating Python bindings (if the library has them)
codecheck passed (See contributing)
All tests passed (See test coverage)
While waiting for a review on your PR, please help review another open pull request to support the maintainers

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by messages.

Signed-off-by: Steve Peters <[email protected]>

Include joint_state.sdf from model_state.sdf and state.sdf for //world/joint states. Signed-off-by: Steve Peters <[email protected]>

Signed-off-by: Steve Peters <[email protected]>

@Degrees

This deprecates the //joint_state/angle element in favor of a joint state specification that supports multi-axis joints by mirroring the //joint/axis and //joint/axis2 elements with * //joint_state/axis_state * //joint_state/axis2_state Each axis state can specify position, velocity, and acceleration, each with an optional @Degrees attribute. Signed-off-by: Steve Peters <[email protected]>

Deprecate the //link_state/velocity and //link_state/acceleration elements since the `pose` type is not well-suited to represent vector6 data. Add pairs of vector3 angular_* and linear_* elements for velocity and acceleration to replace the pose-typed elements. Signed-off-by: Steve Peters <[email protected]>

also rephrase some element descriptions Signed-off-by: Steve Peters <[email protected]>

Signed-off-by: Steve Peters <[email protected]>

Also use a larger values in an angular_velocity. Signed-off-by: Steve Peters <[email protected]>

update migration guide Signed-off-by: Steve Peters <[email protected]>

azeey · 2024-08-27T22:29:51Z

Migration.md

+### Deprecations
+
+1. **joint_state.sdf**:
+    + `//joint_state/angle` is deprecated in favor of `//axis_state/position`


Just to make it clear that it's still within joint_state.

Suggested change

+ `//joint_state/angle` is deprecated in favor of `//axis_state/position`

+ `//joint_state/angle` is deprecated in favor of `//joint_state/axis_state/position`

ok, will fix

azeey · 2024-08-27T22:31:37Z

Migration.md

+    + `//link_state/wrench` is deprecated in favor of `//link_state/angular_wrench`
+      and  `//link_state/linear_wrench`.


I've commonly seen the term wrench refer to the 6D vector that represents torques and forces. If we split them into two 3D vectors, would it make sense to call them torque and force instead of angular_wrench and linear_wrench?

yeah, that's a good point; I was trying to keep symmetry with angular_ and liner_ prefixes, but force and torque are better. I will update this

I updated the pull request description with force and torque as well

azeey · 2024-08-27T22:33:08Z

sdf/1.12/joint_state.sdf

+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If true, the joint position is expressed in units of degrees [deg],


Can you specify that this would not apply to prismatic joints and the unit will be meters regardless of this attribute?

azeey · 2024-08-27T22:33:31Z

sdf/1.12/joint_state.sdf

+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If true, the joint velocity is expressed in units of degrees per


Similar to the position, can you add a qualifier for prismatic joints?

jennuine · 2024-08-27T23:36:35Z

sdf/1.12/joint_state.sdf

+      Contains the state of the first joint axis.
+    </description>
+
+    <element name="position" type="double" default="0" required="0">


Shouldn't position be a vector?

this position element is under //joint_state/axis_state and represents the position of the first axis / degree of freedom. there is another position element under //joint_state/axis2_state for the second axis. this mirrors the specification of the //joint/axis and //joint/axis2 elements

Signed-off-by: Steve Peters <[email protected]>

scpeters added 9 commits July 7, 2024 20:37

Spec 1.12: add _state suffix to state subelements

b979877

Signed-off-by: Steve Peters <[email protected]>

Define //joint_state in joint_state.sdf

f5d2571

Include joint_state.sdf from model_state.sdf and state.sdf for //world/joint states. Signed-off-by: Steve Peters <[email protected]>

Update Migration guide

f84706e

Signed-off-by: Steve Peters <[email protected]>

Merge branch 'main' into scpeters/state_1_12_suffix

e577e15

Merge branch 'main' into scpeters/state_1_12_suffix

a6fccc3

Merge branch 'main' into scpeters/state_1_12_suffix

53a5378

update migration guide

9af6119

Signed-off-by: Steve Peters <[email protected]>

azeey added the beta Targeting beta release of upcoming collection label Jul 29, 2024

azeey requested a review from jennuine August 6, 2024 21:12

Base automatically changed from scpeters/state_1_12_suffix to main August 18, 2024 21:11

scpeters added 4 commits August 18, 2024 18:38

Merge branch 'main' into scpeters/state_1_12

f0e5536

Add //link_state/angular_*/@Degrees

d7a887f

also rephrase some element descriptions Signed-off-by: Steve Peters <[email protected]>

Add //link_state/*_wrench, //joint_state/*/effort

4e07a21

Signed-off-by: Steve Peters <[email protected]>

Specify model_state within a model

a266d6b

Signed-off-by: Steve Peters <[email protected]>

azeey added the Breaking change Breaks API, ABI or behavior. Must target unstable version. label Aug 20, 2024

scpeters added 2 commits August 22, 2024 00:19

nested_model test: Update state syntax

56e59f8

Also use a larger values in an angular_velocity. Signed-off-by: Steve Peters <[email protected]>

Add //world/include/model_state

de15ea6

update migration guide Signed-off-by: Steve Peters <[email protected]>

scpeters changed the base branch from main to sdf15 August 26, 2024 18:38

Merge branch 'sdf15' into scpeters/state_1_12

17c8efd

scpeters added the 🏛️ ionic Gazebo Ionic label Aug 26, 2024

scpeters marked this pull request as ready for review August 26, 2024 21:38

scpeters requested a review from azeey as a code owner August 26, 2024 21:38

Merge branch 'sdf15' into scpeters/state_1_12

3ecd891

azeey reviewed Aug 27, 2024

View reviewed changes

jennuine reviewed Aug 28, 2024

View reviewed changes

scpeters added 3 commits August 27, 2024 17:35

Clarify element path in migration guide

3fa2308

Signed-off-by: Steve Peters <[email protected]>

Use force, torque instead of angular/linear_wrench

8521907

Signed-off-by: Steve Peters <[email protected]>

Merge remote-tracking branch 'origin/sdf15' into scpeters/state_1_12

107146b

Clarify that degrees is only for rotational axes

1b77045

Signed-off-by: Steve Peters <[email protected]>

azeey approved these changes Aug 28, 2024

View reviewed changes

scpeters merged commit c2c4f91 into sdf15 Aug 28, 2024
12 checks passed

scpeters deleted the scpeters/state_1_12 branch August 28, 2024 20:54

This was referenced Aug 28, 2024

link_state velocity, acceleration, and wrench data should not use pose type #1366

Closed

add joint velocity and joint acceleration to state structure #83

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Spec 1.12: link_state, joint_state changes #1461

Spec 1.12: link_state, joint_state changes #1461

scpeters commented Jul 20, 2024 •

edited

Loading

azeey Aug 27, 2024

scpeters Aug 28, 2024

scpeters Aug 28, 2024

azeey Aug 27, 2024

scpeters Aug 28, 2024

scpeters Aug 28, 2024

scpeters Aug 28, 2024

azeey Aug 27, 2024

scpeters Aug 28, 2024

azeey Aug 27, 2024

scpeters Aug 28, 2024

jennuine Aug 27, 2024

scpeters Aug 28, 2024

	+ `//joint_state/angle` is deprecated in favor of `//axis_state/position`
	+ `//joint_state/angle` is deprecated in favor of `//joint_state/axis_state/position`

		+ `//link_state/wrench` is deprecated in favor of `//link_state/angular_wrench`
		and `//link_state/linear_wrench`.

Spec 1.12: link_state, joint_state changes #1461

Spec 1.12: link_state, joint_state changes #1461

Conversation

scpeters commented Jul 20, 2024 • edited Loading

🎉 New feature

Summary

Link state changes

Joint state changes

Link and Joint states: add boolean @degrees attribute to some angular types

Allow specification of model state within a model

Test it

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scpeters commented Jul 20, 2024 •

edited

Loading

Link and Joint states: add boolean `@degrees` attribute to some angular types