pycram.description

pycram.description#

Classes#

`EntityDescription`	A description of an entity. This can be a link, joint or object description.
`LinkDescription`	A link description of an object.
`JointDescription`	A class that represents the description of a joint.
`ObjectEntity`	An abstract base class that represents a part of an Object.
`Link`	A link of an Object in the World.
`RootLink`	The root link of an Object in the World.
`Joint`	Represent a joint of an Object in the World.
`ObjectDescription`	A class that represents the description of an object.

Module Contents#

class pycram.description.EntityDescription(parsed_description: typing_extensions.Optional[typing_extensions.Any] = None)#

Bases: abc.ABC

A description of an entity. This can be a link, joint or object description.

parsed_description = None#

property origin: pycram.datastructures.pose.PoseStamped#

Abstractmethod:
Returns:: the origin of this entity.

property name: str#

Abstractmethod:
Returns:: the name of this entity.

class pycram.description.LinkDescription(parsed_link_description: typing_extensions.Any, mesh_dir: typing_extensions.Optional[str] = None)#

Bases: EntityDescription

A link description of an object.

mesh_dir = None#

property geometry: typing_extensions.Union[typing_extensions.List[pycram.datastructures.dataclasses.VisualShape], pycram.datastructures.dataclasses.VisualShape, None]#

Abstractmethod:

The geometry type of the collision element of this link.

class pycram.description.JointDescription(parsed_joint_description: typing_extensions.Optional[typing_extensions.Any] = None, is_virtual: bool = False)#

Bases: EntityDescription

A class that represents the description of a joint.

is_virtual: typing_extensions.Optional[bool] = False#

property type: pycram.datastructures.enums.JointType#

Abstractmethod:
Returns:: The type of this joint.

property axis: pycram.datastructures.pose.Point#

Abstractmethod:
Returns:: The axis of this joint, for example the rotation axis for a revolute joint.

property has_limits: bool#

Abstractmethod:
Returns:: True if the joint has limits, False otherwise.

property limits: typing_extensions.Tuple[float, float]#

Returns:: The lower and upper limits of this joint.

property lower_limit: typing_extensions.Union[float, None]#

Abstractmethod:
Returns:: The lower limit of this joint, or None if the joint has no limits.

property upper_limit: typing_extensions.Union[float, None]#

Abstractmethod:
Returns:: The upper limit of this joint, or None if the joint has no limits.

property parent: str#

Abstractmethod:
Returns:: The name of the parent link of this joint.

property child: str#

Abstractmethod:
Returns:: The name of the child link of this joint.

property damping: float#

Abstractmethod:
Returns:: The damping of this joint.

property friction: float#

Abstractmethod:
Returns:: The friction of this joint.

class pycram.description.ObjectEntity(obj: pycram.world_concepts.world_object.Object)#

An abstract base class that represents a part of an Object. This can be a link or a joint of an Object.

object: pycram.world_concepts.world_object.Object#

property object_name: str#: The name of the object to which this joint belongs.

property object_id: int#

Returns:: the id of the object to which this entity belongs.

class pycram.description.Link(_id: int, link_description: LinkDescription, obj: pycram.world_concepts.world_object.Object, concept: typing_extensions.Type[pycrap.ontologies.Base] = pycrap.ontologies.Link, parse_name: bool = True)#

Bases: pycram.datastructures.world_entity.PhysicalBody, ObjectEntity, LinkDescription, abc.ABC

A link of an Object in the World.

description#

local_transformer: pycram.local_transformer.LocalTransformer#

constraint_ids: typing_extensions.Dict[Link, int]#

reset()#: Reset the link to its initial state.

property parts: typing_extensions.Dict[str, pycram.datastructures.world_entity.PhysicalBody]#

property parent_entity: pycram.world_concepts.world_object.Object#

Returns:: The parent of this link, which is the object.

property name: str#

Returns:: The name of this link.

