com.sun.j3d.utils.picking
Class PickTool

java.lang.Object
  extended by com.sun.j3d.utils.picking.PickTool
Direct Known Subclasses:
PickCanvas

public class PickTool
extends java.lang.Object

The base class for picking operations. The picking methods will return a PickResult object for each object picked, which can then be queried to obtain more detailed information about the specific objects that were picked.

The pick mode specifies the detail level of picking before the PickResult is returned:

The utility method PickTool.setCapabilities(Node, int) can be used before the scene graph is made live to set the capabilities of Shape3D, Morph or Geometry nodes to allow picking.

A PickResult from a lower level of detail pick can be used to inquire more detailed information if the capibility bits are set. This can be used to filter the PickResults before the more computationally intensive intersection processing. For example, the application can do a BOUNDS pick and then selectively inquire intersections on some of the PickResults. This will save the effort of doing intersection computation on the other PickResults. However, inquiring the intersections from a GEOMETRY pick will make the intersection computation happen twice, use GEOMETRY_INTERSECT_INFO if you want to inquire the intersection information on all the PickResults.

When using pickAllSorted or pickClosest methods, the picks will be sorted by the distance from the start point of the pick shape to the intersection point.

Morph nodes cannot be picked using the displayed geometry in GEOMETRY_INTERSECT_INFO mode due to limitations in the current Java3D core API (the current geometry of the the Morph cannot be inquired). Instead they are picked using the geometry at index 0 in the Morph, this limitation may be eliminated in a future release of Java3D.

If the pick shape is a PickBounds, the pick result will contain only the scene graph path, even if the mode is GEOMETRY_INTERSECT_INFO.


Field Summary
static int BOUNDS
          Use this mode to pick by bounds and get basic information on the pick.
private  boolean debug
           
static int GEOMETRY
          Use this mode to pick by geometry and get basic information on the pick.
static int GEOMETRY_INTERSECT_INFO
          Use this mode to pick by geometry and save information about the intersections (intersected primitive, intersection point and closest vertex).
static int INTERSECT_COORD
          Flag to pass to setCapabilities(Node, int) to set the Node's capabilities to allow inquiry of the intersection coordinate information.
static int INTERSECT_FULL
          Flag to pass to setCapabilities(Node, int) to set the Node's capabilities to allow inquiry of all intersection information.
static int INTERSECT_TEST
          Flag to pass to setCapabilities(Node, int) to set the Node's capabilities to allow intersection tests, but not inquire information about the intersections (use for GEOMETRY mode).
(package private)  int mode
           
(package private)  BranchGroup pickRootBG
          Used to store the BranchGroup used for picking
(package private)  Locale pickRootL
          Used to store the Locale used for picking
(package private)  PickShape pickShape
           
(package private)  Point3d start
          Used to store a reference point used in determining how "close" points are.
protected  boolean userDefineShape
           
 
Constructor Summary
PickTool(BranchGroup b)
          Constructor with BranchGroup to be picked.
PickTool(Locale l)
          Constructor with the Locale to be picked.
 
Method Summary
 BranchGroup getBranchGroup()
          Returns the BranchGroup to be picked if the tool was initialized with a BranchGroup, null otherwise.
 Locale getLocale()
          Returns the Locale to be picked if the tool was initialized with a Locale, null otherwise.
 int getMode()
          Gets the picking detail mode.
 PickShape getPickShape()
          Returns the PickShape for this object.
 Point3d getStartPosition()
          Returns the start postion used for distance measurement.
 PickResult[] pickAll()
          Selects all the nodes that intersect the PickShape.
private  PickResult[] pickAll(PickShape pickShape)
           
 PickResult[] pickAllSorted()
          Select all the nodes that intersect the PickShape, returned sorted.
private  PickResult[] pickAllSorted(PickShape pickShape)
           
 PickResult pickAny()
          Select one of the nodes that intersect the PickShape
private  PickResult pickAny(PickShape pickShape)
           
 PickResult pickClosest()
          Select the closest node that intersects the PickShape.
private  PickResult pickClosest(PickShape pickShape)
           
private  PickResult[] pickGeomAll(PickShape pickShape)
           
private  PickResult[] pickGeomAllIntersect(PickShape pickShape)
           
private  PickResult[] pickGeomAllSorted(PickShape pickShape)
           
private  PickResult[] pickGeomAllSortedIntersect(PickShape pickShape)
           
private  PickResult pickGeomAny(PickShape pickShape)
           
private  PickResult pickGeomAnyIntersect(PickShape pickShape)
           
private  PickResult pickGeomClosest(PickShape pickShape)
           
private  PickResult pickGeomClosestIntersect(PickShape pickShape)
           
private  void quicksort(int l, int r, double[] dist, int[] pos)
           
 Locale setBranchGroup(Locale l)
          Deprecated. This method does nothing other than return its input parameter.
