User's Reference - Pick

### Pick

Category

Special

Function

Outputs a pick structure.

Syntax

    picked = Pick(pickname, imagename, locations, reexecute, first,
                  persistent, interpolate, object, camera);

Inputs

Name | Type | Default | Description
--- | --- | --- | ---
`pickname` | string | none | name of cached picks
`imagename` | string | none | name of cached scene
`locations` | vectorlist | no default | 2-D screen coordinate pick positions
`reexecute` | flag | none | cause reexecution whenever pick list is reset
`first` | flag | 1 | 0: include all "picks" 1: include only first "picks"
`persistent` | flag | 1 | 0: "picks" not saved 1: "picks" saved
`interpolate` | integer | 0 | 0: no data interpolation 1: nearest vertex interpolation 2: interpolate
`object` | object | no default | object to be "poked"
`camera` | camera | none | camera used to create scene picked in

Outputs

Name | Type | Description
--- | --- | ---
`picked` | field | pick structure

Functional Details

Picking involves using the mouse to determine information about an object rendered in an image. (If there is more than one image in the visual program, then the image which is assumed is the one from which picking was made active using the View Control dialog.) The user may select one or more points on the screen by positioning the mouse and pressing the left button; each such action is referred to as a "poke." Each poke may intersect the object at one or more places or may miss the object altogether. Each intersection is called a "pick." For example, a poke on a spherical isosurface will result in two picks, one on the front surface and one on the rear.

Individual subobjects in a structured scene may be made unpickable by attaching an attribute named "pickable", with a value of 0 (zero), to the root of the subobject, using the Options module.

The information returned by Pick in `picked` includes the positions in the (xyz) world-coordinate system at which the picks occurred. These positions (contained in the "positions" component of `picked`) may be used to determine the coordinates of points on objects, to start streamlines, or to label points on the surface (by using AutoGlyph appropriately). These kinds of operations can be done directly in a visual program, without writing a special module.

In addition to the pick positions, `picked` contains information identifying the individual elements of the object structure that was picked. This information can be used to select elements of the object structure at any level down to the connections element and vertex closest to the pick point. See IBM Visualization Data Explorer Programmer's Reference for an example module that uses the position information contained in the pick structure.

`pickname` | is used only by the user interface and is not intended to be set by users.
`imagename` | is used only by the user interface and is not intended to be set by users.
`locations` | is a list of 2 dimensional screen coordinates pixel positions identifying the picks. If you are using the Image tool, this parameter is set automatically for you by the user interface. If you are using SuperviseWindow and SuperviseState, then the `events` output of SuperviseState should be used to provide this input.
`reexecute` | is used only by the user interface and is not intended to be set by users.
`first` | specifies whether all picks generated by a poke intersecting an object are to be added to the pick structure or only the first pick (i.e., the pick closest to the viewpoint):
0 | All picks are added to the output.
1 | Only the first pick is reported for each poke.
`persistent` | specifies whether or not picks are saved between executions:
0 | Picks are not saved.
1 | Picks are saved and are deleted only when the user makes new pokes. Note: When new picks are made, the previous pick points are discarded.
`interpolate` | specifies whether a "data" component should be created in `picked` and, if so, how the interpolation of values for that component should be performed. If the `interpolate` parameter is set to 1 or 2, the Pick output object will contain a set of components matching the set of dependent components in the picked object. Each of the components in the output object is dependent on the "positions" component of `picked`. For components that are dependent on connections in the picked object, the data for the picked element will be placed in the output component. For components that are dependent on positions in the picked object, the data placed in the output object is determined by one of two options:
1 = "nearest vertex" | The data corresponding to the vertex nearest the pick point is extracted.
2 = "interpolated data" | The data is interpolated from the vertex data of the picked element.
In either case, an additional component is created (called "closest vertex") that receives the coordinates of the vertex closest to the pick point among the vertices of the picked element. Note: Regardless of which of the two options is selected, if different picks result in different sets of components or different data types in components of the same name, an error results.
`object` | allows the user to override the object being picked. By default, this object is the one rendered in the Image window associated with the previous execution of the graph. If the scene consists of several objects collected before rendering, and if only some of them are to be made pickable, the user can pass those objects directly into Pick. The `object` parameter also makes it possible to pick in an object that lies in the same coordinate space as the scene does but is not in fact a part of the scene.
`camera` | sets the camera used to create the scene being picked in. If you are using the Image tool, this parameter is set automatically for you by the user interface. If you are using SuperviseState and SuperviseWindow, then you must provide the camera used to render the scene.

Note: Pick currently supports surfaces, lines, and points. Picking does not support volume elements; if a poke is made on a volume object in the image, no picks will result.

Example Visual Program

    PickStreamline.net

See Also

SuperviseWindow, SuperviseState

"Using Pick" in IBM Visualization Data Explorer User's Guide.

[ OpenDX Home at IBM | OpenDX.org ]