com.kuka.roboticsAPI.geometricModel
Class AbstractFrame

java.lang.Object
  com.kuka.roboticsAPI.geometricModel.AbstractFrame

Direct Known Subclasses:

Frame, ObjectFrame

public abstract class AbstractFrame
extends Object

Base class for frames.

The Robotics API always assumes the translation part of frames to be given in [mm].

Field Summary

static String	COMMENT_PARAMETER Key for the additional frame data "Comment".
static String	LAST_MODIFICATION_TIME_PARAMETER Key for the additional frame data "LastModificationTime".
static String	LEGACY_REDUNDANCE_KEY Legacy redundancy key.
static String	MEASUREMENT_INFORMATION_PARAMETER Key for the additional frame data "MeasurementInformation".
static String	NAME_SEPARATOR Separator for frame path segments.
static String	TEACHINFO_PARAMETER Key for the additional frame data "TeachInformation".
static String	USE_AS_BASE Key for the additional frame data "UseAsBase".

Constructor Summary

protected

AbstractFrame(ITransformationProvider provider) Creates a new AbstractFrame with the given TransformationProvider.

Method Summary

Frame	copy() Creates a snapshot copy of the information in this frame into a new Frame.
Frame	copy(AbstractFrame newParent) Creates a snapshot copy of the information in this frame into a new Frame, with the given Frame set as the parent of the new frame.
Frame	copyWithRedundancy() Creates a snapshot copy of the information in this frame (including redundancy information) into a new Frame.
Frame	copyWithRedundancy(AbstractFrame newParent) Creates a snapshot copy of the information in this frame (including redundancy information) into a new Frame, with the given Frame set as the parent of the new frame.
double	distanceTo(AbstractFrame other) Calculates the euclidean distance of the frame to the specified destination frame.
protected AbstractFrame	findRoot() Gets the root of this frame.
Map<String,Object>	getAdditionalFrameData() Gets the map containing all additional parameters defined for this frame.
Object	getAdditionalParameter(String key) Gets the additional frame parameter for the specified key.
<T> Map<String,T>	getAllParametersOfType(Class<T> paramType) Gets all parameters of this frame of the specified type.
String	getName() Gets the name of this frame.
Point	getOriginOf(AbstractFrame other) Gets the position vector of the other frame's origin relative to this frame's coordinate system.
AbstractFrame	getParent() Gets the parent frame of this frame.
String	getPath() Gets the path from this frame to the worlds root frame.
String	getPathFrom(AbstractFrame frame) Gets the path from this frame to the given frame if both frames are part of the scene graph.
Map<String,IRedundancyCollection>	getRedundancyInformation() Gets the map containing all redundancy informations for this frame.
IRedundancyCollection	getRedundancyInformationForDevice(Robot robot) Gets the redundancy information of a specific Device for this Frame.
Transformation	getTransformationFromParent() Gets the transformation from the reference frame (parent) to the frame itself.
ITransformationProvider	getTransformationProvider() Gets the transformation provider of this frame.
boolean	hasAdditionalParameter(String key) Indicates whether the addition parameter is known or not.
boolean	hasPathTo(AbstractFrame destination) Determines if this frame has a path to the destination.
boolean	hasStaticPathTo(AbstractFrame destination) Determines if this frame has a static path to the destination.
boolean	isChildOf(AbstractFrame frame) Checks whether the given frame is an ancestor of this frame.
boolean	isCloseTo(AbstractFrame other, double maxCartDist, double maxRotDist) Tests whether this frame lies close to another frame in space.
protected void	orientateLikeInternal(AbstractFrame other) Changes the orientation of this frame the frame to match the orientation of the specified frame.
void	removeAdditionalParameter(String keyValue) Remove additional information from this frame.
double	rotationalDistanceTo(AbstractFrame other) Calculates the rotational distance from this frame to the other frame.
protected void	setName(String name) Sets the name of this frame.
protected void	setParent(AbstractFrame parent) Sets the reference frame (parent) for this frame.
protected void	setParentAndTransformation(AbstractFrame parentFrame, ITransformation offsetFromParent) Sets parent for the frame and the transformation from this parent.
void	setRedundancyInformation(Robot robot, IRedundancyCollection redundancy) Sets the redundancy information for this frame for a specific transformation provider.
void	setRedundancyInformation(String providerName, IRedundancyCollection redundancy) Sets the redundancy information for this frame for a specific transformation provider.
protected void	setTransformationFromParent(ITransformation offsetFromParent) Sets the transformation of the frame.
void	setTransformationProvider(ITransformationProvider provider) Sets the transformation provider of this frame.
Transformation	staticTransformationTo(AbstractFrame destination) Calculates the static transformation from this frame to the given destination frame.
String	toString()
String	toStringInWorld() Prints the frame's position in the world coordinate system.
String	toStringTrafo() Prints the frame's transformation to its parent.
Transformation	transformationFromWorld() Calculates the transformation from the world to the frame.
Transformation	transformationTo(AbstractFrame destination) Calculates the transformation from this frame to the given destination frame.
protected void	transformInternal(AbstractFrame reference, ITransformation offset) Transforms this frame relative to the given frame with the specified offset.

