com.kuka.roboticsAPI.geometricModel
Class Frame

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

public class Frame
extends AbstractFrame

Represents a frame whose transformation can be manipulated directly.

This class should be used for auxiliary frames created programmatically as a result of some calculations or measurements. This frame does not know its children, so every instance of this class can be garbage collected if application does not keep a reference to it.

This frame is not immutable. All properties of it can be changed. Supports setting and removing of additional parameters as well.

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

Two frames are considered equal, if and only if they reference the same object, i.e. equals() returns true, only if operator == returns true. The reason for this behaviour is, that even if two frames would represent the same position in the world coordinate system, they could have different parents in the frame graph. The testing of equality of two frames could quickly turn into comparing two branches of the frame graph. This would lead to a hidden performance cost that the user could be unaware of.

Field Summary

Fields inherited from class com.kuka.roboticsAPI.geometricModel.AbstractFrame

COMMENT_PARAMETER, LAST_MODIFICATION_TIME_PARAMETER, LEGACY_REDUNDANCE_KEY, MEASUREMENT_INFORMATION_PARAMETER, NAME_SEPARATOR, TEACHINFO_PARAMETER, USE_AS_BASE

Constructor Summary

Frame()
Creates a new frame instance.

Frame(AbstractFrame parent)
Creates a new frame with the specified parent and the no offset from it's parent.

Frame(AbstractFrame parent, double x, double y, double z)
Creates a new frame with the given parent and the given transformation from it's parent.

Frame(AbstractFrame parent, double x, double y, double z, double a, double b, double c)
Creates a new frame with the given parent and the given transformation from it's parent.

Frame(AbstractFrame parent, ITransformation offsetFromParent)
Creates a new frame with the specified parent and the given transformation from this parent.

Frame(AbstractFrame parent, StaticTransformationProvider transformationProvider)
Creates a new frame connected to the given parent with the specified transformation provider that should provide the transformation between the parent frame and the new frame.

Frame(double x, double y, double z)
Creates a new frame with the World as parent and the given translation from the world.

Frame(double x, double y, double z, double a, double b, double c)
Creates a new frame with the World as parent and the given transformation from the world.

Frame(ITransformation offset)
Creates a new frame with the World as parent and the given transformation from the world.

Method Summary

double	getAlphaRad()
double	getBetaRad()
double	getGammaRad()
double	getX()
double	getY()
double	getZ()
Frame	orientateLike(AbstractFrame other) Changes the orientation of this frame the frame to match the orientation of the specified frame.
void	removeAdditionalParameter(String key) Removes the an additional parameter of this frame.
void	setAdditionalParameter(String key, Object value) Sets the additional parameter for this frame.
Frame	setAlphaRad(double alpha) Sets the alpha angle.
Frame	setBetaRad(double beta) Sets the beta angle.
Frame	setGammaRad(double gamma) Sets the gamma angle.
void	setParent(AbstractFrame parent) Sets the reference frame (parent) for this frame.
void	setParent(AbstractFrame parent, boolean keepTrafoToWorld) Sets the reference frame (parent) for this frame.
void	setParentAndTransformation(AbstractFrame parentFrame, ITransformation offsetFromParent) Sets parent for the frame and the transformation from this parent.
void	setTransformationFromParent(ITransformation offsetFromParent) Sets the transformation of the frame.
Frame	setX(double x) Sets the X component of this frame.
Frame	setY(double y) Sets the Y component of this frame.
Frame	setZ(double z) Sets the Z component of this frame.
Frame	transform(AbstractFrame reference, ITransformation offset) Transforms this frame relative to the given reference frame with the specified offset.
Frame	transform(ITransformation offset) Transforms this frame relative to itself with the specified offset.

Methods inherited from class com.kuka.roboticsAPI.geometricModel.AbstractFrame

copy, copy, copyWithRedundancy, copyWithRedundancy, distanceTo, findRoot, getAdditionalFrameData, getAdditionalParameter, getAllParametersOfType, getName, getOriginOf, getParent, getPath, getPathFrom, getRedundancyInformation, getRedundancyInformationForDevice, getTransformationFromParent, getTransformationProvider, hasAdditionalParameter, hasPathTo, hasStaticPathTo, isChildOf, isCloseTo, orientateLikeInternal, rotationalDistanceTo, setName, setRedundancyInformation, setRedundancyInformation, setTransformationProvider, staticTransformationTo, toString, toStringInWorld, toStringTrafo, transformationFromWorld, transformationTo, transformInternal

Methods inherited from class java.lang.Object

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

Constructor Detail

Frame

public Frame()

Creates a new frame instance.

Created frame does not have a parent. And therefore its position in space is not defined.

Frame

public Frame(AbstractFrame parent,
             StaticTransformationProvider transformationProvider)

Creates a new frame connected to the given parent with the specified transformation provider that should provide the transformation between the parent frame and the new frame.

Parameters:

parent - the parent of the frame.

transformationProvider - the transformation provider for the 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.

Frame

public Frame(AbstractFrame parent,
             ITransformation offsetFromParent)

Creates a new frame with the specified parent and the given transformation from this parent.

Parameters:

parent - the parent.

offsetFromParent - the transformation from the parent.

Frame

public Frame(AbstractFrame parent)

Creates a new frame with the specified parent and the no offset from it's parent.

Transformation from parent will be set to MatrixTransformation.IDENTITY.

Parameters:

parent - the parent.

Frame

public Frame(double x,
             double y,
             double z)

Creates a new frame with the World as parent and the given translation from the world.

