xacro4sdf

xmacro is recommended to replace xacro4sdf, which is a refactor version of xacro4sdf. and xacro4sdf won't be maintained in the future.

xacro4sdf is a simple tool to define and parse XML macro for sdf (sdformat), you can use xacro4sdf to write modularized SDF xml (not nest model)

• xacro4sdf is similar, but different from ros/xacro which is desiged for urdf.
• xacro4sdf is simpler, but easier to use.

Reference: ros/xacro

• With Xacro, you can construct shorter and more readable XML files by using macros that expand to larger XML expressions.

Attention:

• <xacro_include_model> is departed after version2.0.0, you can use the tag with version1.2.6.

1. Usage

Installation

#install by pip
pip install xacro4sdf 
# or install from source code
# git clone https://github.com/gezp/xacro4sdf.git
# cd xacro4sdf && sudo python3 setup.py install

create model.sdf.xmacro file

• refer to files in test/ (for example test/model.sdf.xmacro)

generate model.sdf

#cd test
xacro4sdf model.sdf.xmacro

• it will generate model.sdf (the result should be same as test/model.sdf)
• more examples can be found test folder.

summary of XML Tags

• definition of property and macro : core function
  • <xacro_define_property> and <xacro_define_macro>
• include
  • <xacro_include_definition> :include definition of property and macro from other xmacro file
• use of property and macro:
  • ${xxx} : use of property ,it's very useful to use math expressions.
  • <xacro_macro> : use of macro, it's very useful for modular modeling.

Tip:

• the xacro defination (<xacro_define_property> , <xacro_define_macro> and <xacro_include_definition>) must be child node of root node <sdf> .

2. Features

• Properties
• Macros
• Math expressions
• Include

2.1. Properties

Properties are named values that can be inserted anywhere into the XML document

xacro definition

<!--definition of properties -->
<xacro_define_property name="radius" value="4.3" />
<!--use of properties-->
<circle diameter="${2 * radius}" />

generated xml

<circle diameter="8.6" />

2.2. Macros

The main feature of xacro4sdf is macros.

Define macros with the macro tag <xacro_define_property>, then specify the macro name and a list of parameters. The list of parameters should be whitespace separated.

The usage of Macros is to define <xacro_macro> which will be replaced with <xacro_define_property> block according to the param name.

xacro definition

<!--definition of macro-->
	<xacro_define_property name="mass" value="0.2" />
	<xacro_define_macro macro_name="box_inertia" params="m x y z">
        <mass>${m}</mass>
        <inertia>
            <ixx>${m*(y*y+z*z)/12}</ixx>
            <ixy>0</ixy>
            <ixz>0</ixz>
            <iyy>${m*(x*x+z*z)/12}</iyy>
            <iyz>0</iyz>
            <izz>${m*(x*x+z*z)/12}</izz>
        </inertia>
    </xacro_macro_define>
<!--use of macro-->
            <inertial>
                <pose>0 0 0.02 0 0 0</pose>
                <xacro_macro name="box_inertia" m="${mass}" x="0.3" y="0.1" z="0.2"/>
            </inertial>

generated xml

			<inertial>
				<pose>0 0 0.02 0 0 0</pose>
				<mass>0.2</mass>
				<inertia>
					<ixx>0.0008333333333333335</ixx>
					<ixy>0</ixy>
					<ixz>0</ixz>
					<iyy>0.002166666666666667</iyy>
					<iyz>0</iyz>
					<izz>0.002166666666666667</izz>
				</inertia>
			</inertial>

• only support simple parameters (string and number),but block parameters isn't supported.
• it's supported to use other xacro_macro in xacro_define_macro which is recursive definition.

it's not recommended to define macro recursively (only support <=5).

2.3. Math expressions

• within dollared-braces ${xxxx}, you can also write simple math expressions.
• refer to examples of Properties and Macros
• it's implemented by calling eval() in python, so it's unsafe for some cases.

2.4. Including other xmacro files

definition include

You can include other xmacro files using the <xacro_include_definition> tag ,include other xmacro files according to param uri.

• it will only include the definition of properties with tag <xacro_define_property> and macros with tag <xacro_define_macro>.

<xacro_include_definition uri="model://simple_car/model.sdf.xmacro"/>
<xacro_include_definition uri="file://simple_car/model.sdf.xmacro"/>

• The uri for model means to search file in a list of folders which are defined by environment variable IGN_GAZEBO_RESOURCE_PATH and GAZEBO_MODEL_PATH
• The uri for file means to open the file directly.
  • it try to open the file with relative path simple_car/model.sdf.xmacro .
  • you can also try to open file with absolute path /simple_car/model.sdf.xmacro with uri file:///simple_car/model.sdf.xmacro.

Tips:

• <xacro_include_definition> supports to include recursively.
• Don't use same name for xacro definition (the param name of <xacro_define_property> and <xacro_define_macro>) , otherwise the priority of xacro definition need be considered.
• Be carefully when using <xacro_include_definition> and <xacro_include_model>

2.5 pre-defined common.xmacro

<!--macro defination:inertia-->
<xacro_define_macro name="inertia_cylinder" params="m r l">
<xacro_define_macro name="inertia_box" params="m x y z">
<xacro_define_macro name="inertia_sphere" params="m r">
<!--macro defination:geometry-->
<xacro_define_macro name="geometry_cylinder" params="r l">
<xacro_define_macro name="geometry_box" params="x y z">
<xacro_define_macro name="geometry_sphere" params="r">
<xacro_define_macro name="geometry_mesh" params="uri">
<!--macro defination:visual_collision_with_mesh-->
<xacro_define_macro name="visual_collision_with_mesh" params="prefix uri">

• you can directly use these macros in your xmacro file.

3. Custom usage in python

you can use xacro4sdf in python easily

from xacro4sdf.xacro4sdf import XMLMacro

xmacro=XMLMacro()
#case1 parse from file
xmacro.set_xml_file(inputfile)
xmacro.generate()
xmacro.to_file(outputfile)

#case2 parse from xml string
xmacro.set_xml_string(xml_str)
xmacro.generate()
xmacro.to_file(outputfile)

#case3 generate to string
xmacro.set_xml_file(inputfile)
xmacro.generate()
xmacro.to_string()

#case4 custom property
xmacro.set_xml_file(inputfile)
# use custom property dictionary to overwrite global property  
# defined by <xacro_define_property> (only in 'inputfile')
kv={"rplidar_a2_h":0.8}
xmacro.generate(custom_property=kv)
xmacro.to_file(outputfile)

#case5 set model static
xmacro.set_xml_file(inputfile)
xmacro.generate()
xmacro.set_static(True)
xmacro.to_file(outputfile)

4. Maintainer and License

maintainer : Zhenpeng Ge, zhenpeng.ge@qq.com

xacro4sdf is provided under MIT License.