# IBM Visualization Data Explorer Programmer's Reference

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]

## 9.2 ShowPick Module Example--Using Color to Show a Picked Object

In the following example, the ShowPick module colors the entire object in white, except for the Field, element, or vertex containing the pick point(s). The color of the latter is specified by the user.

The module description file for ShowPick is:

    MODULE ShowPick
    CATEGORY User
    DESCRIPTION sets a triangle in a picked Field to a particular color
    INPUT input; object; (none); object with picked points
    INPUT pickobject; field; (none); picking structure
    INPUT color; string; "red"; color to set
    INPUT colorwhich; integer; 0; color the element (0), vertex (1) or entire field (2)
    INPUT poke; integer; (all); poke selection
    INPUT pick; integer; (all); pick selection
    INPUT depth; integer; (bottom); selection depth
    OUTPUT output; object; object with picked structures marked using color

As the `.mdf` file shows, the ShowPick module takes seven inputs and generates one output. To create a version of Data Explorer that includes this module, copy the following files to the directory where you want to work:

    /usr/share/dx/samples/program_guide/Makefile_supported workstation model
    /usr/share/dx/samples/program_guide/showpick.c
    /usr/share/dx/samples/program_guide/showpick.mdf

Now rename the makefile to `Makefile` and enter: `make showpick`. This command creates an executable that contains the ShowPick module.

To invoke this version (from the directory to which the files were copied), enter:

    dx  -mdf ./showpick.mdf -exec ./dxexec

This command starts Data Explorer (the `showpick.mdf` file tells the graphical user interface about ShowPick and its inputs and outputs). With this version of Data Explorer you can now run any visual program that uses the ShowPick module. One such program is `showpick.net` in the `/usr/share/dx/samples/program_guide` directory.

    01   #include <dx/dx.h>
    02   #include "pick.h"
    03
    04   static Error DoPick(Object, Object, RGBColor, int, int, int, int);
    05   static Error SetColor(Object, RGBColor);
    06
    07   Error m_ShowPick(Object *in, Object *out)
    08   {
    09     Object o = NULL, pickfield;
    10     char *colorstring;
    11     int colorwhich, poke, pick, depth;
    12     RGBColor color;

Copy the structure of `in[0]`, the object in which picking took place.

    13     if (!in[0]) {
    14       DXSetError(ERROR_BAD_PARAMETER, "missing input");
    15       goto error;
    16     }
    17     o = (Object)DXCopy(in[0], COPY_STRUCTURE);
    18     if (!o)
    19       goto error;

First, set all the colors to white, to initialize. (The SetColor routine is defined below.)

    20     if (!SetColor(o, DXRGB(1.0, 1.0, 1.0)))
    21       goto error;

`in[1]` is the pick Field. If the pick Field is `NULL` or an empty Field, just return the copy of the object.

    22     if (!in[1] || DXEmptyField(in[1])) {
    23       out[0] = o;
    24       return OK;
    25     }
    26     pickfield = in[1];

Get the color that will be used for picked Objects, which is `in[2]`.

    27     if (in[2]) {
    28       if (!DXExtractString((Object)in[2], &colorstring)) {
    29         DXSetError(ERROR_BAD_PARAMETER,"color must be a string");
    30         goto error;
    31       }

Convert the color name to an RGB vector.

    32
    33       if (!DXColorNameToRGB(colorstring, &color))
    34         goto error;
    35     }
    36     else {

If `in[2]` is not specified, then the default color is red.

    37       color = DXRGB(1.0, 0.0, 0.0);
    38     }

Determine if we are to color just the picked element, just the vertex closest to the picked point, or the entire Field. The default is to color just the picked element.

    39     if (!in[3]) {
    40       colorwhich = 0;
    41     }
    42     else {
    43       if (!DXExtractInteger(in[3], &colorwhich)) {
    44         DXSetError(ERROR_BAD_PARAMETER,"colorwhich flag must be 0, 1, or 2");
    45         goto error;
    46       }
    47       if ((colorwhich < 0)&&(colorwhich > 2)) {
    48         DXSetError(ERROR_BAD_PARAMETER,"colorwhich flag must be 0, 1, or 2");
    49         goto error;
    50       }
    51     }

Determine if we are to select a particular poke, or all of them. The default is to select all of them.

    52
    53     if (!in[4]) {
    54       poke = -1;
    55     }
    56     else {
    57       if (!DXExtractInteger(in[4], &poke)) {
    58         DXSetError(ERROR_BAD_PARAMETER,"poke must be a nonnegative integer");
    59         goto error;
    60       }
    61       if (poke < 0) {
    62         DXSetError(ERROR_BAD_PARAMETER,"poke must be a nonnegative integer");
    63         goto error;
    64       }
    65     }

Determine if we are to select a particular pick, or all of them. The default is to select all of them.

    66     if (!in[5]) {
    67       pick = -1;
    68     }
    69     else {
    70       if (!DXExtractInteger(in[5], &pick)) {
    71         DXSetError(ERROR_BAD_PARAMETER,"pick must be a nonnegative integer");
    72         goto error;
    73       }
    74       if (pick < 0) {
    75         DXSetError(ERROR_BAD_PARAMETER,"pick must be a nonnegative integer");
    76         goto error;
    77       }
    78     }

Determine if we are to select a depth. The default is to select the deepest level.

    79     if (!in[6]) {
    80       depth = -1;
    81     }
    82     else {
    83       if (!DXExtractInteger(in[6], &depth)) {
    84         DXSetError(ERROR_BAD_PARAMETER,"depth must be a nonnegative integer");
    85         goto error;
    86       }
    87       if (depth < 0) {
    88         DXSetError(ERROR_BAD_PARAMETER,"depth must be a nonnegative integer");
    89         goto error;
    90       }
    91     }

Traverse the picked object, using the pick structure, passing the given parameters.

    92     if (!DoPick(o, pickfield, color, colorwhich, poke, pick, depth))
    93       goto error;

Delete the `opacities` component.

    94     if (DXExists(o, "opacities"))
    95       DXRemove(o,"opacities");

Successful return.

    96     out[0] = o;
    97     return OK;

Return on error.

    98    error:
    99     DXDelete(o);
    100    return ERROR;
    101  }