get_axis_aligned_bounding_box(shift_to_link_position: bool = True) → pycram.datastructures.dataclasses.AxisAlignedBoundingBox#

Parameters:: shift_to_link_position – If True, return the bounding box transformed to the link pose.
Returns:: The axis-aligned bounding box of a link. First try to get it from the simulator, if not, then calculate it depending on the type of the link geometry.

get_rotated_bounding_box() → pycram.datastructures.dataclasses.RotatedBoundingBox#

Returns:: The rotated bounding box of a link. First try to get it from the simulator, if not, then calculate it depending on the type of the link geometry.

get_axis_aligned_bounding_box_from_geometry() → pycram.datastructures.dataclasses.AxisAlignedBoundingBox#

get_convex_hull() → trimesh.Trimesh#

Returns:: The convex hull of the link geometry.

_plot_convex_hull()#: Plot the convex hull of the link geometry.

get_mesh_path(geometry: typing_extensions.Optional[typing_extensions.List[pycram.datastructures.dataclasses.MeshVisualShape]] = None) → typing_extensions.List[str]#

Parameters:: geometry – The geometry/geometries for which the mesh path(s) should be returned.
Returns:: The path(s) of the mesh file(s) of this link if the geometry is a mesh.

get_mesh_filename(geometry: pycram.datastructures.dataclasses.MeshVisualShape) → str#

Returns:

The mesh file name of this link if the geometry is a mesh, otherwise raise a LinkGeometryHasNoMesh.

Raises:

LinkHasNoGeometry – If the link has no geometry.
LinkGeometryHasNoMesh – If the geometry is not a mesh.

set_object_pose_given_link_pose(pose: pycram.datastructures.pose.PoseStamped) → None#

Set the pose of this link to the given pose. NOTE: This will move the entire object such that the link is at the given pose, it will not consider any joints that can allow the link to be at the given pose.

Parameters:: pose – The target pose for this link.

get_object_pose_given_link_pose(pose)#

Get the object pose given the link pose, which could be a hypothetical link pose to see what would be the object pose in that case (assuming that the object itself moved not the joints).

Parameters:: pose – The link pose.

get_pose_given_object_pose(pose)#

Get the link pose given the object pose, which could be a hypothetical object pose to see what would be the link pose in that case (assuming that the object itself moved not the joints).

Parameters:: pose – The object pose.

get_transform_from_root_link() → pycram.datastructures.pose.TransformStamped#: Return the transformation from the root link of the object to this link.

get_transform_to_root_link() → pycram.datastructures.pose.TransformStamped#: Return the transformation from this link to the root link of the object.

property current_state: pycram.datastructures.dataclasses.LinkState#

all_constraint_links_belong_to_same_world(other: pycram.datastructures.dataclasses.LinkState) → bool#

Check if all links belong to the same world as the links in the other link state.

Parameters:: other – The state of the other link.
Returns:: True if all links belong to the same world, False otherwise.

add_fixed_constraint_with_link(child_link: Link, child_to_parent_transform: typing_extensions.Optional[pycram.datastructures.pose.TransformStamped] = None) → int#

Add a fixed constraint between this link and the given link, to create attachments for example.

Parameters:

child_link – The child link to which a fixed constraint should be added.
child_to_parent_transform – The transformation between the two links.

Returns:

The unique id of the constraint.

remove_constraint_with_link(child_link: Link) → None#

Remove the constraint between this link and the given link.

Parameters:: child_link – The child link of the constraint that should be removed.

property is_only_link: bool#

Returns:: True if this link is the only link, False otherwise.

property is_root: bool#

Returns:: True if this link is the root link, False otherwise.

get_transform_to_link(link: Link) → pycram.datastructures.pose.TransformStamped#

Parameters:: link – The link to which the transformation should be returned.
Returns:: A Transform object with the transformation from this link to the given link.

get_transform_from_link(link: Link) → pycram.datastructures.pose.TransformStamped#