Methods inherited from class java.lang.Object

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

Field Detail

LEGACY_REDUNDANCE_KEY

public static final String LEGACY_REDUNDANCE_KEY

Legacy redundancy key.

See Also:

Constant Field Values

NAME_SEPARATOR

public static final String NAME_SEPARATOR

Separator for frame path segments.

See Also:

Constant Field Values

COMMENT_PARAMETER

public static final String COMMENT_PARAMETER

Key for the additional frame data "Comment".

See Also:

Constant Field Values

TEACHINFO_PARAMETER

public static final String TEACHINFO_PARAMETER

Key for the additional frame data "TeachInformation".

See Also:

Constant Field Values

USE_AS_BASE

public static final String USE_AS_BASE

Key for the additional frame data "UseAsBase".

Note: The this constant was formerly known as USE_AS_BASE_FOR_JOGGING. The name was changed to clarify that bases are no longer only used for jogging. TODO: Change value of this constant to UseAsBase. This requires a new version of the data.xml.

See Also:

Constant Field Values

LAST_MODIFICATION_TIME_PARAMETER

public static final String LAST_MODIFICATION_TIME_PARAMETER

Key for the additional frame data "LastModificationTime".

See Also:

Constant Field Values

MEASUREMENT_INFORMATION_PARAMETER

public static final String MEASUREMENT_INFORMATION_PARAMETER

Key for the additional frame data "MeasurementInformation".

See Also:

Constant Field Values

Constructor Detail

AbstractFrame

protected AbstractFrame(ITransformationProvider provider)

Creates a new AbstractFrame with the given TransformationProvider.

Parameters:

provider - the given transformationProvider

Method Detail

getRedundancyInformation

public Map<String,IRedundancyCollection> getRedundancyInformation()

Gets the map containing all redundancy informations for this frame.

Returns:

the map of all redundancy informations.

getAdditionalFrameData

public Map<String,Object> getAdditionalFrameData()

Gets the map containing all additional parameters defined for this frame. No redundancy data contained in this collection.

Returns:

the map of all additional parameters defined for this frame.

getAdditionalParameter

public Object getAdditionalParameter(String key)

Gets the additional frame parameter for the specified key.

Parameters:

key - parameter key.

Returns:

frame parameter or null if no parameter for the specified key found.

hasAdditionalParameter

public boolean hasAdditionalParameter(String key)

Indicates whether the addition parameter is known or not.

Parameters:

key - parameter key

Returns:

true if additional parameter is known.

transformationFromWorld

public Transformation transformationFromWorld()

Calculates the transformation from the world to the frame.

Returns:

The transformation from the world to the frame.

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

getParent

public AbstractFrame getParent()

Gets the parent frame of this frame.

Returns null if this frame is a root of a frame tree.

Returns:

The parent frame of this frame.

getTransformationFromParent

public Transformation getTransformationFromParent()

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

Returns:

The transformation from the parent to this frame.

Throws:

IllegalStateException - if the frame does not have a parent

getTransformationProvider

public ITransformationProvider getTransformationProvider()

Gets the transformation provider of this frame.

Returns:

the transformation provider of this frame.

setTransformationFromParent

