shady.common.multi.chain
Class Block

java.lang.Object
  shady.common.multi.chain.Block

Direct Known Subclasses:

Sentinel, StickBlock, TowerBlock

public abstract class Block
extends java.lang.Object

Abstract block in a MultiShady chain.

MultiShady chains are connected sequences of Blocks. A block is a collection of MemberShadys and MultiSegments with fixed topology but and 1DOF variable geometry.

The actual topology and forward kinematics of a block are left for subclasses to implement in initMembersAndSegments() and recompute(vona.math.RigidTransform2D, double), respectively. A chain may contain blocks of different types as long as they are pairwise connectable, which depends on the implementations of the subclasses.

Block instances construct and are permanently associated with the MemberShadys and MultiSegments which form the block, but the barrel angles of the members are only updated when update() is called.

Every block has an "end frame" associated with it which is the coordinate frame of the end effector if the block is the end of a chain. A RigidTransform2D is available (getTransform(vona.math.RigidTransform2D)) which gives the change of coordinates from the previous block's end frame to this block's end frame.

The forward kinematics of a chain may be effected by directly setting the DOF of individual blocks by setDOF(double) and related methods. The cspace of a block is always compact and connected, and is normalized to [-1.0,1.0]. Inverse kinematics for a chain is provided by the class ChainIK.

Copyright (C) 2006 Marsette A. Vona, III

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author:

Marsette (Marty) A. Vona, III

Field Summary

private static java.lang.String	cvsid CVS id.
(package private) double	dof The current value of the DOF.
protected double[]	leftBarrel The current left barrel angles in order by MemberShady relative index.
protected boolean	locked Whether the DOF of this block are locked.
int	memberStartIndex The index of the first MemberShady in this block.
MultiEnvironment	multiEnvironment The MultiEnvironment containing all the MultiSegments of this block.
MultiShadyCommonAPI	multiShady The MultiShady containing all the MemberShadys of this block.
protected Block	next The next block in the chain or a Sentinel if none.
protected int	numMembers The number of MemberShadys in this block.
protected int	numSegments The number of MultiSegments in this block.
protected Block	previous The previous block in the chain or a Sentinel if none.
protected double[]	rightBarrel The current right barrel angles in order by MemberShady relative index.
int	segmentStartIndex The index of the first MultiSegment in this block.
Sentinel	sentinel The sentinel of this chain.
protected vona.math.RigidTransform2D	transform The current transform from the end frame of previous to the end frame of this block.

Constructor Summary

Block(MultiShadyCommonAPI multiShady, MultiEnvironment multiEnvironment, Sentinel sentinel)
Same as Block(MultiShadyCommonAPI, MultiEnvironment, Sentinel, int, int) but always creates new members and segments.

Block(MultiShadyCommonAPI multiShady, MultiEnvironment multiEnvironment, Sentinel sentinel, int memberStartIndex, int segmentStartIndex)
Create a new block at the end of a chain.

Method Summary

double	getDOF() Get the current value of the block's DOF.
abstract double	getEEOrientationOffset() Return the offset in radians of the EE frame orientation relative to the orientation of the Segment of the end-effector point.
abstract Point.OnSegment	getEEPoint() Get the end-effector point.
Block	getNext() Get the next block in the chain.
Block	getPrevious() Get the previous block in the chain.
vona.math.RigidTransform2D	getTransform() Get a reference to the start-to-end transform.
vona.math.RigidTransform2D	getTransform(vona.math.RigidTransform2D ret) Get a copy of the start-to-end transform.
boolean	hasNext() Check whether this is the last Block in a chain.
boolean	hasPrevious() Check whether this is the first Block in a chain.
protected abstract void	initMembersAndSegments() Subclasses must implement this to set up the MemberShadys and environment segments.
boolean	isLocked() Check whether this block is locked.
boolean	isSentinel() Check whether this is the sentinel.
void	lock() Lock this block.
void	lock(boolean lock) Lock or unlock this block.
protected void	recompute() Wrapper around recompute(vona.math.RigidTransform2D, double), computes into transform with no delta.
(package private) abstract void	recompute(vona.math.RigidTransform2D transform, double delta) Subclasses must implement this to compute the transform from the previouss end frame to this block's end frame according to dof, and possibly to update leftBarrel and rightBarrel from dof.
protected abstract boolean	recoverDOF() Try to figure out the current dof from the state of the barrel angles in multiShady.
boolean	reverseUpdate() Opposite of update(): transfers the angles from the numMembers MemberShadys in multiShady starting at index memberStartIndex to leftBarrel and rightBarrel.
boolean	reverseUpdateChain() Convenience method to reverseUpdate() the entire chain.
void	setDOF(double value) Set the value of the block's DOF.
void	setNominal() Set the block's DOF to 0.
void	tweakDOF(double delta) Tweak the value of the block's DOF.
void	unlock() Unlock this block.
void	update() Transfers the angles from leftBarrel and rightBarrel to the numMembers MemberShadys in multiShady starting at index memberStartIndex.
void	updateChain() Convenience method to update() the entire chain.

