Examples of HeatChart

The HeatChart class describes a chart which can display 3-dimensions of values - x,y and z, where x and y are the usual 2-dimensional axis and z is portrayed by colour intensity. Heat charts are sometimes known as heat maps.

Use of this chart would typically involve 3 steps:

Construction of a new instance, providing the necessary z-values.
Configure the visual settings.
A call to either getChartImage() or saveToFile(String).

Instantiation

Construction of a new HeatChart instance is through its one constructor which takes a 2-dimensional array of doubles which should contain the z-values for the chart. Consider this array to be the grid of values which will instead be represented as colours in the chart.

Setting of the x-values and y-values which are displayed along the appropriate axis is optional, and by default will simply display the values 0 to n-1, where n is the number of rows or columns. Otherwise, the x/y axis values can be set with the setXValues and setYValues methods. Both methods are overridden with two forms:

Object axis values

The simplist way to set the axis values is to use the methods which take an array of Object[]. This array must have the same length as the number of columns for setXValues and same as the number of rows for setYValues. The string representation of the objects will then be used as the axis values.

Offset and Interval

This is convenient way of defining numerical values along the axis. One of the two methods takes an interval and an offset for either the x or y axis. These parameters supply the necessary information to describe the values based upon the z-value indexes. The quantity of x-values and y-values is already known from the lengths of the z-values array dimensions. Then the offset parameters indicate what the first value will be, with the intervals providing the increment from one column or row to the next.

Consider an example:

 double[][] zValues = new double[][]{ {1.2, 1.3, 1.5}, {1.0, 1.1, 1.6}, {0.7, 0.9, 1.3} }; double xOffset = 1.0; double yOffset = 0.0; double xInterval = 1.0; double yInterval = 2.0; chart.setXValues(xOffset, xInterval); chart.setYValues(yOffset, yInterval);

In this example, the z-values range from 0.7 to 1.6. The x-values range from the xOffset value 1.0 to 4.0, which is calculated as the number of x-values multiplied by the xInterval, shifted by the xOffset of 1.0. The y-values are calculated in the same way to give a range of values from 0.0 to 6.0.

Configuration

This step is optional. By default the heat chart will be generated without a title or labels on the axis, and the colouring of the heat map will be in grayscale. A large range of configuration options are available to customise the chart. All customisations are available through simple accessor methods. See the javadoc of each of the methods for more information.

Output

The generated heat chart can be obtained in two forms, using the following methods:

getChartImage() - The chart will be returned as a BufferedImage object that can be used in any number of ways, most notably it can be inserted into a Swing component, for use in a GUI application.
saveToFile(File) - The chart will be saved to the file system at the file location specified as a parameter. The image format that the image will be saved in is derived from the extension of the file name.

Note: The chart image will not actually be created until either saveToFile(File) or getChartImage() are called, and will be regenerated on each successive call.