Parameters:

x - the x component of the translation in [mm].

y - the y component of the translation in [mm].

z - the z component of the translation in [mm].

Frame

public Frame(double x,
             double y,
             double z,
             double a,
             double b,
             double c)

Creates a new frame with the World as parent and the given transformation from the world.

Parameters:

x - the X component of the transformation in [mm].

y - the Y component of the transformation in [mm].

z - the Z component of the transformation in [mm].

a - the A component of the transformation in [rad].

b - the B component of the transformation in [rad].

c - the C component of the transformation in [rad].

Frame

public Frame(ITransformation offset)

Creates a new frame with the World as parent and the given transformation from the world.

Parameters:

offset - the transformation from the world frame.

Frame

public Frame(AbstractFrame parent,
             double x,
             double y,
             double z)

Creates a new frame with the given parent and the given transformation from it's parent.

Parameters:

parent - the parent.

x - the X component of the transformation in [mm].

y - the Y component of the transformation in [mm].

z - the Z component of the transformation in [mm].

Frame

public Frame(AbstractFrame parent,
             double x,
             double y,
             double z,
             double a,
             double b,
             double c)

Creates a new frame with the given parent and the given transformation from it's parent.

Parameters:

parent - the parent.

x - the X component of the transformation in [mm].

y - the Y component of the transformation in [mm].

z - the Z component of the transformation in [mm].

a - the A component of the transformation in [rad].

b - the B component of the transformation in [rad].

c - the C component of the transformation in [rad].

Method Detail

setTransformationFromParent

public void setTransformationFromParent(ITransformation offsetFromParent)

Description copied from class: AbstractFrame

Sets the transformation of the frame.

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

Overrides:

setTransformationFromParent in class AbstractFrame

Parameters:

offsetFromParent - the new transformation from parent to the frame.

setParentAndTransformation

public void setParentAndTransformation(AbstractFrame parentFrame,
                                       ITransformation offsetFromParent)

Description copied from class: AbstractFrame

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

Overrides:

setParentAndTransformation in class AbstractFrame

Parameters:

parentFrame - a new parent to set.

offsetFromParent - an offset from the new parent

transform

public Frame transform(AbstractFrame reference,
                       ITransformation offset)

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

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

Parameters:

reference - the reference frame.

offset - the offset.

Returns:

This frame (builder pattern),

Throws:

IllegalArgumentException - if reference or offset is null or if one of the frame relations is dynamic.

transform

public Frame transform(ITransformation offset)

Transforms this frame relative to itself with the specified offset.

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

Parameters:

offset - the offset.

Returns:

this frame (builder pattern).

Throws:

IllegalArgumentException - if reference or offset is null or if one of the frame transformation provider is dynamic.

setParent

public void setParent(AbstractFrame parent,
                      boolean keepTrafoToWorld)

Sets the reference frame (parent) for this frame.

If the parameter keepTrafoToWorld is set to true, the current absolute position (relative to the world frame) of this frame will be kept. If no path exists from this frame to the given parent and keepTrafoToWorld is true, a PathNotFoundException is thrown.

Parameters:

parent - the new parent.

keepTrafoToWorld - if set to true, the absolute position of the frame (relative to the world frame) will be kept.

setParent

public final void setParent(AbstractFrame parent)

Description copied from class: AbstractFrame

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.

Overrides:

setParent in class AbstractFrame

Parameters:

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

setAlphaRad

public Frame setAlphaRad(double alpha)

Sets the alpha angle.

Parameters:

alpha - the new alpha value in [rad]. This is the rotation around the Z axis.

Returns:

This frame (fluent interface).

setBetaRad

public Frame setBetaRad(double beta)

Sets the beta angle.

Parameters:

beta - the new beta value in [rad]. This is the rotation around the Y axis.

Returns:

this frame (fluent interface).

setGammaRad

public Frame setGammaRad(double gamma)

Sets the gamma angle.

Parameters:

gamma - the new gamma value in [rad]. This is the rotation around the X axis.

Returns:

this frame (fluent interface).

setX

public Frame setX(double x)

Sets the X component of this frame.

Parameters:

x - the new X value in [mm].

Returns:

this frame (fluent interface).

setY

public Frame setY(double y)

Sets the Y component of this frame.

Parameters:

y - the new Y value in [mm].

Returns:

this frame (fluent interface).

setZ

public Frame setZ(double z)

Sets the Z component of this frame.

Parameters:

z - the new Z value in [mm].

Returns:

this frame (fluent interface).

orientateLike

public Frame orientateLike(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.

Returns:

this frame (fluent interface).

setAdditionalParameter

public void setAdditionalParameter(String key,
                                   Object value)

Sets the additional parameter for this frame.

Parameters:

key - parameter key

value - parameter value

removeAdditionalParameter

public void removeAdditionalParameter(String key)

Removes the an additional parameter of this frame.

Overrides:

removeAdditionalParameter in class AbstractFrame

Parameters:

key - key of the parameter to remove.

getAlphaRad

public double getAlphaRad()

Returns:

the current alpha value in [rad]. This is the rotation around the Z axis.

getBetaRad

public double getBetaRad()

Returns:

the current beta value in [rad]. This is the rotation around the Y axis.

getGammaRad

public double getGammaRad()

Returns:

the current gamma value in [rad]. This is the rotation around the X axis.

getX

public double getX()

Returns:

the current X value in [mm].

getY

public double getY()

Returns:

the current Y value in [mm].

getZ

public double getZ()

Returns:

The current Z value in [mm].