pickingExt
Class PickObject

java.lang.Object
  |
  +--pickingExt.PickObject

public class PickObject
extends java.lang.Object

Contains methods to aid in picking. A PickObject is created for a given Canvas3D and a BranchGroup. SceneGraphObjects under the specified BranchGroup can then be checked to determine if they have been picked.

The pick modes are PICK_BOUNDS and PICK_GEOMETRY. PICK_BOUNDS traverses the scene graph and returns the SceneGraphPaths whose bounds intersect the pick shape. PICK_GEOMETRY takes the result of a PICK_BOUNDS then returns the SceneGraphPaths whose geometry intersects the pick shape.

The pick shape is generated using the x,y location of the pick and the pick shape mode. The pick shape modes are SHAPE_RAY, SHAPE_APERTURE and SHAPE_RAY_APERTURE. SHAPE_RAY generates a PickRay through the x,y location of the pick for use for both the bounds and geometry phases of the pick. SHAPE_APERTURE generates a PickBounds (using a BoundingPolytope) around the x,y location of the pick in the shape specified by the pick aperture. The PickBounds is is used for both the bounds and geometry phases of the pick. SHAPE_RAY_APERTURE uses a PickRay for the bounds phase of the pick and then a PickBounds for the geometry phase of the pick.

The best performance comes from doing PICK_BOUNDS picking using a SHAPE_RAY pick shape.

More accurate picks come from using PICK_GEOMETRY. When using PICK_GEOMETRY, the ALLOW_INTERSECT bit must be set on the Shape3D nodes to be picked. Picking lines is difficult or impossible using SHAPE_RAY, use SHAPE_APERTURE or SHAPE_RAY_APERTURE instead. SHAPE_RAY_APERTURE should give better performance than SHAPE_APERTURE, but it may make it slightly harder to pick shapes that are near the back of the scene.


Field Summary
static int BRANCH_GROUP
          A flag to indicate to the pickNode method to return a BranchGroup node from a given SceneGraphPath.
static int GROUP
          A flag to indicate to the pickNode method to return a Group node from a given SceneGraphPath.
static int LINK
          A flag to indicate to the pickNode method to return a Link node from a given SceneGraphPath.
static int MORPH
          A flag to indicate to the pickNode method to return a Morph node from a given SceneGraphPath.
static int PRIMITIVE
          A flag to indicate to the pickNode method to return a Primitive node from a given SceneGraphPath.
static int SHAPE_APERTURE
          Sets the pick shape mode to use an aperture-based pick shape
static int SHAPE_RAY
          Sets the pick shape mode to use a ray-based pick shape
static int SHAPE_RAY_APERTURE
          Sets the pick shape mode to use a ray-based pick shape for bounds intersections and an aperture-based pick shape for geometry intersections
static int SHAPE3D
          A flag to indicate to the pickNode method to return a Shape3D node from a given SceneGraphPath.
static int SWITCH
          A flag to indicate to the pickNode method to return a Switch node from a given SceneGraphPath.
static int TRANSFORM_GROUP
          A flag to indicate to the pickNode method to return a TransformGroup node from a given SceneGraphPath.
static int USE_BOUNDS
          Set this flag if you want to pick by bounds.
static int USE_GEOMETRY
          Set this flag if you want to pick by bounds and then geometry.
 
Constructor Summary
PickObject(javax.media.j3d.Canvas3D c, javax.media.j3d.BranchGroup root)
          Creates a PickObject with a ray-based pick shape
 
