semantic_digital_twin.adapters.gazebo

semantic_digital_twin.adapters.gazebo#

Attributes#

logger

Exceptions#

`MissingRootElement`	Raised when a description file contains none of the expected root elements.
`MalformedPose`	Raised when a pose does not consist of a position and roll-pitch-yaw triple.
`UnsupportedJointType`	Raised when a parsed joint uses a type that has no connection counterpart.
`UnsupportedGeometryType`	Raised when a parsed geometry uses a shape that has no counterpart.
`UnsupportedPoseReference`	Raised when a pose is expressed relative to a named frame.
`UnsupportedAxisReference`	Raised when a joint axis is expressed in a frame other than the joint frame.

Classes#

`JointDescription`	A joint that has been read from a description and validated, but not yet turned into
`GazeboParser`	Parses Gazebo SDF model and world descriptions into worlds.

Module Contents#

semantic_digital_twin.adapters.gazebo.logger#

class semantic_digital_twin.adapters.gazebo.JointDescription#

A joint that has been read from a description and validated, but not yet turned into a connection.

Reading a joint can fail on constructs the parser does not support, while creating a connection modifies a world. Keeping the two apart lets a failure surface before a world has been touched.

name: semantic_digital_twin.datastructures.prefixed_name.PrefixedName#: The name of the connection the joint becomes.

connection_type: Type[semantic_digital_twin.world_description.world_entity.Connection]#: The type of connection the joint becomes.

parent: semantic_digital_twin.world_description.world_entity.Body#: The body the joint moves the child relative to.

child: semantic_digital_twin.world_description.world_entity.Body#: The body the joint moves.

parent_T_connection: semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix#: The pose of the joint relative to the parent body.

connection_T_child: semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix#: The pose of the child body relative to the joint.

axis: semantic_digital_twin.spatial_types.spatial_types.Vector3 | None = None#: The axis the joint moves along, in the frame of the joint.

limits: semantic_digital_twin.world_description.degree_of_freedom.DegreeOfFreedomLimits | None = None#: The limits of the joint’s degree of freedom.

dynamics: semantic_digital_twin.world_description.connection_properties.JointDynamics#: The dynamic properties of the joint.

class semantic_digital_twin.adapters.gazebo.GazeboParser#

Parses Gazebo SDF model and world descriptions into worlds.

Files of SDF 1.4 through 1.8 are accepted: both the pre-1.7 frame and the post-1.7 relative_to pose syntax are read, and both are only supported with default frame semantics. Constructs outside the supported subset, such as named frame references, axes expressed in another frame, and joint or geometry types without a counterpart, raise a ParsingError subclass naming the construct. The declared version is never branched on.

Note

A model declared static is attached rigidly, but joints inside it stay movable.

connection_type_map: ClassVar[Dict[str, Type[semantic_digital_twin.world_description.world_entity.Connection]]]#: Maps a joint’s declared type to the connection it becomes.

world_link_name: ClassVar[str] = 'world'#: The reserved link name that refers to the simulation world rather than a model link.

truthy_values: ClassVar[Tuple[str, Ellipsis]] = ('1', 'true')#: The texts that SDF accepts for a boolean element that is set.

interpreted_elements: ClassVar[Tuple[str, Ellipsis]] = ('model', 'include', 'link', 'joint', 'pose', 'static')#: The child elements of a world or model that carry into the parsed world.

sdf: str#: The SDF document.

prefix: str | None = None#: The prefix for every name used in this world.

path_resolver: semantic_digital_twin.adapters.package_resolver.PathResolver#: The path resolver used for the URIs referenced by this document.

model_element_cache: dict#: Maps a model description file path to its already parsed model element, so that a world instantiating the same model many times parses its file only once.

classmethod from_file(file_path: str, prefix: str | None = None, path_resolver: semantic_digital_twin.adapters.package_resolver.PathResolver | None = None) → GazeboParser#

Creates a parser for a description file.

Unless a resolver is given, one is built that finds model:// URIs relative to the file, so that a world shipped next to its models parses without further configuration.

Parameters:

file_path – The path of the file to parse.
prefix – The prefix for every name used in this world.
path_resolver – The resolver for the URIs referenced by the file.

Returns:

A parser for the described world.

static resolver_for_file(file_path: str) → semantic_digital_twin.adapters.package_resolver.CompositePathResolver#

