## com.sun.j3d.utils.pickfast
Class PickTool

    java.lang.Object
      com.sun.j3d.utils.pickfast.PickTool

Direct Known Subclasses:
  PickCanvas

    public class PickTool

extends java.lang.Object

The base class for optimized picking operations. The picking methods will return a PickInfo 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 PickInfo is returned:

- PickInfo.PICK_BOUNDS - Pick using the only bounds of the pickable nodes.
- PickInfo.PICK_GEOMETRY will pick using the geometry of the pickable nodes. Geometry nodes in the scene must have the ALLOW_INTERSECT capability set for this mode.

The pick flags specifies the content of the PickInfo(s) returned by the pick methods. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :

`PickInfo.SCENEGRAPHPATH` - request for computed SceneGraphPath.
`PickInfo.NODE` - request for computed intersected Node.
`PickInfo.LOCAL_TO_VWORLD` - request for computed local to virtual world transform.
`PickInfo.CLOSEST_INTERSECTION_POINT` - request for closest intersection point.
`PickInfo.CLOSEST_DISTANCE` - request for the distance of closest intersection.
`PickInfo.CLOSEST_GEOM_INFO` - request for only the closest intersection geometry information.
`PickInfo.ALL_GEOM_INFO` - request for all intersection geometry information.

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.

See Also:
  `Locale.pickClosest(int,int,javax.media.j3d.PickShape)`

Field Summary
`static int` `TYPE_BRANCH_GROUP` Flag to pass to `getNode(int)` to return a `BranchGroup` node from the `SceneGraphPath`.
`static int` `TYPE_GROUP` Flag to pass to `getNode(int)` to return a `Group` node from the `SceneGraphPath`.
`static int` `TYPE_LINK` Flag to pass to `getNode(int)` to return a `Link` node from the `SceneGraphPath`.
`static int` `TYPE_MORPH` Flag to pass to `getNode(int)` to return a `Morph` node from the `SceneGraphPath`.
`static int` `TYPE_PRIMITIVE` Flag to pass to `getNode(int)` to return a `Primitive` node from the `SceneGraphPath`.
`static int` `TYPE_SHAPE3D` Flag to pass to `getNode(int)` to return a `Shape3D` node from the `SceneGraphPath`.
`static int` `TYPE_SWITCH` Flag to pass to `getNode(int)` to return a `Switch` node from the `SceneGraphPath`.
`static int` `TYPE_TRANSFORM_GROUP` Flag to pass to `getNode(int)` to return a `TransformGroup` node from the `SceneGraphPath`.
`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.
`int` `getFlags()` Gets the PickInfo content flags.
`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.
`Node` `getNode(PickInfo pickInfo, int type)` Get the first node of a certain type up the SceneGraphPath
`PickShape` `getPickShape()` Returns the PickShape for this object.
`Point3d` `getStartPosition()` Returns the start postion used for distance measurement.
`PickInfo[]` `pickAll()` Selects all the nodes that intersect the PickShape.
`PickInfo[]` `pickAllSorted()` Select all the nodes that intersect the PickShape, returned sorted.
`PickInfo` `pickAny()` Select one of the nodes that intersect the PickShape
`PickInfo` `pickClosest()` Select the closest node that intersects the PickShape.
`void` `setFlags(int flags)` Sets the PickInfo content flags.
`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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### TYPE_SHAPE3D

    public static final int TYPE_SHAPE3D

  Flag to pass to `getNode(int)` to return a `Shape3D` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### TYPE_MORPH

    public static final int TYPE_MORPH

  Flag to pass to `getNode(int)` to return a `Morph` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### TYPE_PRIMITIVE

    public static final int TYPE_PRIMITIVE

  Flag to pass to `getNode(int)` to return a `Primitive` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### TYPE_LINK

    public static final int TYPE_LINK

  Flag to pass to `getNode(int)` to return a `Link` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### TYPE_GROUP

    public static final int TYPE_GROUP

  Flag to pass to `getNode(int)` to return a `Group` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### TYPE_TRANSFORM_GROUP

    public static final int TYPE_TRANSFORM_GROUP

  Flag to pass to `getNode(int)` to return a `TransformGroup` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### TYPE_BRANCH_GROUP

    public static final int TYPE_BRANCH_GROUP

  Flag to pass to `getNode(int)` to return a `BranchGroup` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### TYPE_SWITCH

    public static final int TYPE_SWITCH

  Flag to pass to `getNode(int)` to return a `Switch` node from the `SceneGraphPath`.

  See Also:
    Constant Field Values

### userDefineShape

    protected boolean userDefineShape

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.

### 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 PickInfo.PICK_BOUNDS.

  Parameters:
    `mode` - One of PickInfo.PICK_BOUNDS or PickInfo.PICK_GEOMETRY.
  Throws:
    `java.lang.IllegalArgumentException` - if mode is not a legal value

### getMode

    public int getMode()

  Gets the picking detail mode.

### setFlags

    public void setFlags(int flags)

  Sets the PickInfo content flags. The default is PickInfo.NODE.

  Parameters:
    `flags` - specified as one or more individual bits that are bitwise "OR"ed together :
    `PickInfo.SCENEGRAPHPATH` - request for computed SceneGraphPath.
    `PickInfo.NODE` - request for computed intersected Node.
    `PickInfo.LOCAL_TO_VWORLD` - request for computed local to virtual world transform.
    `PickInfo.CLOSEST_INTERSECTION_POINT` - request for closest intersection point.
    `PickInfo.CLOSEST_DISTANCE` - request for the distance of closest intersection.
    `PickInfo.CLOSEST_GEOM_INFO` - request for only the closest intersection geometry information.
    `PickInfo.ALL_GEOM_INFO` - request for all intersection geometry information.
  Throws:
    `java.lang.IllegalArgumentException` - if any other bits besides the above are set.

### getFlags

    public int getFlags()

  Gets the PickInfo content flags.

### 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
    `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 PickInfo[] pickAll()

  Selects all the nodes that intersect the PickShape.

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

### pickAny

    public PickInfo pickAny()

  Select one of the nodes that intersect the PickShape

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

### pickAllSorted

    public PickInfo[] 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 `PickInfo` objects which will contain information about the picked instances. `null` if nothing was picked.

### pickClosest

    public PickInfo pickClosest()

  Select the closest node that intersects the PickShape. See note above to see how "closest" is determined.

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

### getNode

    public Node getNode(PickInfo pickInfo,
                        int type)

  Get the first node of a certain type up the SceneGraphPath

  Parameters:
    `type` - the type of node we are interested in
  Returns:
    a Node object
  Throws:
    `java.lang.NullPointerException` - if pickInfo does not contain a Scenegraphpath or a picked node

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