private static void setCapabilities(CompressedGeometry cg, int level)
           
private static void setCapabilities(GeometryArray ga, int level)
           
private static void setCapabilities(IndexedGeometryArray iga, int level)
           
static void setCapabilities(Node node, int level)
          Sets the capabilities on the Node and it's components to allow picking at the specified detail level.
 void setMode(int mode)
          Sets the picking detail mode.
 void setShape(PickShape ps, Point3d startPt)
          Sets the pick shape to a user-provided PickShape object
 void setShapeBounds(Bounds bounds, Point3d startPt)
          Sets the pick shape to use a user-provided Bounds object
 void setShapeConeRay(Point3d start, Vector3d dir, double angle)
          Sets the pick shape to an infinite PickCone.
 void setShapeConeSegment(Point3d start, Point3d end, double angle)
          Sets the pick shape to a capped PickCone
 void setShapeCylinderRay(Point3d start, Vector3d dir, double radius)
          Sets the pick shape to an infinite PickCylinder.
 void setShapeCylinderSegment(Point3d start, Point3d end, double radius)
          Sets the pick shape to a capped PickCylinder
 void setShapeRay(Point3d start, Vector3d dir)
          Sets the pick shape to a PickRay.
 void setShapeSegment(Point3d start, Point3d end)
          Sets the pick shape to a PickSegment.
private  PickResult[] sortPickResults(PickResult[] pr, double[] dist)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

debug

private final boolean debug
See Also:
Constant Field Values

userDefineShape

protected boolean userDefineShape

pickShape

PickShape pickShape

pickRootBG

BranchGroup pickRootBG
Used to store the BranchGroup used for picking


pickRootL

Locale pickRootL
Used to store the Locale used for picking


start

Point3d start
Used to store a reference point used in determining how "close" points are.


mode

int mode

BOUNDS

public static final int BOUNDS
Use this mode to pick by bounds and get basic information on the pick.

See Also:
Constant Field Values

GEOMETRY

public static final int GEOMETRY
Use this mode to pick by geometry and get basic information on the pick.

See Also:
Constant Field Values

GEOMETRY_INTERSECT_INFO

public static final int GEOMETRY_INTERSECT_INFO
Use this mode to pick by geometry and save information about the intersections (intersected primitive, intersection point and closest vertex).

See Also:
Constant Field Values

INTERSECT_TEST

public static final int INTERSECT_TEST
Flag to pass to setCapabilities(Node, int) to set the Node's capabilities to allow intersection tests, but not inquire information about the intersections (use for GEOMETRY mode).

See Also:
setCapabilities(javax.media.j3d.Node, int), Constant Field Values

INTERSECT_COORD

public static final int INTERSECT_COORD
Flag to pass to setCapabilities(Node, int) to set the Node's capabilities to allow inquiry of the intersection coordinate information.

See Also:
setCapabilities(javax.media.j3d.Node, int), Constant Field Values

INTERSECT_FULL

public static final int INTERSECT_FULL
Flag to pass to setCapabilities(Node, int) to set the Node's capabilities to allow inquiry of all intersection information.

See Also:
setCapabilities(javax.media.j3d.Node, int), Constant Field Values
Constructor Detail

PickTool

public PickTool(BranchGroup b)
Constructor with BranchGroup to be picked.


PickTool

public PickTool(Locale l)
Constructor with the Locale to be picked.

Method Detail

getBranchGroup

public BranchGroup getBranchGroup()
Returns the BranchGroup to be picked if the tool was initialized with a BranchGroup, null otherwise.


getLocale

public Locale getLocale()
Returns the Locale to be picked if the tool was initialized with a Locale, null otherwise.


setBranchGroup

public Locale setBranchGroup(Locale l)
Deprecated. This method does nothing other than return its input parameter.


setCapabilities

public static void setCapabilities(Node node,
                                   int level)
Sets the capabilities on the Node and it's components to allow picking at the specified detail level.

Note that by default all com.sun.j3d.utils.geometry.Primitive objects with the same parameters share their geometry (e.g., you can have 50 spheres in your scene, but the geometry is stored only once). Therefore the capabilities of the geometry are also shared, and once a shared node is live, the capabilities cannot be changed. To assign capabilities to Primitives with the same parameters, either set the capabilities before the primitive is set live, or specify the Primitive.GEOMETRY_NOT_SHARED constructor parameter when creating the primitive.

Parameters:
node - The node to modify
level - The capability level, must be one of INTERSECT_TEST, INTERSECT_COORD or INTERSECT_FULL
Throws:
java.lang.IllegalArgumentException - if Node is not a Shape3D or Morph or if the flag value is not valid.
RestrictedAccessException - if the node is part of a live or compiled scene graph.

setCapabilities