Builds a resolver that searches for models and assets in the usual places relative to a description file, covering both flat and nested world directory layouts.

Models are looked up in a models directory at or above the file, and the directories holding those are also searched for the relative paths that descriptions written for a resource search path use.

Parameters:: file_path – The path of the file whose location is used for the search.
Returns:: The resolver for the URIs referenced by that file.

parse() → semantic_digital_twin.world.World#

Parses the document into a world.

Returns:: The world described by a world element, or by a single model element if the document describes one model.

parse_world(element: xml.etree.ElementTree.Element) → semantic_digital_twin.world.World#

Parses a world element into a world with an explicit root body that all contained models are attached to.

Parameters:: element – The world element to parse.
Returns:: The world holding every model the element contains.

attach_contained_models(world: semantic_digital_twin.world.World, container: xml.etree.ElementTree.Element) → None#

Attaches every model the container references to the root of the world, whether it is included by URI or written inline.

Gazebo’s non-canonical idiom of wrapping an include in a model element is supported alongside the canonical form; the wrapper supplies the instance name and a pose that composes with the pose of the include.

Parameters:

world – The world the models are attached to.
container – The world or model element holding the references.

attach_included_model(world: semantic_digital_twin.world.World, include_element: xml.etree.ElementTree.Element, instance_name: str | None, wrapper_pose: semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix | None = None) → None#

Resolves an include to its model file and attaches an instance of it.

Parameters:

world – The world the instance is attached to.
include_element – The include element to resolve.
instance_name – The name of the instance, taken from a wrapping model element if there is one.
wrapper_pose – The pose of the wrapping model element, which the pose of the include is expressed in.

merge_at_pose(world: semantic_digital_twin.world.World, sub_world: semantic_digital_twin.world.World, pose: semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix, is_static: bool) → None#

Merges a model into the world at a pose relative to the world root.

A static model is attached rigidly, so that it does not gain the degrees of freedom a free-floating model would.

Parameters:

world – The world the model is merged into.
sub_world – The world holding the model.
pose – The pose of the model relative to the root of the world.
is_static – Whether the model is declared static.

load_model_element(uri: str) → xml.etree.ElementTree.Element#

Loads the model element a model:// URI refers to.

Documents are cached, because a world typically instantiates the same model many times.

Parameters:: uri – The URI of the model directory.
Returns:: The model element of the model’s description file.

model_file_of_directory(model_directory: str) → str#

Reads the model.config of a model directory and returns the description file it points at, preferring the highest declared version.

The version only selects between the files a model ships; whether the parser supports the file’s contents is decided per construct while parsing.

Parameters:: model_directory – The directory holding the model.
Returns:: The path of the model’s description file.

static version_of(version: str) → Tuple[int, Ellipsis]#

Parameters:: version – A dotted version such as 1.6.
Returns:: The version as a tuple that orders like the version does.

parse_model(element: xml.etree.ElementTree.Element, instance_name: str) → semantic_digital_twin.world.World#

Parses a model element into a world of its own, whose root is the model’s root link.

Link poses in SDF are relative to the model rather than to the parent link, so the kinematic tree is reconstructed from the joints.

Parameters:

element – The model element to parse.
instance_name – The name that prefixes every name in the model, which distinguishes several instances of the same model.

Returns:

The world holding the model.

static root_body_of(bodies: Dict[str, semantic_digital_twin.world_description.world_entity.Body], child_link_names: set, instance_name: str) → semantic_digital_twin.world_description.world_entity.Body#

Determines the root link of a model, which is the first link no joint moves.

Parameters:

bodies – The bodies of the model, by link name.
child_link_names – The names of the links that are the child of a joint.
instance_name – The name of the model instance, used when it has no links.

Returns:

The body that roots the model.

attach_unjointed_link(world: semantic_digital_twin.world.World, root_body: semantic_digital_twin.world_description.world_entity.Body, body: semantic_digital_twin.world_description.world_entity.Body, root_T_link: semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix, is_static: bool) → None#

Attaches a link that no joint connects to the root of its model.

Such a link is a free body, unless the model is static, in which case it is fixed in place like the rest of the model.

Parameters:

world – The world the link is added to.
root_body – The root of the model.
body – The body of the unjointed link.
root_T_link – The pose of the link relative to the root of the model.
is_static – Whether the model is declared static.

is_attached_to_a_link(joint_element: xml.etree.ElementTree.Element) → bool#

