shady.common
Class ShadyPose

java.lang.Object
  extended by shady.common.ShadyPose
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public class ShadyPose
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

A mechanism pose in an Environment.

Whereas ShadyState only records the intrinsic kinematic state of the mechanism, ShadyPose also knows where it is in the environment.

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
See Also:
Serialized Form

Field Summary
protected  AbstractSegment bodySegmentCC
          Cached body segment for getBodySegment(), consed on demand.
 int connectedBarrel
          The barrel which is connected at connectionPoint, negative for none.
 Point.OnSegment connectionPoint
          The location where connectedBarrel is attached to environment, null for none.
private static java.lang.String cvsid
          CVS id.
static double DEFAULT_ORIENTATION_SLOP
          Default orientation slop allowed, in degrees, while still considering the distal barrel to be aligned.
static double DEFAULT_TRANSLATION_SLOP
          Default translation slop allowed, in meters, while still considering the distal barrel to be aligned.
 Point.OnSegment distalPoint
          The location where the distal barrel is attached to environment.
 Environment environment
          The Environment.
 boolean invertConnectionSense
          Whether the connection sense of connectedBarrel is inverted.
 boolean invertDistalSense
          Like invertConnectionSense but applies to distal barrel.
 ShadyState state
          The intrinsic state, null for none.
 
Constructor Summary
ShadyPose()
          Covers ShadyPose(Environment), uses no environment.
ShadyPose(Environment environment)
          Create a new ShadyPose in an Environment.
 
