com.kuka.roboticsAPI.geometricModel
Class ObjectFrame

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

public class ObjectFrame
extends AbstractFrame

Base class for all frames that belong to spatial objects. Initialized with an object.

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

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

protected	ObjectFrame(String name, ObjectFrame parent, ITransformation offset) Creates a new frame with the specified parent and the given transformation from the parent.
	ObjectFrame(String name, ObjectFrame parent, SceneGraphObject owner, ITransformationProvider transformationProvider) Creates a new ObjectFrame instance with the given name, the given parent frame and owner.
protected	ObjectFrame(String name, SceneGraphObject owner, ObjectFrame parent) Creates a new ObjectFrame instance with the given name and the owners base frame as parent.
protected	ObjectFrame(String id, String name, ObjectFrame parent, ITransformation offset) Creates a new frame with the specified parent and the given transformation from the parent.
protected	ObjectFrame(String id, String name, SceneGraphObject owner, ObjectFrame parent) Creates a new ObjectFrame instance with the given id, name and the owners base frame as parent.

Method Summary

protected void	addChild(ObjectFrame frame) Adds the frame to this frames children list, if it's not a child yet.
void	attachTo(ObjectFrame frame) Attaches the owner object of this frame to another object by creating the geometric link between this frame and the specified frame with the MatrixTransformation.IDENTITY transformation.
void	attachTo(ObjectFrame frame, ITransformation trans) Attaches the owner object of this frame to another object by creating the geometric link between this frame and the specified frame with the specified transformation.
protected void	changeParent(ObjectFrame parent) Changes the parent of this frame.
double	getAlphaRad()
double	getBetaRad()
ObjectFrame	getChild(String childName) Gets the child frame with the given childName if it is a child of this frame.
List<ObjectFrame>	getChildren() Deprecated. This method contains an inherent threading flaw; use getChildrenSnapshot() instead.
List<ObjectFrame>	getChildrenSnapshot() Returns a snapshot of this frame's direct child frames.
double	getGammaRad()
String	getId()
SceneGraphObject	getOwner() Gets the owner object to which this frame belongs to.
ObjectFrame	getParent() Gets the parent frame of this frame.
double	getX()
double	getY()
double	getZ()
protected void	internalSetOwner(SceneGraphObject newOwner) Sets a new owner to this frame and all children of the old object.
protected boolean	isPartOfSubTree(ObjectFrame frame) Checks if the given frame appears in the current ObjectFrames children.
IMotionContainer	move(IMotion motion) Moves this frame according to the given motion.
IMotionContainer	move(IMotion motion, IMotionContainerListener listener) Moves this frame according to the given motion.
IMotionContainer	moveAsync(IMotion motion) Moves this frame according to the given motion.
IMotionContainer	moveAsync(IMotion motion, IMotionContainerListener listener) Moves this frame according to the given motion.
protected void	removeChild(ObjectFrame frame) Removes the given frame from this frames the children list.
void	setAdditionalParameter(String key, Object value) Sets the additional parameter for this frame.
protected void	setOwner(SceneGraphObject owner) Sets a new owner for this frame.
protected void	setParent(AbstractFrame parent) Sets the reference frame (parent) for this frame.
protected void	unregisterFromParent() Removes the parent's reference to this frame, so that it and its children can get garbage collected.

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

copy, copy, copyWithRedundancy, copyWithRedundancy, distanceTo, findRoot, getAdditionalFrameData, getAdditionalParameter, getAllParametersOfType, getName, getOriginOf, getPath, getPathFrom, getRedundancyInformation, getRedundancyInformationForDevice, getTransformationFromParent, getTransformationProvider, hasAdditionalParameter, hasPathTo, hasStaticPathTo, isChildOf, isCloseTo, orientateLikeInternal, removeAdditionalParameter, rotationalDistanceTo, setName, setParentAndTransformation, setRedundancyInformation, setRedundancyInformation, setTransformationFromParent, 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

ObjectFrame

public ObjectFrame(String name,
                   ObjectFrame parent,
                   SceneGraphObject owner,
                   ITransformationProvider transformationProvider)

Creates a new ObjectFrame instance with the given name, the given parent frame and owner. Sets the specified owner to the frames owner.

Parameters:

name - the name of the frame.

parent - the new parent frame. Can be null.

owner - the object to which the new frame should belong.

transformationProvider - the new transformation for this frame.

ObjectFrame

protected ObjectFrame(String name,
                      ObjectFrame parent,
                      ITransformation offset)

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

The owner of the frame will be set to parent's owner.

Parameters:

name - the name of the new frame.

parent - the new parent frame. Can not be null.

offset - the transformation from the parent.

ObjectFrame

protected ObjectFrame(String id,
                      String name,
                      ObjectFrame parent,
                      ITransformation offset)

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

The owner of the frame will be set to parent's owner.

Parameters:

id - the id of the frame.

name - the name of the new frame.

parent - the new parent frame. Can not be null.

offset - the transformation from the parent.

ObjectFrame

protected ObjectFrame(String name,
                      SceneGraphObject owner,
                      ObjectFrame parent)

Creates a new ObjectFrame instance with the given name and the owners base frame as parent. Sets the specified owner to the frames owner.

Parameters:

name - the name of the frame.

owner - the new owner object of this frame.

parent - the new parent of this frame. May be null for base Frames.

Throws:

IllegalArgumentException - if target or owner are null.

ObjectFrame

