Skip to content

Migration.md

Latest commit

 

History

History
658 lines (514 loc) · 27.4 KB

Migration.md

File metadata and controls

658 lines (514 loc) · 27.4 KB

Migration Guide for SDFormat Specification

This document contains information about migrating between different versions of the SDFormat specification. The SDFormat specification 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..

libsdformat 11.1.0 to 11.2.0

ABI was broken for sdf::Element, and restored on version 11.2.1.

libsdformat 11.0.0 to 11.x.x

Additions

  1. sdf/Console.hh Add functions to retrieve message stream objects. These can be useful for redirecting the console output to other streams.

    • ConsoleStream &GetMsgStream()
    • ConsoleStream &GetLogStream()

  2. sdf/ParserConfig.hh:

    • void SetDeprecatedElementsPolicy(EnforcementPolicy _policy)
    • void ResetDeprecatedElementsPolicy()
    • EnforcementPolicy DeprecatedElementsPolicy() const

  3. test/test_utils.hh:

    • ScopeExit: A utility struct that calls a function when going out of scope.
    • RedirectConsoleStream: A utility class used for redirecting the output of sdferr, sdfwarn, etc to a more convenient stream object like a std::stringstream for testing purposes.

libsdformat 10.x to 11.0

Additions

  1. sdf/ParserConfig.hh A class that contains configuration options for the libsdformat parser.

  3. sdf/Joint.hh

    • Errors ResolveChildLink(std::string&) const
    • Errors ResolveParentLink(std::string&) const

  4. sdf/Model.hh:

    • std::pair<const Link *, std::string> CanonicalLinkAndRelativeName() const;

  5. sdf/Root.hh sdf::Root elements can now only contain one of either Model, Light or Actor since multiple items would conflict with overrides specified in an tag.

    • const sdf::Model *Model();
    • const sdf::Light *Light();
    • const sdf::Actor *Actor();

Modifications

  1. sdf/Model.hh: the following methods now accept nested names relative to the model's scope that can begin with a sequence of nested model names separated by :: and may end with the name of an object of the specified type.

    • const Frame *FrameByName(const std::string &) const
    • const Joint *JointByName(const std::string &) const
    • const Link *LinkByName(const std::string &) const
    • bool FrameNameExists(const std::string &) const
    • bool JointNameExists(const std::string &) const
    • bool LinkNameExists(const std::string &) const

  2. sdf/Heightmap.hh: sampling now defaults to 1 instead of 2.

Deprecations

  1. src/Root.hh: The following methods have been deprecated in favor of the new methods. For now the behavior is unchanged, but Root elements should only contain one or none of Model/Light/Actor.
    • const sdf::Model *ModelByIndex();
    • uint64_t ModelCount();
    • bool ModelNameExists(const std::string &_name) const;
    • const sdf::Light *LightByIndex();
    • uint64_t LightCount();
    • bool LightNameExists(const std::string &_name) const;
    • const sdf::Actor *ActorByIndex();
    • uint64_t ActorCount();
    • bool ActorNameExists(const std::string &_name) const;

libsdformat 10.2.0 to 10.x.x

Modifications

  1. Fixed Atmosphere DOM class's temperature default value. Changed from -0.065 to -0.0065.

  2. Fixed parsing of <sensor><pose> tags on lumped links when converting from URDF.

libsdformat 9.x to 10.0

Modifications

  1. Axis vectors specified in are normalized if their norm is greater than 0. A vector with 0 norm generates an error

    • Minimum/maximum values specified in SDFormat description files are now enforced
    • Pull request 303

Deletions

    • Removed the parser_urdf.hh header file and its URDF2SDF class
    • Pull request 276
    • Removed the deprecated Pose(), SetPose(), and *PoseFrame() API's in all DOM classes:
    • const ignition::math::Pose3d &Pose()
    • void SetPose(const ignition::math::Pose3d &)
    • const std::string &PoseFrame()
    • void SetPoseFrame(const std::string &)
    • Removed deprecated functions from sdf/JointAxis.hh:
    • bool UseParentModelFrame()
    • void SetUseParentModelFrame(bool)

Additions

  1. sdf/Element.hh

    • void AddValue(const std::string &, const std::string &, bool, const std::string &, const std::string &, const std::string &)

  2. sdf/Param.hh

    • Param(const std::string &, const std::string &e, const std::string &, bool, const std::string &, const std::string &, const std::string &)
    • std::optionalstd::string GetMinValueAsString() const;
    • std::optionalstd::string GetMaxValueAsString() const;
    • bool ValidateValue() const;

