IntensityGridSeries (heatmap)

IntensityGridSeries allows visualizing M x N array of nodes, colored by assigned value-range palette. The colors between nodes are interpolated. IntensityGridSeries is an evenly spaced, rectangular series in X and Y dimension. This series allows rendering contour lines, contour line labels, and wireframe as well.

info

To see feature demonstration as example, check Heat map, Spectrogram, Intensity grid mouse control from our Demo.

IntensityGridSeries properties.

The data is stored in Data property as two-dimensional array. Each array item is of type IntensityPoint. Store the data value of each node in Value field of IntensityPoint structure, which tells what color should be used from the ValueRangePalette.

IntensityGrid series showing a heat map presentation. Legend box shows the value-range color palette.

Setting intensity grid data

IntensityGridSeries nodes. SizeX = 5, SizeY = 7.

Node distances are automatically calculated as

• Set X range by using RangeMinX and RangeMaxX properties, to order the minimum and maximum value of assigned X axis.
• Set Y range by using RangeMinY and RangeMaxY properties, to order the minimum and maximum value of assigned Y axis.
• Set SizeX and SizeY properties to give the grid a size as columns and rows.
• Set Value for each node:

// Method, with Data array index
for (int nodeIndexX = 0; nodeIndexX < columnCount; nodeIndexX ++)
{
	for (int nodeIndexY = 0; nodeIndexY < rowCount; nodeIndexY ++)
     	{
		  intensityValue =//some height value. 
	  gridSeries.Data[iNodeX, iNodeY].Value = intensityValue;
     	}
}
gridSeries.InvalidateData(); //Notify new values are ready and to refresh

// Alternative method, usage of SetDataValue
for (int nodeIndexX = 0; nodeIndexX < columnCount; nodeIndexX ++)
{
	for (int nodeIndexY = 0; nodeIndexY < rowCount; nodeIndexY ++)
     	{
		  intensityValue =//some height value
		  gridSeries.SetDataValue(nodeIndexX, nodeIndexY,
		      	0, //X value ís irrelevant in grid
0, //Y value is irrelevant in grid
intensityValue,	                               
Color.Green); //Source point colors are not used in this example, so use any color here 
     	}
}
gridSeries.InvalidateData(); //Notify new values are ready and to refresh

Setting Values only to existing grid

When the geometry of IntensityMesh, or SizeX or SizeY for IntensityGrid series doesn’t change while data is changing rapidly, it is most advantageous to use SetValuesData method. Since it accepts Double[][] format data array, scrolling or re-ordering rows or columns is quick. Especially when combined with PixelRendering property (see here), it is a very effective approach for high-resolution scrolling spectrogram visualization. Note that when PixelRendering is disabled with external data array set by SetValuesData, Data property can’t be null.

Setting Colors only to existing grid

When the geometry of IntensityMesh, or SizeX or SizeY for IntensityGrid series doesn’t change while data is changing rapidly, it is most advantageous to use SetColorsData method. It accepts int[][] format values, i.e. ARGB values that GPU accepts directly. With this kind of data array, scrolling or re-ordering rows or columns is quick. Especially when combined with PixelRendering property (see here), it is a very effective approach for high-resolution scrolling spectrogram visualization. Note that when PixelRendering is disabled with external data array set by SetColorsData, Data property can’t be null.

Creating intensity grid data from bitmap file

Create a surface from a bitmap image. Use SetHeightDataFromBitmap method to achieve this. The series Data array property gets the size of the bitmap size (if no anti-aliasing or resampling is used). For each bitmap image pixel, Red, Green and Blue values are summed. The greater the sum, the greater will be the data value for that node. Black and dark colors get lower values and bright and white colors get higher values.

Source bitmap and calculated intensity values data. Dark values stay low and bright values get higher values.

info

To see feature demonstration as example, check Heat map, Spectrogram, Intensity grid mouse control from our Demo.

Fill styles

Use Fill property to select the filling style. The following options are available:

None

By using this, no filling is applied. This is the selection to use with wireframe mesh or plain contour lines.

FromSurfacePoints

