TreeMap API

To use the TreeMap API for Java/Swing, place the macrofocus-treemap.jar, macrofocus-common.jar, macrofocus-visualization.jar, and macrofocus-slider.jar libraries in your class path. An efficient starting point is to instantiate the com.treemap.TreeMap component.

To use the TreeMap API for JavaScript/HTML5, place the content of the TreeMap directory on your web server and start the loading of the module using the TreeMap/TreeMap.nocache.js script. The loading of the module happens asynchronously. Once it is loaded, then the treeMapModuleLoaded() `callback method is called. The `com.treemap.TreeMap component is now ready to be instantiated and should be attached to an HTML element by passing its id.

You may read your data from any data sources such as a database table, a file, a piece of data in memory. The data should be in tabular format that can be converted to TableModel as defined in Java Swing. From TreeMap API point of view, the only data it will accept is the TableModel. As long as you convert your raw data to TableModel, you can use it in TreeMap API.

The JavaScript API of TreeMap supports loading data in JSON format or by passing a JavaScript array using one of the method call below:

When loading data through a URL, please pay attention to the same-origin policy, i.e. the data should originate from the same scheme, hostname, and port number as the TreeMap library.

The default implementation of the TreeMapModel interface uses a standard Swing TableModel `as the underlying data holder. The default implementation of the `TreeMapModel interface will automatically map the size to the first numerical column, the color to the second numerical column, the labels to the first categorical column, and the group by to the second categorical column.

If your data model is not in tabular form or you want to customize how the data are fed into the TreeMap, then you can extend the AbstractTreeMapModel class. Key methods to implement are getChildren(), getParent() `and `getValueAt().

The default implementation of the TreeMapView interface will automatically coalesce multiple changes to the model to a single repaint operation and has the possibility of updating the display progressively should very large datasets be displayed.

The default implementation of the TreeMapController interface supports probing, selection, zooming, panning, and drilling operations. Probing is achieved by simply moving the mouse over the shape of interest and a popup will then display detailed information about that item. Selection is done through left-mouse click and lasso operations by pressing down the kbd:[Alt] key while dragging the mouse. Zooming can comfortably be done using a mouse wheel or zooming gesture of a trackpad. Finally, drilling is supported using the Page-Down and Page-Up keys.

As the treemap visualization technique attempts to keep the area of the shapes on the screen proportional to some data values, it is key to specify which column in the TableModel should be used as a proxy for the size. This can specified using one of the following two methods, depending on whether you prefer to use the column index or the column name:

The specified column should contain numerical values of type Integer, Float, or Double. If the value is null, then it will simply not be included in the treemap layout. Since values can be negative but shapes cannot have negative areas, the default behavior is to use the absolute value. To override this behavior, it is possible to use another scaling scheme, such as:

In this case, negative values will not be included in the treemap layout.

How each shape should be colored can be defined by using a colormap that will convert numerical and categorical values into colors according to a defined scale or dictionary. Which column to use should be defined using its index or name:

To override the default colormap that is assigned to each column, it is possible to set a customized one, for example:

The ColorMapFactory class provides a range of static methods for creating standard colormaps for categorical, sequential, and diverging values. The PaletteFactory gives access to a wide range of predefined color gradients.

A Colormap contains both an Interval and a Palettte, which are conjointly used to map the actual values into the normalized range (0..1) used to retrieve the colors defined in the palette. To create a custom colormap and palette that associate -200 to red, 0 to white, and 200 to green, you need to:

You can then customize it further by assigning special colors to values that fall outside of the range defined by the Interval by using the setUnderColor() and setOverColor() methods, or to missing values with the setNullColor() method.

The shapes can extend to the third dimension by specifying the column index or name containing their relative height:

In conjunction, the maximum relative height (as a percentage of the overall treemap size) of the shapes can be controlled through:

Treemap visualization is a very effective method when used with hierarchical data. To define how each row of the original TableModel should be grouped and sub-grouped, the list of columns indices or names can be defined:

Should your data have an unbalanced hierarchy, you can specify the hierarchal placement of each row in the TableModel by having a column of type Path.

Labels containing values from the original TableModel can be incorporated within each shape, either as a list where each value is displayed below one another:

and/or by filling the entire area with one value:

TreeMap API includes a wide range of treemap and related layout algorithms:

The one to use can easily be set using the following method call:

Many options are provided to tune the appearance of the resulting treemap visualization. The most common is to define whether the shapes should be rendered with a cushion effect that highlight the hierarchical placement or using a solid color with a optional border:

Another important customization area is to define how the headers of the various groups be displayed, for example by setting the placement of the header and font to use:

Similarly, the font to use to display the labels can be specified as well:

Finally, the color used for probing and selection can be customized using:

It is possible to fine tune the appearance and the positioning of the headers, labels, and tooltips by customizing their respective renderers: TreeMapHeaderRenderer, TreeMapLabelRenderer, and TreeMapTooltipRenderer. We provide default implementations for each of them that allow to customize, for example, the visual effect (drop shadow, glow), the vertical and horizontal alignment of the text, the minimum number of character to display, and how text should be truncated:

final DefaultTreeMapHeaderRenderer headerRenderer = new DefaultTreeMapHeaderRenderer();

The foreground, background and effect colors, as well as the font, have to be customized through the settings:

Setting the appropriate Format to each column can specify how values are formatted:

The content of the tooltip can be changed by enabling/disabling the display of particular values and labels:

In addition, the width of the tooltip and its type can be adjusted. The Painted tooltip type will clip any region outside of the TreeMap component, while the Lightweight type allows for overflow within the application window, and the Heavyweight type relies on a native borderless window that is only limited by the size of the display.

Furthermore, a tailored implementation of the TreeMapToolTip interface, or an extension of the DefaultTreeMapToolTip can be provided. The Global2000Demo exemplify what can typically be achieved.

The selected nodes can be retrieved using TreeMapModel.getSelection(). The node currently under the mouse can be accessed using TreeMapModel.getProbing(). It is possible to turn off multiple selection by using the DefaultTreeMapController.setMultipleSelectionEnabled() method.

The TreeMapController controls the content of the popup menu. It can be extended with additional entries using: