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