timor.Bodies ============ .. py:module:: timor.Bodies Classes ------- .. autoapisummary:: timor.Bodies.Body timor.Bodies.BodyBase timor.Bodies.BodySet timor.Bodies.Connector timor.Bodies.ConnectorSet timor.Bodies.Gender timor.Bodies.PinBody Module Contents --------------- .. py:class:: Body(body_id, collision, visual = None, connectors = (), inertia = pin.Inertia(0, np.zeros(3), np.zeros((3, 3))), in_module = None) .. autoapi-inheritance-diagram:: timor.Bodies.Body :parts: 1 :private-bases: The default body class, represents a static/immutable rigid body. Construct a Body. :param body_id: The unique ID of the body :param collision: The collision geometry of the body :param visual: The visual geometry of the body. If None is given, defaults to collision :param connectors: The connectors of the body, defining possible interfaces to other bodies :param inertia: The inertia of the body, as pin.Inertia :param in_module: The module this body is part of. Will be automatically assigned if the body is defined and added to a module later on. .. py:method:: __copy__() Custom copy to allow differing connector parent references .. py:method:: __eq__(other) Equality check. The visual attribute is not checked as it does not provide relevant functionality. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashing: We assume IDs are unique, so it poses a valid hash. .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: __str__() The string representation of a body .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:attribute:: _id :type: str :value: '' .. py:attribute:: _visual :type: timor.Geometry.Geometry :value: None .. py:method:: as_pin_body(placement = Transformation.neutral()) Extracts the body properties that describe a body in a pinocchio robot. Always places the body in the origin. :param placement: Relative placement of the body to its parent joint .. py:attribute:: collision :type: timor.Geometry.Geometry .. py:attribute:: connectors :type: ConnectorSet .. py:method:: from_json_data(d, package_dir = None, *args, **kwargs) :classmethod: Maps the json-serialized body description to an instance of this class. The dictionary will be modified in-place until empty (everything was parsed). :param d: A dictionary with relevant meta-information :param package_dir: If a mesh is given, it is given relative to a package directory that must be specified :return: An instantiated body .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, package_dir = None) :classmethod: Maps the json-serialized body description to an instance of this class. :param s: A json string with relevant meta-information :param package_dir: If a mesh is given, it is given relative to a package directory that must be specified :return: An instantiated body .. py:property:: id :type: Tuple[Union[None, str], str] Composed ID: (module ID, body ID) .. py:attribute:: in_module :type: ModuleBase :value: None .. py:attribute:: inertia :type: pinocchio.Inertia .. py:property:: mass :type: float The mass of the body in [kg] .. py:method:: possible_connections_with(other) Returns a set of connectors that can connect this with other body. This method does not check whether the connector IDs of the other body overlap with the connector IDs of this body - this has to be achieved by e.g. putting both bodies in a module or in the same ModulesDB. :param other: Another body :return: A list of matching connector pairs like (this_body_connector, other_body_connector) .. py:method:: to_json_data() :return: Returns the body specification in a json-ready dictionary .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:property:: visual :type: timor.Geometry.Geometry Defaults to collision if not explicitly specified .. py:class:: BodyBase .. autoapi-inheritance-diagram:: timor.Bodies.BodyBase :parts: 1 :private-bases: A body describes a rigid robot element with kinematic, dynamic, geometric, and connection properties. A body is defined by a geometry and inertia-parameters. Its placement is defined implicitly by the connectors attached to it. .. py:method:: __copy__() :abstractmethod: Returns a copy of the body .. py:method:: __eq__(other) Equality check. The visual attribute is not checked as it does not provide relevant functionality. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashing: We assume IDs are unique, so it poses a valid hash. .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: __str__() The string representation of a body .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:attribute:: _id :type: str .. py:attribute:: _visual :type: Optional[timor.Geometry.Geometry] :value: None .. py:method:: as_pin_body(placement = Transformation.neutral()) Extracts the body properties that describe a body in a pinocchio robot. Always places the body in the origin. :param placement: Relative placement of the body to its parent joint .. py:attribute:: collision :type: timor.Geometry.Geometry .. py:attribute:: connectors :type: ConnectorSet .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Create from a json description. .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:property:: id :type: Tuple[Union[None, str], str] Composed ID: (module ID, body ID) .. py:attribute:: in_module :type: ModuleBase .. py:attribute:: inertia :type: pinocchio.Inertia .. py:property:: mass :type: float The mass of the body in [kg] .. py:method:: possible_connections_with(other) Returns a set of connectors that can connect this with other body. This method does not check whether the connector IDs of the other body overlap with the connector IDs of this body - this has to be achieved by e.g. putting both bodies in a module or in the same ModulesDB. :param other: Another body :return: A list of matching connector pairs like (this_body_connector, other_body_connector) .. py:method:: to_json_data() :return: Returns the body specification in a json-ready dictionary .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:property:: visual :type: timor.Geometry.Geometry Defaults to collision if not explicitly specified .. py:class:: BodySet(*elements) .. autoapi-inheritance-diagram:: timor.Bodies.BodySet :parts: 1 :private-bases: A set that raises an error if a duplicate body is added Custom init function. Might be slow, but provides safety that every element in the input argument is checked using the tested update and add methods. For sophisticated element checking, consider overriding the __contains__ method in sub-classes. .. py:method:: __contains__(item) Custom duplicate check (unique ID) .. py:method:: __eq__(other) If there is a unique ordering to this set, try to sort the elements and compare them .. py:method:: __hash__() Hash all the contained elements .. py:method:: __ne__(other) Override the not equal operatorof a set .. py:attribute:: _err :value: 'Element {} already present!' .. py:method:: _sorting_key(element) :classmethod: Key function for sorting elements in this set .. py:method:: add(element) Custom add to set needed s.t. uniqueness is ensured .. py:method:: copy() Custom copy should also return a SingleSet .. py:method:: filter(func) Convenience function to avoid set comparison over and over again :param func: A filter function that takes an element of this set and evaluates to true if the element should be kept :return: A new set of elements fulfilling the filter criterion .. py:method:: intersection(*s) Intersection should also retutrn a SingleSet .. py:method:: union(*s) Returns a SingleSet of the union of this and the input .. py:method:: update(*s) Update method that does not change this instance if the input iterable contains duplicates .. py:class:: Connector(connector_id, body2connector = Transformation.neutral(), parent = None, gender = Gender.hermaphroditic, connector_type = '', size = tuple()) .. autoapi-inheritance-diagram:: timor.Bodies.Connector :parts: 1 :private-bases: A connector is the interface defining where a body can be attached to another body. In order to connect two bodies, they must have a matching pair of connectors. The connector coordinate system is always "pointing away from the body it is attached to". Construct a Connector. :param connector_id: Unique "own" ID of the connector :param body2connector: The transformation from the body cos to connector coordinates :param parent: The body this connector is attached to. Will be set automatically when the connector is defined before the body and added later on. Every instance can have at most one parent. :param gender: Connector gender. Male and Female connect, Hermaphroditic and Hermaphroditic connect. :param connector_type: Can be a custom string to define the type of the connector. :param size: Can be an integer, float or array describing the size of the connector. .. py:method:: __copy__() Custom copy behavior: Remove the reference to the parent body. .. py:method:: __eq__(other) Equality check: Same ID, gender, type, size, and pose .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashing: We assume IDs are unique, so it poses a valid hash. .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:method:: __str__() The string representation of the connector .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:attribute:: _id :type: str :value: '' .. py:attribute:: _type :type: str :value: '' .. py:attribute:: body2connector :type: timor.utilities.transformation.Transformation .. py:property:: connector2body :type: timor.utilities.transformation.Transformation The inverse transformation from connector to body coordinates .. py:method:: connects(other) Checks if this connector can be connected with "other". :param other: Another connector :return: True if connection is possible. False else. .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Maps the serialized connector description to an instance of this class. :param d: A dictionary with relevant meta-information :return: An instantiated connector .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:attribute:: gender :type: Gender .. py:property:: id :type: Tuple[Union[None, str], Union[None, str], str] Composed ID: (module ID, body ID, connector ID) .. py:property:: own_id :type: str The last part of the id - uniquely identifying a connector within its module .. py:attribute:: parent :type: BodyBase :value: None .. py:attribute:: size :type: Union[int, float, numpy.ndarray] :value: () .. py:method:: to_json_data() :return: Returns the connector specification in a json-ready dictionary .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:property:: type :type: str Wrapped as _type attribute to not be confused with python-native type(). Also, is kind of static anyway .. py:class:: ConnectorSet(*elements) .. autoapi-inheritance-diagram:: timor.Bodies.ConnectorSet :parts: 1 :private-bases: A set that raises an error if a duplicate connector is added. Custom init function. Might be slow, but provides safety that every element in the input argument is checked using the tested update and add methods. For sophisticated element checking, consider overriding the __contains__ method in sub-classes. .. py:method:: __contains__(item) Custom duplicate check (unique ID) .. py:method:: __eq__(other) If there is a unique ordering to this set, try to sort the elements and compare them .. py:method:: __hash__() Hash all the contained elements .. py:method:: __ne__(other) Override the not equal operatorof a set .. py:attribute:: _err :value: 'Element {} already present!' .. py:method:: _sorting_key(element) :classmethod: Key function for sorting elements in this set .. py:method:: add(element) Custom add to set needed s.t. uniqueness is ensured .. py:method:: copy() Custom copy should also return a SingleSet .. py:method:: filter(func) Convenience function to avoid set comparison over and over again :param func: A filter function that takes an element of this set and evaluates to true if the element should be kept :return: A new set of elements fulfilling the filter criterion .. py:method:: intersection(*s) Intersection should also retutrn a SingleSet .. py:method:: union(*s) Returns a SingleSet of the union of this and the input .. py:method:: update(*s) Update method that does not change this instance if the input iterable contains duplicates .. py:class:: Gender(*args, **kwds) .. autoapi-inheritance-diagram:: timor.Bodies.Gender :parts: 1 :private-bases: Enumerates possible connector genders .. py:method:: __str__() Ensures defined string casting behavior when storing a connector of a certain gender as json .. py:method:: connects(other) Indicates whether two genders form a connection. (sorry, code is homoamoric-agnostic) Possible connections: h <-> h f <-> m :param other: Another gender :return: True if connection works .. py:attribute:: f :value: 0 .. py:attribute:: female :value: 0 .. py:attribute:: h :value: 2 .. py:attribute:: hermaphroditic :value: 2 .. py:attribute:: m :value: 1 .. py:attribute:: male :value: 1 .. py:class:: PinBody(inertia, placement, name, collision_geometries = None, visual_geometries = None) A wrapper for a body in pinocchio, which is usually represented only implicitly Set up a container for a pinocchio body. :param inertia: the inertia of the body, as a pinocchio inertia object :param placement: the placement of the body, as a pinocchio SE3 object :param name: the name of the body, should be unique within the robot :param collision_geometries: the collision geometries of the body :param visual_geometries: the visual geometries of the body .. py:method:: body_data(parent_joint_id) Returns a dictionary that can be used as kwargs for appendBodyToJoint (pinocchio) .. py:method:: body_frame_data(parent_joint_id, parent_frame_id) Returns a dictionary that can be used as kwargs for addBodyFrame (pinocchio) .. py:attribute:: collision_geometries :type: List[pinocchio.GeometryObject] :value: [] .. py:attribute:: inertia :type: pinocchio.Inertia .. py:attribute:: name :type: str .. py:attribute:: placement :type: pinocchio.SE3 .. py:attribute:: visual_geometries :type: List[pinocchio.GeometryObject] :value: []