timor.utilities.frames ====================== .. py:module:: timor.utilities.frames Attributes ---------- .. autoapisummary:: timor.utilities.frames.FRAME_ID_TYPE timor.utilities.frames.NOMINAL_FRAME timor.utilities.frames.SPECIAL_FRAMES timor.utilities.frames.WORLD_FRAME Classes ------- .. autoapisummary:: timor.utilities.frames.Frame timor.utilities.frames.FrameTree timor.utilities.frames.NominalFrameType timor.utilities.frames.WorldFrameType Module Contents --------------- .. py:data:: FRAME_ID_TYPE .. py:class:: Frame(ID, transformation, parent) .. autoapi-inheritance-diagram:: timor.utilities.frames.Frame :parts: 1 :private-bases: A frame is a position and orientation in a 3D world. It is defined by a transformation relative to a parent frame. All frames span up a tree with a single root node: the world frame. The following special frames exist: - `world`: denotes the world frame. - `nominal`: denotes the nominal placement of a tolerated pose. Create a frame with a given transformation relative to its parent frame. :param ID: The ID of the frame as a tuple of strings. IDs with . are special for auto-generation (see frame-tree). :param transformation: The transformation from the parent frame to this frame. :param parent: The parent frame. .. py:property:: ID :type: FRAME_ID_TYPE Return the name of the frame. .. py:attribute:: _ID :type: FRAME_ID_TYPE .. py:method:: __eq__(other) Two frames are equal if they represent the same reference coordinate system. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Return a hash of the frame. .. py:method:: __matmul__(other) Returns the absolute transformation in world coordinates, assuming `other` is given in this frame. .. py:method:: __repr__() Return a debug representation of the frame. .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:method:: __str__() Return a string representation of the frame by giving its absolute pose. .. 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:: _parent :type: Frame .. py:attribute:: _transformation :type: timor.utilities.transformation.Transformation .. py:property:: absolute :type: timor.utilities.transformation.Transformation Return the transformation from the world frame to this frame. .. py:property:: frame2parent :type: timor.utilities.transformation.Transformation Return the transformation from this frame to the parent frame. .. 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:method:: in_world_coordinates() Return the transformation from the world frame to this frame. .. py:property:: parent :type: Frame Return the parent frame. .. py:property:: parent2frame :type: timor.utilities.transformation.Transformation Return the transformation from the parent frame to this frame. .. py:method:: rotate_to_this_frame(t, old_basis) This method performs a change of basis using a similarity transformation. Given a transformation t, expressed in old_basis, this method assumes a new basis frame, centered in the same point as old_basis, but with axis aligned to the ones of this frame. This is especially useful when there's a need to express deviations between a desired and an actual pose (with delta t) in an unrelated (e.g., WORLD) frame. :param t: The transformation to be transformed. :param old_basis: The frame (or the world2frame transformation for an imaginary frame) t is expressed in. :return: t in a new basis with axis aligned to this frame. .. py:method:: to_json_data() Return a json representation of the frame as used by a (tolerated) pose, i.e., without a name / ID. .. 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:method:: visualize(viz, name_space = None, *args, **kwargs) Visualize the frame like a transformation. :param viz: The visualizer to use. :param name_space: The prefix in viz to use for the frame. :param kwargs: Additional arguments passed to visualize of underlying transformation. .. py:class:: FrameTree(frames) .. autoapi-inheritance-diagram:: timor.utilities.frames.FrameTree :parts: 1 :private-bases: A tree of frames with a single root (the world frame). :note: . is a reserved keyword in frame IDs to have namespace for auto-generated frames such as goal.goal_ID frame. They are especially useful when serializing the frame tree as these can be omitted. Create a frame tree from a dictionary of frames. :param frames: A dictionary with key = frame name and value = dictionary with keys "parent" and "transformation" to create each frame from. .. py:method:: __contains__(frame) Returns whether the given frame is known. .. py:method:: __eq__(other) Returns whether the two frame trees are equal. .. py:method:: __getitem__(frame_name) Returns the given frame. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __iter__() Returns an iterator over the frames in the tree. .. py:method:: __len__() Returns the number of frames in the tree. .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. 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:: _known_frames :type: Dict[FRAME_ID_TYPE, Frame] .. py:method:: add(ID, transformation, parent) Create and add a new frame to the tree. :param ID: The ID of the frame. If None, a random ID is generated. :param transformation: The transformation from the parent frame to this frame. :param parent: The parent frame of the fresh generated frame. Can either be an ID or a frame instance. The parent must already be part of the tree. .. py:method:: empty() :classmethod: Create an empty frame tree. .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Create a frame tree from a dictionary of frames. .. 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:method:: to_json_data() Return a dictionary of primary frames, i.e., those without a dot in their ID. .. 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:method:: visualize(viz, scale = 1.0, name_space = 'FrameTree', line_color = None) Draws this frame tree inside the visualizer object :param viz: Visualizer to add frame tree to. :param scale: Size in meter of each axis of placement :param name_space: Name to add geometry of frame tree to the viewer with (overwrites existing!) :param line_color: Color of the line between frames as RGB from 0 to 1 .. py:data:: NOMINAL_FRAME .. py:class:: NominalFrameType .. autoapi-inheritance-diagram:: timor.utilities.frames.NominalFrameType :parts: 1 :private-bases: The nominal frame is a special frame that is used to represent the nominal placement of a tolerated pose. Opposed to any other frame, it is not fixed in space: It transforms with the pose it represents. It is implemented as a singleton, i.e., there is only one NominalFrame, but it can represent any number of poses. We will create the nominal frame exactly once. .. py:property:: ID :type: FRAME_ID_TYPE Return the name of the frame. .. py:attribute:: UndefinedError .. py:attribute:: _ID :value: 'nominal' .. py:method:: __eq__(other) Singleton equality means same instance. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Return a hash of the frame. .. py:method:: __matmul__(other) Returns the absolute transformation in world coordinates, assuming `other` is given in this frame. .. py:method:: __repr__() There is not much debug information about the nominal frame. .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:method:: __str__() Return a string representation of the frame by giving its absolute pose. .. 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:: _parent :type: Frame .. py:attribute:: _transformation :type: timor.utilities.transformation.Transformation .. py:property:: absolute :type: timor.utilities.transformation.Transformation Return the transformation from the world frame to this frame. .. py:property:: frame2parent :type: timor.utilities.transformation.Transformation Return the transformation from this frame to the parent frame. .. 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:method:: in_world_coordinates() This method is not well-defined. .. py:property:: parent :type: Frame The nominal's frame parent is the world frame, always. .. py:property:: parent2frame :type: timor.utilities.transformation.Transformation This is not defined .. py:method:: rotate_to_this_frame(t, old_basis = None) For the nominal frame, no matter the old basis, we will just use it. .. py:method:: to_json_data() The nominal frame cannot be serialized, it is used by tolerances on-the-fly only. .. 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:method:: visualize(viz, name_space = None, *args, **kwargs) A nominal frame doesn't have a fixed placement and can't be visualized. .. py:data:: SPECIAL_FRAMES .. py:data:: WORLD_FRAME .. py:class:: WorldFrameType .. autoapi-inheritance-diagram:: timor.utilities.frames.WorldFrameType :parts: 1 :private-bases: The world frame is a special frame that always represents the root node in a frame tree. It's the "world origin". We will create the world frame exactly once .. py:property:: ID :type: FRAME_ID_TYPE Return the name of the frame. .. py:attribute:: RootError .. py:attribute:: _ID :value: 'world' .. py:method:: __eq__(other) Two frames are equal if they represent the same reference coordinate system. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Return a hash of the frame. .. py:method:: __matmul__(other) Returns the absolute transformation in world coordinates, assuming `other` is given in this frame. .. py:method:: __repr__() Return a debug representation of the frame. .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:method:: __str__() Return a string representation of the frame by giving its absolute pose. .. 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:: _parent :type: Frame .. py:attribute:: _transformation :type: timor.utilities.transformation.Transformation .. py:property:: absolute :type: timor.utilities.transformation.Transformation Return the transformation from the world frame to this frame. .. py:property:: frame2parent :type: timor.utilities.transformation.Transformation Return the transformation from this frame to the parent frame. .. 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:method:: in_world_coordinates() Neutral .. py:property:: parent :type: Frame The world frame has no parent .. py:property:: parent2frame :type: timor.utilities.transformation.Transformation This is not defined .. py:method:: rotate_to_this_frame(t, old_basis) For the world frame, this method only needs to 'neutralize' the old_basis rotation .. py:method:: to_json_data() The world frame is the only frame without a parent. .. 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:method:: visualize(viz, name_space = None, *args, **kwargs) Visualize the frame like a transformation. :param viz: The visualizer to use. :param name_space: The prefix in viz to use for the frame. :param kwargs: Additional arguments passed to visualize of underlying transformation.