Method Summary
 javax.media.j3d.PickBounds generatePickAperture(int xpos, int ypos)
          Creates a bounding polytope PickShape which is a set of planes around the point (xpos,ypos).
 javax.media.j3d.PickRay generatePickRay(int xpos, int ypos)
          Creates a PickRay that starts at the viewer position and points into the scene in the direction of (xpos, ypos) specified in window space.
 javax.media.j3d.PickShape generatePickShape(int xpos, int ypos, int pickType)
          Creates a PickShape using the window space selection point (xpos, ypos).
 java.awt.Point[] getPickAperture()
          Returns the pick aperture for SHAPE_APERTURE or SHAPE_RAY_APERTURE mode
 int getPickMode()
          Returns the pick mode
 int getPickShapeMode()
          Returns the pick shape mode
 javax.media.j3d.SceneGraphPath[] pickAll(int xpos, int ypos)
          Returns an array referencing all the items that are pickable below the BranchGroup (specified in the PickObject constructor) that intersect with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.SceneGraphPath[] pickAll(int xpos, int ypos, int flag)
          Returns an array referencing all the items that are pickable below the BranchGroup (specified in the PickObject constructor) that intersect with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.SceneGraphPath[] pickAllSorted(int xpos, int ypos)
          Returns a sorted array of references to all the Pickable items below the BranchGroup (specified in the PickObject constructor) that intersects with pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.SceneGraphPath[] pickAllSorted(int xpos, int ypos, int flag)
          Returns a sorted array of references to all the Pickable items below the BranchGroup (specified in the PickObject constructor) that intersects with pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.SceneGraphPath pickAny(int xpos, int ypos)
          Returns a reference to any item that is Pickable below the specified BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.SceneGraphPath pickAny(int xpos, int ypos, int flag)
          Returns a reference to any item that is Pickable below the specified BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.SceneGraphPath pickClosest(int xpos, int ypos)
          Returns a reference to the item that is closest to the viewer and is Pickable below the BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.SceneGraphPath pickClosest(int xpos, int ypos, int flag)
          Returns a reference to the item that is closest to the viewer and is Pickable below the BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
 javax.media.j3d.Node pickNode(javax.media.j3d.SceneGraphPath sgPath, int flags)
          Returns a reference to a Pickable Node that is of the specified type that is contained in the specified SceneGraphPath.
 javax.media.j3d.Node pickNode(javax.media.j3d.SceneGraphPath sgPath, int flags, int occurrence)
          Returns a reference to a Pickable Node that is of the specified type that is contained in the specified SceneGraphPath.
 void setPickAperture(java.awt.Point[] aperturePts)
          Sets the pick aperture for SHAPE_APERTURE or SHAPE_RAY_APERTURE mode
 void setPickMode(int mode)
          Sets the pick mode
 void setPickShapeMode(int mode)
          Sets the pick shape mode
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SHAPE3D

public static final int SHAPE3D
A flag to indicate to the pickNode method to return a Shape3D node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

MORPH

public static final int MORPH
A flag to indicate to the pickNode method to return a Morph node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

PRIMITIVE

public static final int PRIMITIVE
A flag to indicate to the pickNode method to return a Primitive node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

LINK

public static final int LINK
A flag to indicate to the pickNode method to return a Link node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

GROUP

public static final int GROUP
A flag to indicate to the pickNode method to return a Group node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

TRANSFORM_GROUP

public static final int TRANSFORM_GROUP
A flag to indicate to the pickNode method to return a TransformGroup node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

BRANCH_GROUP

public static final int BRANCH_GROUP
A flag to indicate to the pickNode method to return a BranchGroup node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

SWITCH

public static final int SWITCH
A flag to indicate to the pickNode method to return a Switch node from a given SceneGraphPath.
See Also:
pickNode(javax.media.j3d.SceneGraphPath, int)

USE_GEOMETRY

public static final int USE_GEOMETRY
Set this flag if you want to pick by bounds and then geometry.

USE_BOUNDS

public static final int USE_BOUNDS
Set this flag if you want to pick by bounds.

SHAPE_RAY

public static final int SHAPE_RAY
Sets the pick shape mode to use a ray-based pick shape

SHAPE_APERTURE

public static final int SHAPE_APERTURE
Sets the pick shape mode to use an aperture-based pick shape

SHAPE_RAY_APERTURE