Parameters:: link – The link from which the transformation should be returned.
Returns:: A Transform object with the transformation from the given link to this link.

get_pose_wrt_link(link: Link) → pycram.datastructures.pose.PoseStamped#

Parameters:: link – The link with respect to which the pose should be returned.
Returns:: A Pose object with the pose of this link with respect to the given link.

get_origin_transform() → pycram.datastructures.pose.TransformStamped#

Returns:: the transformation between the link frame and the origin frame of this link.

property pose: pycram.datastructures.pose.PoseStamped#

Returns:: The pose of this link.

property color: pycram.datastructures.dataclasses.Color#

Returns:: A Color object containing the rgba_color of this link.

property tf_frame: str#: The name of the tf frame of this link.

property origin_transform: pycram.datastructures.pose.TransformStamped#: The transformation between the link frame and the origin frame of this link.

__copy__()#

class pycram.description.RootLink(obj: pycram.world_concepts.world_object.Object)#

Bases: Link, abc.ABC

The root link of an Object in the World. This differs from the normal AbstractLink class in that the pose and the tf_frame is the same as that of the object.

property tf_frame: str#

Returns:: the tf frame of the root link, which is the same as the tf frame of the object.

property pose: pycram.datastructures.pose.PoseStamped#

Returns:: The pose of the root link, which is the same as the pose of the object.

__copy__()#

class pycram.description.Joint(_id: int, joint_description: JointDescription, obj: pycram.world_concepts.world_object.Object, is_virtual: typing_extensions.Optional[bool] = False, concept: typing_extensions.Type[pycrap.ontologies.Base] = pycrap.ontologies.Joint)#

Bases: pycram.datastructures.world_entity.WorldEntity, ObjectEntity, JointDescription, abc.ABC

Represent a joint of an Object in the World.

description#

acceptable_error#

_update_ontology_data()#: Update the ontology data of this joint and its parent and child links.

property name: str#

Returns:: The name of this joint.

property parent_entity: Link#

Returns:: The parent of this joint, which is the object.

property tf_frame: str#: The tf frame of a joint is the tf frame of the child link.

property pose: pycram.datastructures.pose.PoseStamped#

Returns:: The pose of this joint. The pose is the pose of the child link of this joint.

_update_position() → None#: Update the current position of the joint from the physics simulator.

property parent_link: Link#

Returns:: The parent link as a AbstractLink object.

property child_link: Link#

Returns:: The child link as a AbstractLink object.

property position: float#

reset_position(position: float) → None#

get_object_id() → int#

Returns:: The integer id of the object to which this joint belongs.

enable_force_torque_sensor() → None#

disable_force_torque_sensor() → None#

get_reaction_force_torque() → typing_extensions.List[float]#

get_applied_motor_torque() → float#

property current_state: pycram.datastructures.dataclasses.JointState#

__copy__()#

class pycram.description.ObjectDescription(path: typing_extensions.Optional[str] = None)#

Bases: EntityDescription

A class that represents the description of an object.

mesh_extensions: typing_extensions.Tuple[str] = ('.obj', '.stl', '.dae', '.ply')#: The file extensions of the mesh files that can be used to generate a description file.

class Link(_id: int, link_description: LinkDescription, obj: pycram.world_concepts.world_object.Object, concept: typing_extensions.Type[pycrap.ontologies.Base] = pycrap.ontologies.Link, parse_name: bool = True)#

Bases: Link, abc.ABC

A link of an Object in the World.

class RootLink(obj: pycram.world_concepts.world_object.Object)#

Bases: RootLink, abc.ABC

The root link of an Object in the World. This differs from the normal AbstractLink class in that the pose and the tf_frame is the same as that of the object.

class Joint(_id: int, joint_description: JointDescription, obj: pycram.world_concepts.world_object.Object, is_virtual: typing_extensions.Optional[bool] = False, concept: typing_extensions.Type[pycrap.ontologies.Base] = pycrap.ontologies.Joint)#

Bases: Joint, abc.ABC

