skbot.transform.Frame

class skbot.transform.Frame(ndim, *, name=None)

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)

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)

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 (signature custom_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.

Return type

Tuple[List[Frame], List[Link]]

find_frame(path, *, ignore_frames=None)

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.

• None (//)

  Omitting a name indicates that the name of this frame is 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

Frame

frames_between(to_frame, *, include_self=True, include_to_frame=True, ignore_frames=None, metric=<function DepthFirst>, max_depth=None)

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 and to_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 (signature custom_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)

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 implement skbot.transform.Link.transformation.

Return type

ndarray

joints_between(to_frame, *, ignore_frames=None, metric=<function DepthFirst>, max_depth=None)

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 a tf: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 (signature custom_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)

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 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 (signature custom_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)

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)

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 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 (signature custom_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]

previous

skbot.transform

next

skbot.transform.Link