The colors (Color field) of the Data property nodes are used.

Toned

ToneColor property is applied

Paletted

See ValueRangePalette.

Enable FullInterpolation property to use enhanced interpolation method in the fill. Note that it will cause more CPU and GPU usage. By using full interpolation, the fill quality is better, but can be seen only when the data array size is quite small.

Rendering as pixel map

By enabling PixelRendering property, the nodes are rendered as pixels, or rectangles. This is a very high-performance rendering style e.g. for real-time high-resolution thermal imaging applications. Note that when this rendering mode is selected, many other options are disabled, such as contour lines, wireframe and interpolation. If logarithmic axes are used, the logarithmic transformation is only applied to corners of the series, the pixels in the bitmap remain evenly spaced and no logarithmic transformation is applied to them.

PixelRendering = true.

tip

PixelRendering relies on DirectX texture. In DirextX11 maximum size of X or Y is 16384. In DirectX 9 dimensions is twice smaller. If grid is bigger than DirectX texture, then user needs splitting into smaller grids instead (each occupying particular xy-range). However, it maybe just easier to go for ImageLayer approach.

ValueRangePalette

With ValueRangePalette property, define color steps for value coloring. ValueRangePalette can be used for:

• Fill (see Fill styles)
• Wireframe (see Wireframe)
• Contour lines (see Contour lines)

tip

Define several steps for contour palette. Each step has a height value and the corresponding color. From v12.1.1 user can have hundreds of steps in palette without performance penalty. However, note that to create smooth palette (color-bar) user don't need to use hundreds of steps. Instead, user can use PaletteType.Gradient with only few colors, which will do color interpolation in between (see image on the left).

On the left, IntensityGridSeries Fill is set to Paletted and Palette Type is set to Gradient. On the right, Palette Type is set to Uniform.

The palette is defined with MinValue, Type and Steps properties. For Type, there are two choices: Uniform and Gradient. The contour palettes (check the legend boxes) of the previous figures show:

• MinValue: -50
• Type: Uniform
• Steps:
  • Steps[0]: MaxValue: -10, Color: Blue
  • Steps[1]: MaxValue: 10, Color: Teal
  • Steps[2]: MaxValue: 25, Color: Green
  • Steps[3]: MaxValue: 35, Color: Yellow
  • Steps[4]: MaxValue: 60, Color: Red
  • Steps[5]: MaxValue: 100, Color: White

MinValue

MinValue is always lowest palette value. If any of Step MaxValue is below it, step will be skipped. The values below the first step value (i.e. towards MinValue) are colored with the first step’s color. While ColorBar always includes min-value, the label for it can be disabled with ValueRangePalette. ShowMinValueLegendLabel property.

Customization of labels for PaletteStep

On default, MaxValue of each step is converted to string according to format set by intensitySeries. LegendBoxValuesFormat property (default "0.0"). Labels are shown in LegendBox, if there is enough space to show them without overlap (overwise some labels are skipped).

However, it is possible to replace / customize the palette-step label completely. To do that user needs to subscribe to palette. FormatStepValueText event. In the event handler user just replaces step's value with any string. For example,

    palette.FormatStepValueText += Palette_FormatStepValueText;


private string Palette_FormatStepValueText(object sender, double step)
{
    if (step >= 100.0)
    {
        return "\u221E";        // 'INFINITY'
    }
    else
    {
        return string.Format("t={0:0.00}", step);
    }
}

ValueRangePalette is customized with FormatStepValueText event handler.

In version 12.4, a new property is added for PaletteStep. CustomLegendLabelText defines Custom Label-text for palette step label. If it is not Null (default), then it will be used next to LegendBox color-bar (instead of Step.MaxValue). If user don't want to show particular value, then empty-string can be used for CustomLegendLabelText or ShowLegendLabel property can be disabled. For example,

    // create Custom Labeltext for palette step labels
    PaletteStepList steps = _intensityGrid.ValueRangePalette.Steps;
    for (int i=0; i < steps.Count; i++)
    {
        steps[i].CustomLegendLabelText = "Custom " + i.ToString();
    }