protected void setTransformationFromParent(ITransformation offsetFromParent)

Sets the transformation of the frame.

Parent of the frame must be at before setting the transformation. Please use setParentAndTransformation(com.kuka.roboticsAPI.geometricModel.AbstractFrame, com.kuka.roboticsAPI.geometricModel.math.ITransformation) to set both at once.

Parameters:

offsetFromParent - the new transformation from parent to the frame.

Throws:

IllegalStateException - if the frame does not have a parent.

setParentAndTransformation

protected void setParentAndTransformation(AbstractFrame parentFrame,
                                          ITransformation offsetFromParent)

Sets parent for the frame and the transformation from this parent.

Parameters:

parentFrame - a new parent to set.

offsetFromParent - an offset from the new parent

setTransformationProvider

public void setTransformationProvider(ITransformationProvider provider)

Sets the transformation provider of this frame.

Parameters:

provider - the new transformation provider of this frame.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

hasStaticPathTo

public boolean hasStaticPathTo(AbstractFrame destination)

Determines if this frame has a static path to the destination.

A static path is a path that does not go over the frames with dynamic transformations between them.

Parameters:

destination - the destination frame.

Returns:

True if a static path exists.

hasPathTo

public boolean hasPathTo(AbstractFrame destination)

Determines if this frame has a path to the destination.

Parameters:

destination - the destination frame.

Returns:

true if a path exists.

setParent

protected void setParent(AbstractFrame parent)

Sets the reference frame (parent) for this frame.

If the frame is already a child of another parent, it will get removed automatically from it's old parent.

Parameters:

parent - The new parent. Can be null to indicate that the frame has not parent and is therefore a root frame.

toString

public String toString()

Overrides:

toString in class Object

toStringTrafo

public String toStringTrafo()

Prints the frame's transformation to its parent.

Returns:

a string representing the transformation to the frame's parent.

toStringInWorld

public String toStringInWorld()

Prints the frame's position in the world coordinate system.

Returns:

a string representing the transformation from world.

See Also:

transformationFromWorld()

setName

protected void setName(String name)

Sets the name of this frame.

Parameters:

name - The name of this frame.

getName

public String getName()

Gets the name of this frame.

Returns:

the name of this frame.

distanceTo

public double distanceTo(AbstractFrame other)

Calculates the euclidean distance of the frame to the specified destination frame.

Parameters:

other - the destination frame.

Returns:

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

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

rotationalDistanceTo

public double rotationalDistanceTo(AbstractFrame other)

Calculates the rotational distance from this frame to the 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.

Parameters:

other - another frame

Returns:

the positive rotational distance to the other frame in [rad]

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

isCloseTo

public boolean isCloseTo(AbstractFrame other,
                         double maxCartDist,
                         double maxRotDist)

Tests whether this frame lies close to another frame in space. This function compares the cartesian distance of the origin of the two frames, and the rotational distance of the orientation of the frames.

Parameters:

other - the other frame to test

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

maxRotDist - 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.

See Also:

distanceTo(AbstractFrame), rotationalDistanceTo(AbstractFrame)

getOriginOf

public Point getOriginOf(AbstractFrame other)

Gets the position vector of the other frame's origin relative to this frame's coordinate system.

Parameters:

other - Some frame.

Returns:

The position vector of the other frame's origin relative to this frame's coordinate system in [mm].

transformationTo

public Transformation transformationTo(AbstractFrame destination)

Calculates the transformation from this frame to the given destination frame.

Parameters:

destination - the frame to which the transformation will be calculated.

Returns:

the calculated transformation from this frame to the given frame.

Throws:

PathNotFoundException - if path from this frame to destination frame does not exist.

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

staticTransformationTo

public Transformation staticTransformationTo(AbstractFrame destination)

Calculates the static transformation from this frame to the given destination frame. Only static relations will be used to find the path between the frames.

Parameters:

destination - the frame to which the transformation will be calculated.

Returns:

the calculated transformation from this frame to the given frame.

Throws:

PathNotFoundException - if static path from this frame to destination frame does not exist.

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

copy

public Frame copy()