libsdformat 9.4 to 9.5

Additions

  1. sdf/Element.hh
    • sdf::ElementPtr FindElement() const

libsdformat 9.3 to 9.4

Modifications

  1. camera.sdf
    • Reduce minimum value of //camera/clip/far

Deprecations

  1. Fix spelling of supported shader types in //material/shader/@type
    • normal_map_objectspace replaced by normal_map_object_space
    • normal_map_tangentspace replaced by normal_map_tangent_space
    • pull request 383

libsdformat 9.0 to 9.3

Additions

  1. sdf/Model.hh
    • uint64_t ModelCount() const
    • const Model *ModelByIndex(const uint64_t) const
    • const Model *ModelByName(const std::string &) const
    • bool ModelNameExists(const std::string &) const

Modifications

  1. Permit models without links if they contain a nested canonical link.

SDFormat 8.x to 9.0

Additions

  1. sdf/Collision.hh

    • sdf::SemanticPose SemanticPose() const

  2. sdf/Element.hh

    • void Clear()
    • const std::string &OriginalVersion() const
    • void SetOriginalVersion(const std::string &)

  3. sdf/Frame.hh: DOM class for frames in the model or world.

    • Errors ResolveAttachedToBody(std::string&) const
    • sdf::SemanticPose SemanticPose() const

  4. sdf/Joint.hh

    • sdf::SemanticPose SemanticPose() const

  5. sdf/JointAxis.hh

    • Errors ResolveXyz(ignition::math::Vector3d &, const std::string &) const

  6. sdf/Light.hh

    • sdf::SemanticPose SemanticPose() const

  7. sdf/Link.hh

    • sdf::SemanticPose SemanticPose() const

  8. sdf/Model.hh

    • uint64_t FrameCount() const
    • const Frame *FrameByIndex(const uint64_t) const
    • const Frame *FrameByName(const std::string &) const
    • bool FrameNameExists(const std::string &) const
    • sdf::SemanticPose SemanticPose() const

  9. sdf/SDFImpl.hh

    • void Clear()
    • const std::string &OriginalVersion() const
    • void SetOriginalVersion(const std::string &)

  10. sdf/SemanticPose.hh: Helper class for resolving poses of DOM objects.

  11. sdf/Sensor.hh

    • sdf::SemanticPose SemanticPose() const

  12. sdf/Visual.hh

    • sdf::SemanticPose SemanticPose() const

  13. sdf/World.hh

    • uint64_t FrameCount() const
    • const Frame *FrameByIndex(const uint64_t) const
    • const Frame *FrameByName(const std::string &) const
    • bool FrameNameExists(const std::string &) const
    • const Model *ModelByName(const std::string &) const

  14. sdf/parser.hh

    • bool checkCanonicalLinkNames(sdf::Root*)
    • bool checkFrameAttachedToGraph(sdf::Root*)
    • bool checkFrameAttachedToNames(sdf::Root*)
    • bool checkJointParentChildLinkNames(sdf::Root*)
    • bool checkPoseRelativeToGraph(sdf::Root*)
    • bool recursiveSameTypeUniqueNames(sdf::ElementPtr)
    • bool recursiveSiblingUniqueNames(sdf::ElementPtr)
    • bool shouldValidateElement(sdf::ElementPtr)

Deprecations

  1. sdf/parser_urdf.hh

    • Deprecation: URDF2SDF
    • Replacement: None. Use the functions sdf::readFile or sdf::readString, which automatically convert URDF to SDFormat.

  2. All DOM classes with Pose() and PoseFrame() API's:

    • Deprecation: const ignition::math::Pose3d &Pose()
    • Replacement: const ignition::math::Pose3d &RawPose()
    • Deprecation: const std::string &PoseFrame()
    • Replacement: const std::string &PoseRelativeTo()
    • Deprecation: void SetPose(const ignition::math::Pose3d &)
    • Replacement: void SetRawPose(const ignition::math::Pose3d &)
    • Deprecation: void SetPoseFrame(const std::string &)
    • Replacement: void SetPoseRelativeTo(const std::string &)

  3. sdf/JointAxis.hh

    • Deprecation: bool UseParentModelFrame()
    • Replacement: const std::string &XyzExpressedIn()
    • Deprecation: void SetUseParentModelFrame(bool)
    • Replacement: void SetXyzExpressedIn(const std::string &)

SDFormat 8.0 to 8.1

