IBM Visualization Data Explorer Programmer's Reference

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


Chapter 12. Working with Data Model Objects

Partial Table-of-Contents

  • 12.1 Field Class
  • 12.2 Group Class
  • Generic Operations
  • Series Groups
  • MultiGrid Groups
  • Composite Fields
  • Parts
  • 12.3 Array Class
  • Generic Operations
  • Irregular Arrays
  • String List Routines
  • Array Handling
  • Creating Positions and Connections Grids
  • Regular Arrays
  • Path Arrays
  • Product Arrays
  • Mesh Arrays
  • Constant Arrays
  • 12.4 String Class
  • 12.5 Private Class
  • 12.6 Printing Objects
  • 12.7 Field Construction
  • Points and Dependent Data
  • Connections
  • Standard Components
  • 12.8 Extracting Module Parameters
  • 12.9 Creating Simple Data Explorer Objects
  • 12.10 Component Manipulation
  • 12.11 Data Import and Export
  • Data Explorer Format Files
  • netCDF Data

  • This chapter describes the programming interface for creating and manipulating the basic Objects of the Data Explorer data model (some Objects are discussed in later chapters). For a brief summary of the data model, see Chapter 1. "Overview". For a detailed description, see Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.

    Data Explorer is an object-oriented graphical application. Its objects are data structures in global memory, they are passed by reference, and their contents are private to the implementation. See Table 1.

    Table 1. Data Explorer Objects
    The first column shows the hierarchical relationship of the Objects to one another. For subclasses  Field  through  Private , see 12.1 , "Field Class" through 12.5 , "Private Class" in this chapter; for  Interpolator , see Chapter 14. "Data Processing"; and for the remainder, see Chapter 16. "Rendering".
    Type Description Class
    Object Object Class CLASS_OBJECT
      Field Data sampled on a regular or irregular grid CLASS_FIELD
      Group Collections of Objects CLASS_GROUP
        Series Time (or other) series CLASS_SERIES
        Multigrid Group of Fields to be treated as one Field CLASS_MULTIGRID
        Composite Field Group of Fields to be treated as one Field CLASS_COMPOSITEFIELD
      Array Dynamic Arrays of data such as points CLASS_ARRAY
        Regular Array One-dimensional series of evenly spaced points CLASS_REGULARARRAY
        Path Array One-dimensional series of connected line segments CLASS_PATHARRAY
        Product Array Regular or semi-regular grid positions CLASS_PRODUCTARRAY
        Mesh Array Regular or semi-regular grid connections CLASS_MESHARRAY
        Constant Array Array with a constant value CLASS_CONSTANTARRAY
      String Object containing a string CLASS_STRING
      Private Object pointing to private user data CLASS_PRIVATE
      Interpolator Used to query Fields for data values CLASS_INTERPOLATOR
      Xform Transformation matrix applied to an Object CLASS_FORM
      Screen Object aligned to the screen CLASS_SCREEN
      Clipped One Object clipped by another CLASS_CLIPPED
      Camera Viewpoint, viewport, resolution CLASS_CAMERA
      Light Lights CLASS_LIGHT
    Note: Any Group other than the three types listed here is a generic Group.
    Any Array other than the five types listed here is an irregular Array.


    12.1 Field Class

    Each Field has some number of named components. Each component has a value (usually an Array) and some number of attributes, whose values are often strings or numbers. However, in the data model both components and attributes can be any Object. The defined components and attributes are listed in Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.

    Field DXNewField()

    Creates a new Field Object. See Note on Use, and DXNewField.

    Field DXSetComponentValue()

    Adds a component to a Field. See Note on Use, and DXSetComponentValue.

    Field DXSetComponentAttribute()

    Adds or removes a named attribute from a component of a Field. See DXSetComponentAttribute.

    Object DXGetComponentValue()

    Returns a specified component of a Field. See Note on Use See DXGetComponentValue.

    Note on Use

    The following code segment illustrates how to make a component of one Field also a component of another Field:

        f = DXNewField();
        if (!f)
           return ERROR;
        c = DXGetComponentValue(oldfield, "positions");
        if (!DXSetComponentValue(f, "positions", c))
           return ERROR;
    

    Object DXGetComponentAttribute()

    Returns a named attribute of a specified component of a Field. See DXGetComponentAttribute.

    Object DXGetEnumeratedComponentValue()
    Object DXGetEnumeratedComponentAttribute()

    Return a component or component attribute by index. These routines can be used to retrieve the components or component attributes when their names are not known. See DXGetEnumeratedComponentValue and DXGetEnumeratedComponentAttribute.

    Field DXDeleteComponent()

    Deletes a named component from a Field. See DXDeleteComponent.

    Less Commonly Used Routines

    Error DXComponentReq()
    Error DXComponentOpt();
    Error DXComponentReqLoc();
    Error DXComponentOptLoc();

    Access or type-check a component in a Field. See Note on Use. See also DXComponentReq, DXComponentOpt, DXComponentReqLoc, DXComponentOptLoc.

    Note on Use

    An example of the expected use of DXComponentReq() follows:

        a = DXGetComponentValue(f, "positions");
        if (!DXComponentReq(a, &points, &npoints, 0, TYPE_FLOAT, 3))
            return NULL;
        a = DXGetComponentValue(f, "colors");
        if (!DXComponentOpt(a, &colors, NULL, npoints, TYPE_FLOAT, 3))
            return NULL;
        if (colors) ...
    

    The first two statements check and retrieve a required "positions" component, while the next two check and retrieve an optional "colors" component that must have the same number of elements. Since the second call uses DXComponentOpt(), the program must check colors for NULL to determine whether the colors were present.


    [ 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 ]