ValueRangePalette is customized with CustomLegendLabelText property.

Modifying distance between palette labels

In version 12.4, a new property is added for ValueRangePalette, LabelShowModeInLegend.

LabelShowModeInLegend controls how labels are spaced next to the color-bar in the LegendBox (as well as extend of step's color). There are 3 options:

• ValueDepended, previously (and the current default behavior) palette-step labels were positioned in a linear manner (based on value's relative distance between palette's maximum and minimum).
• ValueDependedLogarithmical, allows to position labels on logarithmic scale (for example, labels for palette steps 1, 10 and 100 will be equidistantly positioned).
• EquidistantAllocation, which draws palette-steps' labels at equal distance from each other regardless of actual value.

From left to right ValueRangePalette. LabelShowModeInLegend options: ValueDepended, ValueDependedLogarithmical and EquidistantAllocation.

Note

palette. MinValue will also be used as label in LegendBox, if palette. ShowMinValueLegendLabel property is enabled.

ValueRangePalette is used by ViewXY 'intensity' series, by View3D 'surface' series and by ViewPolar 'heatmap'.

Wireframe

Use WireframeType to select the wireframe style. The options are:

None

no wireframe

Wireframe

a solid color wireframe. Use WireframeLineStyle.Color to set the color

WireframePaletted

the wireframe coloring follows ValueRangePalette (see ValueRangePalette)

WireframeSourcePointColored

the wireframe coloring follows the color of grid nodes (Color field)

Dots

solid color dots are drawn in the grid node positions

DotsPaletted

dots are drawn in the grid node positions and colored by ValueRangePalette

DotsSourcePointColored

dots are drawn in the grid node positions, coloring follows the color of grid nodes (Color field)

The wireframe line style (color, width, pattern) can be edited by using WireframeLineStyle.

tip

Note! Palette colored wireframe lines and dots are available only when WireframeLineStyle.Width = 1 and WireframeLineStyle.Pattern = Solid.

Contour lines

info

To see feature demonstration as example, check Heatmap color spread, Contours with labels from our Demo.

Contour lines can be used with fill and wireframe properties. By setting ContourLineType property, contour lines can be drawn with different styles:

None

no contour lines are shown

FastColorZones

The lines are drawn as thin zones on palette step end. Allows very powerful rendering, which suits very well for continuously updated or animated surface. Steep value changes are shown as thin line, while gently sloping height differences are shown with thick zone. Each line uses the same color defined with ContourLineStyle.Color property. The zone width can be set by FastContourZoneRange property. The value is in Y axis range.

FastPalettedZones

Like FastColorZones, but line coloring follows ValueRangePalette options (see ValueRangePalette).

ColorLine

Like FastColorZones, but the contour lines are actual lines. Rendering takes longer and is not recommended for continuously updated or animated surface. The line width can be adjusted with ContourLineStyle.Width property.

PalettedLine

Like ColorLine, but line coloring follows ValueRangePalette options.

On the top-left, ContourLineType = FastColorZones. On the top-right, ContourLineType = FastPalettedZones. On the bottom -left, ContourLineType = ColorLine. On the bottom-right, ContourLineType = PalettedLine.

Contour line labels

When contour lines are visible, numeric values can be shown within the line paths (ContourLineLabels properties).

Use LabelsNumberFormat for custom string formatting, for example setting the number of decimals.

The properties of ContourLineLabels and the result.

StencilAreas

StencilArea feature allows masking in or out areas of drawn data. StencilArea can be applied by creating a new StencilArea object, then defining its size as PointDouble2D -array via AddPolygon() and finally adding them to the series that should be masked.
There are two types of StencilAreas:

• AdditiveAreas creates a positive stencil mask - only data inside the area is drawn, while the outside is clipped.
• SubtractiveAreas creates a negative stencil mask - data inside the area is clipped, while the outside is drawn.

An IntensityGrid without any stencils on the top. On the bottom, the same grid with an AdditiveArea.

ClipAreas

Series support ClipAreas.

DataCursor

Series can be tracked with DataCursor.

LimitYToStackSegment

Series support LimitYToStackSegment.