public static final int SHAPE_RAY_APERTURE
Sets the pick shape mode to use a ray-based pick shape for bounds intersections and an aperture-based pick shape for geometry intersections
Constructor Detail

PickObject

public PickObject(javax.media.j3d.Canvas3D c,
                  javax.media.j3d.BranchGroup root)
Creates a PickObject with a ray-based pick shape
Parameters:
c - Current J3D canvas.
root - The portion of the scenegraph for which picking is to occur on. It has to be a BranchGroup.
See Also:
BranchGroup, Canvas3D
Method Detail

generatePickRay

public javax.media.j3d.PickRay generatePickRay(int xpos,
                                               int ypos)
Creates a PickRay that starts at the viewer position and points into the scene in the direction of (xpos, ypos) specified in window space.
Parameters:
xpos - The value along the x-axis.
ypos - The value along the y-axis.
Returns:
A PickShape object that is the constructed PickRay.

generatePickAperture

public javax.media.j3d.PickBounds generatePickAperture(int xpos,
                                                       int ypos)
Creates a bounding polytope PickShape which is a set of planes around the point (xpos,ypos). There will be a plane projected through each segment of the the pick aperature and planes for the front and back clipping planes.
Parameters:
xpos - The value along the x-axis.
ypos - The value along the y-axis.
Returns:
A PickShape object that is the bounding polytope.

generatePickShape

public javax.media.j3d.PickShape generatePickShape(int xpos,
                                                   int ypos,
                                                   int pickType)
Creates a PickShape using the window space selection point (xpos, ypos). The returned shape will be either a PickRay or a PickBounds, depending on the pick shape mode and the pick mode
Parameters:
xpos - The value along the x-axis.
ypos - The value along the y-axis.
mode - The pick mode, either USE_BOUNDS or USE_GEOMETRY
Returns:
The constructed PickShape

setPickMode

public void setPickMode(int mode)
Sets the pick mode
Parameters:
mode - The pick mode, either USE_GEOMETRY or USE_BOUNDS. The default is USE_BOUNDS.

getPickMode

public int getPickMode()
Returns the pick mode

setPickShapeMode

public void setPickShapeMode(int mode)
Sets the pick shape mode
Parameters:
mode - The pick shape mode, either SHAPE_RAY, SHAPE_APERTURE, or SHAPE_RAY_APERTURE. The default is SHAPE_RAY.

getPickShapeMode

public int getPickShapeMode()
Returns the pick shape mode

setPickAperture

public void setPickAperture(java.awt.Point[] aperturePts)
Sets the pick aperture for SHAPE_APERTURE or SHAPE_RAY_APERTURE mode
Parameters:
Point[] - aperturePts The pick aperture, which should be a convex, counter-clockwise loop of Points around 0,0

getPickAperture

public java.awt.Point[] getPickAperture()
Returns the pick aperture for SHAPE_APERTURE or SHAPE_RAY_APERTURE mode

pickAll

public javax.media.j3d.SceneGraphPath[] pickAll(int xpos,
                                                int ypos)
Returns an array referencing all the items that are pickable below the BranchGroup (specified in the PickObject constructor) that intersect with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space. The resultant array is unordered.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
Returns:
The array of SceneGraphPath objects that contain Objects that were picked If no pickable object is found null is returned..
See Also:
SceneGraphPath

pickAllSorted

public javax.media.j3d.SceneGraphPath[] pickAllSorted(int xpos,
                                                      int ypos)
Returns a sorted array of references to all the Pickable items below the BranchGroup (specified in the PickObject constructor) that intersects with pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space. Element [0] references the item closest to viewer.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
Returns:
A sorted arrayof SceneGraphPath objects that contain Objects that were picked. The array is sorted from closest to farthest from the viewer If no pickable object is found null is returned..
See Also:
SceneGraphPath

pickAny

public javax.media.j3d.SceneGraphPath pickAny(int xpos,
                                              int ypos)
