com.kuka.geometry
Class SpatialObject

java.lang.Object
  com.kuka.geometry.SpatialObject

All Implemented Interfaces:

IMovable

Direct Known Subclasses:

World

public class SpatialObject
extends Object
implements IMovable

Represents a geometric object that may be part of a scene graph.

A spatial object can have a parent object and child objects. Thus it can be placed in a tree structure which in most cases is the scene graph.
Every spatial object has a root frame getRootFrame() that describes the position of the object in space. Additionally objects can own any number of ObjectFrames that form a tree structure under the object's root frame and determine the geometric structure of the object.
Spatial objects can optionally possess load data getLoadData() which allows to set mass, center of mass and inertia of the object. Also optionally, it can possess information about the object's geometric form ( SpatialForm).

This class is thread-safe.

See Also:

SpatialObjectUtils

Field Summary

static String

PATH_SEPARATOR Name separator for object path.

Constructor Summary

	SpatialObject(String name) Creates a new spatial object instance with given name.
protected	SpatialObject(String name, String id) Creates a new spatial object instance with given name.

Method Summary

void	attachTo(ObjectFrame target) Changes the parent of the objects root frame to the given frame and sets the transformation to Transformation.IDENTITY.
void	attachTo(ObjectFrame target, Frame matchPosition) Changes the parent of the objects root frame to the given frame and moves it to the matchingPosition in space.
void	attachTo(ObjectFrame target, ITransformation rootDelta) Changes the parent of objects root frame to the given frame and sets the given transformation.
void	attachWithCurrentPositionTo(ObjectFrame target) Changes the parent of the objects root frame to the given frame and keeps the position in space of this object.
ObjectFrame	createFrame(String name, IFrameConnection parentConnection) Creates a new object frame that belongs to this object.
ObjectFrame	createFrame(String name, ITransformation transformationFromParent) Creates a new object frame that belongs to this object.
ObjectFrame	createFrame(String name, ObjectFrame parent, IFrameConnection parentConnection) Creates a new object frame that belongs to this object.
ObjectFrame	createFrame(String name, ObjectFrame parent, ITransformation transformationFromParent) Creates a new object frame that belongs to this object.
ObjectFrame	createFrameFrom(Frame source) Creates a new object frame that belongs to this object.
void	detach() Detaches the SpatialObject from its parent and sets this objects parent to null.
protected SpatialObject	findRootObject() Searches the root SpatialObject in the object tree containing the element object.
List<SpatialObject>	getAllChildObjects() Returns a list of all children of this object, plus all of the children's children and so on.
List<ObjectFrame>	getAllFrames() Gets all frames belonging to this object.
SpatialObject	getChildObject(String path) Gets the child object with the specified path.
List<SpatialObject>	getChildObjects() Returns a list of all direct children of this object.
ObjectFrame	getDefaultMotionFrame() Gets the current defaultMotionFrame.
SpatialForm	getForm() Gets the spatial form of this object.
ObjectFrame	getFrame(String framePath) Gets the object frame belonging to the object under the specified path.
protected ReadWriteLock	getFrameLock() Returns a Lock object that can be used to lock all ObjectFrames owned by this SpatialObject.
String	getId() Gets the attribute Id.
LoadData	getLoadData() Gets the load data of this object.
String	getName() Gets the name of the object.
SpatialObject	getParentObject() Gets the parent of this object.
ObjectFrame	getRootFrame() Gets the root frame of this object.
Object	getTag(String key) Gets the data stored under the given key.
IUserParameters	getUserParameters() Gets a collection of user parameters that belong to this object.
boolean	hasAncestor(SpatialObject obj) Returns true if the given object is an ancestor (parent, grand parent, etc...) of this.
boolean	hasDescendant(SpatialObject obj) Returns true if the given object is a descendant (child, grandchild, etc...) of this.
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	removeForm() Removes the spatial form from this object.
void	removeFrame(ObjectFrame frame) Removes the specified object frame from the object and disconnects it from its parent frame.
void	setDefaultMotionFrame(ObjectFrame defaultMotionFrame) Sets the defaultMotionFrame of the object.
void	setForm(SpatialForm form, ObjectFrame reference) Sets a spatial form for this object.
protected void	setId(String id) Sets the attribute Id.
void	setLoadData(LoadData load) Sets the load data of this object.
void	setName(String name) Sets the name of the SpatialObject.
void	setTag(String key, Object value) Stores data under the given key.
String	toString()
protected SpatialObject	tryGetChild(String path) Gets the child object with the specified path.

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

Name separator for object path.

See Also:

Constant Field Values

Constructor Detail

SpatialObject

public SpatialObject(String name)

Creates a new spatial object instance with given name.

Parameters:

name - object name

SpatialObject

protected SpatialObject(String name,
                        String id)

Creates a new spatial object instance with given name.

Parameters:

name - object name

uuid - object identification

Method Detail

getName

public String getName()

Gets the name of the object.

Returns:

the name of the object.

getRootFrame

public ObjectFrame getRootFrame()

Gets the root frame of this object.