private static void setCapabilities(GeometryArray ga,
                                    int level)

setCapabilities

private static void setCapabilities(IndexedGeometryArray iga,
                                    int level)

setCapabilities

private static void setCapabilities(CompressedGeometry cg,
                                    int level)

setShape

public void setShape(PickShape ps,
                     Point3d startPt)
Sets the pick shape to a user-provided PickShape object

Parameters:
ps - The pick shape to pick against.
startPt - The start point to use for distance calculations

setShapeBounds

public void setShapeBounds(Bounds bounds,
                           Point3d startPt)
Sets the pick shape to use a user-provided Bounds object

Parameters:
bounds - The bounds to pick against.
startPt - The start point to use for distance calculations

setMode

public void setMode(int mode)
Sets the picking detail mode. The default is BOUNDS.

Parameters:
mode - One of BOUNDS, GEOMETRY, GEOMETRY_INTERSECT_INFO, or
Throws:
java.lang.IllegalArgumentException - if mode is not a legal value

getMode

public int getMode()
Gets the picking detail mode.


setShapeRay

public void setShapeRay(Point3d start,
                        Vector3d dir)
Sets the pick shape to a PickRay.

Parameters:
start - The start of the ray
dir - The direction of the ray

setShapeSegment

public void setShapeSegment(Point3d start,
                            Point3d end)
Sets the pick shape to a PickSegment.

Parameters:
start - The start of the segment p @param end The end of the segment

setShapeCylinderSegment

public void setShapeCylinderSegment(Point3d start,
                                    Point3d end,
                                    double radius)
Sets the pick shape to a capped PickCylinder

Parameters:
start - The start of axis of the cylinder
end - The end of the axis of the cylinder
radius - The radius of the cylinder

setShapeCylinderRay

public void setShapeCylinderRay(Point3d start,
                                Vector3d dir,
                                double radius)
Sets the pick shape to an infinite PickCylinder.

Parameters:
start - The start of axis of the cylinder
dir - The direction of the axis of the cylinder
radius - The radius of the cylinder

setShapeConeSegment

public void setShapeConeSegment(Point3d start,
                                Point3d end,
                                double angle)
Sets the pick shape to a capped PickCone

Parameters:
start - The start of axis of the cone
end - The end of the axis of the cone
angle - The angle of the cone

setShapeConeRay

public void setShapeConeRay(Point3d start,
                            Vector3d dir,
                            double angle)
Sets the pick shape to an infinite PickCone.

Parameters:
start - The start of axis of the cone
dir - The direction of the axis of the cone
angle - The angle of the cone

getPickShape

public PickShape getPickShape()
Returns the PickShape for this object.


getStartPosition

public Point3d getStartPosition()
Returns the start postion used for distance measurement.


pickAll

public PickResult[] pickAll()
Selects all the nodes that intersect the PickShape.

Returns:
An array of PickResult objects which will contain information about the picked instances. null if nothing was picked.

pickAny

public PickResult pickAny()
Select one of the nodes that intersect the PickShape

Returns:
A PickResult object which will contain information about the picked instance. null if nothing was picked.

pickAllSorted

public PickResult[] pickAllSorted()
Select all the nodes that intersect the PickShape, returned sorted. The "closest" object will be returned first. See note above to see how "closest" is determined.

Returns:
An array of PickResult objects which will contain information about the picked instances. null if nothing was picked.

pickClosest

public PickResult pickClosest()
Select the closest node that intersects the PickShape. See note above to see how "closest" is determined.

Returns:
A PickResult object which will contain information about the picked instance. null if nothing was picked.

pickAll

private PickResult[] pickAll(PickShape pickShape)

pickAllSorted

private PickResult[] pickAllSorted(PickShape pickShape)

pickAny

private PickResult pickAny(PickShape pickShape)

pickClosest

private PickResult pickClosest(PickShape pickShape)

pickGeomAll

private PickResult[] pickGeomAll(PickShape pickShape)

pickGeomAllSorted

private PickResult[] pickGeomAllSorted(PickShape pickShape)

pickGeomAny

private PickResult pickGeomAny(PickShape pickShape)

pickGeomClosest

private PickResult pickGeomClosest(PickShape pickShape)

pickGeomAllIntersect

private PickResult[] pickGeomAllIntersect(PickShape pickShape)

pickGeomAllSortedIntersect

private PickResult[] pickGeomAllSortedIntersect(PickShape pickShape)

pickGeomClosestIntersect

private PickResult pickGeomClosestIntersect(PickShape pickShape)

pickGeomAnyIntersect

private PickResult pickGeomAnyIntersect(PickShape pickShape)

sortPickResults

private PickResult[] sortPickResults(PickResult[] pr,
                                     double[] dist)

quicksort

private final void quicksort(int l,
                             int r,
                             double[] dist,
                             int[] pos)


Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.