Method Summary
 ShadyPose conjugate()
          Convenience cover of conjugate(Point.OnSegment), always uses getNearestDistalPointOnSegment(shady.common.Point.OnSegment).
 ShadyPose conjugate(Point.OnSegment distalPoint)
          Convenience cover of conjugate(Point.OnSegment, ShadyPose), always conjugates into this ShadyPose.
 ShadyPose conjugate(Point.OnSegment distalPoint, ShadyPose ret)
          Compute the ShadyPose corresponding to this one but where the distal barrel (i.e.
 ShadyPose copy()
          Return an independent deep copy.
 ShadyPose copyInto(ShadyPose dest)
          Deep copy into dest.
 Point.Cartesian getBarrelLocation(int barrel)
          Convenience cover of getBarrelLocation(int, double) always uses ShadyCommon.CC.
 Point.Cartesian getBarrelLocation(int barrel, double l)
          Convenience cover of getBarrelLocation(int, double, Point.Cartesian), always conses.
 Point.Cartesian getBarrelLocation(int barrel, double l, Point.Cartesian ret)
          Get the location of one of the barrels.
 Point.Cartesian getBarrelLocation(int barrel, Point.Cartesian ret)
          Convenience cover of getBarrelLocation(int, double, Point.Cartesian) always uses ShadyCommon.CC.
 double getBarrelOrientation(int barrel)
          Get the orientation of one of the barrels.
 Point.Cartesian getBodyCenter(Point.Cartesian ret)
          Get the location of the body center point, always uses ShadyCommon.CC.
 Point.Cartesian getBodyCenter(Point.Cartesian ret, double l)
          Get the location of the body center point.
 double getBodyOrientation()
          Get the orientation of the shady body vector, relative to the positive x axis of the environment.
 Point.Cartesian getBodyPoint(Point.Cartesian ret, double l, double where)
          Get a point at where (in [0.0,1.0]) along the body vector from the connected barrel (where=0.0) to the distal barrel (where=1.0).
 AbstractSegment getBodySegment()
          Covers getBodySegment(double), uses ShadyCommon.CC.
 AbstractSegment getBodySegment(double l)
          Get a body AbstractSegment which tracks this pose.
 Point.Cartesian getConnectedBarrelLocation()
          Convenience cover of getConnectedBarrelLocation(Point.Cartesian), always conses.
 Point.Cartesian getConnectedBarrelLocation(Point.Cartesian ret)
          Get the location of the connectedBarrel.
 double getConnectedBarrelOrientation()
          Get the orientation of connectedBarrel vector, relative to the positive x axis of the environment.
 double getDistalBarrelAngleTo(Segment segment)
          Get the angle from the distal barrel orientation to segment's orientation, in degrees.
 Point.Cartesian getDistalBarrelLocation()
          Convenience cover of getDistalBarrelLocation(double), always uses ShadyCommon.CC.
 Point.Cartesian getDistalBarrelLocation(double l)
          Convenience cover of getDistalBarrelLocation(Point.Cartesian, double), always conses.
 Point.Cartesian getDistalBarrelLocation(Point.Cartesian ret, double l)
          Get the location of the distal barrel, i.e.
 double getDistalBarrelOrientation()
          Get the orientation of the distal barrel vector, i.e.
 Point.OnSegment getNearestDistalPointOnSegment()
          Convenience cover of getNearestDistalPointOnSegment(Point.OnSegment), always conses.
 Point.OnSegment getNearestDistalPointOnSegment(Point.OnSegment ret)
          If distalPoint is valid and we are aligned on it then return a copy of it.
 ShadyPose invalidate()
          Invalidate this Pose.
 boolean isDistalBarrelAligned()
          Convenience cover of isDistalBarrelAligned(Point.OnSegment), always uses getNearestDistalPointOnSegment(shady.common.Point.OnSegment).
 boolean isDistalBarrelAligned(Point.OnSegment distalPoint)
          Convenience cover of isDistalBarrelAligned(Point.OnSegment, double, double), always uses DEFAULT_TRANSLATION_SLOP and DEFAULT_ORIENTATION_SLOP.
 boolean isDistalBarrelAligned(Point.OnSegment distalPoint, double translationSlop, double orientationSlop)
          Check whether the distal barrel (i.e.
 boolean isDistalBarrelAlignmentInverted(Point.OnSegment distalPoint)
          Check whether the distal barrel alignment is inverted with respect to the segment orientation of distalPoint.
 boolean isValid()
          Check whether this pose is valid.
 
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

DEFAULT_TRANSLATION_SLOP

public static final double DEFAULT_TRANSLATION_SLOP

Default translation slop allowed, in meters, while still considering the distal barrel to be aligned.

See Also:
Constant Field Values

DEFAULT_ORIENTATION_SLOP

public static final double DEFAULT_ORIENTATION_SLOP

Default orientation slop allowed, in degrees, while still considering the distal barrel to be aligned.

See Also:
Constant Field Values

environment

public transient Environment environment

The Environment.

Note this is transient, which matters (only) in the case that the Shady implementation is accessed via RMI. This allows ShadyPose instances to be passed by copy without too much overhead (otherwise the whole environment would need to be copied every time a ShadyPose is passed to or returned from the Shady implementation).


state

public ShadyState state

The intrinsic state, null for none.


connectedBarrel

public int connectedBarrel

The barrel which is connected at connectionPoint, negative for none.


connectionPoint

public Point.OnSegment connectionPoint

The location where connectedBarrel is attached to environment, null for none.


distalPoint

public Point.OnSegment distalPoint

The location where the distal barrel is attached to environment.

If the distal gripper is not closed then this may or may not be nulled or invalidated, as callers wish. It must always be the case that callers should maintain this to be compatible with the pose, that is, it must always be the case that the distal barrel is algned on the segment of distalPoint iff distalPoint is non-null and valid.

If this is set, valid, and aligned, it is returned immediately from getNearestDistalPointOnSegment(shady.common.Point.OnSegment).


invertConnectionSense

public boolean invertConnectionSense

Whether the connection sense of connectedBarrel is inverted.

If the connection is not inverted then the vector from the connected environment segment start to the environment segment end points in the same direction as the connected barrel vector (see class header doc for ShadyState for a definition of this latter vector). If the connection is inverted then these two vectors point in opposite directions.


invertDistalSense

public boolean invertDistalSense

Like invertConnectionSense but applies to distal barrel.


bodySegmentCC

protected AbstractSegment bodySegmentCC

Cached body segment for getBodySegment(), consed on demand.

Constructor Detail

ShadyPose

public ShadyPose(Environment environment)

Create a new ShadyPose in an Environment.

Parameters:
environment - the Environment, null for none

ShadyPose

public ShadyPose()

Covers ShadyPose(Environment), uses no environment.

Method Detail

isValid

public boolean isValid()

Check whether this pose is valid.

A valid pose has non-null environment and valid connectedBarrel and connectionPoint.

Returns:
true iff this pose is valid

invalidate

public ShadyPose invalidate()

Invalidate this Pose.

After calling this isValid() will return false.

Returns:
self ref

getBodySegment

public AbstractSegment getBodySegment(double l)

Get a body AbstractSegment which tracks this pose.

The body segment starts at the left barrel point and ends at the right barrel point.

Parameters:
l - the link length (the distance between barrel centers) in meters
Returns:
a body segment which tracks this pose

getBodySegment

public AbstractSegment getBodySegment()

Covers getBodySegment(double), uses ShadyCommon.CC.


getBarrelLocation

public Point.Cartesian getBarrelLocation(int barrel,
                                         double l,
                                         Point.Cartesian ret)

Get the location of one of the barrels.

Defers to getConnectedBarrelLocation(shady.common.Point.Cartesian) or getDistalBarrelLocation(shady.common.Point.Cartesian, double).

Parameters:
barrel - the barrel location to get
l - the link length (the distance between barrel centers) in meters
ret - the location is written here on return, or if null a new Point.Cartesian is consed
Returns:
the location of barrel

getBarrelLocation

public Point.Cartesian getBarrelLocation(int barrel,
                                         double l)

Convenience cover of getBarrelLocation(int, double, Point.Cartesian), always conses.


getBarrelLocation

public Point.Cartesian getBarrelLocation(int barrel)

Convenience cover of getBarrelLocation(int, double) always uses ShadyCommon.CC.


getBarrelLocation

public Point.Cartesian getBarrelLocation(int barrel,
                                         Point.Cartesian ret)

Convenience cover of getBarrelLocation(int, double, Point.Cartesian) always uses ShadyCommon.CC.


getConnectedBarrelLocation

public Point.Cartesian getConnectedBarrelLocation(Point.Cartesian ret)

Get the location of the connectedBarrel.

Parameters:
ret - the location is written here on return, or if null a new Point.Cartesian is consed
Returns:
the location of connectedBarrel

getConnectedBarrelLocation

public Point.Cartesian getConnectedBarrelLocation()

Convenience cover of getConnectedBarrelLocation(Point.Cartesian), always conses.


getBodyCenter

public Point.Cartesian getBodyCenter(Point.Cartesian ret)

Get the location of the body center point, always uses ShadyCommon.CC.

Parameters:
ret - the location is written here on return, or if null a new Point.Cartesian is consed

getBodyCenter

public Point.Cartesian getBodyCenter(Point.Cartesian ret,
                                     double l)

Get the location of the body center point.

Parameters:
ret - the location is written here on return, or if null a new Point.Cartesian is consed
l - the link length (the distance between barrel centers) in meters

getBodyPoint

public Point.Cartesian getBodyPoint(Point.Cartesian ret,
                                    double l,
                                    double where)

Get a point at where (in [0.0,1.0]) along the body vector from the connected barrel (where=0.0) to the distal barrel (where=1.0).

Parameters:
ret - the location is written here on return, or if null a new Point.Cartesian is consed
l - the link length (the distance between barrel centers) in meters
where - the relative location of the point from the connected barrel (where=0.0) to the distal barrel (where=1.0)
Returns:
the requested point

getDistalBarrelLocation

public Point.Cartesian getDistalBarrelLocation(Point.Cartesian ret,
                                               double l)

Get the location of the distal barrel, i.e. the opposite barrel from connectedBarrel.

Parameters:
ret - the location is written here on return, or if null a new Point.Cartesian is consed
l - the link length (the distance between barrel centers) in meters
Returns:
the location of the opposite of connectedBarrel

getDistalBarrelLocation

public Point.Cartesian getDistalBarrelLocation(double l)

Convenience cover of getDistalBarrelLocation(Point.Cartesian, double), always conses.


getDistalBarrelLocation

public Point.Cartesian getDistalBarrelLocation()

Convenience cover of getDistalBarrelLocation(double), always uses ShadyCommon.CC.


getBarrelOrientation

public double getBarrelOrientation(int barrel)

Get the orientation of one of the barrels.

Defers to getConnectedBarrelOrientation() or getDistalBarrelOrientation().

Parameters:
barrel - the barrel orientation to get
Returns:
the orientation of barrel

getConnectedBarrelOrientation

public double getConnectedBarrelOrientation()

Get the orientation of connectedBarrel vector, relative to the positive x axis of the environment.

See the class header doc for ShadyState for a definition of the barrel vectors.

This is simply the orientation of the Segment of connectionPoint (see AbstractSegment.getOrientation()).

Returns:
the orientation of connectedBarrel vector, relative to the positive x axis of the environment, in degrees, in the range (-180, 180]

getDistalBarrelOrientation

public double getDistalBarrelOrientation()

Get the orientation of the distal barrel vector, i.e. the barrel opposite connectedBarrel, relative to the positive x axis of the environment.

See the class header doc for ShadyState for a definition of the barrel vectors.

Returns:
the orientation of the distal barrel vector, relative to the positive x axis of the environment, in degrees, in the range (-180, 180]

getBodyOrientation

public double getBodyOrientation()

Get the orientation of the shady body vector, relative to the positive x axis of the environment.

See the class header doc for ShadyState for a definition of the shady body vector.

Returns:
the orientation of the shady body vector, relative to the positive x axis of the environment, in degrees, in the range (-180, 180]

getNearestDistalPointOnSegment

public Point.OnSegment getNearestDistalPointOnSegment(Point.OnSegment ret)

If distalPoint is valid and we are aligned on it then return a copy of it. Otherwise search the environment for the nearest point on a Segment to the distal barrel center (i.e. the center of the barrel opposite connectedBarrel).

This is basically defined as the nearest projection closer than DEFAULT_TRANSLATION_SLOP of getDistalBarrelLocation(shady.common.Point.Cartesian, double) on a Segment in environment. However, if more than one such point is closer than DEFAULT_TRANSLATION_SLOP, then the point in that set with minimal orientation misalignment is returned (exact ties are broken arbitrarily but deterministically).

Parameters:
ret - the location is written here on return, or if null a new Point.OnSegment is consed
Returns:
the nearest point within DEFAULT_TRANSLATION_SLOP, or a point with a null segment if no segment points were within range

getNearestDistalPointOnSegment

public Point.OnSegment getNearestDistalPointOnSegment()

Convenience cover of getNearestDistalPointOnSegment(Point.OnSegment), always conses.


isDistalBarrelAligned

public boolean isDistalBarrelAligned(Point.OnSegment distalPoint,
                                     double translationSlop,
                                     double orientationSlop)

Check whether the distal barrel (i.e. the barrel opposite connectedBarrel is aligned within given slop to a given distalPoint.

As long as the passed distalPoint is not distalPoint then inverted alignment is not penalized. However if the two are the same, the alignment sense must be as specified by invertDistalSense.

Parameters:
distalPoint - the point against which to check alignment. If null or invalid getNearestDistalPointOnSegment(shady.common.Point.OnSegment) is called (which may mutate distalPoint)
translationSlop - translation slop allowed, in meters, while still considering the distal barrel to be aligned
orientationSlop - orientation slop allowed, in degrees, while still considering the distal barrel to be aligned
Returns:
true iff the distal barrel is aligned within the given slop

isDistalBarrelAligned

public boolean isDistalBarrelAligned(Point.OnSegment distalPoint)

Convenience cover of isDistalBarrelAligned(Point.OnSegment, double, double), always uses DEFAULT_TRANSLATION_SLOP and DEFAULT_ORIENTATION_SLOP.


isDistalBarrelAligned

public boolean isDistalBarrelAligned()

Convenience cover of isDistalBarrelAligned(Point.OnSegment), always uses getNearestDistalPointOnSegment(shady.common.Point.OnSegment).


isDistalBarrelAlignmentInverted

public boolean isDistalBarrelAlignmentInverted(Point.OnSegment distalPoint)

Check whether the distal barrel alignment is inverted with respect to the segment orientation of distalPoint.

If the passed distalPoint is distalPoint and that point is aligned then invertDistalSense is returned directly.

Parameters:
distalPoint - the point against which to check alignment. If null or invalid getNearestDistalPointOnSegment(shady.common.Point.OnSegment) is called (which may mutate distalPoint)
Returns:
true iff the orientation of the distal barrel (getDistalBarrelOrientation()) is greater than 90 degrees different than the orientation of distalPoint.segment, false if the distal barrel is not aligned in either direction

getDistalBarrelAngleTo

public double getDistalBarrelAngleTo(Segment segment)

Get the angle from the distal barrel orientation to segment's orientation, in degrees.

Returns:
the angle from the distal barrel orientation to segment's orientation, in degrees, in the range (-180, 180]

conjugate

public ShadyPose conjugate(Point.OnSegment distalPoint,
                           ShadyPose ret)

Compute the ShadyPose corresponding to this one but where the distal barrel (i.e. the opposite of connectedBarrel) is connected to distalPoint.

Note that this method does not verify that the distal barrel is aligned with distalPoint.

Parameters:
distalPoint - the point against which to check alignment. If null or invalid getNearestDistalPointOnSegment(shady.common.Point.OnSegment) is called (which may mutate distalPoint)
ret - the return pose is written here, if null then conjugate into this ShadyPose.
Returns:
the conjugate pose

conjugate

public ShadyPose conjugate(Point.OnSegment distalPoint)

Convenience cover of conjugate(Point.OnSegment, ShadyPose), always conjugates into this ShadyPose.


conjugate

public ShadyPose conjugate()

Convenience cover of conjugate(Point.OnSegment), always uses getNearestDistalPointOnSegment(shady.common.Point.OnSegment).


copy

public ShadyPose copy()

Return an independent deep copy.

state, connectionPoint, and distalPoint are deep-copied, but environment is referenced.

Returns:
an indpendent deep copy

copyInto

public ShadyPose copyInto(ShadyPose dest)

Deep copy into dest.

state, connectionPoint, and distalPoint are deep-copied, but environment is referenced.

Parameters:
dest - the destination of the copy, or null to cons a new one
Returns:
the copy