The `DoPick()` routine traverses the picked object.

    102  static
    103    Error
    104    DoPick(Object o, Object pickfield, RGBColor color, int colorwhich,
    105       int pokes, int picks, int depth)
    106  {
    107    int pokecount, pickcount, poke, pick, i, pathlength;
    108    int vertexid, elementid, *path, numitems, index;
    109    Object current;
    110    Matrix matrix;
    111    Array a, newcolors=NULL, oldcolors;
    112    char *depatt;
    113    RGBColor *newcolors_ptr, oldcolor;
    114    int pokemin, pokemax;
    115    int pickmin, pickmax;
    116    int thisdepth;

`pickfield` is expected to be a Field.

    117    if (!(DXGetObjectClass(pickfield)==CLASS_FIELD)) {
    118      DXSetError(ERROR_INVALID_DATA,"pickfield must be a field");
    119      goto error;
    120    }

Find out the number of pokes.

    121    DXQueryPokeCount(pickfield, &pokecount);

The user has chosen to mark all pokes.

    122    if (pokes < 0) {
    123      pokemin = 0, pokemax = pokecount-1;
    124    }

The user has specified a poke larger than the number present.

    125    else if (pokes > pokecount-1) {
    126      DXSetError(ERROR_BAD_PARAMETER,
    127             "only %d pokes are present", pokecount);
    128      return ERROR;
    129    }

Consider only the specified poke.

    130    else
    131      pokemin = pokemax = pokes;

For each poke...

    132    for (poke=pokemin; poke<=pokemax; poke++) {

Find out how many picks there are in this poke.

    133      if (!DXQueryPickCount(pickfield, poke, &pickcount))
    134        goto error;

Issue warning if this particular poke does not contain as many picks as the user has specified.

    135      if (picks > pickcount-1) {
    136        DXWarning("poke %d contains only %d picks", poke, pickcount);
    137      }
    138
    139      else {
    140        if (picks < 0) {
    141          pickmin = 0, pickmax = pickcount-1;
    142        }
    143        else {
    144          pickmin = pickmax = picks;
    145        }

For each pick...

    146
    147        for (pick=pickmin; pick<=pickmax; pick++) {

For the given `pickfield`, the current poke number, and the current pick number, get the traversal path `path`, the length of the traversal path `pathlength`, and the IDs of the picked element and the picked vertex.

    148   DXQueryPickPath(pickfield, poke, pick, &pathlength, &path,
    149                   &elementid, &vertexid);

Initialize `current` to the picked object, and `matrix` to the identity matrix.

    150   current = o;
    151   matrix = Identity;
    152   if (depth != -1 && pathlength > depth)
    153     thisdepth = depth;
    154   else
    155     thisdepth = pathlength;

Iterate through the pick path.

    156   for (i=0; i<thisdepth; i++) {
    157     current = DXTraversePickPath(current, path[i], &matrix);
    158     if (!current)
    159       goto error;
    160   }

`current` is now the Field level of the picked Object, and we have the element and vertex IDs of the picked object.

    161   if (colorwhich == 2 || DXGetObjectClass(current) != CLASS_FIELD) {

We are simply to color the entire Field.

    162     if (!SetColor(current, color))
    163       goto error;
    164   }
    165   else {

Otherwise, we want to set the indicated element or vertex to the given color. We start by making a new colors component (not compact), but only if the input colors component is still compact. If it is already expanded, then modify it.

First, determine the dependency of the colors.

    166     if (colorwhich == 0) {
    167          if (a = DXGetComponentValue(current, "connections")) {
    168              index = elementid;
    169              depatt = "connections";
    170          }
    171          else if (a = DXGetComponentValue(current, "faces")) {
    172              index = elementid;
    173              depatt = "faces";
    174          }
    175          else {
    176               a = DXGetComponentValue(current, "positions");
    177               index = vertexid;
    178               depatt = "positions";
    179          }
    180     }
    181     else {
    182       a = DXGetComponentValue(current, "positions");
    183       index = vertexid;
    184       depatt = "positions";
    185     }

Determine the number of items.

    186     if (!DXGetArrayInfo(a, &numitems,NULL,NULL,NULL,NULL))
    187       goto error;

If the traversal index is greater than the number of items, something is wrong.

    188        if (index >= numitems) {
    189          DXSetError(ERROR_INVALID_DATA,
    190                  "pick structure does not correspond to picked object");
    191          goto error;
    192        }

Get the original colors component.

    193        oldcolors = DXGetComponentValue((Field)current, "colors");

If it is a constant Array, we need to expand it so that we can set just one element or vertex to the given color.

    194     if (DXQueryConstantArray(oldcolors, NULL, &oldcolor)) {

Create a new colors Array and allocate space to it.

    195       newcolors = DXNewArray(TYPE_FLOAT,CATEGORY_REAL, 1, 3);
    196       if (!DXAddArrayData(newcolors, 0, numitems, NULL))
    197         goto error;

Start by setting all colors to the original constant color.

    198       newcolors_ptr = (RGBColor *)DXGetArrayData(newcolors);
    199       for (i=0; i<numitems; i++) {
    200         newcolors_ptr[i] = oldcolor;
    201       }

Replace the colors in the Field with the new colors component.

    202       if (!DXSetComponentValue((Field)current, "colors",
    203                        (Object)newcolors))
    204         goto error;
    205       newcolors=NULL;
    206
    207       DXSetComponentAttribute((Field)current, "colors", "dep",
    208                        (Object)DXNewString(depatt));
    209     }
    210
    211
    212     else {

The colors are already expanded, presumably from an earlier pick in this Field.

    213       newcolors_ptr = (RGBColor *)DXGetArrayData(oldcolors);
    214     }

Set the correct triangle or position to the given color.

    215     newcolors_ptr[index] = color;
    216    }
    217   }
    218  }
    219 }
    220
    221  return OK;
    222
    223   error:
    224    DXDelete((Object)newcolors);
    225    return ERROR;
    226  }