Parameters:: joint_element – The joint element to check.
Returns:: Whether both ends of the joint are links of the model rather than the simulation world.

parse_link(element: xml.etree.ElementTree.Element, prefix: str) → semantic_digital_twin.world_description.world_entity.Body#

Parses a link element into a body with its shapes and inertial properties.

Parameters:

element – The link element to parse.
prefix – The prefix of the name of the body.

Returns:

The body describing the link.

parse_inertial(element: xml.etree.ElementTree.Element | None, body: semantic_digital_twin.world_description.world_entity.Body) → semantic_digital_twin.world_description.inertial_properties.Inertial | None#

Parses an inertial element.

SDF expresses the inertia tensor in the inertial frame of the link, so it is rotated into the link frame, which is the frame Inertial expects.

Parameters:

element – The inertial element to parse.
body – The body the properties belong to, used as their reference frame.

Returns:

The inertial properties, or None if the link declares none.

parse_shapes(elements: List[xml.etree.ElementTree.Element], body: semantic_digital_twin.world_description.world_entity.Body) → semantic_digital_twin.world_description.shape_collection.ShapeCollection#

Parses the visual or collision elements of a link.

Parameters:

elements – The elements to parse.
body – The body the shapes belong to, used as their reference frame.

Returns:

The shapes of the link.

parse_geometry(element: xml.etree.ElementTree.Element, origin: semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix, color: semantic_digital_twin.world_description.geometry.Color) → semantic_digital_twin.world_description.geometry.Shape#

Parses a geometry element into the shape it describes.

Parameters:

element – The geometry element to parse.
origin – The pose of the shape relative to its link.
color – The color of the shape.

Returns:

The shape described by the element.

parse_color(element: xml.etree.ElementTree.Element | None) → semantic_digital_twin.world_description.geometry.Color#

Parses the diffuse color of a material element.

Parameters:: element – The material element to parse.
Returns:: The color of the material, white if it declares none.

parse_joint(element: xml.etree.ElementTree.Element, bodies: Dict[str, semantic_digital_twin.world_description.world_entity.Body], model_T_link: Dict[str, semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix], prefix: str) → JointDescription#

Parses a joint element into a validated description of the connection it becomes.

The pose of an SDF joint is relative to its child link, so the connection is placed at the joint and the child is offset back to its own frame.

Parameters:

element – The joint element to parse.
bodies – The bodies of the model, by link name.
model_T_link – The poses of the links relative to the model.
prefix – The prefix of the name of the connection.

Returns:

The description of the joint.

Raises:

UnsupportedJointType – If the joint type has no connection counterpart.

create_connection(world: semantic_digital_twin.world.World, description: JointDescription) → semantic_digital_twin.world_description.world_entity.Connection#

Creates the connection a joint description denotes, adding its degree of freedom to the world.

Parameters:

world – The world the degree of freedom is added to.
description – The description of the joint.

Returns:

The connection describing the joint.

parse_axis(element: xml.etree.ElementTree.Element, joint_name: str, parent_body: semantic_digital_twin.world_description.world_entity.Body) → semantic_digital_twin.spatial_types.spatial_types.Vector3#

Parses the axis of a joint element.

The axis is expressed in the frame of the joint, which is the frame the connection places its motion in, so it is taken as it is written.

Parameters:

element – The joint element to parse.
joint_name – The name of the joint, used to report an unsupported frame.
parent_body – The parent of the joint, used as the reference frame.

Returns:

The axis the joint moves along.

Raises:

UnsupportedAxisReference – If the axis is expressed in another frame.

parse_limits(element: xml.etree.ElementTree.Element, joint_type: str, joint_name: str) → semantic_digital_twin.world_description.degree_of_freedom.DegreeOfFreedomLimits#

Parses the limits of a joint element.

A continuous joint turns without end, so it is given no position limits.

Parameters:

element – The joint element to parse.
joint_type – The declared type of the joint.
joint_name – The name of the joint, used to report a negative velocity.

Returns:

The limits of the joint’s degree of freedom.

parse_dynamics(element: xml.etree.ElementTree.Element | None) → semantic_digital_twin.world_description.connection_properties.JointDynamics#

Parses a dynamics element.

Properties the joint leaves undeclared keep their default.

Parameters:: element – The dynamics element to parse.
Returns:: The dynamic properties of the joint.