Modifications

    • Change installation path of SDF description files to allow side-by-side installation.
    • {prefix}/share/sdformat/1.*/*.sdf -> {prefix}/share/sdformat8/1.*/*.sdf
    • BitBucket pull request 538

SDFormat 5.x to 6.x

Deprecations

  1. sdf/Types.hh
    • Deprecated: sdf::Color class
    • Replacement: ignition::math::Color class

SDFormat 4.x to 5.x

Deletions

  1. Removed the following functions from parser.hh
    • bool initDoc(TiXmlDocument *_xmlDoc, SDFPtr _sdf);
    • bool initDoc(TiXmlDocument *_xmlDoc, ElementPtr _sdf);
    • bool initXml(TiXmlElement *_xml, ElementPtr _sdf);
    • bool readDoc(TiXmlDocument *_xmlDoc, SDFPtr _sdf, const std::string &_source);
    • bool readDoc(TiXmlDocument *_xmlDoc, ElementPtr _sdf, const std::string &_source);
    • bool readXml(TiXmlElement *_xml, ElementPtr _sdf);
    • void copyChildren(ElementPtr _sdf, TiXmlElement *_xml);
    • std::string getBestSupportedModelVersion(TiXmlElement *_modelXML, std::string &_modelFileName);

Deprecations

  1. sdf/Param.hh

    • Deprecation: const std::type_info &GetType() const
    • Replacement: template bool IsType() const

  2. sdf/SDFImpl.hh

    • Deprecation: ElementPtr root
    • Replacement: ElementPtr Root() const / void Root(const ElementPtr _root)
    • Deprecation: static std::string version
    • Replacement: static std::string Version()

  3. sdf/Types.hh

    • Deprecation: sdf::Vector2i
    • Replacement: ignition::math::Vector2i
    • Deprecation: sdf::Vector2d
    • Replacement: ignition::math::Vector2d
    • Deprecation: sdf::Vector3
    • Replacement: ignition::math::Vector3d
    • Deprecation: sdf::Quaternion
    • Replacement: ignition::math::Quaterniond
    • Deprecation: sdf::Pose
    • Replacement: ignition::math::Pose3d

SDFormat 3.x to 4.x

Additions

  1. New SDFormat specification 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. Lump:: prefix in link names

SDFormat specification 1.7 to 1.8

Additions

  1. capsule.sdf and ellipsoid.sdf new shape types included in //geometry

    • capsule.sdf: A shape consisting of a cylinder capped by hemispheres with parameters for the radius and length of cylindrical section.
    • ellipsoid.sdf: A convex shape with up to three radii defining its shape in of the form (x^2/a^2 + y^2/b^2 + z^2/c^2 = 1).

  2. light.sdf //light/intensity element

    • description: Scale factor to set the relative power of a light.
    • type: double
    • default: 1
    • required: 0
    • pull request 484

Modifications

  1. joint.sdf child and parent elements accept frame names instead of only link names

  2. heightmap.sdf: sampling now defaults to 1 instead of 2.

  3. Element attribute names containing delimiter "::" no longer accepted

Deprecations

  1. joint.sdf initial_position element in <joint><axis> and <joint><axis2> is deprecated

Removals

  1. inerial.sdf //inertial/pose/@relative_to attribute is removed

SDFormat specification 1.6 to 1.7

Additions

  1. frame.sdf //frame/@attached_to attribute

    • description: Name of the link or frame to which this frame is attached. If a frame is specified, recursively following the attached_to attributes of the specified frames must lead to the name of a link, a model, or the world frame.
    • type: string
    • default: ""
    • required: *
    • BitBucket pull request 603

  2. joint.sdf //axis/xyz/@expressed_in and //axis2/xyz/@expressed_in attributes

    • description: The name of the frame in which the //axis/xyz value is expressed. When migrating from sdf 1.6, a use_parent_model_frame value of true will be mapped to a value of __model__ for the expressed_in attribute.
    • type: string
    • default: ""
    • required: 0
    • BitBucket pull request 589

  3. material.sdf //material/double_sided element

    • description: Flag to indicate whether the mesh that this material is applied to will be rendered as double sided.
    • type: bool
    • default: false
    • required: 0
    • pull request 418

  4. model.sdf //model/@canonical_link attribute

    • description: The name of the canonical link in this model to which the model's implicit frame is attached. This implies that a model must have at least one link (unless it is static), which is also stated in the Modifications section.
    • type: string
    • default: ""
    • required: 0
    • BitBucket pull request 601

  5. world.sdf //world/frame element is now allowed.

