PlotIntensity

int PlotIntensity (int panelHandle, int controlID, void *zArray, int numberOfXPoints, int numberOfYPoints, int zDataType, ColorMapEntry colorMapArray[], int hiColor, int numberOfColors, int interpColors, int interpPixels);

Purpose

Draws a solid rectangular plot in a graph control. If you want to apply scaling factors and offsets to the data values, refer to PlotScaledIntensity.

The plot consists of pixels whose colors correspond to the magnitude of data values in a two-dimensional array and whose coordinates correspond to the locations of the same data values in the array. For instance, the pixel associated with zArray[2][3] is located at {x=3, y=2}.

The lower left corner of the plot area is at {0,0}.

The upper right corner of the plot area is at {numXpts—1, numYpts—1}, where,

numXpts = Number of x Points

numYpts = Number of y Points

Parameters

Input
Name Type Description
panelHandle integer Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID integer The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by NewCtrl or DuplicateCtrl.
zArray numeric array Array that contains the data values to convert to colors.

zArray must be one of the following data types, which you specify in zDataType:

VAL_DOUBLE
VAL_FLOAT
VAL_INTEGER
VAL_SHORT_INTEGER
VAL_CHAR
VAL_UNSIGNED_INTEGER
VAL_UNSIGNED_SHORT_INTEGER
VAL_UNSIGNED_CHAR


The locations at which the colors appear on the graph depend on the location of the data values in zArray. zArray must be a two-dimensional array of the following form:

Array[numberOfYPoints][numberOfXPoints]

Each element of the array is associated with a pixel on the graph. The pixel associated with element zArray[y][x] is located at {x, y} on the graph.
numberOfXPoints integer Number of points to display along the x-axis in each row.
numberOfYPoints integer Number of points to display along the y-axis in each column.
zDataType integer The data type of the elements in zArray, as well as the data type of the color map values.

The following table lists the valid data types.

double-precision VAL_DOUBLE
float VAL_FLOAT
integer VAL_INTEGER
short integer VAL_SHORT_INTEGER
character VAL_CHAR
unsigned integer VAL_UNSIGNED_INTEGER
unsigned short integer VAL_UNSIGNED_SHORT_INTEGER
unsigned character VAL_UNSIGNED_CHAR
colorMapArray ColorMapEntry Array of ColorMapEntry structures.

colorMapArray contains up to 255 ColorMapEntry structures that are defined as follows:

typedef struct
{

union
{

char valChar;
int valInt;
short valShort;
float valFloat;
double valDouble;
unsigned char valUChar;
unsigned long valULong;
unsigned short valUShort;

} dataValue;
int color;

} ColorMapEntry;



colorMapArray defines how to translate data values in zArray into color values. If a data value matches exactly to a data value in one of the ColorMapEntry structures, the function converts it to the corresponding color. Otherwise, the following rules apply:

  • If interpColors is zero, the color associated with the next higher data value is used.
  • If interpColors is nonzero, the color is calculated using a weighted mean of the colors associated with the color map data values immediately above and below the zArray value.

If there is no higher value, the function uses the color specified in hiColor.

The colorMapArray entries do not need to be in sorted order.
hiColor integer RGB value to which to translate zArray values that are higher than the highest data value in colorMapArray.
numberOfColors integer Number of entries in colorMapArray. numberOfColors must be less than or equal to 255.

If interpColors is nonzero, numberOfColors must be greater than or equal to two.
interpColors integer Indicates how to assign colors to zArray data values that do not exactly match the data values in the colorMapArray.

If interpColors is zero, the data value is assigned the color associated with the next higher color map data value.

If interpColors is nonzero, the color is calculated using a weighted mean of the colors associated with the color map data values immediately above and below the zArray value.

Regardless of the value of interpColors, the following rules apply:

  • Data values below the lowest color map data value are assigned the color of the lowest color map data value.
  • Data values above the highest color map data value are assigned the value of the hiColor parameter.
interpPixels integer Indicates how to color pixels between the pixels assigned to the zArray values.

If interpPixels is zero, an unassigned pixel is given the same color as the closest assigned pixel.

If interpPixels is nonzero, an unassigned pixel is first given a data value using a weighted mean of the data values associated with the four closest assigned pixels. Then the color is calculated using the colorMapArray.

Performance Considerations

If interpPixels is zero, the performance degrades as the number of data points in zArray increases.

If interpPixels is nonzero, the performance degrades as total number of pixels in the plot area increases.

Return Value

Name Type Description
plotHandle integer The handle of the new plot that you can use in subsequent function calls to reference the plot.

If the handle is positive, the new plot was successfully added to the graph. Negative values indicate that an error occurred.

Note  If ATTR_DATA_MODE is set to VAL_DISCARD, the function returns 0.
Code Error Message String
xx Plot handle (success)