1# Migration Guide for SDF Protocol 2This document contains information about migrating 3between different versions of the SDF protocol. 4The SDF protocol version number is specified in the `version` attribute 5of the `sdf` element (1.4, 1.5, 1.6, etc.) 6and is distinct from sdformat library version 7(2.3, 3.0, 4.0, etc.). 8 9# Note on backward compatibility 10There are `*.convert` files that allow old sdf files to be migrated 11forward programmatically. 12This document aims to contain similar information to those files 13but with improved human-readability.. 14 15## SDFormat 5.x to 6.x 16 17### Deprecations 18 191. **sdf/Types.hh** 20 + ***Deprecated:*** sdf::Color class 21 + ***Replacement:*** ignition::math::Color class 22 23## SDFormat 4.x to 5.x 24 25### Deletions 26 271. **Removed the following functions from `parser.hh`** 28 + bool initDoc(TiXmlDocument *_xmlDoc, SDFPtr _sdf); 29 + bool initDoc(TiXmlDocument *_xmlDoc, ElementPtr _sdf); 30 + bool initXml(TiXmlElement *_xml, ElementPtr _sdf); 31 + bool readDoc(TiXmlDocument *_xmlDoc, SDFPtr _sdf, const std::string &_source); 32 + bool readDoc(TiXmlDocument *_xmlDoc, ElementPtr _sdf, const std::string &_source); 33 + bool readXml(TiXmlElement *_xml, ElementPtr _sdf); 34 + void copyChildren(ElementPtr _sdf, TiXmlElement *_xml); 35 + std::string getBestSupportedModelVersion(TiXmlElement *_modelXML, std::string &_modelFileName); 36 37### Deprecations 38 391. **sdf/Param.hh** 40 + ***Deprecation:*** const std::type_info &GetType() const 41 + ***Replacement:*** template<typename Type> bool IsType() const 42 431. **sdf/SDFImpl.hh** 44 + ***Deprecation:*** ElementPtr root 45 + ***Replacement:*** ElementPtr Root() const / void Root(const ElementPtr _root) 46 + ***Deprecation:*** static std::string version 47 + ***Replacement:*** static std::string Version() 48 491. **sdf/Types.hh** 50 + ***Deprecation:*** sdf::Vector2i 51 + ***Replacement:*** ignition::math::Vector2i 52 + ***Deprecation:*** sdf::Vector2d 53 + ***Replacement:*** ignition::math::Vector2d 54 + ***Deprecation:*** sdf::Vector3 55 + ***Replacement:*** ignition::math::Vector3d 56 + ***Deprecation:*** sdf::Quaternion 57 + ***Replacement:*** ignition::math::Quaterniond 58 + ***Deprecation:*** sdf::Pose 59 + ***Replacement:*** ignition::math::Pose3d 60 61## SDFormat 3.x to 4.x 62 63### Additions 64 651. **New SDF protocol version 1.6** 66 + Details about the 1.5 to 1.6 transition are explained below in this same 67 document 68 69### Modifications 70 711. **Boost pointers and boost::function** 72 + All boost pointers, boost::function in the public API have been replaced 73 by their std:: equivalents (C++11 standard) 74 751. **`gravity` and `magnetic_field` elements are moved from `physics` to `world`** 76 + In physics element: gravity and magnetic_field tags have been moved 77 from Physics to World element. 78 + [pull request 247](https://bitbucket.org/osrf/sdformat/pull-requests/247) 79 + [gazebo pull request 2090](https://bitbucket.org/osrf/gazebo/pull-requests/2090) 80 811. **New noise for IMU** 82 + A new style for representing the noise properties of an `imu` was implemented 83 in [pull request 199](https://bitbucket.org/osrf/sdformat/pull-requests/199) 84 for sdf 1.5 and the old style was declared as deprecated. 85 The old style has been removed from sdf 1.6 with the conversion script 86 updating to the new style. 87 + [pull request 199](https://bitbucket.org/osrf/sdformat/pull-requests/199) 88 + [pull request 243](https://bitbucket.org/osrf/sdformat/pull-requests/243) 89 + [pull request 244](https://bitbucket.org/osrf/sdformat/pull-requests/244) 90 911. **Lump:: prefix in link names** 92 + Changed to \_fixed_joint_lump__ to avoid confusion with scoped names 93 + [Pull request 245](https://bitbucket.org/osrf/sdformat/pull-request/245) 94 95## SDF protocol 1.5 to 1.6 96 97### Additions 98 991. **physics.sdf** `dart::solver::solver_type` element 100 + description: The DART LCP/constraint solver to use. 101 Either dantzig or pgs (projected Gauss-Seidel) 102 + type: string 103 + default: dantzig 104 + required: 0 105 + [pull request 369](https://bitbucket.org/osrf/sdformat/pull-requests/369) 106 1071. **link.sdf** `enable_wind` element 108 + description: If true, the link is affected by the wind 109 + type: bool 110 + default: false 111 + required: 0 112 + [pull request 240](https://bitbucket.org/osrf/sdformat/pull-requests/240) 113 1141. **link.sdf** `light` element 115 + included from `light.sdf` with required="*", 116 so a link can have any number of attached lights. 117 + [pull request 373](https://bitbucket.org/osrf/sdformat/pull-requests/373) 118 1191. **model.sdf** `enable_wind` element 120 + description: If set to true, all links in the model will be affected by 121 the wind. Can be overriden by the link wind property. 122 + type: bool 123 + default: false 124 + required: 0 125 + [pull request 240](https://bitbucket.org/osrf/sdformat/pull-requests/240) 126 1271. **model_state.sdf** `scale` element 128 + description: Scale for the 3 dimensions of the model. 129 + type: vector3 130 + default: "1 1 1" 131 + required: 0 132 + [pull request 246](https://bitbucket.org/osrf/sdformat/pull-requests/246) 133 1341. **physics.sdf** `island_threads` element under `ode::solver` 135 + description: Number of threads to use for "islands" of disconnected models. 136 + type: int 137 + default: 0 138 + required: 0 139 + [pull request 380](https://bitbucket.org/osrf/sdformat/pull-requests/380) 140 1411. **physics.sdf** `thread_position_correction` element under `ode::solver` 142 + description: Flag to use threading to speed up position correction computation. 143 + type: bool 144 + default: 0 145 + required: 0 146 + [pull request 380](https://bitbucket.org/osrf/sdformat/pull-requests/380) 147 1481. **state.sdf** allow `light` tags within `insertions` element 149 * [pull request 325](https://bitbucket.org/osrf/sdformat/pull-request/325) 150 1511. **surface.sdf** `category_bitmask` element 152 + description: Bitmask for category of collision filtering. 153 Collision happens if `((category1 & collision2) | (category2 & collision1))` is not zero. 154 If not specified, the category_bitmask should be interpreted as being the same as collide_bitmask. 155 + type: unsigned int 156 + default: 65535 157 + required: 0 158 + [pull request 318](https://bitbucket.org/osrf/sdformat/pull-requests/318) 159 1601. **world.sdf** `wind` element 161 + description: The wind tag specifies the type and properties of the wind. 162 + required: 0 163 + [pull request 240](https://bitbucket.org/osrf/sdformat/pull-requests/240) 164 1651. **world.sdf** `wind::linear_velocity` element 166 + description: Linear velocity of the wind. 167 + type: vector3 168 + default: "0 0 0" 169 + required: 0 170 + [pull request 240](https://bitbucket.org/osrf/sdformat/pull-requests/240) 171