pycram.description ================== .. py:module:: pycram.description Classes ------- .. autoapisummary:: pycram.description.EntityDescription pycram.description.LinkDescription pycram.description.JointDescription pycram.description.ObjectEntity pycram.description.Link pycram.description.RootLink pycram.description.Joint pycram.description.ObjectDescription Module Contents --------------- .. py:class:: EntityDescription(parsed_description: typing_extensions.Optional[typing_extensions.Any] = None) Bases: :py:obj:`abc.ABC` A description of an entity. This can be a link, joint or object description. .. py:attribute:: parsed_description :value: None .. py:property:: origin :type: pycram.datastructures.pose.PoseStamped :abstractmethod: :return: the origin of this entity. .. py:property:: name :type: str :abstractmethod: :return: the name of this entity. .. py:class:: LinkDescription(parsed_link_description: typing_extensions.Any, mesh_dir: typing_extensions.Optional[str] = None) Bases: :py:obj:`EntityDescription` A link description of an object. .. py:attribute:: mesh_dir :value: None .. py:property:: geometry :type: 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. .. py:class:: JointDescription(parsed_joint_description: typing_extensions.Optional[typing_extensions.Any] = None, is_virtual: bool = False) Bases: :py:obj:`EntityDescription` A class that represents the description of a joint. .. py:attribute:: is_virtual :type: typing_extensions.Optional[bool] :value: False .. py:property:: type :type: pycram.datastructures.enums.JointType :abstractmethod: :return: The type of this joint. .. py:property:: axis :type: pycram.datastructures.pose.Point :abstractmethod: :return: The axis of this joint, for example the rotation axis for a revolute joint. .. py:property:: has_limits :type: bool :abstractmethod: :return: True if the joint has limits, False otherwise. .. py:property:: limits :type: typing_extensions.Tuple[float, float] :return: The lower and upper limits of this joint. .. py:property:: lower_limit :type: typing_extensions.Union[float, None] :abstractmethod: :return: The lower limit of this joint, or None if the joint has no limits. .. py:property:: upper_limit :type: typing_extensions.Union[float, None] :abstractmethod: :return: The upper limit of this joint, or None if the joint has no limits. .. py:property:: parent :type: str :abstractmethod: :return: The name of the parent link of this joint. .. py:property:: child :type: str :abstractmethod: :return: The name of the child link of this joint. .. py:property:: damping :type: float :abstractmethod: :return: The damping of this joint. .. py:property:: friction :type: float :abstractmethod: :return: The friction of this joint. .. py:class:: 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. .. py:attribute:: object :type: pycram.world_concepts.world_object.Object .. py:property:: object_name :type: str The name of the object to which this joint belongs. .. py:property:: object_id :type: int :return: the id of the object to which this entity belongs. .. py: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: :py:obj:`pycram.datastructures.world_entity.PhysicalBody`, :py:obj:`ObjectEntity`, :py:obj:`LinkDescription`, :py:obj:`abc.ABC` A link of an Object in the World. .. py:attribute:: description .. py:attribute:: local_transformer :type: pycram.local_transformer.LocalTransformer .. py:attribute:: constraint_ids :type: typing_extensions.Dict[Link, int] .. py:method:: reset() Reset the link to its initial state. .. py:property:: parts :type: typing_extensions.Dict[str, pycram.datastructures.world_entity.PhysicalBody] .. py:property:: parent_entity :type: pycram.world_concepts.world_object.Object :return: The parent of this link, which is the object. .. py:property:: name :type: str :return: The name of this link. .. py:method:: get_axis_aligned_bounding_box(shift_to_link_position: bool = True) -> pycram.datastructures.dataclasses.AxisAlignedBoundingBox :param shift_to_link_position: If True, return the bounding box transformed to the link pose. :return: 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. .. py:method:: get_rotated_bounding_box() -> pycram.datastructures.dataclasses.RotatedBoundingBox :return: 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. .. py:method:: get_axis_aligned_bounding_box_from_geometry() -> pycram.datastructures.dataclasses.AxisAlignedBoundingBox .. py:method:: get_convex_hull() -> trimesh.Trimesh :return: The convex hull of the link geometry. .. py:method:: _plot_convex_hull() Plot the convex hull of the link geometry. .. py:method:: get_mesh_path(geometry: typing_extensions.Optional[typing_extensions.List[pycram.datastructures.dataclasses.MeshVisualShape]] = None) -> typing_extensions.List[str] :param geometry: The geometry/geometries for which the mesh path(s) should be returned. :return: The path(s) of the mesh file(s) of this link if the geometry is a mesh. .. py:method:: get_mesh_filename(geometry: pycram.datastructures.dataclasses.MeshVisualShape) -> str :return: 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. :raises LinkGeometryHasNoMesh: If the geometry is not a mesh. .. py:method:: 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. :param pose: The target pose for this link. .. py:method:: 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). :param pose: The link pose. .. py:method:: 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). :param pose: The object pose. .. py:method:: get_transform_from_root_link() -> pycram.datastructures.pose.TransformStamped Return the transformation from the root link of the object to this link. .. py:method:: get_transform_to_root_link() -> pycram.datastructures.pose.TransformStamped Return the transformation from this link to the root link of the object. .. py:property:: current_state :type: pycram.datastructures.dataclasses.LinkState .. py:method:: 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. :param other: The state of the other link. :return: True if all links belong to the same world, False otherwise. .. py:method:: 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. :param child_link: The child link to which a fixed constraint should be added. :param child_to_parent_transform: The transformation between the two links. :return: The unique id of the constraint. .. py:method:: remove_constraint_with_link(child_link: Link) -> None Remove the constraint between this link and the given link. :param child_link: The child link of the constraint that should be removed. .. py:property:: is_only_link :type: bool :return: True if this link is the only link, False otherwise. .. py:property:: is_root :type: bool :return: True if this link is the root link, False otherwise. .. py:method:: get_transform_to_link(link: Link) -> pycram.datastructures.pose.TransformStamped :param link: The link to which the transformation should be returned. :return: A Transform object with the transformation from this link to the given link. .. py:method:: get_transform_from_link(link: Link) -> pycram.datastructures.pose.TransformStamped :param link: The link from which the transformation should be returned. :return: A Transform object with the transformation from the given link to this link. .. py:method:: get_pose_wrt_link(link: Link) -> pycram.datastructures.pose.PoseStamped :param link: The link with respect to which the pose should be returned. :return: A Pose object with the pose of this link with respect to the given link. .. py:method:: get_origin_transform() -> pycram.datastructures.pose.TransformStamped :return: the transformation between the link frame and the origin frame of this link. .. py:property:: pose :type: pycram.datastructures.pose.PoseStamped :return: The pose of this link. .. py:property:: color :type: pycram.datastructures.dataclasses.Color :return: A Color object containing the rgba_color of this link. .. py:property:: tf_frame :type: str The name of the tf frame of this link. .. py:property:: origin_transform :type: pycram.datastructures.pose.TransformStamped The transformation between the link frame and the origin frame of this link. .. py:method:: __copy__() .. py:class:: RootLink(obj: pycram.world_concepts.world_object.Object) Bases: :py:obj:`Link`, :py:obj:`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. .. py:property:: tf_frame :type: str :return: the tf frame of the root link, which is the same as the tf frame of the object. .. py:property:: pose :type: pycram.datastructures.pose.PoseStamped :return: The pose of the root link, which is the same as the pose of the object. .. py:method:: __copy__() .. py: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: :py:obj:`pycram.datastructures.world_entity.WorldEntity`, :py:obj:`ObjectEntity`, :py:obj:`JointDescription`, :py:obj:`abc.ABC` Represent a joint of an Object in the World. .. py:attribute:: description .. py:attribute:: acceptable_error .. py:method:: _update_ontology_data() Update the ontology data of this joint and its parent and child links. .. py:property:: name :type: str :return: The name of this joint. .. py:property:: parent_entity :type: Link :return: The parent of this joint, which is the object. .. py:property:: tf_frame :type: str The tf frame of a joint is the tf frame of the child link. .. py:property:: pose :type: pycram.datastructures.pose.PoseStamped :return: The pose of this joint. The pose is the pose of the child link of this joint. .. py:method:: _update_position() -> None Update the current position of the joint from the physics simulator. .. py:property:: parent_link :type: Link :return: The parent link as a AbstractLink object. .. py:property:: child_link :type: Link :return: The child link as a AbstractLink object. .. py:property:: position :type: float .. py:method:: reset_position(position: float) -> None .. py:method:: get_object_id() -> int :return: The integer id of the object to which this joint belongs. .. py:method:: enable_force_torque_sensor() -> None .. py:method:: disable_force_torque_sensor() -> None .. py:method:: get_reaction_force_torque() -> typing_extensions.List[float] .. py:method:: get_applied_motor_torque() -> float .. py:property:: current_state :type: pycram.datastructures.dataclasses.JointState .. py:method:: __copy__() .. py:class:: ObjectDescription(path: typing_extensions.Optional[str] = None) Bases: :py:obj:`EntityDescription` A class that represents the description of an object. .. py:attribute:: mesh_extensions :type: typing_extensions.Tuple[str] :value: ('.obj', '.stl', '.dae', '.ply') The file extensions of the mesh files that can be used to generate a description file. .. py: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: :py:obj:`Link`, :py:obj:`abc.ABC` A link of an Object in the World. .. py:class:: RootLink(obj: pycram.world_concepts.world_object.Object) Bases: :py:obj:`RootLink`, :py:obj:`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. .. py: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: :py:obj:`Joint`, :py:obj:`abc.ABC` Represent a joint of an Object in the World. .. py:attribute:: _links :type: typing_extensions.Optional[typing_extensions.List[LinkDescription]] :value: None .. py:attribute:: _joints :type: typing_extensions.Optional[typing_extensions.List[JointDescription]] :value: None .. py:attribute:: _link_map :type: typing_extensions.Optional[typing_extensions.Dict[str, typing_extensions.Any]] :value: None .. py:attribute:: _joint_map :type: typing_extensions.Optional[typing_extensions.Dict[str, typing_extensions.Any]] :value: None .. py:attribute:: original_path :type: typing_extensions.Optional[str] :value: None .. py:attribute:: virtual_joint_names :type: typing_extensions.List[str] :value: [] .. py:property:: child_map :type: typing_extensions.Dict[str, typing_extensions.List[typing_extensions.Tuple[str, str]]] :abstractmethod: :return: 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. .. py:property:: parent_map :type: typing_extensions.Dict[str, typing_extensions.Tuple[str, str]] :abstractmethod: :return: A dictionary mapping the name of a link to its parent joint and link as a tuple. .. py:property:: link_map :type: typing_extensions.Dict[str, LinkDescription] :abstractmethod: :return: A dictionary mapping the name of a link to its description. .. py:property:: joint_map :type: typing_extensions.Dict[str, JointDescription] :abstractmethod: :return: A dictionary mapping the name of a joint to its description. .. py:method:: is_joint_virtual(name: str) -> bool :param name: The name of the joint. :return: True if the joint is virtual, False otherwise. .. py:method:: 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 :abstractmethod: Add a joint to this object. :param name: The name of the joint. :param child: The name of the child link. :param joint_type: The type of the joint. :param axis: The axis of the joint. :param parent: The name of the parent link. :param origin: The origin of the joint. :param lower_limit: The lower limit of the joint. :param upper_limit: The upper limit of the joint. :param is_virtual: True if the joint is virtual, False otherwise. .. py:method:: 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] :abstractmethod: Merge the description of this object with the description of the other object. :param other: The object description to merge with this one. :param parent_link: The name of the parent link of the joint connecting the two objects. :param child_link: The name of the child link of the joint connecting the two objects. :param joint_type: The type of the joint connecting the two objects. :param axis: The axis of the joint connecting the two objects. :param lower_limit: The lower limit of the joint connecting the two objects. :param upper_limit: The upper limit of the joint connecting the two objects. :param child_pose_wrt_parent: The pose of the child link with respect to the parent link. :param in_place: True if the merge should be done in place, False otherwise. :param 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. :return: The merged object description, could be a new object description if in_place is False else self. .. py:method:: update_description_from_file(path: str) -> None Update the description of this object from the file at the given path. :param path: The path of the file to update from. .. py:method:: update_description_from_string(description_string: str) -> None Update the description of this object from the given description string. :param description_string: The description string to update from. .. py:method:: load_description_from_string(description_string: str) -> typing_extensions.Any :abstractmethod: Load the description from the given string. :param description_string: The description string to load from. .. py:property:: parsed_description :type: typing_extensions.Any :return: The object parsed from the description file. .. py:method:: load_description(path: str) -> typing_extensions.Any :abstractmethod: Load the description from the file at the given path. :param path: The path to the source file, if only a filename is provided then the resources directories will be searched. .. py:method:: 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. :param path: The path of the file to preprocess. :param name: The name of the object. :param extension: The file extension of the file to preprocess. :param save_path: The path to save the generated description file. :param scale_mesh: The scale of the mesh. :param mesh_transform: The transformation matrix to apply to the mesh. :param color: The color of the object. :raises ObjectDescriptionNotFound: If the description file could not be found/read. .. py:method:: check_description_file_exists_and_can_be_read(path: str) -> bool :staticmethod: Check if the description file exists at the given path. :param path: The path to the description file. :return: True if the file exists, False otherwise. .. py:method:: write_description_to_file(description_string: str, save_path: str) -> None :staticmethod: Write the description string to the file at the given path. :param description_string: The description string to write. :param save_path: The path of the file to write to. .. py:method:: get_file_name(path_object: pathlib.Path, extension: str, object_name: str) -> str :param path_object: The path object of the description file or the mesh file. :param extension: The file extension of the description file or the mesh file. :param object_name: The name of the object. :return: The file name of the description file. .. py:method:: generate_from_mesh_file(path: str, name: str, save_path: str, color: pycram.datastructures.dataclasses.Color) -> None :classmethod: :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. :param path: The path to the .obj file. :param name: The name of the object. :param save_path: The path to save the generated description file. :param color: The color of the object. .. py:method:: generate_from_description_file(path: str, save_path: str, make_mesh_paths_absolute: bool = True) -> None :classmethod: :abstractmethod: Preprocess the given file and return the preprocessed description string. The preprocessed description will be saved at the given save_path. :param path: The path of the file to preprocess. :param save_path: The path to save the preprocessed description file. :param make_mesh_paths_absolute: Whether to make the mesh paths absolute. .. py:method:: generate_from_parameter_server(name: str, save_path: str) -> None :classmethod: :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. :param name: The name of the description on the parameter server. :param save_path: The path to save the preprocessed description file. .. py:property:: links :type: typing_extensions.List[LinkDescription] :abstractmethod: :return: A list of links descriptions of this object. .. py:method:: get_link_by_name(link_name: str) -> LinkDescription :return: The link description with the given name. .. py:property:: joints :type: typing_extensions.List[JointDescription] :abstractmethod: :return: A list of joints descriptions of this object. .. py:method:: get_joint_by_name(joint_name: str) -> JointDescription :return: The joint description with the given name. .. py:method:: get_root() -> str :abstractmethod: :return: the name of the root link of this object. .. py:method:: get_tip() -> str :abstractmethod: :return: the name of the tip link of this object. .. py:method:: 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] :abstractmethod: :return: the chain of links from 'start_link_name' to 'end_link_name'. .. py:method:: get_file_extension() -> str :staticmethod: :abstractmethod: :return: The file extension of the description file.