timor.utilities.frames
Attributes
Classes
A frame is a position and orientation in a 3D world. It is defined by a transformation relative to a parent frame. |
|
A tree of frames with a single root (the world frame). |
|
The nominal frame is a special frame that is used to represent the nominal placement of a tolerated pose. |
|
The world frame is a special frame that always represents the root node in a frame tree. It's the "world origin". |
Module Contents
- timor.utilities.frames.FRAME_ID_TYPE
- class timor.utilities.frames.Frame(ID, transformation, parent)
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.
- Parameters:
ID (FRAME_ID_TYPE) – The ID of the frame as a tuple of strings. IDs with . are special for auto-generation (see frame-tree).
transformation (timor.utilities.transformation.TransformationLike) – The transformation from the parent frame to this frame.
parent (Frame) – The parent frame.
- property ID: FRAME_ID_TYPE
Return the name of the frame.
- Return type:
FRAME_ID_TYPE
- _ID: FRAME_ID_TYPE
- __eq__(other)
Two frames are equal if they represent the same reference coordinate system.
- __getstate__()
Return objects which will be pickled and saved.
- __hash__()
Return a hash of the frame.
- __matmul__(other)
Returns the absolute transformation in world coordinates, assuming other is given in this frame.
- Parameters:
- Return type:
- __repr__()
Return a debug representation of the frame.
- __setstate__(state)
Take object from parameter and use it to retrieve class state.
- __str__()
Return a string representation of the frame by giving its absolute pose.
- static _deduce_package_dir(filepath, content)
Logic for deducing the package directory if the JSONable object is loaded from a file.
- Parameters:
filepath (pathlib.Path) – The path to the file.
content (Union[Dict, List]) – 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.
- Return type:
- _transformation: timor.utilities.transformation.Transformation
- property absolute: timor.utilities.transformation.Transformation
Return the transformation from the world frame to this frame.
- Return type:
- property frame2parent: timor.utilities.transformation.Transformation
Return the transformation from this frame to the parent frame.
- Return type:
- classmethod from_json_data(d, *args, **kwargs)
Create from a json description.
- Parameters:
d (Dict)
- classmethod from_json_file(filepath, *args, **kwargs)
Factory method to load a class instance from a json file.
- Parameters:
filepath (Union[pathlib.Path, str]) – The path to the json file.
args – Additional arguments to pass to the from_json_data factory method of the specific class.
kwargs – Additional arguments to pass to the from_json_data factory method of the specific class.
- in_world_coordinates()
Return the transformation from the world frame to this frame.
- Return type:
- property parent2frame: timor.utilities.transformation.Transformation
Return the transformation from the parent frame to this frame.
- Return type:
- 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.
- Parameters:
old_basis (Union[Frame, timor.utilities.transformation.Transformation])
- Return type:
- to_json_data()
Return a json representation of the frame as used by a (tolerated) pose, i.e., without a name / ID.
- to_json_file(save_at, *args, **kwargs)
Writes the instance to a json file.
- Parameters:
save_at (Union[pathlib.Path, str]) – File location or folder to write the class to.
- visualize(viz, name_space=None, *args, **kwargs)
Visualize the frame like a transformation.
- Parameters:
viz (pinocchio.visualize.MeshcatVisualizer) – The visualizer to use.
name_space (str) – The prefix in viz to use for the frame.
kwargs – Additional arguments passed to visualize of underlying transformation.
- class timor.utilities.frames.FrameTree(frames)
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.
- Parameters:
frames (Dict[FRAME_ID_TYPE, Dict[str, timor.utilities.transformation.TransformationLike]])
Create a frame tree from a dictionary of frames.
- Parameters:
frames (Dict[FRAME_ID_TYPE, Dict[str, timor.utilities.transformation.TransformationLike]]) – A dictionary with key = frame name and value = dictionary with keys “parent” and “transformation” to create each frame from.
- __contains__(frame)
Returns whether the given frame is known.
- __getitem__(frame_name)
Returns the given frame.
- Parameters:
frame_name (FRAME_ID_TYPE)
- Return type:
- __getstate__()
Return objects which will be pickled and saved.
- __setstate__(state)
Take object from parameter and use it to retrieve class state.
- static _deduce_package_dir(filepath, content)
Logic for deducing the package directory if the JSONable object is loaded from a file.
- Parameters:
filepath (pathlib.Path) – The path to the file.
content (Union[Dict, List]) – 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.
- Return type:
- add(ID, transformation, parent)
Create and add a new frame to the tree.
- Parameters:
ID (Optional[FRAME_ID_TYPE]) – The ID of the frame. If None, a random ID is generated.
transformation (timor.utilities.transformation.TransformationLike) – The transformation from the parent frame to this frame.
parent (Union[FRAME_ID_TYPE, Frame]) – 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.
- Return type:
- classmethod from_json_data(d, *args, **kwargs)
Create a frame tree from a dictionary of frames.
- Parameters:
d (Dict)
- Return type:
- classmethod from_json_file(filepath, *args, **kwargs)
Factory method to load a class instance from a json file.
- Parameters:
filepath (Union[pathlib.Path, str]) – The path to the json file.
args – Additional arguments to pass to the from_json_data factory method of the specific class.
kwargs – Additional arguments to pass to the from_json_data factory method of the specific class.
- to_json_data()
Return a dictionary of primary frames, i.e., those without a dot in their ID.
- to_json_file(save_at, *args, **kwargs)
Writes the instance to a json file.
- Parameters:
save_at (Union[pathlib.Path, str]) – File location or folder to write the class to.
- visualize(viz, scale=1.0, name_space='FrameTree', line_color=None)
Draws this frame tree inside the visualizer object
- Parameters:
viz (pinocchio.visualize.MeshcatVisualizer) – Visualizer to add frame tree to.
scale (float) – Size in meter of each axis of placement
name_space (str) – Name to add geometry of frame tree to the viewer with (overwrites existing!)
line_color (Optional[numpy.ndarray]) – Color of the line between frames as RGB from 0 to 1
- timor.utilities.frames.NOMINAL_FRAME
- class timor.utilities.frames.NominalFrameType
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.
- property ID: FRAME_ID_TYPE
Return the name of the frame.
- Return type:
FRAME_ID_TYPE
- UndefinedError
- _ID = 'nominal'
- __eq__(other)
Singleton equality means same instance.
- __getstate__()
Return objects which will be pickled and saved.
- __hash__()
Return a hash of the frame.
- __matmul__(other)
Returns the absolute transformation in world coordinates, assuming other is given in this frame.
- Parameters:
- Return type:
- __repr__()
There is not much debug information about the nominal frame.
- __setstate__(state)
Take object from parameter and use it to retrieve class state.
- __str__()
Return a string representation of the frame by giving its absolute pose.
- static _deduce_package_dir(filepath, content)
Logic for deducing the package directory if the JSONable object is loaded from a file.
- Parameters:
filepath (pathlib.Path) – The path to the file.
content (Union[Dict, List]) – 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.
- Return type:
- _transformation: timor.utilities.transformation.Transformation
- property absolute: timor.utilities.transformation.Transformation
Return the transformation from the world frame to this frame.
- Return type:
- property frame2parent: timor.utilities.transformation.Transformation
Return the transformation from this frame to the parent frame.
- Return type:
- classmethod from_json_data(d, *args, **kwargs)
Create from a json description.
- Parameters:
d (Dict)
- classmethod from_json_file(filepath, *args, **kwargs)
Factory method to load a class instance from a json file.
- Parameters:
filepath (Union[pathlib.Path, str]) – The path to the json file.
args – Additional arguments to pass to the from_json_data factory method of the specific class.
kwargs – Additional arguments to pass to the from_json_data factory method of the specific class.
- in_world_coordinates()
This method is not well-defined.
- Return type:
- property parent2frame: timor.utilities.transformation.Transformation
This is not defined
- Return type:
- rotate_to_this_frame(t, old_basis=None)
For the nominal frame, no matter the old basis, we will just use it.
- Parameters:
- Return type:
- to_json_data()
The nominal frame cannot be serialized, it is used by tolerances on-the-fly only.
- to_json_file(save_at, *args, **kwargs)
Writes the instance to a json file.
- Parameters:
save_at (Union[pathlib.Path, str]) – File location or folder to write the class to.
- timor.utilities.frames.SPECIAL_FRAMES
- timor.utilities.frames.WORLD_FRAME
- class timor.utilities.frames.WorldFrameType
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
- property ID: FRAME_ID_TYPE
Return the name of the frame.
- Return type:
FRAME_ID_TYPE
- RootError
- _ID = 'world'
- __eq__(other)
Two frames are equal if they represent the same reference coordinate system.
- __getstate__()
Return objects which will be pickled and saved.
- __hash__()
Return a hash of the frame.
- __matmul__(other)
Returns the absolute transformation in world coordinates, assuming other is given in this frame.
- Parameters:
- Return type:
- __repr__()
Return a debug representation of the frame.
- __setstate__(state)
Take object from parameter and use it to retrieve class state.
- __str__()
Return a string representation of the frame by giving its absolute pose.
- static _deduce_package_dir(filepath, content)
Logic for deducing the package directory if the JSONable object is loaded from a file.
- Parameters:
filepath (pathlib.Path) – The path to the file.
content (Union[Dict, List]) – 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.
- Return type:
- _transformation: timor.utilities.transformation.Transformation
- property absolute: timor.utilities.transformation.Transformation
Return the transformation from the world frame to this frame.
- Return type:
- property frame2parent: timor.utilities.transformation.Transformation
Return the transformation from this frame to the parent frame.
- Return type:
- classmethod from_json_data(d, *args, **kwargs)
Create from a json description.
- Parameters:
d (Dict)
- classmethod from_json_file(filepath, *args, **kwargs)
Factory method to load a class instance from a json file.
- Parameters:
filepath (Union[pathlib.Path, str]) – The path to the json file.
args – Additional arguments to pass to the from_json_data factory method of the specific class.
kwargs – Additional arguments to pass to the from_json_data factory method of the specific class.
- in_world_coordinates()
Neutral
- Return type:
- property parent2frame: timor.utilities.transformation.Transformation
This is not defined
- Return type:
- rotate_to_this_frame(t, old_basis)
For the world frame, this method only needs to ‘neutralize’ the old_basis rotation
- Parameters:
old_basis (Union[Frame, timor.utilities.transformation.Transformation])
- Return type:
- to_json_data()
The world frame is the only frame without a parent.
- to_json_file(save_at, *args, **kwargs)
Writes the instance to a json file.
- Parameters:
save_at (Union[pathlib.Path, str]) – File location or folder to write the class to.
- visualize(viz, name_space=None, *args, **kwargs)
Visualize the frame like a transformation.
- Parameters:
viz (pinocchio.visualize.MeshcatVisualizer) – The visualizer to use.
name_space (str) – The prefix in viz to use for the frame.
kwargs – Additional arguments passed to visualize of underlying transformation.