com.kuka.geometry
Class Frame

java.lang.Object
  com.kuka.geometry.Frame

Direct Known Subclasses:

LocalFrame, ObjectFrame

public abstract class Frame
extends Object

A frame represents a coordinate system in three-dimensional space. Normally, a frame has a reference coordinate system, which is called its parent frame. The position and orientation of the frame relative to its parent frame can be expressed as a spatial transformation. A frame without parent frame is called a root frame.

With this relation, one can build a tree structure of connected frames. For any two frames under a common root frame, one can calculate the location of one frame in the coordinate system of the other frame. This location is expressed as a "transformation to" one frame as seen from the other frame, and can be calculated with calculateTransformationTo(Frame).

A frame is connected to its parent frame using a frame connection. Depending on the type of connection, there may be inter-process or inter-machine communication involved when querying a frame's position relative to its parent.

There are mainly two types of frame:

• An object frame (ObjectFrame), which belongs to a SpatialObject.
• A temporary frame (LocalFrame), that can be used for intermediate results of calculations or for motion targets, for example.

There should be no need to derive own types from this class. If you need to implement an adapter to another geometry library, you would implement IFrameConnection or IQueryConnection, and use those connections with LocalFrame.

Implementation note: The default implementation of the methods setConnectionFromParent(IFrameConnection) and setTransformationFromParent(ITransformation) call connectToParent(Frame, IFrameConnection) internally.

See Also:

ITransformation, QueryConnectionChain, FrameUtils, RedundancyUtils

Method Summary

Transformation	calculateTransformationTo(Frame target) Calculates the transformation from this frame to the given target frame, combining the connections between the frames along the frame graph.
double	distanceTo(Frame other) Calculates the euclidean distance from this frame to the given other frame.
IFrameConnection	getConnectionFromParent() Returns the connection from the parent frame to this frame.
String	getName() Returns the name of this frame.
Frame	getParent() Returns the parent frame.
Map<String,IRedundancyCollection>	getRedundancyDataMap() Gets the map containing all redundancy informations for this frame.
IRedundancyCollection	getRedundancyInformation(String redundancyKey) Sets the redundancy information of this frame for a specific redundancy key.
Transformation	getTransformationFromParent() Gets the transformation from the reference frame (parent) to this frame.
boolean	hasAncestor(Frame frame) Checks whether the given frame is a direct or indirect ancestor of this frame, i.e. if the frame can be found by recursive calls to getParent(), starting with this frame.
boolean	hasPathTo(Frame target) Tests whether this frame has a path to the given target frame.
boolean	hasStaticPathTo(Frame target) Tests whether this frame has a static path to the given target frame.
boolean	isNearTo(Frame other, double maxCartesianDistance, double maxRotationalDistance) Tests whether this frame lies close to another frame in space.
Point3D	representationOf(Frame reference, Point3D point) Returns the representation of the given point, which is expressed in the given frame reference, in this frame's coordinate system.
Vector3D	representationOf(Frame reference, Vector3D vector) Returns the representation of the given vector, which is expressed in the given frame reference, in this frame's coordinate system.
void	rotate(Frame reference, IRotation rotation) Changes this frame's orientation by rotating it in the coordinate system of the given reference frame.
void	rotate(IRotation rotation) Changes this frame's orientation by rotating it in its own coordinate system.
void	rotateTo(Frame target) Changes this frame's orientation in space by rotating it into the same orientation in space as the given target frame.
double	rotationalDistanceTo(Frame other) Calculates the rotational distance from this frame to the given other frame.
void	setConnectionFromParent(IFrameConnection connection) Changes the connection to the parent of this frame.
void	setName(String name) Sets the name of this frame.
void	setRedundancyInformation(String redundancyKey, IRedundancyCollection redundancy) Sets the redundancy information of this frame for a specific redundancy key.
String	toString()
void	transform(Frame reference, ITransformation delta) Changes this frame's position by applying the given translation and rotation to this frame in the coordinate system of the given reference frame.
void	transform(ITransformation delta) Changes this frame's position by applying the given translation and rotation to this frame in its own coordinate system.
void	transformTo(Frame target) Changes this frame's position and orientation in space by bringing it to the same position and orientation in space as the given target frame.
void	translate(Frame reference, Vector3D translation) Changes this frame's position by translating this frame by the given amount in the coordinate system of the given reference frame.
void	translate(Vector3D translation) Changes this frame's position by translating this frame by the given amount in its own coordinate system.
void	translateTo(Frame target) Changes this frame's position by bringing its origin to the same location in space as the origin of the given target frame.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getName

