SFA Project On-line Documentation: MappingNode

The MappingNode class encapsulates the the raw data translation functionality in a C++ class library called MappingNode. Below is the current contents of MappingNode.H. The rcsid variable indicates the revision of this file.

The originally intended use of mapping nodes was to allow a layer of abstraction in the process of applying a transformation (or transfer function) to a vector of data. Thus the programmer creates a mapping node and gives it a logical name (e.g. "8-bit Quantized Temperature" if what it's doing is quantizing temperature to 8 bits.). Following this (or upon construction), s/he may assign a vector of data, and or a mapping function. Then comes time to actually do work with the mapping node.

There are three methods that actually perform work with the mapping node, only two of which have currently been implemented. The first is mapValue() which takes a double and converts it to an int by way of the assigned mapping transform. If no transformation has been assigned, the program exits with error 1 after printing a message that tells you that no mapping function has been assigned. The second is mapAllData() which takes a PackedGlyph array, the length of that array, and an integer indicating which "field" of the PackedGlyph this transforms into. This method iterates through the data vector pointed to by the mapping node and for each value, applies the mapping transform and places the value in the appropriate slot in the PackedGlyph.  

//
//  MappingNode.H  -  The Mapping Node Class
//
//  James M. Kukla, UMBC CSEE
//
//  $Id: MappingNode.H,v 1.2 1998/02/26 18:42:15 panda Exp $

#ifndef SFA_MAPPING_NODE_H
#define SFA_MAPPING_NODE_H 1

static char rcsid[] = "$Id: MappingNode.H,v 1.2 1998/02/26 18:42:15 panda Exp $";

#include 
#include 
#include "Defines.H"
#include "String.H"
#include "PackedGlyph.H"




//  Define a function type for a generic Mapping Operation
typedef int (* MappingFunction)(double);

//  Note:  The MappingNode's pointers point to data of which it is the SECONDARY owner.  
//  By this I mean that we're a reference to someone else's data and we DO NOT UNDER ANY
//  CIRCUMSTANCES DELETE THEM!

class MappingNode {
public:
  MappingNode(String l, double *da=NULL, MappingFunction op=NULL) 
    : label(l), 
    data_array(da),
    mapping_function(op), 
    data_location_index(-1) {};
  
  //  Mutators
  void setDataArray(double *d) ;
  void setDataArrayIndex(int i) { data_location_index = i; }
  void setMappingFunction(MappingFunction op) ;
  void setLabel(String s) ;

  //  Accessors
  double *         getDataArray(void) ;
  MappingFunction  getMappingFunction(void) ;
  String           getLabel(void) ;
  int              getDataArrayIndex(void) { return data_location_index; }

  //  Other operations
  int    mapValue(double d);
  int    mapAllData(PackedGlyph *pg, int num_glyphs, int byte_offset, int pack_size);
  int    mapAllData(PackedGlyph *pg, int num_glyphs, int field);

private:
  double *data_array;
  MappingFunction mapping_function;
  String  label;
  int  data_location_index;
  
};



#endif
 

Mutators

void setDataArray(double *d)

This method takes the array d and sets the internal data_array pointer to the same value. (i.e. they "are" the same array)

Note that because this is sharing this data array it should NOT be free()-ed after passing it to this function and should never be free()-ed in the MappingNode destructor.

There are no error conditions for this method.

void setDataArrayIndex(int i)

Stores/sets the index in the DataSet that this MappingNode uses.

Correctness here is up to the user: there is no guarantee from the software's point of view that the index and the array will actually correspond.

Note that this is not needed except for time sequence data sets. The purpose of this method is automate the process of jumping from time step to time step among "parallel" arrays of data.

There are no error conditions for this method.

void setMappingFunction(MappingFunction op)

Sets the mapping operation used by the node. The MappingFunction is any routine that takes a double and returns an int.

There are no error conditions for this method.

void setLabel(String s)

Sets the label of this node. This is useful in identifying which dimension a particular node corresponds to.

Correctness is the burder of the user: There is no guarantee that the name give to the node is meaningful, useful, or corresponds in any way to the actual purpose of the node instance. 

Accessors

The accessor functions rely on specific initial values (set in the constructor) to handle error conditions. No error codes are ever set or returned.

double * getDataArray(void)

This function retuns the value of data_array. Note that data_array is NULL until it is initially set and must be explicitly set back to NULL if an "unset" is desired.

MappingFunction getMappingFunction(void)

Returns the value of mapping_function.

String getLabel(void)

Returns the MappingNode label.

int getDataArrayIndex(void)

Returns the value of data_array_index. 

Methods that Manage Mapping

int mapValue(double d)

This method takes d and returns the value returned by the mapping_function contained within this instance of the node.

If no mapping_function is defined, a fatal error is given and the program exits printing an error message.

int mapAllData(PackedGlyph *pg, int num_glyphs, int field)

This method takes an array of num_glyphs PackedGlyph structures and performs the mapping for the specified field. Valid field values are given in defines.h.

If successful, this function returns SFA_OK.

If there are no data assigned to this MappingNode (data_array == NULL) or if there is no mapping function (mapping_function == NULL) an error is printed. Since this is a non-fatal error, SFA_OK is returned.

NOTE: Currently this method`s body is commented out, thus this method does nothing. Please consult the latest version of the file MappingNode.H to see if this is still the case and update the documentation once this function is operational. 


back to main page