The data type described here, cxPick, can be used in two kinds of modules: those that read cxPick data objects on their input ports, and those that write cxPick data objects through their output ports.

The purpose of the cxPick data type is to enable the user to pick, or select, a particular location in a module display window and obtain information about it. cxPick is a specialized data type, used only in 2-D and 3-D modules.

You can obtain information about an image in the window of a module that displays images (2-D), or a geometry object in the window of a rendering module (3-D).You do this by using the mouse to select items out of a picture in a module display window. For example, you may want to query part of a picture of an isosurface. You could find the coordinates of a spot on the surface or the temperature at that point. The window in which the isosurface is displayed can be in the Render module, in DisplayImg, or in your own rendering module, all of which have Pick output ports.

You can send the information you have picked in the Render or DisplayImg window to a module with a Pick input port, such as PrintPick.

You can also create an object where one did not previously exist, or position an object in a particular location in a rendering module display window. As you click on the position in the window, the information goes to the upstream module, which creates an object, for example a line or an atom, and sends it to the selected position in the Render window.

There are two points to note about the cxPick data type:

You can use cxPick in any module that you want to output information about geometry objects, and in any module that you want to receive this information. In the Explorer module suite, for example, the QueryLat, PrintPick, and MoleculeBuilder modules all have cxPick on their input ports and can therefore read pick data. The Render module can write pick data to its Pick output port and hence feed information back to the QueryLat and MoleculeBuilder modules.

Module users can activate Pick mode in a Render window by selecting “User Pick Mode” from the Viewing Menu and toggling the “eye” icon to turn off viewing mode. To use Pick mode in a DisplayImg window, they simply press the middle mouse button.

The cxPick data type provides a vast amount of data, as you can see from its data type structure in Figure 6-1. It takes some thought to decide exactly what you want cxPick to do for you. There are two ways in which module writers commonly use cxPick; to build modules that read pick data, and to build modules that write pick data. Further, your module could read pick data from either an image (2-D) or from geometry (3-D). Or it could write pick data obtained from an image or a geometry object.

The cxPick Structure

The variables in the cxPick data structure let you specify all the information you want to put into or get from the module. You may not need all the variables; for example, if you write a module that displays images, you will not need the variables that pertain to the picking of geometric objects. When you create the cxPick type, you should null out all the unfilled variables.

Terminology

To make the function of each variable easier to understand, it helps to clarify some terms. A pick is what you do when you select a spot in the display window of a module by clicking the mouse on it. A hit is when you touch on part of an object or image, instead of empty space. A pick object is the object or image you touched on. A pick event is the act of picking the object, and it occurs when you press a mouse button or key, or drag the mouse across the window.

Once you have made a hit, you can gather a great deal of information about the object you hit. This information is laid out in the subtype, cxPickHit.

This is the data type definition:

root typedef struct { int eventType “Event Type”; long eventData “Event Data”; long eventModifiers “Modifier Keys”; int position[2] “Position Array”; int windowSize[2] “Window Size Array”; float origin[3] “Ray Origin”; float direction[3] “Ray Direction”; float projectionMatrix[4, 4] “Projection Matrix”; int numHits “Num Object Hits”; cxPickHit hit[numHits] “Hits Array”; } cxPick;

The variables are:

event type		Indicates what the user action was, i.e., whether the user dragged the mouse, pressed or released a mouse button, or pressed a key. The action is specified by the X event number for the particular action.
eventData		Indicates which mouse button or key was pressed. The X windows definitions are used for buttons and keys.
eventModifiers		Indicates whether a modifier key, such as <Shift> or <Alt>, was pressed. Specified by the X event set of flags.
position		Gives the exact 2-D position in the window where the action took place. It is x,y from the top left corner, in integers)
windowSize		Gives the size of the module window (in pixels) in which the pick occurred.
origin		Indicates the position of the eye (3-D only). It can be defined as a ray running from eye point to the pick point, and it has both position and direction.
direction		Specifies the direction of the ray from eye to object (3-D only)
projectionMatrix		Specifies the 3-D projection; contains a perspective transformation, if present. Of the standard Explorer modules, only Render generates this data.
numHits		Gives the number of object that were clicked on, or “hit” by the user's action
hit		Tells you what kind of object you hit, ordered from nearest to furthest from the viewer. The information is given by cxObjectDefine, which specifies whether the hit was on a point, face, or volume.