A spatial object always has a root frame (ObjectFrame) which cannot be removed.
This frame is the root of the frame tree that describes the geometric structure of the object. All frames owned by this object (ObjectFrame.getOwner()) must be part of this tree.

Returns:

the root frame of this object.

createFrame

public ObjectFrame createFrame(String name,
                               ITransformation transformationFromParent)

Creates a new object frame that belongs to this object. The parent frame is the object root frame.

Parameters:

name - name of the new frame.

transformationFromParent - transformation from this objects root frame to the new frame.

Returns:

the newly created object frame.

createFrame

public ObjectFrame createFrame(String name,
                               ObjectFrame parent,
                               ITransformation transformationFromParent)

Creates a new object frame that belongs to this object.

Parameters:

name - name of the new frame.

parent - parent frame for the new frame. Parent frame must already belong to this object.

transformationFromParent - transformation from the parent frame to the new frame.

Returns:

the newly created object frame.

createFrame

public ObjectFrame createFrame(String name,
                               IFrameConnection parentConnection)

Creates a new object frame that belongs to this object. The parent frame is the object root frame.

Parameters:

name - name of the new frame.

parentConnection - frame connection that must provide the transformation from parent to the new frame.

Returns:

the newly created object frame.

createFrame

public ObjectFrame createFrame(String name,
                               ObjectFrame parent,
                               IFrameConnection parentConnection)

Creates a new object frame that belongs to this object.

Parameters:

name - name of the new frame.

parent - parent frame for the new frame. Parent frame must already belong to this object.

parentConnection - frame connection that must provide the transformation from parent to the new frame.

Returns:

the newly created object frame.

createFrameFrom

public ObjectFrame createFrameFrom(Frame source)

Creates a new object frame that belongs to this object. The parent of the new object frame is the root frame of this object. The name and the parent connection is copied from the source frame.

Parameters:

source - source frame

Returns:

the newly created object frame.

removeFrame

public void removeFrame(ObjectFrame frame)

Removes the specified object frame from the object and disconnects it from its parent frame.

Parameters:

frame - the frame to be removed.

Throws:

IllegalArgumentException - in any of the following cases:

• the given frame is null
• the given frame is the root frame of the object
• the given frame does not belong to this object

findRootObject

protected SpatialObject findRootObject()

Searches the root SpatialObject in the object tree containing the element object.

Returns:

the root SpatialObject of the object. If the object does not have a parent, the object itself is returned.

Throws:

IllegalArgumentException - if the given object is null

getFrame

public ObjectFrame getFrame(String framePath)

Gets the object frame belonging to the object under the specified path.

For the following frame-chain path: ROOT->P1->P2
path looks like: /P1/P2
The leading forward slash is optional.

Parameters:

framePath - path to the frame

Returns:

the object frame under the specified path

Throws:

IllegalArgumentException - if no frame exists under the specified path

getAllFrames

public List<ObjectFrame> getAllFrames()

Gets all frames belonging to this object.

Returns:

list with all frames belonging to this object.

getUserParameters

public IUserParameters getUserParameters()

Gets a collection of user parameters that belong to this object.

Returns:

collection of user parameters, see IUserParameters

getChildObject

public SpatialObject getChildObject(String path)

Gets the child object with the specified path. Child objects that are directly attached can be obtained by simply using the child objects name as path. If child objects on lower levels shall be returned, the different levels have to be separated by forward slashes ( / ). The leading forward slash is optional.

Parameters:

path - path including name of the object to look for

Returns:

child object at the specified path

Throws:

IllegalArgumentException - if no object was found among the specified path and name

tryGetChild

protected SpatialObject tryGetChild(String path)

Gets the child object with the specified path. Child objects that are directly attached can be obtained by simply using the child objects name as path. If child objects on lower levels shall be returned, the different levels have to be separated by forward slashes ( / ). The leading forward slash is optional.

Parameters:

path - path including name of the object to look for

Returns:

child object at the specified path

Throws:

IllegalArgumentException - if no object was found among the specified path and name

getChildObjects

public List<SpatialObject> getChildObjects()

Returns a list of all direct children of this object.

Returns:

a list of all direct children

getAllChildObjects

public List<SpatialObject> getAllChildObjects()

Returns a list of all children of this object, plus all of the children's children and so on.

Returns:

a list of all children and children's children

getParentObject

public SpatialObject getParentObject()

Gets the parent of this object.

Returns:

the parent of this object. Can return null if the object is the root object in a tree.

setName

public void setName(String name)

Sets the name of the SpatialObject. An object name must be unique on the same hierarchy level (i.e. spatial objects under the same parent object must have unique names).

Parameters:

name - the new name to be set. May not be null or empty.

Throws:

IllegalArgumentException - if the given name is null or empty

IllegalStateException - if another object under the same parent already has the given name. The name of this object remains unchanged.

getFrameLock

protected ReadWriteLock getFrameLock()

Returns a Lock object that can be used to lock all ObjectFrames owned by this SpatialObject. Using this lock, operations such as traversing frame trees, calculating connections between frames, adding child frames etc. can be performed in a thread safe manner.