This routine sets all colors in object `o` to the given color.

    227  static Error SetColor(Object o, RGBColor color)
    228  {
    229    Object subo;
    230    Array a, newcolors=NULL;
    231    int numitems, i;
    232
    233
    234    switch (DXGetObjectClass(o)) {
    235
    236
    237    case (CLASS_GROUP):
    238

If `o` is a Group, call `SetColor` recursively on its children.

    239      for (i=0; subo = DXGetEnumeratedMember((Group)o, i, NULL); i++))
    240        SetColor(subo, color);
    241      break;
    242
    243
    244    case (CLASS_XFORM):

If `o` is an Xform, call `SetColor` on its child.

    245      DXGetXformInfo((Xform)o, &subo, NULL);
    246      SetColor(subo, color);
    247      break;
    248
    249
    250    case (CLASS_CLIPPED):

If `o` is a Clipped object, call `SetColor` on its child.

    251      DXGetClippedInfo((Clipped)o, &subo, NULL);
    252      SetColor(subo, color);
    253      break;
    254
    255
    256    case (CLASS_FIELD):

If `o` is a Field, set the colors to the given color.

    257      if (DXEmptyField((Field)o))
    258        return OK;

The number of colors and the dependency of the colors will depend on whether connections are present. If not, it is checked for the presence of faces. Otherwise, the colors will be dependent on positions.

    259      if (a = DXGetComponentValue((Field)o, "connections")) {
    260        DXGetArrayInfo(a, &numitems, NULL, NULL, NULL, NULL);
    261        newcolors = (Array)DXNewConstantArray(numitems, &color,
    262                                TYPE_FLOAT,
    263                                CATEGORY_REAL, 1, 3);
    264        DXSetComponentValue((Field)o, "colors", (Object)newcolors);
    265        newcolors = NULL;
    266        DXSetComponentAttribute((Field)o,"colors", "dep",
    267                        (Object)DXNewString("connections"));
    268      }
    269      else if (a = DXGetComponentValue((Field)o, "faces")) {
    270        DXGetArrayInfo(a, &numitems, NULL, NULL, NULL, NULL);
    271        newcolors = (Array)DXNewConstantArray(numitems, &color,
    272                                TYPE_FLOAT,
    273                                CATEGORY_REAL, 1, 3);
    274        DXSetComponentValue((Field)o, "colors", (Object)newcolors);
    275        newcolors = NULL;
    276        DXSetComponentAttribute((Field)o,"colors", "dep",
    277                        (Object)DXNewString("faces"));
    278      }

    279      else {
    280        a = DXGetComponentValue((Field)o, "positions");
    281        DXGetArrayInfo(a, &numitems, NULL, NULL, NULL, NULL);
    282        newcolors = (Array)DXNewConstantArray(numitems, &color,
    283                                TYPE_FLOAT,
    284                                CATEGORY_REAL, 1, 3);
    285        DXSetComponentValue((Field)o, "colors", (Object)newcolors);
    286        newcolors = NULL;
    287        DXSetComponentAttribute((Field)o,"colors", "dep",
    288                        (Object)DXNewString("positions"));
    289      }
    290
    291      break;
    292    }
    293

Successful return or return on error.

    294
    295    return OK;
    296   error:
    297    DXDelete((Object)newcolors);
    298    return ERROR;
    299  }

[ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
[Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

[Data Explorer Home Page]

[IBM Home Page | Order | Search | Contact IBM | Legal ]