If the user does not hit any object in the module window, or if the window is empty, the variable numhits is zero and hits will contain no data.

If the user actually hits something, then a cxPickhit data structure will be filled in with information about the object or objects.

Figure 6-1 depicts the pick data type structure.

Figure 6-1. Schematic Structure of the Pick Data Type

Getting Data on the Hit Object

When the user presses a button in Pick mode and hits an object or image, the cxPickHit data structure can provide a lot of information about that object or image.

The data type definition is:

typedef struct { long id; long validInfo; float point[3]; float normal[3]; float color[3]; string label; float localTransform[4, 4]; float globalTransform[4, 4]; cxPickObject objectType; switch (objectType) { case cx_pick_point: long index; case cx_pick_line: long index[2]; float point[2, 3]; float normal[2, 3]; case cx_pick_face: long nvertices; long index[nvertices]; float point[nvertices, 3]; float normal[nvertices, 3]; case cx_pick_cone: long part; case cx_pick_cylinder: long part; } o; } cxPickHit;

These are the variables:

id		Gives an ID for the module that generated the picked image or object. This field allows the module that generated the picked geometry to identify it. For example, if a module generates geometry and then gets back pick information, it can compare the pick ID with its own ID to see if they match. If not, it can ignore the information.
validInfo		A bit vector that indicates whether the pick information in the following six fields is valid. The fields are all bit fields in validInfo.
point		Defines a point which gives the placement of an object. DisplayImg returns coordinates (x, y) in image space and Render in 3-D world space (x, y, z). The coordinates are floating point values.
normal		Gives the surface normal (if available) through the API routine cxGeoNormalAdd.
color		Gives the color, if it has one. The color of an object in Render is governed by an upstream module, which may not necessarily send any color value down. In this case, Render gives the object a default color, but the hue bears no relation to the data values at all. You can use the API routines cxGeoColorAdd or cxGeoABGRAdd to set a color. You can also use the Inventor nodes SoMaterial, SoBaseColor, and SoPackedColor if you are working with geometry.
label		Names the object by its label name in the geometry scene graph. DisplayImg does not use the label field. You can use cxGeoLabelAdd or add the label in Inventor.
localTransform		Gives the transform matrix if a geometry object has been translated or rotated in the Render module that generated the pick event. Upstream modules don't know about local transforms. You can use the API routines cxGeoRotate, cxGeoTranslate, and cxGeoScale to perform the transform.
globalTransform		Gives the transform matrix if the object has been translated or rotated anywhere in the module chain This includes transforms from upstream modules. It is a camera transform.

---

Note: Not all fields are applicable to all objects. The bit masks for each field in validInfo are in the cxPickValid enumeration in /usr/explorer/include/cx/Pick.h

---

objectType

Tells you what kind of object sustained the hit. For some objects, including points, lines, faces, cones, and cylinders, you can collect information about indices, normals, vertices, and parts.

Figure 6-2 shows the structure of the cxPickHit data type.

Figure 6-2. Schematic Structure of the PickHit Data Type

Labeling Items in Scene Graphs

The QueryLat module is an example of how to label items in a scene graph. QueryLat responds to pick mouse button events by determining the lattice value at the first pick intersection and creating a label, which is text geometry, with that value. The value passes into Render through its annotation port and is displayed at the correct location in the Render window.

Figure 6-3 shows the “pick” map, which contains QueryLat. The map is distributed with Explorer and can be launched from the Module Librarian.

Figure 6-3. The Pick Map

QueryLat takes as input a lattice and the pick data from the Render module. The input port of QueryLat has connections from ReadLat and the Render pick output. Its output port is wired into the Render “Annotations” input port. When you hold down the mouse button (in User Pick mode) on a point in the Render window, the value of the lattice at that point is displayed. If you pick on an empty part of the window, the value is null.

Gathering Shape Information.

You can collect more information about certain types of hit objects from the Render module:

