skbot.transform.Frame¶
- class skbot.transform.Frame(ndim, *, name=None)[source]¶
Representation of a coordinate system.
Each coordinate frame is a node in a directed graph where edges (
skbot.transform.Link
) describe transformations between frames. This transformation is not limited to neighbours, but works between any two frames that share a chain of links pointing from a parent to the (grand-)child.- Parameters
- ndimint
Number of coordinate dimensions.
- namestr
The name of this coordinate frame. Defaults to
None
.
Method Summary
add_link
(edge, child)Add an edge to the frame graph.
chain_between
(to_frame, *[, ignore_frames, ...])Get the frames and links between this frame and
to_frame
.find_frame
(path, *[, ignore_frames])Find a frame matching a given path.
frames_between
(to_frame, *[, include_self, ...])Get the frames between this frame and
to_frame
.get_affine_matrix
(to_frame, *[, ignore_frames])Affine transformation matrix to
to_frame
(if existant).joints_between
(to_frame, *[, ignore_frames, ...])Get the links between this frame and
to_frame
.links_between
(to_frame, *[, ignore_frames, ...])Get the links between this frame and
to_frame
.transform
(x, to_frame, *[, ignore_frames])Express the vector x in to_frame.
transform_chain
(to_frame, *[, ...])Get a transformation chain into
to_frame
(deprecated).Methods
- add_link(edge, child)[source]¶
Add an edge to the frame graph.
The edge is directional and points from this frame to another (possibliy identical) frame.
- Parameters
- edgeLink
The transformation to add to the graph.
- childFrame
The frame that following this link leads to.
- Return type
None
- chain_between(to_frame, *, ignore_frames=None, metric=<function DepthFirst>, max_depth=None)[source]¶
Get the frames and links between this frame and
to_frame
.New in version 0.9.0.
This function searches the frame graph for a chain of transformations from the current frame into
to_frame
and returns both, the sequence of frames and the sequence of links involved in this transformation.The sequence of frames will have this frame as its first element, and
`to_frame
as its last element.The first element of the returned sequence of links takes as input the vector expressed in the current frame; each following element takes as input the vector expressed in its predecessor’s output frame. The last element outputs the vector expressed in
to_frame
.- Parameters
- to_frameFrame, str
The frame in which to express vectors. If
str
, the graph is searched for any node matching that name and the transformation chain to the first node matching the name is returned.- ignore_framesList[Frame]
A list of frames to exclude while searching for a transformation chain.
- metricCallable[[Tuple[Frame], Tuple[Link]], float]
A function to compute the priority of a sub-chain. Sub-chains are searched in order of priority starting with the lowest value. The first chain that matches
to_frame
is returned. You can use a custom function that takes a sequence of frames and links involved in the sub-chain as input and returns a float (signaturecustom_fn(frames, links) -> float
), or you can use a pre-build function:- skbot.transform.metric.DepthFirst
The frame graph is searched depth-first with no preference among frames (default).
- skbot.transform.metric.BreadthFirst
The frame graph is searched breadth-first with no preference among frames.
- max_depthint
If not None, the maximum depth to search, i.e., the maximum length of the transform chain.
- Returns
- framesList[Frame]
A list of frames between this frame and
to_frame
(inclusive).- linksList[Link]
A list of links between this frame and
to_frame
.
- find_frame(path, *, ignore_frames=None)[source]¶
Find a frame matching a given path.
New in version 0.3.0: This method was added to frame.
This method allows you to find reachable frames using an xpath inspired syntax. Path elements are spearated using the / character. Each element of the path is the name of a frame. For example,
world/link1/link2/gripper
, denotes a sequence of 4 frames with names["world", "link1", "link2", "gripper"]
. The final frame in the path (gripper) is returned.By default an element along the path is directly connected to its next element. In the previous example this means that there must exist a direct link from “world” to “link1”. An exception to this rule is the use of an ellipsis (…), in which case an element must be connected to its next element by a transformation chain (a sequence of links).
The following path elements have special meanings:
- Ellipsis (
...
) Indicates that the previous frame and the next frame are connected by a transformation chain instead of being connected directly.
- Ellipsis (
- None (
//
) Omitting a name indicates that the name of this frame is None.
- None (
- Parameters
- xpathstr
A xpath string describing the frame to search for.
- ignore_framesList[Frame]
Any frames that should be ignored when matching the path.
- Returns
- matched_frameFrame
A frame matching the given path.
Notes
In directed graphs there is no clear notion of search order; hence it is undefined which frame is found if multiple matches for the path exist. In this case an arbitrary match is returned, and you should not count on the result to be deterministic.
Because
...
and//
have special meaning, frames with names"..."
or""
will be ignored by this method and can not be found. Similarly, frames that use slashes, e.g.namespace/my_frame
, will be ignored and instead the sequences["namespace", "my_frame"]
will be matched.Each element of the path is assumed to represent a unique frame. This means that circular paths will not be matched.
- Return type
- frames_between(to_frame, *, include_self=True, include_to_frame=True, ignore_frames=None, metric=<function DepthFirst>, max_depth=None)[source]¶
Get the frames between this frame and
to_frame
.New in version 0.9.0.
This function searches the frame graph for a chain of transformations from the current frame into
to_frame
and returns the sequence of frames between this frame andto_frame
.- Parameters
- include_selfbool
If
True
(default) this frame will be added as the first element of the returned sequence.- include_to_framebool
If
True
(default)to_frame
will be added as the last element of the returned sequence.- to_frameFrame, str
The frame in which to express vectors. If
str
, the graph is searched for any node matching that name and the transformation chain to the first node matching the name is returned.- ignore_framesList[Frame]
A list of frames to exclude while searching for a transformation chain.
- metricCallable[[Tuple[Frame], Tuple[Link]], float]
A function to compute the priority of a sub-chain. Sub-chains are searched in order of priority starting with the lowest value. The first chain that matches
to_frame
is returned. You can use a custom function that takes a sequence of frames and links involved in the sub-chain as input and returns a float (signaturecustom_fn(frames, links) -> float
), or you can use a pre-build function:- skbot.transform.metric.DepthFirst
The frame graph is searched depth-first with no preference among frames (default).
- skbot.transform.metric.BreadthFirst
The frame graph is searched breadth-first with no preference among frames.
- max_depthint
If not None, the maximum depth to search, i.e., the maximum length of the transform chain.
- get_affine_matrix(to_frame, *, ignore_frames=None)[source]¶
Affine transformation matrix to
to_frame
(if existant).- Parameters
- to_frameFrame
The frame in which x should be expressed.
- ignore_framesFrame
Any frames that should be ignored when searching for a suitable transformation chain.
- Returns
- tf_matrixnp.ndarray
The matrix describing the transformation.
- Raises
- RuntimeError
If no suitable chain of transformations can be found, a RuntimeError is raised.
Notes
The affine transformation matrix between two frames only exists if the transformation chain is linear in
self.ndim+1
dimensions. Requesting a non-existing affine matrix will raise an Exception. In practice, this means that each link along the transformation chain needs to implementskbot.transform.Link.transformation
.- Return type
ndarray
- joints_between(to_frame, *, ignore_frames=None, metric=<function DepthFirst>, max_depth=None)[source]¶
Get the links between this frame and
to_frame
.New in version 0.12.0.
This function searches the frame graph for a chain of transformations from the current frame into
to_frame
and returns the sequence of joints involved in this transformation. All joints will be “unwraped”, i.e., if a Joint occurs inside atf:InvertLink
or similar, then only the Joint will be returned. The resulting order matches the order that links are encountered in the transformation chain.- Parameters
- to_frameFrame, str
The frame in which to express vectors. If
str
, the graph is searched for any node matching that name and the transformation chain to the first node matching the name is returned.- ignore_framesList[Frame]
A list of frames to exclude while searching for a transformation chain.
- metricCallable[[Tuple[Frame], Tuple[Link]], float]
A function to compute the priority of a sub-chain. Sub-chains are searched in order of priority starting with the lowest value. The first chain that matches
to_frame
is returned. You can use a custom function that takes a sequence of frames and links involved in the sub-chain as input and returns a float (signaturecustom_fn(frames, links) -> float
), or you can use a pre-build function:- skbot.transform.metric.DepthFirst
The frame graph is searched depth-first with no preference among frames (default).
- skbot.transform.metric.BreadthFirst
The frame graph is searched breadth-first with no preference among frames.
- max_depthint
If not None, the maximum depth to search, i.e., the maximum length of the transform chain.
- links_between(to_frame, *, ignore_frames=None, metric=<function DepthFirst>, max_depth=None)[source]¶
Get the links between this frame and
to_frame
.New in version 0.9.0.
This function searches the frame graph for a chain of transformations from the current frame into
to_frame
and returns the sequence of links involved in this transformation. The first element of the returned sequence takes as input the vector expressed in the current frame; each following element takes as input the vector expressed in its predecessor’s output frame. The last element outputs the vector expressed into_frame
.- Parameters
- to_frameFrame, str
The frame in which to express vectors. If
str
, the graph is searched for any node matching that name and the transformation chain to the first node matching the name is returned.- ignore_framesList[Frame]
A list of frames to exclude while searching for a transformation chain.
- metricCallable[[Tuple[Frame], Tuple[Link]], float]
A function to compute the priority of a sub-chain. Sub-chains are searched in order of priority starting with the lowest value. The first chain that matches
to_frame
is returned. You can use a custom function that takes a sequence of frames and links involved in the sub-chain as input and returns a float (signaturecustom_fn(frames, links) -> float
), or you can use a pre-build function:- skbot.transform.metric.DepthFirst
The frame graph is searched depth-first with no preference among frames (default).
- skbot.transform.metric.BreadthFirst
The frame graph is searched breadth-first with no preference among frames.
- max_depthint
If not None, the maximum depth to search, i.e., the maximum length of the transform chain.
- transform(x, to_frame, *, ignore_frames=None)[source]¶
Express the vector x in to_frame.
Express the vector x - assumed to be in this frame - in the coordinate frame to_frame. If it is not possible to find a transformation between this frame and to_frame a RuntimeError will be raised.
- Parameters
- xArrayLike
A vector expressed in this frame.
- to_frameFrame, str
The frame in which x should be expressed. If it is a string,
transform()
will search for a child frame with the given string as name. In case of duplicate names in a frame graph, the first one found is used.- ignore_framesFrame
Any frames that should be ignored when searching for a suitable transformation chain. Note that this currently does not support string aliases.
- Returns
- x_newnp.ndarray
The vector x expressed to_frame.
- Raises
- RuntimeError
If no suitable chain of transformations can be found, a RuntimeError is raised.
- Return type
ndarray
- transform_chain(to_frame, *, ignore_frames=None, metric=<function DepthFirst>, max_depth=None)[source]¶
Get a transformation chain into
to_frame
(deprecated).Deprecated since version 0.9.0: This method is deprecated and will be removed in scikit-bot v1.0. Use
Frame.links_between
instead.New in version 0.5.0: This method was added to Frame.
This function searches the frame graph for a chain of transformations from the current frame into
to_frame
and returns the sequence of links involved in this transformation. The first element of the returned sequence takes as input the vector expressed in the current frame; each following element takes as input the vector expressed in its predecessor’s output frame. The last element outputs the vector expressed into_frame
.- Parameters
- to_frameFrame, str
The frame in which to express vectors. If
str
, the graph is searched for any node matching that name and the transformation chain to the first node matching the name is returned.- ignore_framesList[Frame]
A list of frames to exclude while searching for a transformation chain.
- metricCallable[[Tuple[Frame], Tuple[Link]], float]
A function to compute the priority of a sub-chain. Sub-chains are searched in order of priority starting with the lowest value. The first chain that matches
to_frame
is returned. You can use a custom function that takes a sequence of frames and links involved in the sub-chain as input and returns a float (signaturecustom_fn(frames, links) -> float
), or you can use a pre-build function:- skbot.transform.metric.DepthFirst
The frame graph is searched depth-first with no preference among frames (default).
- skbot.transform.metric.BreadthFirst
The frame graph is searched breadth-first with no preference among frames.
- max_depthint
If not None, the maximum depth to search, i.e., the maximum length of the transform chain.
- Return type
List
[Link
]