public String getName()

Returns the name of this frame. Depending on the implementation, the name of a frame can be used to find the frame in a hierarchy of child frames (see ObjectFrame.getChild(String)), or it might simply be used to print the name in toString().

Returns:

the name of the frame, or null if the frame has no name.

getParent

public Frame getParent()

Returns the parent frame.

Returns:

the parent frame, or null if the frame has no parent.

getConnectionFromParent

public IFrameConnection getConnectionFromParent()

Returns the connection from the parent frame to this frame.

Returns:

the connection from the parent frame to this frame. Only null if this frame has no parent.

See Also:

getParent(), IFrameConnection

getTransformationFromParent

public Transformation getTransformationFromParent()

Gets the transformation from the reference frame (parent) to this frame.

Returns:

The transformation from this frame to its parent.

Throws:

IllegalStateException - if the frame does not have a parent

translate

public void translate(Vector3D translation)

Changes this frame's position by translating this frame by the given amount in its own coordinate system.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

For example, the following instruction will change the position of frame by shifting it 10 mm along its positive X axis:

frame.translate(Vector3D.of(10, 0, 0));

Parameters:

translation - the amount by which this frame's position should be changed

Throws:

IllegalArgumentException - if the parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

Vector3D, translate(Frame, Vector3D), rotate(IRotation), transform(ITransformation)

translate

public void translate(Frame reference,
                      Vector3D translation)

Changes this frame's position by translating this frame by the given amount in the coordinate system of the given reference frame.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

For example, the following instruction will change the position of frame by shifting it 10 mm along the positive X axis of base:

frame.translate(base, Vector3D.of(10, 0, 0));

Parameters:

reference - the reference frame for the translation

translation - the amount by which this frame's position should be changed

Throws:

IllegalArgumentException - if there is no connection or an unknown connection type between this frame and the reference frame, or if any parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection, or if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

Vector3D, translate(Vector3D), rotate(Frame, IRotation), transform(Frame, ITransformation)

translateTo

public void translateTo(Frame target)

Changes this frame's position by bringing its origin to the same location in space as the origin of the given target frame. The frame's orientation in space is not changed.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

Parameters:

target - the frame that specifies the target position for the origin of this frame

Throws:

IllegalArgumentException - if there is no connection or an unknown connection type between this frame and the target frame, or if the parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection or if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

rotate

public void rotate(IRotation rotation)

Changes this frame's orientation by rotating it in its own coordinate system.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

For example, the following instruction will change the orientation of frame by rotating it 45° around its Z axis:

frame.rotate(Rotation.ofDeg(45, 0, 0));

Parameters:

rotation - the rotation to apply to this frame's orientation

Throws:

IllegalArgumentException - if the parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

Rotation, rotate(Frame, IRotation), translate(Vector3D), transform(ITransformation)

rotate

public void rotate(Frame reference,
                   IRotation rotation)

Changes this frame's orientation by rotating it in the coordinate system of the given reference frame.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

For example, the following instruction will change the orientation of frame by rotating it 45° around the Z axis of base:

frame.rotate(base, Rotation.ofDeg(45, 0, 0));

Parameters:

reference - the reference frame for the rotation

rotation - the rotation to apply to this frame's orientation

Throws:

IllegalArgumentException - if there is no connection or an unknown connection type between this frame and the reference frame, or if any parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection, or if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

Rotation, rotate(IRotation), translate(Frame, Vector3D), transform(Frame, ITransformation)

rotateTo

public void rotateTo(Frame target)

Changes this frame's orientation in space by rotating it into the same orientation in space as the given target frame. The frame's location will not be changed.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

Parameters:

target - the frame that specifies the target orientation for this frame

Throws:

IllegalArgumentException - if there is no connection or an unknown connection type between this frame and the target frame, or if the parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection, or if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

transform

public void transform(ITransformation delta)