xpoints		you can determine the index of the point that was hit
lines		you can collect the indices of end-points and the normals at the end-points (if they exist)
polygons		you can determine the number of sides, and the indices, locations, and normals of the vertices (3-D only)
cones and cylinders		Render outputs a part number, taken from Inventor, which indicates whether you picked the side, base, or top of the object. For cylinders, the part numbers are: side = 1 top = 2 bottom = 4 For cones, the part numbers are: side = 1 bottom = 2

The cxPick data type, though defined in the Explorer typing language, can be considered as a C structure. Fortran users need to set pointers to the data type structures when they use them. The type declaration resides in the header file /usr/explorer/include/cx/cxPick.h.

typedef enum {
    cx_pick_none,
    cx_pick_point,
    cx_pick_line,
    cx_pick_face,
    cx_pick_sphere,
    cx_pick_cone,
    cx_pick_cylinder,
    cx_pick_nurb,
    cx_pick_splat,
    cx_pick_other
} cxPickObject;

typedef struct cxPickHit {
    long              id;
    long              validInfo;
    float            *point;
    float            *normal;
    float            *color;
    char             *label;
    float            *localTransform;
    float            *globalTransform;
    cxPickObject      objectType;
    union {
        struct {
            long              index;
        } cx_pick_point;
        struct {
            long             *index;
            float            *point;
            float            *normal;
        } cx_pick_line;
        struct {
            long              nvertices;
            long             *index;
            float            *point;
            float            *normal;
            } cx_pick_face;
        struct {
            long              part;
        } cx_pick_cone;
        struct {
            long              part;
        } cx_pick_cylinder;
    } o;
} cxPickHit;

typedef struct cxPick {
    cxDataCtlr       ctlr;
    int               eventType;
    long              eventData;
    long              eventModifiers;
    int              *position;
    int              *windowSize;
    float            *origin;
    float            *direction;
    float            *projectionMatrix;
    int               numHits;
    cxPickHit        *hit;
} cxPick;

The Fortran type enumerations reside in /usr/explorer/include/cx/cxPick.inc.

INTEGER cx_pick_none
INTEGER cx_pick_point
INTEGER cx_pick_line
INTEGER cx_pick_face
INTEGER cx_pick_sphere
INTEGER cx_pick_cone
INTEGER cx_pick_cylinder
INTEGER cx_pick_nurb
INTEGER cx_pick_splat
INTEGER cx_pick_other
PARAMETER (cx_pick_none                    = 0)
PARAMETER (cx_pick_point                   = 1)
PARAMETER (cx_pick_line                    = 2)
PARAMETER (cx_pick_face                    = 3)
PARAMETER (cx_pick_sphere                  = 4)
PARAMETER (cx_pick_cone                    = 5)
PARAMETER (cx_pick_cylinder                = 6)
PARAMETER (cx_pick_nurb                    = 7)
PARAMETER (cx_pick_splat                   = 8)
PARAMETER (cx_pick_other                   = 9)

You can use the API (Application Programming Interface) routines to manipulate the pick data type in Explorer. They are described in detail in the IRIS Explorer Reference Pages. They let you:

Table 6-1 lists the subroutines and briefly describes the purpose of each one.

This section includes examples of user functions for modules that read pick data. The user function for a module that writes pick data is given in “Writing Pick Data.”

#include<stdio.h>

#include<cx/DataAccess.h>
#include<cx/cxLattice.h>
#include<cx/cxPick.h>