Creates a snapshot copy of the information in this frame into a new Frame. The parent of the new frame will be the same as the parent of this frame (note: the parent can be null). The new frame's transformation to the parent will be a snapshot of the current transformation of this frame.

Returns:

a copy of this frame

copy

public Frame copy(AbstractFrame newParent)

Creates a snapshot copy of the information in this frame into a new Frame, with the given Frame set as the parent of the new frame. The new frame's transformation to its new parent will be a snapshot of the current transformation of this frame to the new parent. Copies the information of this Frame into a new Frame, with the given Frame set as the parent of the new frame.

Parameters:

newParent - the parent for the newly created copy of this frame

Returns:

a copy of this frame with the given frame as parent.

Throws:

PathNotFoundException - if path from this frame to the new parent frame does not exist.

copyWithRedundancy

public Frame copyWithRedundancy()

Creates a snapshot copy of the information in this frame (including redundancy information) into a new Frame. The parent of the new frame will be the same as the parent of this frame (note: the parent can be null). The new frame's transformation to the parent will be a snapshot of the current transformation of this frame.

Returns:

A copy of this frame (including redundancy information)

copyWithRedundancy

public Frame copyWithRedundancy(AbstractFrame newParent)

Creates a snapshot copy of the information in this frame (including redundancy information) into a new Frame, with the given Frame set as the parent of the new frame. The new frame's transformation to its new parent will be a snapshot of the current transformation of this frame to the new parent.

Parameters:

newParent - the parent for the newly created copy of this frame

Returns:

a copy of this frame (including redundancy information) with the given frame as parent.

Throws:

PathNotFoundException - if path from this frame to the new parent frame does not exist.

findRoot

protected AbstractFrame findRoot()

Gets the root of this frame.

Can be the frame itself if no parent is set for the frame.

Returns:

the root of this frame.

getAllParametersOfType

public <T> Map<String,T> getAllParametersOfType(Class<T> paramType)

Gets all parameters of this frame of the specified type.

Type Parameters:

T - parameter type

Parameters:

paramType - type of the parameters to get

Returns:

map of parameter having the specified type

removeAdditionalParameter

public void removeAdditionalParameter(String keyValue)

Remove additional information from this frame.

Parameters:

keyValue - key, e.g. type name of specific additional data to remove

isChildOf

public boolean isChildOf(AbstractFrame frame)

Checks whether the given frame is an ancestor of this frame.

Parameters:

frame - frame which should be the ancestor of this frame.

Returns:

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

getPath

public String getPath()

Gets the path from this frame to the worlds root frame.

Returns:

a string with full path from this frame to world.

getPathFrom

public String getPathFrom(AbstractFrame frame)

Gets the path from this frame to the given frame if both frames are part of the scene graph.

Parameters:

frame - the frame to which the path should be given.

Returns:

a string with full path from this frame to the given frame.

transformInternal

protected void transformInternal(AbstractFrame reference,
                                 ITransformation offset)

Transforms this frame relative to the given frame with the specified offset.

This frame and all its children will change their absolute position.

Parameters:

reference - reference frame

offset - new transformation relative to the reference frame

orientateLikeInternal

protected void orientateLikeInternal(AbstractFrame other)

Changes the orientation of this frame the frame to match the orientation of the specified frame. The translation of the frame stays the same.

This method only works if a path exists between the two frames.

Parameters:

other - the other frame.

setRedundancyInformation

public void setRedundancyInformation(Robot robot,
                                     IRedundancyCollection redundancy)

Sets the redundancy information for this frame for a specific transformation provider.

Parameters:

robot - robot for which redundancy information should be set

redundancy - redundancy information to set

setRedundancyInformation

public void setRedundancyInformation(String providerName,
                                     IRedundancyCollection redundancy)

Sets the redundancy information for this frame for a specific transformation provider.

Parameters:

providerName - provider name. See Device.getUniqueName which redundancy information should be set

redundancy - redundancy information to set

getRedundancyInformationForDevice

public IRedundancyCollection getRedundancyInformationForDevice(Robot robot)

Gets the redundancy information of a specific Device for this Frame.

Parameters:

robot - Device to get the corresponding redundancy information for. Can not be null.

Returns:

Redundancy information for given device or 'null'