com.kuka.geometry
Class ObjectFrame

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

All Implemented Interfaces:

IMovable

public class ObjectFrame
extends Frame
implements IMovable

Represents a frame that belongs to a SpatialObject. Object frames describe the geometric structure of a spatial object. Every object frame has references to its parent as well as to its children.

An object frame differs from a temporary frame in the following ways:

• An object frame belongs to one SpatialObject.
• As long as the object frame is owned by a SpatialObject, it will not be garbage collected.
• Every object frame has a name that is unique on the same hierarchy level (i.e. object frames under the same parent must have unique names).
• An object frame can be accessed by giving its path (see getPath()) to SpatialObject.getFrame(String) on its owner object.
• An object frame can only be created by one of the createFrame methods of SpatialObject.
• An object frame is thread safe.

Field Summary

static String

PATH_SEPARATOR Separator for frame path segments.

Method Summary

Map<String,Object>	getAdditionalFrameData() Gets the map containing all additional parameters defined for this frame.
Object	getAdditionalParameter(String key) Gets an additional frame parameter for the specified key.
List<ObjectFrame>	getAllChildren() Returns a list of all children of this frame, plus all of these children's children and so on.
ObjectFrame	getChild(String fullPath) Returns the child frame with the specified name.
List<ObjectFrame>	getChildren() Returns a new list containing child frames of this frame.
IFrameConnection	getConnectionFromParent() Returns the connection from the parent frame to this frame.
String	getId() Gets the attribute Id.
String	getName() Returns the name of this frame.
SpatialObject	getOwner() Returns the spatial object that owns this frame.
ObjectFrame	getParent() Returns the parent frame.
String	getPath() Returns the path to this frame relative to the root frame of the owner object.
IMotionContainer	move(IMotion motion) Moves this object according to the given motion.
IMotionContainer	move(IMotion motion, IMotionContainerListener listener) Moves this object according to the given motion.
IMotionContainer	moveAsync(IMotion motion) Moves this object according to the given motion.
IMotionContainer	moveAsync(IMotion motion, IMotionContainerListener listener) Moves this frame according to the given motion.
void	removeAdditionalParameter(String key) Removes an additional frame parameter for the specified key.
void	setAdditionalParameter(String key, Object value) Sets an additional frame parameter with specified key and value.
void	setConnectionFromParent(IFrameConnection connection) Changes the connection to the parent of this frame.
protected void	setId(String id) Sets the attribute Id.
void	setName(String name) Sets the name of this frame.
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	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	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 com.kuka.geometry.Frame

calculateTransformationTo, distanceTo, getRedundancyDataMap, getRedundancyInformation, getTransformationFromParent, hasAncestor, hasPathTo, hasStaticPathTo, isNearTo, representationOf, representationOf, rotate, rotate, rotateTo, rotationalDistanceTo, setRedundancyInformation, toString, transform, translate, translate

Methods inherited from class java.lang.Object

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

Field Detail

PATH_SEPARATOR

public static final String PATH_SEPARATOR

Separator for frame path segments.

See Also:

Constant Field Values

Method Detail

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.

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

getAdditionalParameter

public Object getAdditionalParameter(String key)

Gets an additional frame parameter for the specified key.

Parameters:

key - parameter key.

Returns:

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

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

setAdditionalParameter

public void setAdditionalParameter(String key,
                                   Object value)

Sets an additional frame parameter with specified key and value.

Parameters:

key - parameter key

value - parameter value

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

removeAdditionalParameter

public void removeAdditionalParameter(String key)

Removes an additional frame parameter for the specified key.

Parameters:

key - key of the parameter to remove.

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

getOwner

public SpatialObject getOwner()

Returns the spatial object that owns this frame.

Returns:

the spatial object that owns this frame.

getChildren

public List<ObjectFrame> getChildren()

Returns a new list containing child frames of this frame. Children of the frame are the frames that have this frame as parent.

Returns:

a new list of child frames of this frame. An empty list if the frame has no child frames.

getAllChildren

public List<ObjectFrame> getAllChildren()

Returns a list of all children of this frame, plus all of these children's children and so on.

Returns:

a list of all of this frame's children and their children's children

getChild

public ObjectFrame getChild(String fullPath)

Returns the child frame with the specified name.

Parameters:

fullPath - relative path to the child frame to be obtained

Returns:

a child frame with the specified path

Throws:

IllegalArgumentException - if childName is null or empty string, or if the child frame with the specified name does not exist.

getPath

public String getPath()

Returns the path to this frame relative to the root frame of the owner object. The frame path is a string that contains the names of all frames on the way from the root frame of the owner object to this frame separated with "/".

Returns:

the path to this frame as seen from the owner object. If this frame is the root frame of the owner object, an empty string is returned. Otherwise, the path starts with a "/" character, followed by the frame names along the hierarchy, separated by "/".

Throws:

