Updated for release version: 1.0.31

This page introduces the Maps Panel interface of ModelGUI, which allows users to load, save, or modify various maps.

Introduction

Maps are an important means of translating between different data representations. For shapes, one of the most important means of visualization, for instance, is to map continuous values associated with vertices ("vertex data columns") with a spectrum of colours, which provides a visual contrast between the values. Suppose, for instance, that you have performed statistics on each of the vertices and want to display the spatial distribution of p-values. You'll need a colour map, which maps your values to RGB values. The various types of maps are described below, as well as the parts of the Maps Panel which allow them to be viewed, modified, created, and read or written to disk.

Colour Maps

Colour maps provide a mapping between numeric values and colours (Red-Green-Blue-Alpha, or RGBA, values). This can be done either by interpolation along a continuous scale (a continuous colour map), or by assigning integers directly to colours (a discrete colour map). These concepts are elaborated below.

Continuous Colour Maps

Continuous colour maps are representing in ModelGUI using an anchor system. Assuming the range of real-valued data can be normalized to the range 0.0 to 1.0, a continuous colour map must have at least two anchors for each of these values. Any number of additional anchors can then be defined intermediate to these values. A typical colour map with five anchors looks like this:

Anchor positions can be changed by dragging them on the display image; when the anchor positions change, the colour map changes, like so:

The Continuous Maps section consists of:

1. Choosing an existing map from the drop-down menu
2. Viewing a colour map with the map panel; this image allows you to (a.) change the anchors by dragging them; (b.) add new anchors by double-clicking where you want them; (c.) removing anchors by right-clicking
3. Change the map's name, and change the anchor values, including its colour and transparency (alpha)
4. Scroll through, add, or delete anchors using the buttons rather than the image; you can also copy a map to a new map (i.e., if you want to create an alternate version of a map without overwriting it), by clicking "Copy"
5. Load a saved map from file, or write the current map to file
6. Invert the map (this sets every anchor value v to 1.0 - v); also to apply the changes you've made to a map, click the "Update" button. Otherwise, if you select another map from the list, these changes will not be applied. Thus, to discard changes, you simply have to select another map.

Additionally, you can save a colour map as an image by right-clicking (not on an anchor!) and selecting "Save as image". This brings up a dialog which allows you to customize the map before saving it, by means of a right-click popup menu. You can play with the options to get an idea of what they do.

Discrete Colour Maps

Discrete colour maps specify a one-to-one mapping between integer values and colours. The Discrete Maps panel is shown below, for a simple mapped called, appropriately, "Simple Map":

This panel allows you to:

1. Choose the current map from a drop-down list
2. Specify an optional Name Map (see below), which associates the map indices with text as well as colours
3. Specify the colours which are associated with a given index value, by clicking the colour button beside it in the table; the button shows the current colour
4. Save the current colour map to disk, or load one from file. Create a new discrete colour map, or delete the current one
5. View the colour map as a layout (this is currently in an alpha state, but will eventually allow the map to be printable, or savable to PDF format)

All changes in this case are immediate (the beta version should provide an "Update" button, similar to the Continuous Map section).

Name Maps

A name map is similar to a discrete colour map, but it associates its integer indices with text strings instead of colours. This is highly useful, for instance, for specifying vertex-wise regions-of-interest (ROIs), which must be represented as integers, since vertex data must be numeric. The Name Maps panel allows you to choose a name map from a drop-down list, and its values will appear in the table below it. The text values can be changed directly in the table. All changes in this case are immediate (the beta version should provide an "Update" button, similar to the Continuous Map section).

Input/Output

Maps can be saved to and loaded from persistent storage, using the "Save" button. Colour map files contained in the "cmaps" subfolder of the ModelGUI application folder are loaded automatically when the program is executed. Other colour maps or name maps can be loaded via the File Panel.

Continuous Colour Maps

Continuous colour maps are stored as comma-separated value (CSV) text files. Each anchor point is represented by a single line, with the format:

{anchor position | [0,1]}, {red value | [0,1]}, {green value | [0,1]}, {blue value | [0,1]}, {alpha value | [0,1]}

Note: Future versions of ModelGUI will represent continuous colour maps as XML files.

Discrete Colour Maps

Discrete colour maps are stored as XML-format files, of the form:

<ColourMap name=String, type=String[discrete,continuous]>
  <NameMap [optional] name=String>
     <Item index=Integer, value=String>
  <Item index=Integer>
     <Colour4f red=Float[0,1], green=Float[0,1], blue=Float[0,1], alpha=Float[0,1]>

Exporting Images

ModelGUI can output colour maps as PNG images, which can be used for instance to print directly, or to include in screenshots of shapes coloured with a particular colour map configuration. These are described below:

Continuous Colour Maps

You can bring up the Output Colour Bar dialog box by right-clicking on a continuous colour map bar in the Maps Panel and selecting "Save as image..", as shown below:

Right-clicking on the dialog image will now bring up a number of options for formatting the colour map. These include adding a padding around the edges, changing the label font, font size, font space relative to the colour bar, data range, background and foreground colours, and so on. Additionally, resizing the dialog to be more vertical than horizontal will update the placement of the labels to the right of the colour bar. You can play with these settings until you're happy with the way the colour bar looks:

Finally, to save the colour bar as a PNG image, click the "Write" button. Click "Cancel" or the "X" button to close the dialog.

Discrete Colour Maps