Changes this frame's position by applying the given translation and rotation to this frame in its own coordinate system.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

For example, the following instruction will change the position of frame by shifting it 10 mm along its positive X axis and rotating it 45° around its Z axis:

frame.transform(Transformation.of(10, 0, 0, 45, 0, 0));

Parameters:

delta - the amount by which this frame's position and/or orientation should be changed

Throws:

IllegalArgumentException - if the parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

Transformation, transform(Frame, ITransformation), translate(Vector3D), rotate(IRotation)

transform

public void transform(Frame reference,
                      ITransformation delta)

Changes this frame's position by applying the given translation and rotation to this frame in the coordinate system of the given reference frame.

This implies that the static connection to the parent frame is changed. This frame and all the frames connected to it will change their position in the model.

For example, the following instruction will change the position of frame by shifting it 10 mm along the positive X axis and rotating it 45° around the Z axis of base:

frame.transform(base, Transformation.of(10, 0, 0, 45, 0, 0));

Parameters:

reference - the reference frame for the transformation

delta - the amount by which this frame's position and/or orientation should be changed

Throws:

IllegalArgumentException - if there is no connection or an unknown connection type between this frame and the reference frame, or if any parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection, or if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

Transformation, transform(ITransformation), translate(Frame, Vector3D), rotate(Frame, IRotation)

transformTo

public void transformTo(Frame target)

Changes this frame's position and orientation in space by bringing it to the same position and orientation in space as the given target frame.

This implies that the static connection to the parent frame is replaced. This frame and all the frames connected to it will change their position in the model.

Parameters:

target - the frame that specifies the target position and orientation in space

Throws:

IllegalArgumentException - if there is no connection or an unknown connection type between this frame and the target frame, or if the parameter is null

IllegalStateException - if this frame's parent connection type is anything other than StaticConnection or if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

translateTo(Frame), rotateTo(Frame)

calculateTransformationTo

public Transformation calculateTransformationTo(Frame target)

Calculates the transformation from this frame to the given target frame, combining the connections between the frames along the frame graph. The resulting transformation represents the spatial location of the target frame in the this frame's coordinate system.

