PATTERNS

map raster layers

Any geographic information system will provide methods for displaying data as a map layer.

To understand these patterns, it will be helpful to review some basic concepts of data visualization.

data values vs. display values

When you visualize data, you map data values to display values. Two things often happen by default:

1. The data type of the digital numbers defines the range of values that get mapped to the display values.
2. The relationship between data values and display values is linear.

---

---

The reason that the displayed values in the example above have such poor contrast is a result of the mismatch between the possible data values defined by the data type and the actual data values stored in the raster.

A histogram is one way to compare the possible and actual data values of a raster.

---

---

A common strategy to improve the contrast of an image is to stretch the display values over the range of actual data values by setting the linear map to begin and end at the minimum and maximum actual data value, respectively. This is usually called stretch enhancement.

---

---

display image as layer

The diagram below shows a general pattern to display an image as a map layer with Earth Engine. The first two tasks – print min & max value and chart histogram – are methods to identify the range of actual data values in the image and how they are distributed, respectively. The middle task – define viz dictionary – is a method for storing the min and max values for stretch enhancements. The last task – display data as map layer – draws the result on the Map.

graph LR

  step01("Print min & max value") ;
  step02("Chart histogram") ;
  step03("Define viz dictionary")  ;
  step04("display data as map layer") ;

  step01 --> step03 
  step02 --> step03 
  step03 --> step04

  classDef task fill:#C3D3E6,stroke-width:0px,color:#000000;

  class step01 task; 
  class step02 task;
  class step03 task;
  class step04 task;

---

print min & max value of image

Print the min and max data value of a raster image to use as min and max values in viz dictionary.

var output_min_max = geo.iCart.iMinMax(image, scale, extent);

print("Min & max value of image", output_min_max);

ARGUMENT	DESCRIPTION
image	The name of the variable that contains the image data to process.
scale	The scale of analysis. If possible, use the scale (resolution) of the input image. If this runs really slow (or times out), then increase the scale of analysis by a factor of 2 or more.
extent	Usually the area of interest or the geographic footprint of the image.

---

chart histogram of data values

See how your data are distributed between the minimum and maximum data value by charting a histogram.

var output_histogram = geo.iCart.iHistogram(image, scale, extent);

print("Image histogram", output_histogram);

ARGUMENT	DESCRIPTION
input_image	The name of the variable that contains the image data to process.
scale	The scale of analysis. If possible, use the scale (resolution) of the input image. If this runs really slow (or times out), then increase the scale of analysis by a factor of 2 or more.
extent	Usually the area of interest or the geographic footprint of the image.

---

define raster viz dictionary

For raster data, store the viz dictionary as a variable and then call this variable when you add the map layer.

Here is a common pattern to visualize single-band images with grayscale:

var single_viz = 
    {
        min: [],        
        max: [],        
    }
;

---

Here is a common pattern to visualize single-band images with color (this includes both color gradient layers and nominal layers where a unique color displays each unique class):

var single_viz = 
    {
        min: [],        
        max: [],        
        palette: [],    
    }
;

---

This is a common pattern to visualize multi-band images as a combination of red, green, and blue channels:

var multi_viz = 
    {
        bands: [],      
        min:  [].      
        max: [],        
        gamma: [],      
    }
;

---

If your image data represents nominal data with integers, you can quickly visualize this data with random colors using the .randomVisualizer() method on the image and calling an empty dictionary for the viz parameters.

Map.addLayer(image.randomVisualizer(), {}, "Nominal Classes");

This pattern is most useful for quick visualizations, when the color used to display the class does not matter too much. If you want to be able to control which color displays each class, then you should use the single band image with color pattern described earlier and make sure that the length (number of) integer values in your class set equals the length of colors in your palette.

---

add map layer

Map.addLayer() method will display data as a map layer.

Map.addLayer(data,viz,"Layer Name",show,opacity);

The Map.addLayer() method takes the following arguments:

ARGUMENT	DESCRIPTION
data	The name of the variable that contains the data that you wish to display.
viz	The viz dictionary that defines how to visualize (display) the data.
layer name	A string that provides a label for the data in the list of layers.
show	A boolean argument to control whether or not the layer is displayed when first loaded.
opacity	A decimal number between 0 and 1 to adjust the opacity of the layer.

---

complete pattern

Here is a complete pattern for single-band grayscale images.

// Print min and max values of image. 

print("Min & max value of image", geo.iCart.iMinMax(image, scale, extent));

// Chart histogram of actual data values.

print("Image histogram", geo.iCart.iHistogram(image, scale, extent));

// Define viz dictionary. 

var single_viz = 
    {
        min: [],        
        max: [],        
    }
;

// Add map layer. 

Map.addLayer(image,single_viz,"Layer Name");

---

This work is licensed under CC BY-NC-SA 4.0