Returns a reference to any item that is Pickable below the specified BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
Returns:
A SceneGraphPath of an object that was picked. This is not guarenteed to return the same result for multiple picks If no pickable object is found null is returned..
See Also:
SceneGraphPath

pickClosest

public javax.media.j3d.SceneGraphPath pickClosest(int xpos,
                                                  int ypos)
Returns a reference to the item that is closest to the viewer and is Pickable below the BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
Returns:
A SceneGraphPath which contains the closest pickable object. If no pickable object is found, null is returned.
See Also:
SceneGraphPath

pickAll

public javax.media.j3d.SceneGraphPath[] pickAll(int xpos,
                                                int ypos,
                                                int flag)
Returns an array referencing all the items that are pickable below the BranchGroup (specified in the PickObject constructor) that intersect with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space. The resultant array is unordered.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
flag - Specifies USE_BOUNDS or USE_GEOMETRY
Returns:
The array of SceneGraphPath objects that contain Objects that were picked If no pickable object is found null is returned..
See Also:
SceneGraphPath

pickAllSorted

public javax.media.j3d.SceneGraphPath[] pickAllSorted(int xpos,
                                                      int ypos,
                                                      int flag)
Returns a sorted array of references to all the Pickable items below the BranchGroup (specified in the PickObject constructor) that intersects with pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space. Element [0] references the item closest to viewer.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
flag - Specifies USE_BOUNDS or USE_GEOMETRY
Returns:
A sorted arrayof SceneGraphPath objects that contain Objects that were picked. The array is sorted from closest to farthest from the viewer If no pickable object is found null is returned..
See Also:
SceneGraphPath

pickAny

public javax.media.j3d.SceneGraphPath pickAny(int xpos,
                                              int ypos,
                                              int flag)
Returns a reference to any item that is Pickable below the specified BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
flag - Specifies USE_BOUNDS or USE_GEOMETRY
Returns:
A SceneGraphPath of an object that was picked. This is not guarenteed to return the same result for multiple picks If no pickable object is found null is returned..
See Also:
SceneGraphPath

pickClosest

public javax.media.j3d.SceneGraphPath pickClosest(int xpos,
                                                  int ypos,
                                                  int flag)
Returns a reference to the item that is closest to the viewer and is Pickable below the BranchGroup (specified in the PickObject constructor) which intersects with the pick shape specified by the pick shape mode, centered on the point (xpos, ypos) in window space.
Parameters:
xpos - The x coordinate of the pick shape
ypos - The y coordinate of the pick shape
flag - Specifys picking by Geometry or Bounds.
Returns:
A SceneGraphPath which contains the closest pickable object. If no pickable object is found, null is returned.
See Also:
SceneGraphPath

pickNode

public javax.media.j3d.Node pickNode(javax.media.j3d.SceneGraphPath sgPath,
                                     int flags)
Returns a reference to a Pickable Node that is of the specified type that is contained in the specified SceneGraphPath. If more than one node of the same type is encountered, the node closest to the Object will be returned.
Parameters:
sgPath - The SceneGraphPath to be traversed.
flags - The Node types interested in picking.
Returns:
This first occurrence of the specified Node type. Starting from the Locale. If no pickable object is found null of the specifed types, null is returned.

pickNode

public javax.media.j3d.Node pickNode(javax.media.j3d.SceneGraphPath sgPath,
                                     int flags,
                                     int occurrence)
Returns a reference to a Pickable Node that is of the specified type that is contained in the specified SceneGraphPath. The Node returned is the nth occurrence of a Node that is of the specified type.
Parameters:
sgPath - The SceneGraphPath to be traversed.
flags - The Node types interested.
occurrence - Which occurrence of a Node that matches the specified type to return. An occurrence of 1 means to return the first occurrence of that object type (the object closest to the viewer).
Returns:
The nth occurrence of a Node of type flags, starting from the Locale. If no pickable object is found, null is returned.