Represent a joint of an Object in the World.

_links: typing_extensions.Optional[typing_extensions.List[LinkDescription]] = None#

_joints: typing_extensions.Optional[typing_extensions.List[JointDescription]] = None#

_link_map: typing_extensions.Optional[typing_extensions.Dict[str, typing_extensions.Any]] = None#

_joint_map: typing_extensions.Optional[typing_extensions.Dict[str, typing_extensions.Any]] = None#

original_path: typing_extensions.Optional[str] = None#

virtual_joint_names: typing_extensions.List[str] = []#

property child_map: typing_extensions.Dict[str, typing_extensions.List[typing_extensions.Tuple[str, str]]]#

Abstractmethod:
Returns:: A dictionary mapping the name of a link to its children which are represented as a tuple of the child joint name and the link name.

property parent_map: typing_extensions.Dict[str, typing_extensions.Tuple[str, str]]#

Abstractmethod:
Returns:: A dictionary mapping the name of a link to its parent joint and link as a tuple.

property link_map: typing_extensions.Dict[str, LinkDescription]#

Abstractmethod:
Returns:: A dictionary mapping the name of a link to its description.

property joint_map: typing_extensions.Dict[str, JointDescription]#

Abstractmethod:
Returns:: A dictionary mapping the name of a joint to its description.

is_joint_virtual(name: str) → bool#

Parameters:: name – The name of the joint.
Returns:: True if the joint is virtual, False otherwise.

abstract add_joint(name: str, child: str, joint_type: pycram.datastructures.enums.JointType, axis: pycram.datastructures.pose.Point, parent: typing_extensions.Optional[str] = None, origin: typing_extensions.Optional[pycram.datastructures.pose.PoseStamped] = None, lower_limit: typing_extensions.Optional[float] = None, upper_limit: typing_extensions.Optional[float] = None, is_virtual: typing_extensions.Optional[bool] = False) → None#

Add a joint to this object.

Parameters:

name – The name of the joint.
child – The name of the child link.
joint_type – The type of the joint.
axis – The axis of the joint.
parent – The name of the parent link.
origin – The origin of the joint.
lower_limit – The lower limit of the joint.
upper_limit – The upper limit of the joint.
is_virtual – True if the joint is virtual, False otherwise.

abstract merge_description(other: ObjectDescription, parent_link: typing_extensions.Optional[str] = None, child_link: typing_extensions.Optional[str] = None, joint_type: pycram.datastructures.enums.JointType = JointType.FIXED, axis: typing_extensions.Optional[pycram.datastructures.pose.Point] = None, lower_limit: typing_extensions.Optional[float] = None, upper_limit: typing_extensions.Optional[float] = None, child_pose_wrt_parent: typing_extensions.Optional[pycram.datastructures.pose.PoseStamped] = None, in_place: bool = False, new_description_file: typing_extensions.Optional[str] = None) → typing_extensions.Union[ObjectDescription, typing_extensions.Self]#

Merge the description of this object with the description of the other object.

Parameters:

other – The object description to merge with this one.
parent_link – The name of the parent link of the joint connecting the two objects.
child_link – The name of the child link of the joint connecting the two objects.
joint_type – The type of the joint connecting the two objects.
axis – The axis of the joint connecting the two objects.
lower_limit – The lower limit of the joint connecting the two objects.
upper_limit – The upper limit of the joint connecting the two objects.
child_pose_wrt_parent – The pose of the child link with respect to the parent link.
in_place – True if the merge should be done in place, False otherwise.
new_description_file – If given, the new description will be saved to this file, otherwise the new description will be saved in place of the original file.

Returns:

The merged object description, could be a new object description if in_place is False else self.

update_description_from_file(path: str) → None#

Update the description of this object from the file at the given path.

Parameters:: path – The path of the file to update from.

update_description_from_string(description_string: str) → None#

Update the description of this object from the given description string.

Parameters:: description_string – The description string to update from.