Methods inherited from class java.lang.Object

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

Field Detail

cvsid

private static final java.lang.String cvsid

CVS id.

See Also:

Constant Field Values

multiShady

public final MultiShadyCommonAPI multiShady

The MultiShady containing all the MemberShadys of this block.

multiEnvironment

public final MultiEnvironment multiEnvironment

The MultiEnvironment containing all the MultiSegments of this block.

sentinel

public final Sentinel sentinel

The sentinel of this chain.

previous

protected Block previous

The previous block in the chain or a Sentinel if none.

next

protected Block next

The next block in the chain or a Sentinel if none.

numMembers

protected int numMembers

The number of MemberShadys in this block.

numSegments

protected int numSegments

The number of MultiSegments in this block.

memberStartIndex

public final int memberStartIndex

The index of the first MemberShady in this block.

segmentStartIndex

public final int segmentStartIndex

The index of the first MultiSegment in this block.

leftBarrel

protected double[] leftBarrel

The current left barrel angles in order by MemberShady relative index.

rightBarrel

protected double[] rightBarrel

The current right barrel angles in order by MemberShady relative index.

transform

protected final vona.math.RigidTransform2D transform

The current transform from the end frame of previous to the end frame of this block.

locked

protected boolean locked

Whether the DOF of this block are locked.

dof

double dof

The current value of the DOF.

Constructor Detail

Block

public Block(MultiShadyCommonAPI multiShady,
             MultiEnvironment multiEnvironment,
             Sentinel sentinel,
             int memberStartIndex,
             int segmentStartIndex)

Create a new block at the end of a chain.

Parameters:

multiShady - the MultiShady in which to create the block's members

multiEnvironment - the MultiEnvironment in which to create the block's MultiSegments

sentinel - the Sentinel of the chain, not null

memberStartIndex - the index of the first MemberShady in the block (the members must be contiguous and must be in standard pose), or negative to initMembersAndSegments(). Can only be negative if segmentStartIndex is also negative.

segmentStartIndex - the index of the first MultiSegment in the block (the segments must be contiguous and must be in standard pose), or negative to initMembersAndSegments(). Can only be negative if memberStartIndex is also negative.

Block

public Block(MultiShadyCommonAPI multiShady,
             MultiEnvironment multiEnvironment,
             Sentinel sentinel)

Same as Block(MultiShadyCommonAPI, MultiEnvironment, Sentinel, int, int) but always creates new members and segments.

Method Detail

recompute

abstract void recompute(vona.math.RigidTransform2D transform,
                        double delta)

Subclasses must implement this to compute the transform from the previouss end frame to this block's end frame according to dof, and possibly to update leftBarrel and rightBarrel from dof.

Parameters:

transform - the computed transform is to be written here, not null

delta - if non-zero then the DOF is incremented by this amount before computing the transform (the persistent dof is not affected). This is used by ChainIK to compute columns of the chain Jacobian. The barrel angles are (allocated and) computed iff delta is 0.0. The caller must ensure that the incremented value will be in the range [-1.0,1.0].