Modifications

  1. A non-static model must have at least one link, as specified in the proposal.

  2. Unique names for all sibling elements:

    • As described in the proposal, all named sibling elements must have unique names. Uniqueness is forced so that referencing implicit frames is not ambiguous, e.g. you cannot have a link and joint share an implicit frame name. Some existing SDFormat models may not comply with this requirement. The ign sdf --check command can be used to identify models that violate this requirement.
    • BitBucket pull request 600

  3. Reserved names:

    • As described in the proposal, entities in a simulation must not use world as a name. It has a special interpretation when specified as a parent or child link of a joint. Names starting and ending with double underscores (eg. __wheel__) must be reserved for use by library implementors and the specification. For example, such names might be useful during parsing for setting sentinel or default names for elements with missing names. If explicitly stated, they can be referred to (e.g. __model__ / world for implicit model / world frames, respectively).

  4. joint.sdf //joint/child may no longer be specified as world.

  5. pose.sdf //pose/@frame attribute is renamed to //pose/@relative_to.

Removals

  1. <frame> element is now only allowed in <model> and <world>. It is no longer allowed in the following elements:

    • actor
    • audio_source
    • camera
    • collision
    • frame
    • gui
    • inertial
    • joint
    • light
    • light_state
    • link
    • link_state
    • population
    • projector
    • sensor
    • visual
    • BitBucket pull request 603

  2. actor.sdf static element was deprecated in BitBucket pull request 280 and is now removed.

  3. imu.sdf topic element was deprecated in BitBucket pull request 532 and is now removed.

  4. joint.sdf //axis/use_parent_model_frame and //axis2/use_parent_model_frame elements are removed in favor of the //axis/xyz/@expressed_in and //axis2/xyz/@expressed_in attributes. When migrating from sdf 1.6, a use_parent_model_frame value of true will be mapped to a value of __model__ for the expressed_in attribute.

  5. joint.sdf //physics/ode/provide_feedback was deprecated in BitBucket pull request 38 and is now removed.

  6. world.sdf //world/joint was removed as it has never been used.

SDFormat specification 1.5 to 1.6

Additions

  1. actor.sdf tension element

    • description: The tension of the trajectory spline. The default value of zero equates to a Catmull-Rom spline, which may also cause the animation to overshoot keyframes. A value of one will cause the animation to stick to the keyframes.
    • type: double
    • default: 0.0
    • min: 0.0
    • max: 1.0
    • required: 0
    • BitBucket pull request 466

  2. camera.sdf depth_camera/clip sub-elements: near, far

  3. camera.sdf intrinsics sub-elements: fx, fy, cx, cy, s

  4. heightmap_shape.sdf sampling element

    • description: Samples per heightmap datum. For rasterized heightmaps, this indicates the number of samples to take per pixel. Using a lower value, e.g. 1, will generally improve the performance of the heightmap but lower the heightmap quality.
    • type: unsigned int
    • default: 2
    • required: 0
    • Bitbucket pull request 293

  5. link.sdf enable_wind element

  6. link.sdf light element

  7. 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
    • BitBucket pull request 240

  8. model_state.sdf scale element

  9. physics.sdf dart::collision_detector element

    • description: The collision detector for DART to use. Can be dart, fcl, bullet or ode.
    • type: string
    • default: fcl
    • required: 0
    • BitBucket pull request 440

  10. physics.sdf dart::solver::solver_type element

    • description: The DART LCP/constraint solver to use. Either dantzig or pgs (projected Gauss-Seidel)
    • type: string
    • default: dantzig
    • required: 0
    • BitBucket pull request 369

  11. physics.sdf friction_model element

    • description: Name of ODE friction model to use. Valid values include:
      • pyramid_model: (default) friction forces limited in two directions in proportion to normal force.
      • box_model: friction forces limited to constant in two directions.
      • cone_model: friction force magnitude limited in proportion to normal force. See gazebo pull request 1522 (merged in gazebo 8c05ad64967c) for the implementation of this feature.
    • type: string
    • default: "pyramid_model"
    • required: 0
    • Bitbucket pull request 294

  12. 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
    • BitBucket pull request 380

  13. 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
    • BitBucket pull request 380

  14. sonar.sdf geometry element

    • description: The sonar collision shape. Currently supported geometries are: "cone" and "sphere".
    • type: string
    • default: "cone"
    • required: 0
    • BitBucket pull request 495

  15. state.sdf allow light tags within insertions element

  16. 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
    • BitBucket pull request 318

  17. world.sdf wind element

  18. world.sdf wind::linear_velocity element

Modifications

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

  2. New noise for IMU