IllegalStateException - if the frame has no owner object

getParent

public ObjectFrame getParent()

Description copied from class: Frame

Returns the parent frame.

Overrides:

getParent in class Frame

Returns:

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

setConnectionFromParent

public void setConnectionFromParent(IFrameConnection connection)

Description copied from class: Frame

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.

Overrides:

setConnectionFromParent in class Frame

Parameters:

connection - the new type of connection to the parent frame

Throws:

IllegalStateException - if this frame has no parent

See Also:

IFrameConnection

getName

public String getName()

Description copied from class: Frame

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 getChild(String)), or it might simply be used to print the name in Frame.toString().

Overrides:

getName in class Frame

Returns:

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

getConnectionFromParent

public IFrameConnection getConnectionFromParent()

Returns the connection from the parent frame to this frame.

Overrides:

getConnectionFromParent in class Frame

Returns:

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

See Also:

getParent(), IFrameConnection

translateTo

public void translateTo(Frame target)

Description copied from class: Frame

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.

Overrides:

translateTo in class Frame

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)

transform

public void transform(Frame reference,
                      ITransformation delta)

Description copied from class: Frame

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));

Overrides:

transform in class Frame

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(Frame, ITransformation), Frame.translate(com.kuka.math.geometry.Vector3D), Frame.rotate(com.kuka.math.geometry.IRotation)

transformTo

public void transformTo(Frame target)

Description copied from class: Frame

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.

Overrides:

transformTo in class Frame

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), Frame.rotateTo(Frame)

setName

public void setName(String name)

Sets the name of this frame.

Overrides:

setName in class Frame

Parameters:

name - any string, including null or "".

Throws:

IllegalArgumentException - if this frame has a sibling with the name that is supposed to be set or if the given name is null

move

public IMotionContainer move(IMotion motion)

Description copied from interface: IMovable

Moves this object according to the given motion.

The motion will be performed by a robot (or some other device) that should be found in the kinematic chain between this frame and the world origin (or the destination of the specified motion). If such a robot is not found - IllegalStateException will be thrown.
If the specified motion is a cartesian motion - it is this frame that will reach the destination and/or follow the path defined by the motion. If the motion is joint specific - the motion directly affects the joints of the robot connected with this frame.

Specified by:

move in interface IMovable

Parameters:

motion - the motion that should be executed

Returns:

the execution container containing runtime information for the execution of the motion

moveAsync

public IMotionContainer moveAsync(IMotion motion)

Description copied from interface: IMovable

Moves this object according to the given motion.

The motion will be performed by a robot (or some other device) that should be found in the kinematic chain between this frame and the world origin (or the destination of the specified motion). If such a robot is not found - IllegalStateException will be thrown.
If the specified motion is a cartesian motion - it is this frame that will reach the destination and/or follow the path defined by the motion. If the motion is joint specific - the motion directly affects the joints of the robot connected with this frame.

This is an asynchronous call and will return immediately.

Specified by:

moveAsync in interface IMovable

Parameters:

motion - the motion that should be executed

Returns:

the execution container containing runtime information for the execution of the motion

move

public IMotionContainer move(IMotion motion,
                             IMotionContainerListener listener)

Description copied from interface: IMovable

Moves this object according to the given motion.

The motion will be performed by a robot (or some other device) that should be found in the kinematic chain between this frame and the world origin (or the destination of the specified motion). If such a robot is not found - IllegalStateException will be thrown.
If the specified motion is a cartesian motion - it is this frame that will reach the destination and/or follow the path defined by the motion. If the motion is joint specific - the motion directly affects the joints of the robot connected with this frame.

Specified by:

move in interface IMovable

Parameters:

motion - the motion that should be executed

listener - listener for the motion container

Returns:

the execution container containing runtime information for the execution of the motion

moveAsync

public IMotionContainer moveAsync(IMotion motion,
                                  IMotionContainerListener listener)

Description copied from interface: IMovable

Moves this frame according to the given motion.

The motion will be performed by a robot (or some other device) that should be found in the kinematic chain between this frame and the world origin (or the destination of the specified motion). If such a robot is not found - IllegalStateException will be thrown.
If the specified motion is a cartesian motion - it is this frame that will reach the destination and/or follow the path defined by the motion. If the motion is joint specific - the motion directly affects the joints of the robot connected with this frame.

This is an asynchronous call and will return immediately.

Specified by:

moveAsync in interface IMovable

Parameters:

motion - the motion that should be executed

listener - listener for the motion container

Returns:

the execution container containing runtime information for the execution of the motion

getId

public String getId()

Gets the attribute Id.

Returns:

the value of attribute Id

setId

protected void setId(String id)

Sets the attribute Id. Used internally by the persistence layer of the scene graph. Not intended to be used by robot application developers!

Parameters:

id - the value of attribute Id: unique identifier fulfilling XML naming requirements