IBM Visualization Data Explorer Programmer's Reference

14.3 Invalid Data

In order to support the elimination of unwanted items from a data set, positions, connections, faces, or polylines in a Field can be "invalidated" by placing a corresponding "invalid positions," "invalid connections," "invalid faces," or "invalid polylines" component in that Field. An "invalid" component lists the individual data items of the positions, connections, faces, or polylines component that are invalid.

In position-, connection-, face-, and polyline-dependent components, data items that correspond to invalid elements are themselves invalid. Data may be invalidated by modifying (or creating, if necessary) these invalid components. If no invalid component exists, all data items are assumed to be valid.

An invalid component is represented by one of two types of Array:

1. An Array of length equal to the length of the "positions," "connections," "faces," or "polylines" component. This component has the "dep" attribute of "positions," "connections," "faces," or "polylines" (i.e., the elements correspond one-to-one with the elements in the applicable Array). The Array is either TYPE_BYTE or TYPE_UBYTE; its valid elements have a value of DATA_VALID (0), invalid elements a value of DATA_INVALID (1).

2. An Array of length equal to the number of invalid members of the applicable component. This component has the "ref" attribute of "positions," "connections," "faces," or "polylines." The Array is either TYPE_INT or TYPE_UINT, and the indices of the invalid members are listed.

If many elements of the component are invalid, the first type of Array is preferable. If only a few elements are invalid, the second is preferable.

The routines described here simplify the handling of both types of invalid component.

Once positions have been invalidated, their immediate connections, faces, or polylines can also be invalidated by calling DXInvalidateConnections(), which will create an "invalid connections," "invalid faces," or "invalid polylines" component if necessary. (Note that this component cannot be assumed to be up-to-date unless this routine is called.)

Invalid positions, connections, faces, and polylines (and their dependent information) can be removed from the data set by calling DXCull(). This routine:

• Removes all invalidated elements and the corresponding elements of components that are dependent on invalidated elements.
• Renumbers components that reference positions, connections, faces, and polylines (inserting a -1 for indices that refer to removed positions, connections, faces, and polylines).
• Removes invalid positions, invalid connections, invalid faces, and invalid polylines components.

Removal of invalid components may affect system performance significantly if it requires the conversion of regular positions and connections components to irregular form (i.e., by greatly increasing the memory used for these components). For example, DXCreateInvalidComponentHandle() creates a "handle" for a specified invalid component. Other routines set particular elements as valid or invalid or they determine the validity of a given element. The module writer can set up a handle to mark elements as either valid or invalid (e.g., initializing all elements to invalid and validating the appropriate elements or vice versa).

When the time comes to create an invalid-component Array, the information stored in the handle is used to create one of the two kinds of Array just described, depending on the relative number of invalid elements.

Note: Before adding a new invalid component to a Field, it is important to explicitly remove any invalid component having the same name. The reason for this requirement is that the attributes of an existing component will be copied to the new component. Overwriting a "dep" invalid component with a "ref" invalid component will result in a component with both attributes, which is self-contradictory.

#define DATA_VALID   0
#define DATA_INVALID 1

Examples

Invalid-component handles have a variety of uses, as shown in these examples.

• The call to DXCreate... creates an invalid-component handle that stores the validity state of the data associated with the positions. If there is an initial "invalid positions" component, its contents initialize the handle.

  handle = DXCreateInvalidComponentHandle(field, NULL, "positions")
  

• Here the call to DXCreate... creates an invalid-component handle associated with array (in this case a connections component). No initialization takes place; the handle is initialized to "all valid."

     array = (Array)DXGetComponentValue(field, NULL, "connections");
     handle = DXCreateInvalidComponentHandle(array, NULL, NULL);
  

  Note that in this example DXCreate... has no way of determining the component name of array and, when the handle is converted to an Array, cannot attach a "dep" or "ref" attribute. It is therefore the caller's responsibility to attach the appropriate attribute before placing the Array in a Field. You can determine whether a "dep" or "ref" attribute is needed by examining the type of the invalid Array: TYPE_INT or TYPE_UINT implies references. As noted earlier, if this component is added to a Field, any previous component of the same name must be explicitly deleted.

  Since it is easier to create an invalid-component handle from a Field and component name (as in the first example), DXSaveInvalidComponent() can be used to add the modified validity information to the Field.

• Here the call to DXCreate... creates an invalid-component handle associated with the positions component and initializes it with the invalid-positions Array.

     array = (Array)DXGetComponentValue(field, "positions");
     iarray = (Array)DXGetComponentValue(field, "invalid positions");
     handle = DXCreateInvalidComponentHandle(array, iarray, NULL);
  

  This example is similar in concept to the first except that it prevents the user from calling DXSaveInvalidComponent().

• This example performs part of the Include operation: it invalidates all connections that reference an invalid position. Any invalid connections remain.

     inv_pos_h = DXCreateInvalidComponentHandle(field, NULL, "positions");
     inv_con_h = DXCreateInvalidComponentHandle(field, NULL, "connections");
     if (!inv_pos_h || !inv_con_h)
        goto error;
  

     for (i = 0; i < nConnections; i++)
     {
        elt = (int *) DXCalculateArrayEntry(array_handle, i, scratch);
        for (j=0; j < vertsPerElement; j++)
           if (DXIsElementInvalid(inv_pos_h, elt[j]))
           {
               DXSetElementInvalid(inv_con_h, i);
               break;
           }
     }
     if (!DXSaveInvalidComponent(field, inv_con_h))
        goto error:
  

• The following example initially invalidates all connections, and then, for each point, validates the connection that contains it. "IndexOfElementContainingPoint" is a user-supplied routine.

     inv_con_h = DXCreateInvalidComponentHandle(field, NULL, "connections");
     if (!inv_con_h)
        goto error;
     DXSetAllInvalid(inv_con_h);
     for (i=0; i < nPoints; i++)
     {
        j =  IndexOfElementContainingPoint (field, point[i]);
        DXSetElementInvalid(inv_con_h, j);
               break;
     }
     if (!DXSaveInvalidComponent(field, inv_con_h))
        goto error:
  

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]