ppovb5fc7/sdformat/Migration.md

Migration Guide for SDF Protocol

This document contains information about migrating between different versions of the SDF protocol. The SDF protocol version number is specified in the version attribute of the sdf element (1.4, 1.5, 1.6, etc.) and is distinct from sdformat library version (2.3, 3.0, 4.0, etc.).

Note on backward compatibility

There are *.convert files that allow old sdf files to be migrated forward programmatically. This document aims to contain similar information to those files but with improved human-readability..

SDFormat 3.x to 4.x

Additions

1. New SDF protocol version 1.6
   • Details about the 1.5 to 1.6 transition are explained below in this same document

Modifications

1. Boost pointers and boost::function

   • All boost pointers, boost::function in the public API have been replaced by their std:: equivalents (C++11 standard)

2. gravity and magnetic_field elements are moved from physics to world

   • In physics element: gravity and magnetic_field tags have been moved from Physics to World element.
   • pull request 247
   • gazebo pull request 2090

3. New noise for IMU

   • A new style for representing the noise properties of an imu was implemented in pull request 199 for sdf 1.5 and the old style was declared as deprecated. The old style has been removed from sdf 1.6 with the conversion script updating to the new style.
   • pull request 199
   • pull request 243
   • pull request 244

4. Lump:: prefix in link names

   • Changed to _fixed_joint_lump__ to avoid confusion with scoped names
   • Pull request 245

SDF protocol 1.5 to 1.6

Additions

1. link.sdf enable_wind element

   • description: If true, the link is affected by the wind
   • type: bool
   • default: false
   • required: 0
   • pull request 240

2. link.sdf light element

   • included from light.sdf with required="*", so a link can have any number of attached lights.
   • pull request 373

3. model.sdf enable_wind element

   • description: If set to true, all links in the model will be affected by the wind. Can be overriden by the link wind property.
   • type: bool
   • default: false
   • required: 0
   • pull request 240

4. model_state.sdf scale element

   • description: Scale for the 3 dimensions of the model.
   • type: vector3
   • default: "1 1 1"
   • required: 0
   • pull request 246

5. physics.sdf island_threads element under ode::solver

   • description: Number of threads to use for "islands" of disconnected models.
   • type: int
   • default: 0
   • required: 0
   • pull request 380

6. physics.sdf thread_position_correction element under ode::solver

   • description: Flag to use threading to speed up position correction computation.
   • type: bool
   • default: 0
   • required: 0
   • pull request 380

7. state.sdf allow light tags within insertions element

   • pull request 325

8. surface.sdf category_bitmask element

   • description: Bitmask for category of collision filtering. Collision happens if ((category1 & collision2) | (category2 & collision1)) is not zero. If not specified, the category_bitmask should be interpreted as being the same as collide_bitmask.
   • type: unsigned int
   • default: 65535
   • required: 0
   • pull request 318

9. world.sdf wind element

   • description: The wind tag specifies the type and properties of the wind.
   • required: 0
   • pull request 240

10. world.sdf wind::linear_velocity element

    • description: Linear velocity of the wind.
    • type: vector3
    • default: "0 0 0"
    • required: 0
    • pull request 240