parse_pose(element: xml.etree.ElementTree.Element | None, reference_frame: semantic_digital_twin.world_description.world_entity.Body | None = None) → semantic_digital_twin.spatial_types.spatial_types.HomogeneousTransformationMatrix#

Parses a pose element.

Both the frame attribute of SDF below 1.7 and the relative_to attribute of later versions are read, and both are only supported when they are empty, which is the default frame of the element the pose belongs to.

Parameters:

element – The pose element to parse.
reference_frame – The frame the pose is expressed in.

Returns:

The pose, or the identity if the element is absent.

Raises:

UnsupportedPoseReference – If the pose refers to a named frame.
MalformedPose – If the pose does not hold 6 values.

static parse_vector(text: str | None) → List[float]#

Parameters:: text – Whitespace separated numbers.
Returns:: The numbers the text holds.

classmethod parse_boolean(element: xml.etree.ElementTree.Element | None) → bool#

Parameters:: element – The element holding the flag.
Returns:: Whether the element is present and set.

static parse_float(element: xml.etree.ElementTree.Element | None, name: str, default: float) → float#

Parameters:

element – The element holding the value as a child.
name – The name of the child element.
default – The value to use when the child is absent.

Returns:

The value of the child element.

static parse_optional_float(element: xml.etree.ElementTree.Element, name: str) → float | None#

Parameters:

element – The element holding the value as a child.
name – The name of the child element.

Returns:

The value of the child element, or None if it is absent.

exception semantic_digital_twin.adapters.gazebo.MissingRootElement#

Bases: semantic_digital_twin.exceptions.ParsingError

Raised when a description file contains none of the expected root elements.

expected_elements: List[str] = []#: The element names that were searched for.

error_message() → str#

Returns:: A human-readable description of what went wrong.

suggest_correction() → str#

Returns:: Advice on how to fix the error, or an empty string if there is no specific advice.

exception semantic_digital_twin.adapters.gazebo.MalformedPose#

Bases: semantic_digital_twin.exceptions.ParsingError

Raised when a pose does not consist of a position and roll-pitch-yaw triple.

text: str#: The pose text that could not be interpreted.

error_message() → str#

Returns:: A human-readable description of what went wrong.

suggest_correction() → str#

Returns:: Advice on how to fix the error, or an empty string if there is no specific advice.

exception semantic_digital_twin.adapters.gazebo.UnsupportedJointType#

Bases: semantic_digital_twin.exceptions.ParsingError

Raised when a parsed joint uses a type that has no connection counterpart.

joint_name: str#: The name of the joint that could not be mapped.

joint_type: str#: The joint type that is not supported.

supported_types: List[str] = []#: The joint types that can be mapped to connections.

error_message() → str#

Returns:: A human-readable description of what went wrong.

suggest_correction() → str#

Returns:: Advice on how to fix the error, or an empty string if there is no specific advice.

exception semantic_digital_twin.adapters.gazebo.UnsupportedGeometryType#

Bases: semantic_digital_twin.exceptions.ParsingError

Raised when a parsed geometry uses a shape that has no counterpart.

geometry_type: str#: The geometry type that is not supported.

supported_types: List[str] = []#: The geometry types that can be mapped to shapes.

error_message() → str#

Returns:: A human-readable description of what went wrong.

suggest_correction() → str#

Returns:: Advice on how to fix the error, or an empty string if there is no specific advice.

exception semantic_digital_twin.adapters.gazebo.UnsupportedPoseReference#

Bases: semantic_digital_twin.exceptions.ParsingError

Raised when a pose is expressed relative to a named frame.

Poses are only supported with their default reference, which is the frame of the element the pose belongs to.

attribute: str#: The attribute carrying the frame reference, frame or relative_to.

reference: str#: The referenced frame.

error_message() → str#

Returns:: A human-readable description of what went wrong.

suggest_correction() → str#

Returns:: Advice on how to fix the error, or an empty string if there is no specific advice.

exception semantic_digital_twin.adapters.gazebo.UnsupportedAxisReference#

Bases: semantic_digital_twin.exceptions.ParsingError

Raised when a joint axis is expressed in a frame other than the joint frame.

joint_name: str#: The name of the joint whose axis could not be interpreted.

reference: str#: The frame the axis is expressed in.

error_message() → str#

Returns:: A human-readable description of what went wrong.

suggest_correction() → str#

Returns:: Advice on how to fix the error, or an empty string if there is no specific advice.