XML

World files

The simulator places robots in an environment (world) with obstacles. You can create your own environments or modify the existing ones. The world XML files reside in the “worlds” subfolder of the pySimiam distribution.

Creating new worlds

Although worlds can be written by hand (see next section), it might be more pleasant to create a world in a vector graphics editor. A tool named svg2world is provided with pySimiam to convert SVG [1] files to world files.

svg2world only supports a subset of svg, notably all the groups except the top one are ignored. Only the contents of this top group are processed (in Inkscape, the top group is the default layer).

A path with 1 or 2 points is interpreted as a robot, with the position of the robot determined by the first point, and the direction by the second one. An optional attribute robot defines the robot class and supervisor defines the associated supervisor.

The rectangles and the paths with more than 2 points will be converted to obstacles, unless their ‘id’ attribute begins with ‘marker’, such as ‘marker345’. A robot will collide with obstacles, but will ignore markers.

The color of obstacles, markers and robots is taken directly from the fill color. The stroke color is ignored.

Run the tool with

>>> python tools/svg2world.py your_drawing.svg worlds/your_world.xml

File format

The world for the simulation is specified in an XML file. This file contains the position and shape of all obstacles and markers, as well as the position, class and supervisor class of all robots.

An obstacle is a polygon, that the robot can collide with. It can be detected by proximity sensors. An obstacle tag has to contain a pose and a list of points (minimum three points). This example specifies a triangular obstacle:

<obstacle>
    <pose x="0" y="0" theta="0" />
    <geometry>
        <point x="0" y="0" />
        <point x="0.3" y="0.3" />
        <point x="-0.3" y="0.3" />
    </geometry>
</obstacle>

A marker is like an obstacle that the robot can go through. It can not influence the robot in any way, and will not be detected by proximity sensors. The required fields are the same as in the case of an obstacle. Here is an example of a rotated square marker:

<marker>
    <pose x="0" y="-1.3" theta="1.57" />
    <geometry>
        <point x="0" y="0" />
        <point x="0" y="0.3" />
        <point x="0.3" y="0.3" />
        <point x="0.3" y="0" />
    </geometry>
</marker>

Each robot tag in the world represents a robot. It has to contain the robot pose, class and the supervisor class (see Module strings).

<robot type="Khepera3">
    <supervisor type="K3DefaultSupervisor" />
    <pose x="1" y="0" theta="-1.57" />
</robot>

All objects can also have a color attribute in the form #rrggbb. The objects have to be wrapped in a simulation tag. The DTD for the world XML reads:

<!ELEMENT simulation (robot+,obstacle*,marker*)>

<!ELEMENT robot (supervisor,pose)>
<!ATTLIST robot type CDATA #REQUIRED
                color CDATA #IMPLIED>

<!ELEMENT obstacle (pose, geometry)>
<!ATTLIST obstacle color CDATA #IMPLIED>

<!ELEMENT marker (pose, geometry)>
<!ATTLIST marker color CDATA #IMPLIED>

<!ELEMENT pose EMPTY>
<!ATTLIST pose x CDATA #REQUIRED
               y CDATA #REQUIRED
               theta CDATA #REQUIRED>

<!ELEMENT geometry (point, point+)>
<!ELEMENT point EMPTY>
<!ATTLIST point x CDATA #REQUIRED
                y CDATA #REQUIRED>

[1]	Scalable Vector Graphics is a widely used format. SVG files can be created with e.g. Inkscape

Parameter files

The interface allows users to save the configuration of the supervisor and load it later. The configuration is saved in XML format with an arbitrary scheme. The actual format of the file is defined by the supervisor’s get_ui_description() method. The returned list of (key, value) tuples is interpreted as follows:

• Every key in the list is converted either to an XML tag, if the value

  for this key is also a list, or to a tag attribute, if the value is a number or a string. The contents of the tags are populated recursively, the values of attributes are taken directly from the list.

• The key itself is either a string or a tuple.

  • If it is a tuple, then the first element is the name of the XML tag (or attribute) and the second element is ignored. If this key translates into an XML tag and the tuple has a third element, this one translates into the value for an id attribute of the tag.
  • If the key is a string, it is converted to lower case and used directly as a tag or attribute name.

Readers and writers

class xmlreader.XMLReader(file_, template)

A class to handle reading and parsing of XML files for the simulator and parameters configuration files.

read()

Read in and parse the XML given in file_ representing the specified template.

Parameters:

None

Return:

The result of reading and parsing the file. The type of return is dependent on the template, as follows:

1) simulation: a list of tuples representing robots, obstacles, and markers, as follows:

(‘robot’, robot_type, supervisor_type, pose, color)

(‘obstacle’, pose, [point1, point2, point3, ...], color)

(‘marker’, pose, [point1, point2, point3, ...], color)

2) parameters: a dictionary representing the structure of the XML, as follows:

{ root_element:

{ parameter_name: {attribute_name: attribute_value, ... },

...

(parameter_name, parameter_id): {attribute_name: attribute_value, ... },

...

}

}

class xmlwriter.XMLWriter(file_, template, tree)

A class to handle saving XML files for the simulator and parameters entered via the UI.

write()

Write out the tree as XML representing the specified template to the given file_.

Paramaters:

None

Return:

void

class xmlobject.XMLObject(file_, template)

Base class for XML handling.

validate(schema)

Validate the XML in file_ against a given schema.

Parameters:

schema........path to the schema file (must be RelaxNG)

Return:

True if schema validates successfully, False otherwise