abstract load_description_from_string(description_string: str) → typing_extensions.Any#

Load the description from the given string.

Parameters:: description_string – The description string to load from.

property parsed_description: typing_extensions.Any#

Returns:: The object parsed from the description file.

abstract load_description(path: str) → typing_extensions.Any#

Load the description from the file at the given path.

Parameters:: path – The path to the source file, if only a filename is provided then the resources directories will be searched.

generate_description_from_file(path: str, name: str, extension: str, save_path: str, scale_mesh: typing_extensions.Optional[float] = None, mesh_transform: typing_extensions.Optional[pycram.datastructures.pose.TransformStamped] = None, color: typing_extensions.Optional[pycram.datastructures.dataclasses.Color] = None) → None#

Generate and preprocess the description from the file at the given path and save the preprocessed description. The generated description will be saved at the given save path.

Parameters:

path – The path of the file to preprocess.
name – The name of the object.
extension – The file extension of the file to preprocess.
save_path – The path to save the generated description file.
scale_mesh – The scale of the mesh.
mesh_transform – The transformation matrix to apply to the mesh.
color – The color of the object.

Raises:

ObjectDescriptionNotFound – If the description file could not be found/read.

static check_description_file_exists_and_can_be_read(path: str) → bool#

Check if the description file exists at the given path.

Parameters:: path – The path to the description file.
Returns:: True if the file exists, False otherwise.

static write_description_to_file(description_string: str, save_path: str) → None#

Write the description string to the file at the given path.

Parameters:

description_string – The description string to write.
save_path – The path of the file to write to.

get_file_name(path_object: pathlib.Path, extension: str, object_name: str) → str#

Parameters:

path_object – The path object of the description file or the mesh file.
extension – The file extension of the description file or the mesh file.
object_name – The name of the object.

Returns:

The file name of the description file.

classmethod generate_from_mesh_file(path: str, name: str, save_path: str, color: pycram.datastructures.dataclasses.Color) → None#

Abstractmethod:

Generate a description file from one of the mesh types defined in the mesh_extensions and return the path of the generated file. The generated file will be saved at the given save_path.

Parameters:

path – The path to the .obj file.
name – The name of the object.
save_path – The path to save the generated description file.
color – The color of the object.

classmethod generate_from_description_file(path: str, save_path: str, make_mesh_paths_absolute: bool = True) → None#

Abstractmethod:

Preprocess the given file and return the preprocessed description string. The preprocessed description will be saved at the given save_path.

Parameters:

path – The path of the file to preprocess.
save_path – The path to save the preprocessed description file.
make_mesh_paths_absolute – Whether to make the mesh paths absolute.

classmethod generate_from_parameter_server(name: str, save_path: str) → None#

Abstractmethod:

Preprocess the description from the ROS parameter server and return the preprocessed description string. The preprocessed description will be saved at the given save_path.

Parameters:

name – The name of the description on the parameter server.
save_path – The path to save the preprocessed description file.

property links: typing_extensions.List[LinkDescription]#

Abstractmethod:
Returns:: A list of links descriptions of this object.

get_link_by_name(link_name: str) → LinkDescription#

Returns:: The link description with the given name.

property joints: typing_extensions.List[JointDescription]#

Abstractmethod:
Returns:: A list of joints descriptions of this object.

get_joint_by_name(joint_name: str) → JointDescription#

Returns:: The joint description with the given name.

abstract get_root() → str#

Returns:: the name of the root link of this object.

abstract get_tip() → str#

Returns:: the name of the tip link of this object.

abstract get_chain(start_link_name: str, end_link_name: str, joints: typing_extensions.Optional[bool] = True, links: typing_extensions.Optional[bool] = True, fixed: typing_extensions.Optional[bool] = True) → typing_extensions.List[str]#

Returns:: the chain of links from ‘start_link_name’ to ‘end_link_name’.

static get_file_extension() → str#

Abstractmethod:
Returns:: The file extension of the description file.