readpick(cxPick*pick,cxLattice**lattice)
{
    int     i;        /*loop variable*/
    long    dims[1];  /*dimensions vector*/
    long    id;       /*temporary variable for pickid*/
    float   *p;       /*coordinate pointer*/

    /*don't output anything if the pick didn't hit anything*/
    if ( pick->numHits == 0 )
       return;

     /* create the output lattice */ 
    /*lattice = cxLatNew(1,dims ,1,cx_prim_float ,3,  
     cx_coord_curvilinear );

    /* set the pointer to the coordinates */
    p = (*lattice)->coord->c.cx_coord_curvilinear.values;

    /* loop over the hits */
    for ( i = 0; i < pick->numHits; i++ )
    {
    /* get the location and id */
    cxPickHitGet(pick,i,
        &id, /* pick id */
        HULL, /* valid info flags */
        p, /* coordinate */
        NULL, /* normal */
        NULL, /* color */
        NULL, /* label */
     NULL, /* local transform */
     NULL, /* global transform */
     NULL); /* object type */
   /* set the data value to the pick id */
   (*lattice)->data->d.cx_prim_float.values[i] = id;

   /* increment the coordinate pointer */
   p += 3;
   }
}

   subroutine PickProc(pickPort, numHits, ndim, dims, nDataVar, 
*     primType, data, nCoordVar, coords, coordType)

   integer pickPort
   integer numHits	
   integer ndim, dims(1), nDataVar, nCoordVar, coordType, primType
   real data(1)
   real coords(3,1)

   integer cxPickHitGet

c info from cxPickHitGet
   real point(3)
   integer id, validInfo, objectType
   character*1 label(256)
   real localxform(4,4), globalxform(4,4)
   real color(4), normal(3)

   if(numHits.eq.0) return
c set up the output lattice parameters

  ndim = 1
  dims(1) = numHits
  nDataVar = 1
  primType = 3
  nCoordVar = 3
  coordType = 2
 

  do 100 i=1,numHits
      ier = cxPickHitGet(pickPort,i-1,id,validInfo,point,normal,
 *       color,label,localxform,globalxform,objectType)
      coords(1,i) = point(1)
      coords(2,i) = point(2)
      coords(3,i) = point(3)

      data(i) = id
100 continue

    return
    end
 

#include <stdio.h>

#include <cx/PortAccess.h>
#include <cx/DataTypes.h>
#include <cx/DataAccess.h>
#include <cx/UserFuncs.h>
#include <cx/Geometry.h>
#include <cx/Lookup.h>

#include <cx/Pick.h>

extern “C” long pick2()
{
    static int flag = 1;
    if ( flag )
    {
      flag = 0;
      cxGeoInit();
    }

   /* allocate new geometry object */
   cxGeometry *geo = cxGeoNew();
   cxGeoBufferSelect(geo);

  /* delete everything */
  cxGeoRoot();
   cxGeoDelete();

   /* if this is a new lattice, create the lookup table */
   static cxLookup *lut = NULL;
   static cxPrimType ltype = cx_prim_byte;
   int lport = cxInputPortOpen(“Lattice”);
   if ( cxInputDataChanged(lport) )
   {
      if ( lut )
       cxLookupDestroy(lut);

      cxLattice *lattice = (cxLattice  *)cxInputDataGet(lport);
      lut = cxLookupCreate(lattice,cx_lookup_linear);
      ltype = lattice->data->primType;
   }
/* get the pick information */
   cxPick *p = (cxPick *)cxInputDataGet(cxInputPortOpen(“Pick”));

   if ( p->eventType == CX_PICK_BTNDOWN || p->eventType == CX_PICK_MOTION )
   {
     if ( p->numHits > 0 )
     {
        /* do a lookup */
        switch (ltype)
           {
#define CASE(ctype,type,format) \
  case ctype: { \
    type value; \
    if ( cxLookupInterp(lut,p->hit[0].point,&value) ) \
        cxGeoTextDefine(“domain error”, \
            NULL); \
    else { \
         char str[128]; \
         sprintf(str,format,value); \
         cxGeoTextDefine(str, \
              NULL); \
       }\
   } \
      break;
            CASE(cx_prim_byte,char,”%d”)
            CASE(cx_prim_short,short,”%d”)
            CASE(cx_prim_long,long,”%d”)
            CASE(cx_prim_float,float,”%f”)  
            CASE(cx_prim_double,double,”%f”)
#undef CASE
           }
#endif
           cxGeoTranslate(p->hit[0].point[0],
              p->hit[0].point[1],
              p->hit[0].point[2]);
      }
   }
   /* close the buffer and output */
   cxGeoBufferClose(geo);
   cxOutputDataSet(cxOutputPortOpen(“Annotation”),
                  (void *)geo);

   return 0;
}