protected ObjectFrame(String id,
                      String name,
                      SceneGraphObject owner,
                      ObjectFrame parent)

Creates a new ObjectFrame instance with the given id, name and the owners base frame as parent. Sets the specified owner to the frames owner.

Parameters:

id - the id of the frame.

name - the name of the frame.

owner - the new owner object of this frame.

parent - the new parent of this frame. May be null for base Frames.

Throws:

IllegalArgumentException - if target or owner are null.

Method Detail

unregisterFromParent

protected void unregisterFromParent()

Removes the parent's reference to this frame, so that it and its children can get garbage collected.

addChild

protected void addChild(ObjectFrame frame)

Adds the frame to this frames children list, if it's not a child yet.

Parameters:

frame - the frame which will be added to the children list.

internalSetOwner

protected void internalSetOwner(SceneGraphObject newOwner)

Sets a new owner to this frame and all children of the old object.

Parameters:

newOwner - the owner object

setOwner

protected void setOwner(SceneGraphObject owner)

Sets a new owner for this frame. null is not allowed because an ObjectFrame needs an owner.

Parameters:

owner - the new owner of this frame.

getId

public String getId()

Returns:

the (project wide) unique id of the frame.

removeChild

protected void removeChild(ObjectFrame frame)

Removes the given frame from this frames the children list.

Parameters:

frame - the frame that will be removed from this frames children list.

getParent

public ObjectFrame getParent()

Description copied from class: AbstractFrame

Gets the parent frame of this frame.

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

Overrides:

getParent in class AbstractFrame

Returns:

The parent frame of this frame.

getChildren

@Deprecated
public List<ObjectFrame> getChildren()

Deprecated. This method contains an inherent threading flaw; use getChildrenSnapshot() instead.

Gets the list of all next level child frames.

The returned list is unmodifiable since frames should always be added by using one of the SceneGraphObject.addChildFrame(..) methods.

Returns:

the unmodifiable list with all next level child frames of the given frame.

getChildrenSnapshot

public List<ObjectFrame> getChildrenSnapshot()

Returns a snapshot of this frame's direct child frames.

Returns:

a new list with the direct child frames of this frame

getChild

public ObjectFrame getChild(String childName)

Gets the child frame with the given childName if it is a child of this frame. If there is no frame with the given childName null will be returned.

Parameters:

childName - the child frame name which should be searched for.

Returns:

the child frame if there exists a child frame with the given name. null if there is no child frame with the given name.

getOwner

public SceneGraphObject getOwner()

Gets the owner object to which this frame belongs to. The owner can not be null because an ObjectFrame can not be initialized without an ObjectFrame.

Returns:

the owner to which this frame belongs to.

attachTo

public void attachTo(ObjectFrame frame)

Attaches the owner object of this frame to another object by creating the geometric link between this frame and the specified frame with the MatrixTransformation.IDENTITY transformation.

If the owner object is grouped to the former parent object ( groupToParent()), the whole group will be attached to the new parent, not only the calling object.

Parameters:

frame - the new parent frame for the object frame. It should belong to the object to which the owner of this frame should be attached.

Throws:

IllegalStateException - if owner of this frame is null.

IllegalStateException - if owner is not instance of SpatialObject.

IllegalStateException - if the specified target frame belongs to the same object as this frame.

attachTo

public void attachTo(ObjectFrame frame,
                     ITransformation trans)

Attaches the owner object of this frame to another object by creating the geometric link between this frame and the specified frame with the specified transformation.

If the owner object is grouped to the former parent object ( groupToParent()), the whole group will be attached to the new parent, not only the calling object.

Parameters:

frame - the new parent frame for the object frame. It should belong to the object to which the owner of this frame should be attached.

trans - the transformation from the specified target frame to this frame.

Throws:

IllegalArgumentException - if frame or transformation are null.

IllegalStateException - if owner of this frame is null.

IllegalStateException - if owner is not instance of SpatialObject.

IllegalStateException - if the specified target frame belongs to the same object as this frame.

changeParent

protected void changeParent(ObjectFrame parent)

Changes the parent of this frame.

If a new parent is set by this method, this frame will be removed from the children list of the old parent.

Parameters:

parent - new parent frame for this frame.

setParent

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

isPartOfSubTree

protected boolean isPartOfSubTree(ObjectFrame frame)

Checks if the given frame appears in the current ObjectFrames children. It will be searched in all child layers below the current ObjectFrame.

Parameters:

frame - the frame to search for.

Returns:

true if the given frame is part of the subtree, else false.

moveAsync

public IMotionContainer moveAsync(IMotion motion)

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.

Parameters:

motion - the motion that should be executed

Returns:

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

Throws:

IllegalArgumentException - if motion is null

IllegalStateException - if no robot that can execute the specified motion found

moveAsync

public IMotionContainer moveAsync(IMotion motion,
                                  IMotionContainerListener listener)

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.

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

Throws:

IllegalStateException - if no robot that can execute the specified motion found

move

public IMotionContainer move(IMotion motion)

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.

Parameters:

motion - the motion that should be executed

Returns:

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

Throws:

IllegalStateException - if no robot that can execute the specified motion found

move

public IMotionContainer move(IMotion motion,
                             IMotionContainerListener listener)

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.

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

Throws:

IllegalStateException - if no robot that can execute the specified motion found

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

setAdditionalParameter

public void setAdditionalParameter(String key,
                                   Object value)

Sets the additional parameter for this frame.

Parameters:

key - parameter key

value - parameter value