If there are IQueryConnections along the path (a robot's flange, for example), each query connection is queried for the current transformation, using the query's default behavior. This operation may take a certain time and may be unsuccessful. If there are multiple query connections along the path, care is being taken that the queries are processed simultaneously, if possible.

Parameters:

target - another frame that must be connected to this frame

Returns:

the current transformation from this frame to the target frame, expressed in this frame's coordinate system. Never null.

Throws:

IllegalStateException - if there is no connection between this frame and the target frame

IllegalArgumentException - if there is an unknown connection type between this frame and the target frame, or if the target argument is null

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

hasStaticPathTo

public boolean hasStaticPathTo(Frame target)

Tests whether this frame has a static path to the given target frame.

Parameters:

target - the target frame of the tested path

Returns:

true, if the path between source frame and target frame consists only of StaticConnections.

Throws:

IllegalArgumentException - if the target argument is null

This element is not in its final state and might change in future versions.

hasPathTo

public boolean hasPathTo(Frame target)

Tests whether this frame has a path to the given target frame.

Parameters:

target - the target frame of the tested path

Returns:

true, if a path exists between source frame and target frame.

Throws:

IllegalArgumentException - if the target argument is null

hasAncestor

public boolean hasAncestor(Frame frame)

Checks whether the given frame is a direct or indirect ancestor of this frame, i.e. if the frame can be found by recursive calls to getParent(), starting with this frame.

Parameters:

frame - a frame

Returns:

true if the given frame is an ancestor of this frame, false otherwise

Throws:

IllegalArgumentException - if the given frame is null

representationOf

public Vector3D representationOf(Frame reference,
                                 Vector3D vector)

Returns the representation of the given vector, which is expressed in the given frame reference, in this frame's coordinate system.

Parameters:

reference - the frame where vec is defined

vector - the vector of interest

Returns:

the given vector, expressed in this frame's coordinate system

Throws:

IllegalArgumentException - if either argument is null, or if there is no connection or an unknown connection type between this frame and the reference frame

IllegalStateException - if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

representationOf

public Point3D representationOf(Frame reference,
                                Point3D point)

Returns the representation of the given point, which is expressed in the given frame reference, in this frame's coordinate system.

Parameters:

reference - the frame where point is defined

point - the point of interest

Returns:

the given point, expressed in this frame's coordinate system

Throws:

IllegalArgumentException - if either argument is null, or if there is no connection or an unknown connection type between this frame and the reference frame

IllegalStateException - if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

toString

public String toString()

Overrides:

toString in class Object

setName

public void setName(String name)

Sets the name of this frame.

Parameters:

name - any string, including null or "".

setConnectionFromParent

public void setConnectionFromParent(IFrameConnection connection)

Changes the connection to the parent of this frame.

Caution: Use this method only if you understand the impact, it is designed for advanced use cases - This frame's position in space may be changed. The positions of frames connected to this frame will also be affected by this method.

Parameters:

connection - the new type of connection to the parent frame

Throws:

IllegalStateException - if this frame has no parent

See Also:

IFrameConnection

distanceTo

public double distanceTo(Frame other)

Calculates the euclidean distance from this frame to the given other frame.

Internally, this method uses calculateTransformationTo(Frame).

Parameters:

other - another frame which must have a connection to this frame

Returns:

the euclidean distance of the frame to the specified destination in [mm]

Throws:

IllegalArgumentException - if the argument is null, or if there is no connection or an unknown connection type between this frame and the other frame

IllegalStateException - if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

rotationalDistanceTo

public double rotationalDistanceTo(Frame other)

Calculates the rotational distance from this frame to the given other frame. The rotational distance is the angle of the spatial rotation needed to turn this frame into the same orientation as the other frame. Use this function to determine if two frames have a similar orientation.

Internally, this method uses calculateTransformationTo(Frame).

Parameters:

other - another frame which must have a connection to this frame

Returns:

the positive rotational distance to the other frame in [rad]. Value range: [0-pi]

Throws:

IllegalArgumentException - if the argument is null, or if there is no connection or an unknown connection type between this frame and the other frame

IllegalStateException - if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

isNearTo

public boolean isNearTo(Frame other,
                        double maxCartesianDistance,
                        double maxRotationalDistance)

Tests whether this frame lies close to another frame in space. This function compares the euclidean distance of the origin of the two frames, and the rotational distance of the orientation of the frames. Use this function to determine if two frames have a similar position and orientation.

Internally, this method combines the methods distanceTo(Frame) and rotationalDistanceTo(Frame), which in turn use calculateTransformationTo(Frame).

Parameters:

other - another frame which must have a connection to this frame

maxCartesianDistance - maximum distance in [mm] tolerated between the frame origins. May be negative, in which case this function returns false.

maxRotationalDistance - maximum rotational angle in [rad] between the frame orientations. May be negative, in which case this function returns false.

Returns:

true, if both distances are smaller or equal to the given distances, respectively. False otherwise.

Throws:

IllegalArgumentException - if the argument is null, or if there is no connection or an unknown connection type between this frame and the other frame

IllegalStateException - if the relation between the involved frames could not be determined

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

See Also:

distanceTo(Frame), rotationalDistanceTo(Frame)

getRedundancyDataMap

public Map<String,IRedundancyCollection> getRedundancyDataMap()

Gets the map containing all redundancy informations for this frame.

Returns:

the map of all redundancy informations.

See Also:

setRedundancyInformation(String, IRedundancyCollection)

This element is not in its final state and might change in future versions.

getRedundancyInformation

public IRedundancyCollection getRedundancyInformation(String redundancyKey)

Sets the redundancy information of this frame for a specific redundancy key.

Parameters:

redundancyKey - the redundancy key which usually consists of controllerName/deviceName.

Returns:

the redundancy information

Throws:

IllegalArgumentException - if the given key is null

This element is not in its final state and might change in future versions.

setRedundancyInformation

public void setRedundancyInformation(String redundancyKey,
                                     IRedundancyCollection redundancy)

Sets the redundancy information of this frame for a specific redundancy key.

Parameters:

redundancyKey - the redundancy key which usually consists of controllerName/deviceName.

redundancy - the redundancy information to be set

Throws:

IllegalArgumentException - if the given key is null

This element is not in its final state and might change in future versions.