Tutorial - Tiled Pixelmap

A pixelmap is a way of representing categorical data. It uses a lossless image where, instead of the pixels representing colors, they represent category indices. This is usually compactly represented as a integer split across the red, green, and blue channels, where the category index is computed as (red value) + (green value * 256) + (blue value * 65536).

For large datasets, a single image might be too large to display at once. Much like tile layers used for maps and large images, a pixelmap can also be rendered from a tiled image using the pixelmapLayer. The pixelmapLayer is essentially a hybrid between a tile image layer and a pixelmap feature.

First, let's create our map in the appropriate image coordinates for our pixelmap tile image.

Step 1

Active

Inactive

We can use some of the parameters generated by geo.util.pixelCoordinateParams for the pixelmap tile layer. We need to modify the url to find the image tiles, create an appropriate data array with the categorical data, and determine how to map colors to the categories.

Our categorical image data was generated from a small portion of a histology image using a superpixel algorithm. After dividing the source image into superpixels, the edge of each superpixel was located and set as a separate index value. These happen to always have an index value one greater than the superpixel itself (so the main superpixels are indices 0, 2, 4, ..., and the corresponding edges are indices 1, 3, 5, ...). This data set happens to have 5112 distinct index values. We start with a data array of all zeroes.

Step 2

Active

Inactive

It is more useful to allow the user to modify the data. Change our coloring so that superpixels start transparent with yellow edges and cycle through red, green, and blue as they are selected.

When changing a value in the data array, we need to inform the pixelmap that it is changed. This could be done a variety of ways:

pixelmap.data(data) - this marks the entire data set as changed and will require recomputing the most values.
pixelmap.modified() - this states that the style has changed in some way, but without more specificifity, all of the colors are rechecked.
pixelmap.indexModified(lowIndex, highIndex) - this states that only a small number of indicies' colors have changed, allowing the most efficient update.

Step 3

Active

Inactive

We might want to make it easier for a user to set many superpixels to the same state at once. If the user holds down shift, then the color that the first superpixel that is clicked on is applied to any superpixel entered until the mouse button is released. By using shift, the core pan feature isn't affected.

// disable the default action for left mouse button + shift
map.interactor().removeAction(geo.geo_action.zoomselect);
// if the mouse moves, decide whether we should handle it
var newValue = undefined;
function onOver(evt) {
  // for movement, if shift or the left button aren't down, stop setting values
  if (!evt.mouse.modifiers.shift || !evt.mouse.buttons.left) {
     newValue = undefined;
     return;
  }
  // determine which superpixel to modify
  var index = evt.index - evt.index % 2;
  var data = pixelmap.data();
  // if we just started a movement with shift, update the value and record it
  if (newValue === undefined || evt.event === geo.event.feature.mousedown) {
    data[index] = data[index + 1] = (data[index] + 1) % 4;
    newValue = data[index];
    pixelmap.indexModified(index, index + 1).draw();
  }
  // if we are moving and things have changed, update
  if (data[index] !== newValue) {
    data[index] = data[index + 1] = newValue;
    pixelmap.indexModified(index, index + 1).draw();
  }
}
// An alternative would be to bind on mousemove instead of mousedown and
// mouseover and leave the click handler; this requires movement to start
// setting values, whereas mousedown doesn't require mouse movement.
pixelmap.geoOn(geo.event.feature.mousedown, onOver);
pixelmap.geoOn(geo.event.feature.mouseover, onOver);

Step 4

Active

Inactive