Heatmap Chart (Heatmap)

This chapter explains the rules for Heatmaps in EasyChart: how coordinates/cells are mapped, how SeriesData fields are interpreted, and how the value-to-color range is calculated. It also notes that Heatmap is a Pro feature.

1. Use cases

• 2D matrix visualization (rows/columns)
• Density/intensity visualization

2. Important note (Pro feature)

• The renderer for SerieType.Heatmap is registered by EasyChartProBootstrap.
• If EasyChartPro is not installed/enabled, this serie may be treated as a “dynamic renderer” and attempted to be created, but it usually won’t render.

3. Minimum viable setup (checklist)

1. ChartProfile.coordinateSystem = Cartesian2D
2. Axes (Axis Settings)
   • Most common: X=Category (columns), Y=Category (rows)
   • X/Y can also use Value axes (see section 7)
3. Series
   • Add 1 Serie
   • Serie.type = Heatmap
   • Serie.seriesData has at least 1 point

4. Inspector fields

• Series
  • series[i].type = Heatmap
  • series[i].settings: actual type is HeatmapSettings
    • renderMode: Grid / Gradient / Contour
    • cellGapPx
    • xSplitCount / ySplitCount (used when X/Y are Value axes)
    • autoRange / minValue / maxValue
    • lowColor / midColor / highColor
    • clamp
    • influenceMode: None / Bleed / Smooth
    • sub settings: bleed / smooth / gradient / contour

5. SeriesData field interpretation (runtime behavior)

Each Heatmap data point corresponds to one “cell/pixel area”. Runtime uses:

• X coordinate (column): SeriesData.x
• Y coordinate (row): SeriesData.y
• Intensity: SeriesData.value
• Color override: if SeriesData.useColor = true, runtime uses SeriesData.color directly and skips interpolation from low/mid/high.

Note: Heatmap x/y do not accept string categories. With Category axes, you still use indices.

6. Standard template: 2D Category (X/Y) + value intensity (most common)

6.1 X axis (Category: columns)

• AxisType = Category
• labels = ["Col0","Col1",...]

6.2 Y axis (Category: rows)

• AxisType = Category
• labels = ["Row0","Row1",...]

6.3 Data pattern

• x = column index (runtime applies RoundToInt)
• y = row index (runtime applies RoundToInt)
• value = intensity

6.4 Important detail: cell count vs labelPlacement for Category axes

Runtime uses the axis labelPlacement to decide whether to split into labels.Count cells or labels.Count-1 cells:

• CategoryLabelPlacement.CellCenter

  • X cell count = labels.Count
  • Y cell count = labels.Count

• Others (non CellCenter)

  • X cell count = max(1, labels.Count - 1)
  • Y cell count = max(1, labels.Count - 1)

This directly affects the valid range of indices you should write into x/y.

7. Heatmap with Value axes (X/Y are numeric axes)

When X or Y uses AxisType.Value:

• Cell count no longer comes from labels. It comes from:

  • X: HeatmapSettings.xSplitCount
  • Y: HeatmapSettings.ySplitCount

• SeriesData.x/y are normalized using _xMin/_xMax and _yMin/_yMax, then mapped into cell indices.

This is suitable for intensity/density distribution over a continuous value range.

8. Common pitfalls and troubleshooting

• All cells look the same / low contrast

  • Check whether HeatmapSettings.autoRange is enabled
  • Or manually set minValue/maxValue
  • Also check whether all points have almost the same value

• Colors do not follow low/mid/high

  • Check whether some points set useColor=true (it overrides palette interpolation)

• Cells are misaligned (out-of-range / off-by-one)

  • Check whether Category axis labelPlacement is CellCenter
  • Use section 6.4 to determine correct cell count and index ranges

• Cell gaps are too large/too tight

  • Adjust HeatmapSettings.cellGapPx

9. Further reading

• Axes/range, Series and data: 00_02-WorkflowAndLibrary.md
• Common recipes: 04_08-CommonRecipes.md
• FAQ: 04_09-FAQ.md