recompute

protected void recompute()

Wrapper around recompute(vona.math.RigidTransform2D, double), computes into transform with no delta.

recoverDOF

protected abstract boolean recoverDOF()

Try to figure out the current dof from the state of the barrel angles in multiShady.

It can be assumed that the barrel angles were set as if by a call to recompute(RigidTransform2D, double). If this does not appear to be the case then return false without modifying dof.

Returns:

true iff successful

initMembersAndSegments

protected abstract void initMembersAndSegments()

Subclasses must implement this to set up the MemberShadys and environment segments.

numMembers and numSegments must be set, and the corresponding numbers of members and segments must be initialized (according to dof, leftBarrel, rightBarrel, and transform, which should all be consistent due to a prior call to recompute()) and added to multiShady and multiEnvironment. Internal barrels must be closed to form the block topology, and barrels must be closed to connect to previous iff it's not a Sentinel.

getTransform

public vona.math.RigidTransform2D getTransform(vona.math.RigidTransform2D ret)

Get a copy of the start-to-end transform.

This transforms points in start-frame coordiantes to points in end-frame coordinates.

Returns:

ret containing a copy of the transform, or a new clone of the start-to-end transform

getEEPoint

public abstract Point.OnSegment getEEPoint()

Get the end-effector point.

Note that the point may either reference a standard Segment or the body segment of a member as returned by ShadyPose.getBodySegment(double).

Returns:

the end-effector point

getEEOrientationOffset

public abstract double getEEOrientationOffset()

Return the offset in radians of the EE frame orientation relative to the orientation of the Segment of the end-effector point.

Returns:

the offset in radians of the EE frame orientation relative to the orientation of the Segment of the end-effector point

getTransform

public vona.math.RigidTransform2D getTransform()

Get a reference to the start-to-end transform.

Returns:

a reference to the start-to-end transform

update

public void update()

Transfers the angles from leftBarrel and rightBarrel to the numMembers MemberShadys in multiShady starting at index memberStartIndex.

.

updateChain

public void updateChain()

Convenience method to update() the entire chain.

reverseUpdate

public boolean reverseUpdate()

Opposite of update(): transfers the angles from the numMembers MemberShadys in multiShady starting at index memberStartIndex to leftBarrel and rightBarrel.

.

The barrel angles are only updated if recoverDOF() is successful.

Returns:

true iff recoverDOF() was successful

reverseUpdateChain

public boolean reverseUpdateChain()

Convenience method to reverseUpdate() the entire chain.

Returns:

true iff all the reverse updates were successful

getNext

public Block getNext()

Get the next block in the chain.

Returns:

the next block in the chain, null if none

getPrevious

public Block getPrevious()

Get the previous block in the chain.

Returns:

the previous block in the chain, a Sentinel if none

hasNext

public boolean hasNext()

Check whether this is the last Block in a chain.

Returns:

true iff this is not the last Block in a chain

hasPrevious

public boolean hasPrevious()

Check whether this is the first Block in a chain.

Returns:

true iff this is not the first Block in a chain

isSentinel

public boolean isSentinel()

Check whether this is the sentinel.

Returns:

true iff this is the sentinel

lock

public void lock()

Lock this block.

unlock

public void unlock()

Unlock this block.

isLocked

public boolean isLocked()

Check whether this block is locked.

Returns:

true iff locked

lock

public void lock(boolean lock)

Lock or unlock this block.

Parameters:

lock - whether to lock

getDOF

public double getDOF()

Get the current value of the block's DOF.

Returns:

the current value in the range [-1.0,1.0]

setDOF

public void setDOF(double value)

Set the value of the block's DOF.

Has no effect if locked.

recompute(vona.math.RigidTransform2D, double)s and after setting.

Parameters:

value - the DOF value, will be clamped to [-1.0,1.0]

tweakDOF

public void tweakDOF(double delta)

Tweak the value of the block's DOF.

See setDOF(double).

Parameters:

delta - the tweak

setNominal

public void setNominal()

Set the block's DOF to 0.

See setDOF(double).