Note: this method only returns the Lock itself! This method does not perform any locking whatsoever. The actual locking will have to be performed by the caller on the returned lock object.

Returns:

the Lock object used to lock the entire tree this SpatialObject is part of

getLoadData

public LoadData getLoadData()

Gets the load data of this object.

Returns:

load data of this object. Can return null if load data is not set.

setLoadData

public void setLoadData(LoadData load)

Sets the load data of this object.

Parameters:

load - the load data to be set

attachTo

public void attachTo(ObjectFrame target)

Changes the parent of the objects root frame to the given frame and sets the transformation to Transformation.IDENTITY. This operation is only allowed if:

• The target is not part of the object's subtree
• The target does not already contain a child with this object's name

This method is thread safe.

Parameters:

target - the new parent frame of this objects root frame

Throws:

IllegalArgumentException - if any of the arguments is null

IllegalStateException - if the above conditions are not met

attachTo

public void attachTo(ObjectFrame target,
                     ITransformation rootDelta)

Changes the parent of objects root frame to the given frame and sets the given transformation. This operation is only allowed if:

• The target frame belongs to an object (i.e. the frame was not removed from an object)
• The target is not part of the object's subtree
• The target does not already contain a child with this object's name

This method is thread safe.

Parameters:

target - the new parent frame of this objects root frame

rootDelta - the spatial transformation from the parent object to this object it is being attached to

Throws:

IllegalArgumentException - if any of the arguments is null

IllegalStateException - if the above conditions are not met

attachTo

public void attachTo(ObjectFrame target,
                     Frame matchPosition)

Changes the parent of the objects root frame to the given frame and moves it to the matchingPosition in space. This operation is only allowed if:

• The target is not part of the object's subtree
• The target does not already contain a child with this object's name

This method is thread safe.

Parameters:

target - the new parent frame of this objects root frame

matchPosition - the position in space the object is moved to

Throws:

IllegalArgumentException - if any argument is null, or if there is no connection or an unknown connection type between the given matchPosition frame and this object's root frame

IllegalStateException - if the above conditions are not met, 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)

attachWithCurrentPositionTo

public void attachWithCurrentPositionTo(ObjectFrame target)

Changes the parent of the objects root frame to the given frame and keeps the position in space of this object. This operation is only allowed if:

• The target is not part of the object's subtree
• The target does not already contain a child with this object's name

This method is thread safe.

Parameters:

target - the new parent frame of this objects root frame

Throws:

IllegalArgumentException - if the argument is null, or if there is no connection or an unknown connection type between the given target frame and this object's root frame

IllegalStateException - if the above conditions are not met, 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)

detach

public void detach()

Detaches the SpatialObject from its parent and sets this objects parent to null.

setForm

public void setForm(SpatialForm form,
                    ObjectFrame reference)

Sets a spatial form for this object.

Parameters:

form - the spatial form to be set

reference - the reference frame for the form

Throws:

IllegalArgumentException - if form or reference is null or reference doesn't belong to this object

IllegalStateException - if the reference frame of the form belongs to another object or if the form belongs already to another object

getForm

public SpatialForm getForm()

Gets the spatial form of this object.

Returns:

spatial form

removeForm

public void removeForm()

Removes the spatial form from this object.

hasDescendant

public boolean hasDescendant(SpatialObject obj)

Returns true if the given object is a descendant (child, grandchild, etc...) of this.

Parameters:

obj - the object for which to check whether it is a descendant of this

Returns:

true if the given object is a descendant (child, grandchild, etc...) of this, false otherwise

Throws:

IllegalArgumentException - if the given object is null

hasAncestor

public boolean hasAncestor(SpatialObject obj)

Returns true if the given object is an ancestor (parent, grand parent, etc...) of this.

Parameters:

obj - the object for which to check whether it is an ancestor of this

Returns:

true if the given object is a descendant (parent, grand parent, etc...) of this, false otherwise

Throws:

IllegalArgumentException - if the given object is null

toString

public String toString()

Overrides:

toString in class Object

getTag

public Object getTag(String key)

Gets the data stored under the given key.

This 'tag' can be used to save additional information about the object and to retrieve it from the object.

Parameters:

key - The key. May not be null.

Returns:

The data stored under the given key or null if not found.

See Also:

setTag(String, Object)

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

setTag

public void setTag(String key,
                   Object value)

Stores data under the given key.

This data can be retrieved later from the object.

Parameters:

key - The key. May not be null.

value - The value. May not be null.

See Also:

getTag(String)

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

setDefaultMotionFrame

public void setDefaultMotionFrame(ObjectFrame defaultMotionFrame)

Sets the defaultMotionFrame of the object. By default, the rootFrame is the defaultMotionFrame.

DefaultMotionFrame can be set only once. If set a second time IllegalStateException is thrown.

Parameters:

defaultMotionFrame - the default motion frame

getDefaultMotionFrame

public ObjectFrame getDefaultMotionFrame()

Gets the current defaultMotionFrame.

Returns:

the current defaultMotionFrame

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. Do not use!

Parameters:

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