Spec 1.12: link_state, joint_state changes (#1461)

This makes several changes to the specification for the //state element in SDFormat 1.12. * //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. The new elements for velocity and acceleration have names starting with linear_ or angular_, while the replacement for wrench is force and torque. * //joint_state changes: refactor //joint_state/angle and //joint_state/angle/@axis to //joint_state/axis_state/position and //joint_state/axis2_state/position. Also add velocity, acceleration, and effort to joint axis states. * degrees attribute: add a boolean degrees attribute to the //link_state/angular_* elements and joint axis position, velocity, and acceleration elements. When true, this causes data with units involving radians to interpret it as involving degrees instead. The attribute does not affect prismatic joints. * Specify model state within a model using //model/model_state or when including a model with //model/include/model_state and //state/include/model_state. Signed-off-by: Steve Peters <[email protected]>
gazebosim · Aug 28, 2024 · c2c4f91 · c2c4f91
1 parent d9b26df
commit c2c4f91
Show file tree

Hide file tree

Showing 6 changed files with 296 additions and 40 deletions.
diff --git a/Migration.md b/Migration.md
@@ -628,6 +628,33 @@ ABI was broken for `sdf::Element`, and restored on version 11.2.1.
 
 ## SDFormat specification 1.11 to 1.12
 
+### Additions
+
+1. **joint_state.sdf**:
+    + `//joint_state/axis_state/position`
+    + `//joint_state/axis_state/velocity`
+    + `//joint_state/axis_state/acceleration`
+    + `//joint_state/axis_state/effort`
+    + `//joint_state/axis2_state/position`
+    + `//joint_state/axis2_state/velocity`
+    + `//joint_state/axis2_state/acceleration`
+    + `//joint_state/axis2_state/effort`
+
+1. **link_state.sdf**:
+    + `//link_state/linear_velocity`
+    + `//link_state/angular_velocity`
+    + `//link_state/linear_acceleration`
+    + `//link_state/angular_acceleration`
+    + `//link_state/force`
+    + `//link_state/torque`
+
+1. **model.sdf**:
+    + `//model/model_state`
+    + `//model/include/model_state`
+
+1. **world.sdf**:
+    + `//world/include/model_state`
+
 ### Modifications
 
 1. **state.sdf**, **model_state.sdf**, **joint_state.sdf**, **link_state.sdf**,
@@ -645,6 +672,20 @@ ABI was broken for `sdf::Element`, and restored on version 11.2.1.
     `//world/joint` and `//state/insertions/joint` can represent inserted
     `//world/joint` elements.
 
+### Deprecations
+
+1. **joint_state.sdf**:
+    + `//joint_state/angle` is deprecated in favor of `//joint_state/axis_state/position`
+      and  `//joint_state/axis2_state/position`.
+
+1. **link_state.sdf**:
+    + `//link_state/velocity` is deprecated in favor of `//link_state/angular_velocity`
+      and  `//link_state/linear_velocity`.
+    + `//link_state/acceleration` is deprecated in favor of `//link_state/angular_acceleration`
+      and  `//link_state/linear_acceleration`.
+    + `//link_state/wrench` is deprecated in favor of `//link_state/torque`
+      and  `//link_state/force`.
+
 ## SDFormat specification 1.10 to 1.11
 
 ### Additions

diff --git a/sdf/1.12/joint_state.sdf b/sdf/1.12/joint_state.sdf
@@ -9,11 +9,125 @@
     <description>Name of the joint</description>
   </attribute>
 
-  <element name="angle" type="double" default="0" required="+">
+  <element name="angle" type="double" default="0" required="-1">
     <attribute name="axis" type="unsigned int" default="0" required="1">
       <description>Index of the axis.</description>
     </attribute>
 
     <description>Angle of an axis</description>
   </element>
+
+  <element name="axis_state" required="0">
+    <description>
+      Contains the state of the first joint axis.
+    </description>
+
+    <element name="position" type="double" default="0" required="0">
+      <description>The position of the first joint axis.</description>
+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If this is a rotational axis and this attribute is true,
+          the joint position is expressed in units of degrees [deg],
+          otherwise it is expressed in radians [rad].
+          If this axis is translational (such as a prismatic joint), the
+          units will be interpreted in meters [m] regardless of the value of
+          this attribute.
+        </description>
+      </attribute>
+    </element>
+
+    <element name="velocity" type="double" default="0" required="0">
+      <description>The velocity of the first joint axis.</description>
+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If this is a rotational axis and this attribute is true,
+          the joint velocity is expressed in units of degrees per
+          second [deg/s], otherwise it is expressed in radians per second
+          [rad/s].
+          If this axis is translational (such as a prismatic joint), the
+          units will be interpreted in meters per second [m/s] regardless of
+          the value of this attribute.
+        </description>
+      </attribute>
+    </element>
+
+    <element name="acceleration" type="double" default="0" required="0">
+      <description>The acceleration of the first joint axis.</description>
+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If this is a rotational axis and this attribute is true,
+          the joint acceleration is expressed in units of degrees per
+          second per second [deg/s^2], otherwise it is expressed in radians per
+          second per second [rad/s^2].
+          If this axis is translational (such as a prismatic joint), the
+          units will be interpreted in meters per second per second [m/s^2]
+          regardless of the value of this attribute.
+        </description>
+      </attribute>
+    </element>
+
+    <element name="effort" type="double" default="0" required="0">
+      <description>The effort applied at the first joint axis.</description>
+    </element>
+  </element>
+
+  <element name="axis2_state" required="0">
+    <description>
+      Contains the state of the second joint axis.
+    </description>
+
+    <element name="position" type="double" default="0" required="0">
+      <description>The position of the second joint axis.</description>
+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If this is a rotational axis and this attribute is true,
+          the joint position is expressed in units of degrees [deg],
+          otherwise it is expressed in radians [rad].
+          If this axis is translational (such as a prismatic joint), the
+          units will be interpreted in meters [m] regardless of the value of
+          this attribute.
+        </description>
+      </attribute>
+    </element>
+
+    <element name="velocity" type="double" default="0" required="0">
+      <description>The velocity of the second joint axis.</description>
+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If this is a rotational axis and this attribute is true,
+          the joint velocity is expressed in units of degrees per
+          second [deg/s], otherwise it is expressed in radians per second
+          [rad/s].
+          If this axis is translational (such as a prismatic joint), the
+          units will be interpreted in meters per second [m/s] regardless of
+          the value of this attribute.
+        </description>
+      </attribute>
+    </element>
+
+    <element name="acceleration" type="double" default="0" required="0">
+      <description>The acceleration of the second joint axis.</description>
+
+      <attribute name="degrees" type="bool" default="false" required="0">
+        <description>
+          If this is a rotational axis and this attribute is true,
+          the joint acceleration is expressed in units of degrees per
+          second per second [deg/s^2], otherwise it is expressed in radians per
+          second per second [rad/s^2].
+          If this axis is translational (such as a prismatic joint), the
+          units will be interpreted in meters per second per second [m/s^2]
+          regardless of the value of this attribute.
+        </description>
+      </attribute>
+    </element>
+
+    <element name="effort" type="double" default="0" required="0">
+      <description>The effort applied at the second joint axis.</description>
+    </element>
+  </element>
 </element> <!-- End Joint -->
diff --git a/sdf/1.12/link_state.sdf b/sdf/1.12/link_state.sdf
@@ -10,21 +10,69 @@
     <description>Name of the link</description>
   </attribute>
 
-  <element name="velocity" type="pose" default="0 0 0 0 0 0" required="0">
+  <element name="angular_velocity" type="vector3" default="0 0 0" required="0">
+    <description>Angular velocity of the link frame relative to the world frame.
+    </description>
+
+    <attribute name="degrees" type="bool" default="false" required="0">
+      <description>
+        If true, the angular velocity is expressed in units of degrees per
+        second [deg/s], otherwise it is expressed in radians per second [rad/s].
+      </description>
+    </attribute>
+  </element>
+
+  <element name="linear_velocity" type="vector3" default="0 0 0" required="0">
+    <description>Linear velocity of the link frame relative to the world frame.
+    </description>
+  </element>
+
+  <element name="velocity" type="pose" default="0 0 0 0 0 0" required="-1">
     <description>Velocity of the link. The x, y, z components of the pose
       correspond to the linear velocity of the link, and the roll, pitch, yaw
       components correspond to the angular velocity of the link
     </description>
   </element>
 
-  <element name="acceleration" type="pose" default="0 0 0 0 0 0" required="0">
+  <element name="angular_acceleration" type="vector3" default="0 0 0" required="0">
+    <description>
+      Angular acceleration of the link frame relative to the world frame.
+    </description>
+
+    <attribute name="degrees" type="bool" default="false" required="0">
+      <description>
+        If true, the angular acceleration is expressed in units of degrees per
+        second per second [deg/s^2], otherwise it is expressed in radians per
+        second per second [rad/s^2].
+      </description>
+    </attribute>
+  </element>
+
+  <element name="linear_acceleration" type="vector3" default="0 0 0" required="0">
+    <description>
+      Linear acceleration of the link frame relative to the world frame.
+    </description>
+  </element>
+
+  <element name="acceleration" type="pose" default="0 0 0 0 0 0" required="-1">
     <description>Acceleration of the link. The x, y, z components of the pose
       correspond to the linear acceleration of the link, and the roll,
       pitch, yaw components correspond to the angular acceleration of the link
     </description>
   </element>
 
-  <element name="wrench" type="pose" default="0 0 0 0 0 0" required="0">
+  <element name="torque" type="vector3" default="0 0 0" required="0">
+    <description>Torque acting on the link relative to the world frame.
+    </description>
+  </element>
+
+  <element name="force" type="vector3" default="0 0 0" required="0">
+    <description>
+      Force acting on the link at the link frame relative to the world frame.
+    </description>
+  </element>
+
+  <element name="wrench" type="pose" default="0 0 0 0 0 0" required="-1">
     <description>Force and torque applied to the link. The x, y, z components
       of the pose correspond to the force applied to the link, and the roll,
       pitch, yaw components correspond to the torque applied to the link

diff --git a/sdf/1.12/model.sdf b/sdf/1.12/model.sdf
@@ -62,6 +62,7 @@
       <description>URI to a resource, such as a model</description>
     </element>
 
+    <include filename="model_state.sdf" required="0"/>
     <include filename="pose.sdf" required="0"/>
     <include filename="plugin.sdf" required="*"/>
 
@@ -85,6 +86,8 @@
     </attribute>
   </element>
 
+  <include filename="model_state.sdf" required="0"/>
+
   <element name="enable_wind" type="bool" default="false" required="0">
     <description>If set to true, all links in the model will be affected by the wind. Can be overriden by the link wind property.</description>
   </element>

diff --git a/sdf/1.12/world.sdf b/sdf/1.12/world.sdf
@@ -40,6 +40,7 @@
       <description>Override the static value of the included entity.</description>
     </element>
 
+    <include filename="model_state.sdf" required="0"/>
     <include filename="pose.sdf" required="0"/>
     <include filename="plugin.sdf" required="*"/>