A datamap converts scalar node data or cell data values to RGB colors.
There are several low-level objects that you use to construct a Datamap. These objects are described in the sections below.
define the root object of the Datamap
DatamapTempl
group+Port DatamapTempl {
float+Port2+read dataMin;
float+Port2+read dataMax
int+opt numRanges;
DataRangeTempl+IPort2+read &ranges[];
ColorModel+IPort2 &colorModel;
func+nosave getColors;
func+nosave getARGBs;
func+nosave getMinMax;
ptr+nosave+nonotify+write localPtr;
method+notify_inst init = "DmapInstance";
method+notify_val update = "DmapUpdate";
method+notify_deinst delete = "DmapDelete"
};
ColorModels
group ColorModels {
int numColorModels => array_size(models);
ColorModel+Port2 &models[];
};
Datamap
DatamapTempl Datamap {
numRanges => array_size(ranges);
/* Control the color model from the user interface */
HSVcolorModel HSVcolorModel;
RGBcolorModel RGBcolorModel;
int currentColorModel;
ColorModels ColorModels {
models => { HSVcolorModel, RGBcolorModel };
};
};
Description
Datamap is the root object of a datamap. Datamap consists of one or more data ranges and a color model.
Each data range specifies the minimum and maximum values for the range, a size, and an array of control point values. The color model specifies if the control points in the data range are to be treated as RGB or HSV.
Input Ports
dataMin
dataMax
The minimum and maximum values of the scalar input data, typically obtained through connections to the object GDminmax. These values are read only and exist so dependencies among the GDminmax module, the datamap, and the Graphics Display Kit object that the datamap is attached to are established properly. This causes the modules to execute in the correct order when a change in the data occurs.
ranges
An array of data ranges.
colorModel
A color model for the datamap. The color model specifies how the values in the data range's control points are to be interpreted. Supported color models are RGB or HSV.
Parameters
numRanges
The size of the ranges array. This is automatically incremented or decremented as ranges are added or removed from the datamap.
getColors
A virtual function that gets an array of RGB float color values given an array of scalar data values.
getARGBs
A virtual function that gets an array of packed ARGB values given an array of scalar data values.
getMinMax
A virtual function that returns the minimum and maximum values of the datamap by looking at all the ranges in the datamap.
User Interface Controls
The following set of subobjects are used to control a portion of the user interface for the datamap. They provide the ability to select the color model for the datamap.
HSVcolorModel
RGBcolorModel
An HSV and RGB color model.
currentColorModel
This parameter selects the color model for the datamap.
ColorModels
An array of color models that contains references to HSVcolorModel and RGB colorModel. The currentColorModel parameter indexes this array.
editable
This parameter controls if the datamap can be edited by the DatamapEditor. A value of 0 means the datamap is not editable. A value of 1 means the datamap is editable.
Output Ports
dataMin
dataMax
The minimum and maximum values of the scalar input data, typically obtained through connections to the object GDminmax. These values are normally connected to the minimum and maximum values in one of the data ranges. This allows the datamap to be scaled to the values of the node data or cell data.
Example
Libraries.Templates.DATAMAPS.DefaultLinear
Libraries.Templates.DATAMAPS.HotMetal
File
v/dmap.v
define a single range of a datamap
DataRangeTempl
group+OPort DataRangeTempl {
double+IPort2+req minimum;
double+IPort2+req maximum;
int+IPort2 size;
DataRangeModel+IPort2 &v1Model;
DataRangeModel+IPort2 &v2Model;
DataRangeModel+IPort2 &v3Model;
DataRangeModel+IPort2 &v4Model;
int numControlPoints;
DatamapValue+IPort2 &controlPoints[];
};
DataValues
group DataValues {
int numValues => array_size(dataVals);
float+Port2 &dataVals[];
};
RangeValues
group RangeModels {
int numRangeModels => array_size(models);
DataRangeModel+Port2 &models[];
};
DataRange
DataRangeTempl DataRange {
numControlPoints => array_size(controlPoints);
/* Control the min and max of the range from the user interface */
float DataMinValue;
float UIMinValue;
float DataMaxValue;
float UIMaxValue;
int selectValues;
DataValues MinValues {
dataVals => { DataMinValue, UIMinValue };
};
DataValues MaxValues {
dataVals => { DataMaxValue, UIMaxValue };
};
/* Control if various UI widgets are active for editing */
int minActive;
int maxActive;
int sizeActive;
/* Control the type of range of each component from the user interface. */
LinearRange LinearRange;
StepRange StepRange;
int selectAlphaRange;
int selectColorRange;
RangeModels RangeModels {
models => { LinearRange, StepRange};
};
};
Description
DataRange defines a single data range in a datamap. A data range is defined by the minimum and maximum values for the range, a size, and an array of control point values.
Input Ports
minimum
maximum
The minimum and maximum data values of the data range. When the datamap has only one range, the range's minimum and maximum normally are the same as the minimum and maximum found in the data.
size
The number of discrete color steps from the specified minimum to maximum data values.
v1Model
v2Model
v3Model
v4Model
The data range model for each of the four components in the control points. Each of a color's four components (alpha and HSV or RGB) can have its own data range model. Linear and step models are supported.
controlPoints
The control points for the data range. Control points consist of an alpha component and either RGB or HSV color components as defined by the color model of the datamap.
Parameters
numControlPoints
The number of control points.
User Interface Controls
The following set of subobjects are used to control a portion of the user interface for the datamap. They provide the ability to constrain the range to values either derived from the data or from user interface widgets, enable or disable some of the user interface widgets, and select the data range model for the color and alpha components of the controls points associated with the data range.
DataMinValue
DataMaxValue
Potential minimum and maximum values of the data range. These are normally derived from the actual minimum and maximum values in the data.
UIMinValue
UIMaxValue
Potential minimum and maximum values of the data range. These are normally connected to user interface widgets in the DatamapEditor.
selectValues
Selects if either the derived data or UI values are used as the minimum and maximum of the data range.
MinValues
MaxValues
Two arrays that contain references to the derived data and UI minimum and maximum values. The selectValues parameter is used to index the array and choose a value.
minActive
maxActive
These parameters control if the minimum and maximum data values are editable from the DatamapEditor's user interface.
sizeActive
This parameter controls if the size value is editable in the DatamapEditor's user interface.
LinearRange
StepRange
A linear range and a step range model. These are used to control the type of range of each control point component.
selectAlphaRange
Selects the range model type for the alpha component.
selectColorRange
Selects the range model type for the HSV or RGB control point components.
RangeModels
An array of data range models containing references to LinearRange and StepRange. The selectAlphaRange and selectColorRange parameters are used to index this array.
Example
Libraries.Templates.DMAP.DefaultDatamap
File
v/dmap.v
Synopsis
define the DataRange model that determines interpolation between control points
group+OPort DataRangeModel {
string model;
func interpolate;
};
DataRangeModel LinearRange {
model = "LinearRange";
func interpolate = "interpolateLinear";
};
DataRangeModel StepRange {
model = "StepRange";
func interpolate = "interpolateStep";
};
Description
DataRangeModel specifies the type of interpolation to perform for data values that fall between a data range's minimum and maximum. Supported types of data range models are linear and step.
Parameters
model
The name of the data range model, either "LinearRange" or "StepRange".
interpolate
A virtual function that performs the interpolation between the control points in the data range.
Example
Libraries.Templates.DMAP.DataRange
File
v/dmap.v
Synopsis
define the value for a DataRange control point in the Datamap
double v1; /* Alpha component of Color */
double v2; /* 1st component of Color */
double v3; /* 2nd component of Color */
double v4; /* 3rd component of Color */
};
DmapColor DatamapValue {
double value;
};
Description
DatamapValue specifies a control point color. A data range whose model is linear often has two control points, and thus two control-point colors.
Parameters
v1
The alpha component.
v2
The Hue component if the color model is HSV. The Red component if the color model is RGB.
v3
The Saturation component if the color model is HSV. The Green component if the color model is RGB.
v4
The Value component if the color model is HSV. The Green component if the color model is RGB.
Example
Libraries.Templates.DMAP.DefaultLinearRange
Libraries.Templates.DMAP.DefaultStepRange
File
v/dmap.v
Synopsis
define the color model of the Datamap
group+OPort ColorModel {
string model; /* RGB, HSV */
string v1Label;
string v2Label;
string v3Label;
string v4Label;
func convertToRGB;
func convertFromRGB;
};
ColorModel RGBcolorModel {
model = "RGB";
v1Label = "Alpha";
v2Label = "Red";
v3Label = "Green";
v4Label = "Blue";
func convertToRGB = "convertRGBtoRGB";
func convertfromRGB = "convertRGBtoRGB";
};
ColorModel HSVcolorModel {
model = "HSV";
v1Label = "Alpha";
v2Label = "Hue";
v3Label = "Saturation";
v4Label = "Value";
func convertToRGB = "convertHSVtoRGB";
func convertfromRGB = "convertRGBtoHSV";
};
Description
ColorModel specifies the datamap's color model. Supported color models are HSV and RGB.
Parameters
model
The name of the color model, either "HSV" or "RGB".
v1Label
The label for the first component, "Alpha".
v2Label
The label for the second component, either "Hue" or "Red".
v3Label
The label for the third componenet, either "Saturation" or "Green".
v4Label
The label for the fourth component, either "Value" or "Blue".
Example
Libraries.Template.DMAP.Datamap
File
v/dmap.v