: Class PickTool

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.sun.j3d.utils.picking
Class PickTool

java.lang.Object
  |
  +--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:

PickTool.BOUNDS - Pick using the bounds of the pickable nodes. The PickResult returned will contain the SceneGraphPath to the picked Node.
PickTool.GEOMETRY will pick using the geometry of the pickable nodes. The PickResult returned will contain the SceneGraphPath to the picked Node. Geometry nodes in the scene must have the ALLOW_INTERSECT capability set for this mode.
PickTool.GEOMETRY_INTERSECT_INFO -is the same as GEOMETRY, but the the PickResult will also include information on each intersection of the pick shape with the geometry. The intersection information includes the sub-primitive picked (that is, the point, line, triangle or quad), the closest vertex to the center of the pick shape, and the intersection's coordinate, normal, color and texture coordinates. To allow this information to be generated, Shape3D and Morph nodes must have the ALLOW_GEOMETRY_READ capability set and GeometryArrays must have the ALLOW_FORMAT_READ, ALLOW_COUNT_READ, and ALLOW_COORDINATE_READ capabilities set, plus the ALLOW_COORDINATE_INDEX_READ capability for indexed geometry. To inquire the intersection color, normal or texture coordinates the corresponding READ capability bits must be set on the GeometryArray.

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.

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).

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 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.

PickResult[] pickAllSorted()
          Select all the nodes that intersect the PickShape, returned sorted.

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

PickResult pickClosest()
          Select the closest node that intersects the PickShape.

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

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.

Methods inherited from class java.lang.Object

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

Field Detail

BOUNDS

public static final int BOUNDS

Use this mode to pick by bounds and get basic information on the pick.

GEOMETRY

public static final int GEOMETRY

Use this mode to pick by geometry and get basic information on the pick.

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).

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)





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)






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)










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.



setBranchGroup
public Locale setBranchGroup(Locale l)

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



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.

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.





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
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:
An array of PickResult objects which will contain 
information about the picked instances. 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:
An array of PickResult objects which will contain 
information about the picked instances. null if nothing 
was picked.












  
      Overview 
      Package 
    Class 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES



  SUMMARY:  INNER | FIELD | CONSTR | METHOD

DETAIL:  FIELD | CONSTR | METHOD

Field Summary
`static int`	`BOUNDS` Use this mode to pick by bounds and get basic information on the pick.
`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).`

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`	`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.
`PickResult[]`	`pickAllSorted()` Select all the nodes that intersect the PickShape, returned sorted.
`PickResult`	`pickAny()` Select one of the nodes that intersect the PickShape
`PickResult`	`pickClosest()` Select the closest node that intersects the PickShape.
`Locale`	`setBranchGroup(Locale l)` Returns the Locale to be picked if the tool was initialized with a Locale, null otherwise.
`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.

com.sun.j3d.utils.picking Class PickTool

BOUNDS

GEOMETRY

GEOMETRY_INTERSECT_INFO

INTERSECT_TEST

INTERSECT_COORD

INTERSECT_FULL

PickTool

PickTool

getBranchGroup

setBranchGroup

setCapabilities

setShape

setShapeBounds

setMode

getMode

setShapeRay

setShapeSegment

setShapeCylinderSegment

setShapeCylinderRay

setShapeConeSegment

setShapeConeRay

getPickShape

getStartPosition

pickAll

pickAny

pickAllSorted

pickClosest

com.sun.j3d.utils.picking
Class PickTool