Colorization

Colorization methods are palette, colormap and range colorization. These methods are applied for single band images (including bandmath, grayscale, classified image etc.).

Palette is used for precise colorization of specified pixel values with defined colors, while unaffected pixels remain transparent. It is convenient way to visualize classification image or to pick out desired fetures. Also palette can be used for colorizing bits of Landsat 8 BQA band.

Colormap API is used for colorizing whole image without leaving transparent areas. Many default colormaps have monotonically increasing lightness through them and equal steps in data are perceived as equal steps in the color space, so colorized by such colormap image is better interpreted by the viewer. User can also create its own colormap by specifying colors and their positions.

Range colorization is used for precise colorization of pixels by specifying thresholds and fill colors between these thresholds. There is no need to specify single pixel values, unlike in Palette colorization, and there will be only user-specified colors, unlike Colormap colorization.

Colorization priority is following:

  1. Palette;
  2. Colormap;
  3. Range colorization (Colors + Thresholds);

Palette

Palette is the set of dictionary type pairs of the following form: {“pixel value”:”color code”}. Palette’s colorization feature is strict conformity with set values. Pixels without set color codes are transparent. Palette is used only for integer datasets.

Single band usage

Bandmath pixel values specified as keys by PALETTE dictionary, colors (in form of RGB or hex) that correspond these pixel values are specified as values. If bandmath pixel values don’t have a color tied to them in the PALETTE, pixels are made transparent.

Bit numbers (BQA) usage

PALETTE is a dictionary with bit numbers (1 bit number or 2 as a tuple) as keys and colors (in form of RGB or hex) as values. If in any given pixel some bits have value 1, it’s set to corresponding color from the PALETTE. If bits don’t have a color tied to them in the PALETTE, pixels are made transparent. Without this parameter BQA is colorized with default palette.

Palette usage examples

PALETTE is used as query parameter.

Examples for bandmath usage:

http

GET /api/render/L8/LC08_L1TP_016052_20171117_20171122_01_T1/1$NDWI>0/10/271/477?PALETTE=%7B%221%22%3A%22ff0000%22%7D&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/LC08_L1TP_016052_20171117_20171122_01_T1/1$NDWI>0/10/271/477?PALETTE=%7B%221%22%3A%22ff0000%22%7D&api_key=XXX'

http

GET /api/render/NAIP/ne/2016/60cm/rgbir/40100/m_4010039_sw_14_h_20160918/R+1/15/7264/12357?PALETTE=%7B%22150%22%3A%22ff0000%22%2C%22160%22%3A%2200ff00%22%2C%22170%22%3A%220000ff%22%2C%22180%22%3A%22000000%22%7D&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/NAIP/ne/2016/60cm/rgbir/40100/m_4010039_sw_14_h_20160918/R+1/15/7264/12357?PALETTE=%7B%22150%22%3A%22ff0000%22%2C%22160%22%3A%2200ff00%22%2C%22170%22%3A%220000ff%22%2C%22180%22%3A%22000000%22%7D&api_key=XXX'

Examples for BQA usage:

http

GET /api/render/L8/LC80440342015224LGN00/BQA/15/5277/12696?PALETTE=%7B%22%2815%2C14%29%22%3A%22#33a02c"}&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/LC80440342015224LGN00/BQA/15/5277/12696?PALETTE=%7B%22%2815%2C14%29%22%3A%22#33a02c"}&api_key=XXX'

http

GET /api/render/L8/LC80440342015224LGN00/BQA/12/673/1596?PALETTE=%7B%220%22%3A%5B85%2C0%2C0%5D%7D&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/LC80440342015224LGN00/BQA/12/673/1596?PALETTE=%7B%220%22%3A%5B85%2C0%2C0%5D%7D&api_key=XXX'

Colormap API

Colormap is an array of colors used to map pixel data (represented as indices in the color table) to the actual color values.

Default colormaps from Matplotlib can be used (Accent, viridis, Purples, winter etc., also see Choosing Colormaps).

Examples:

http

GET /api/render/S2/36/U/XU/2016/5/2/0/ndsi/14/9790/5679?COLORMAP=viridis&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/S2/36/U/XU/2016/5/2/0/ndsi/14/9790/5679?COLORMAP=viridis&api_key=XXX'

http

GET /api/render/L8/LC08_L1TP_040030_20171024_20171107_01_T1/B4/11/373/754?COLORMAP=gist_rainbow&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/LC08_L1TP_040030_20171024_20171107_01_T1/B4/11/373/754?COLORMAP=gist_rainbow&api_key=XXX'

For continuous colormaps, COLORS_LIMIT query parameter can be used to limit number of colors, down from 256 to set value.

Example:

http

GET /api/render/S2/36/U/XU/2016/5/2/0/ndsi/14/9790/5679?COLORMAP=viridis&COLORS_LIMIT=10&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/S2/36/U/XU/2016/5/2/0/ndsi/14/9790/5679?COLORMAP=viridis&COLORS_LIMIT=10&api_key=XXX'

To check the list of all available colormaps use:

GET /api/render/colormap/all

Next additional optional parameters are available :

Query Parameters:
 
  • INCLUDE_TYPE – (bool) return information about colormap as object “{name: type}”; [true, false]; default - false
  • TYPE – filtering colormap list in response by type; [“continuous”, “discrete”]; default - without filtering (all colormaps)
Response JSON Object:
 
  • colormap_list (array) – list of available colormaps

Examples:

http

GET /api/render/colormap/ALL?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/colormap/ALL?api_key=XXX'

http

GET /api/render/colormap/all?TYPE=continuous&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/colormap/all?TYPE=continuous&api_key=XXX'

http

GET /api/render/colormap/ALL?INCLUDE_TYPE=1&TYPE=discrete&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/colormap/ALL?INCLUDE_TYPE=1&TYPE=discrete&api_key=XXX'

Colorbar API

PNG image colorbar of the specified colormap.
GET /api/render/colorbar/(colormap_name)
Parameters:
  • colormap_name – name of the colormap for which to create the colorbar

Examples:

http

GET /api/render/colorbar/viridis?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/colorbar/viridis?api_key=XXX'

http

GET /api/render/colorbar/Accent?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/colorbar/Accent?api_key=XXX'

Legend API

This API grants you the ability to generate legend for specified colormap.

GET /api/render/legend/(colormap)

JSON containing legend for the specified colormap. Legend is represented with two attributes: list of hexadecimal COLORS (len(COLORS) == N) and list of THRESHOLDS (len(THRESHOLDS) == N - 1) representing how the COLORS shall be applied.

Parameters:
  • colormap – Colormap for which the legend shall be generated. (See Colorbar API to get the corresponding colorbar)
Query Parameters:
 
  • MIN_MAX – (optional) list of comma separated min,max values for contrast stretching, by default - 0,255
  • LIMIT – (optional) count of colors
Response JSON Object:
 
  • colors (array) – list of hexadecimal colors
  • thresholds (array) – list of internal thresholds, excluding min,max values

Examples:

http

GET /api/render/legend/rainbow?MIN_MAX=-0.13012268930673598%2C0.4157119250833989&LIMIT=10&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/legend/rainbow?MIN_MAX=-0.13012268930673598%2C0.4157119250833989&LIMIT=10&api_key=XXX'

http

GET /api/render/legend/plasma?MIN_MAX=0.45%2C0.96&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/legend/plasma?MIN_MAX=0.45%2C0.96&api_key=XXX'

http

GET /api/render/legend/ocean?MIN_MAX=0.0%2C0.99&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/legend/ocean?MIN_MAX=0.0%2C0.99&api_key=XXX'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "colors": [
            "#8000ff",
            "#4b51fc",
            "#149df1",
            "#21d5e0",
            "#58f7c9",
            "#8efdac",
            "#c4e88b",
            "#fab965",
            "#ff773d",
            "#ff2613"
    ],
    "thresholds": [
        -0.07553917328426105,
        -0.02095565726178611,
            0.03362785876068883,
            0.08821137478316377,
            0.14279489080563867,
            0.19737840682811364,
            0.2519619228505886,
            0.3065454388730635,
            0.3611289548955384
    ]
}

Custom colormaps

Generation of custom colormap is performed by POST-request with specified JSON body.

POST /api/render/colormap/

Create custom colormap, and returns colormap ID.

Form Parameters:
 
  • colors – list of colormap colors (details see below)
  • type(optional) colormap type [discrete, continuous], by default - continuous
  • thresholds_type(optional) [relative, absolute] indicates if thresholds specified by user are relative, i.e. indicate percentage of an image minmax in range 0-1, or absolute. By default - relative.
  • labels(optional) for discrete colormaps - list of names to pair with colors. Has to be same length as colors
Response JSON Object:
 
  • id (string) – colormap ID

Request example:

{
    "colors": [[0.0, "#ff0000"], [0.1, "#00ff00"], [0.9, "#ff00ff"], [1.0, "#0000ff"]],
    "type": "continuous"
}

Response example:

{
    "id": "d519dc9617cce94c817cc0c30ef3fb09"
}
GET /api/render/colormap/(colormap_id)

Get information about custom colormap.

Parameters:
  • colormap_id – colormap ID
Response JSON Object:
 
  • colors (array) – list of colormap colors
  • type (string) – colormap type [discrete, continuous]
  • thresholds_type (string) – thresholds type [relative, absolute]
  • colors_quantity (number) – number of colors
  • labels (array) – (optional) list of labels, if present for given colormap

Request example:

http

GET /api/render/colormap/7b0ec75f45fdd58bf3ba2ddd2d19b174?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/colormap/7b0ec75f45fdd58bf3ba2ddd2d19b174?api_key=XXX'

Response example

{
    "colors": [[0, "#ff9900"],[0.6, "#ffcc00"],[1, "#ffff66"],[2, "#ffff99"],[5.2, "#ff0000"],[7, "#ffffff"],[10, "#336600"]],
    "type": "discrete",
    "thresholds_type": "absolute",
    "labels": ["One", "Two", "Three", "Four", "Five", "Six", "Seven"],
    "colors_quantity": 7
}

Colors list format

For creating custom colormap, need provide to API list with colors.

List without positions

[color, color, color]

List with position

[[0.0, color], [position, color], [position, color],  [1.0, color]]

Supported color formats:

  1. Hexadecimal string. Ex. : “#f33a67”.
  2. RGB list, each band is in range 0..1. Ex.: [0.5, 0.7, 0.3].

By default, supported position is in range 0..1. First color should be in position 0.0, last - 1.0. User can also specify absolute values of position, in range which corresponds to min and max of a dataset to be colorized. In this case, thresholds_type parameter shall be set to “absolute”:

Request example:

{
    "colors": [[-0.3, "#ff0000"], [-0.1, "#00ff00"], [0.1, "#ff00ff"], [0.3, "#0000ff"]],
    "type": "continuous",
    "thresholds_type": "absolute"
}

Colormap ID usage example

Both Colorbar API and Legend API can be used for custom colormaps

Get colorbar (See Colorbar API)

http

GET /api/render/colorbar/d519dc9617cce94c817cc0c30ef3fb09?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/colorbar/d519dc9617cce94c817cc0c30ef3fb09?api_key=XXX'

Get legend (See Legend API)

http

GET /api/render/legend/d519dc9617cce94c817cc0c30ef3fb09?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/legend/d519dc9617cce94c817cc0c30ef3fb09?api_key=XXX'

Applying to tile

http

GET /api/render/L8/LC08_L1TP_029031_20180507_20180517_01_T1/ndvi/14/3765/6102?COLORMAP=d519dc9617cce94c817cc0c30ef3fb09&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/LC08_L1TP_029031_20180507_20180517_01_T1/ndvi/14/3765/6102?COLORMAP=d519dc9617cce94c817cc0c30ef3fb09&api_key=XXX'

The custom colormap also have reversed version. Use the same IDs with “_r” on to the end, for reversing.

Example: d519dc9617cce94c817cc0c30ef3fb09_r

Colormap mechanics explanation

Continuous colormap with specified RGB colors [0.0, “#ff0000”], [0.5, “#00ff00”], [1.0, “#0000ff”]. It has 256 colors

_images/colorbar_continuous.png

Discrete colormap with the same RGB colors.

_images/colorbar_discrete.png

Using Legend API it is also possible to get precise values of thresholds. Thresholds are in range 0..255 unless otherwise specified by MIN_MAX query parameter of Legend API. For this discrete colormap there is only one threshold between R and G colors on 0.5 of range 0..255, i.e. 127.5. Colors are limited to those specified by the colormap.

For continious colormap there are 255 thresholds between 256 colors, so color value is changing monotonically, creating new intermediate colors between set colors and thresholds. Color positions stretch over input data range.

Range colorization

Range colorization (COLORS & THRESHOLDS) is used for single band data. Unlike colormap, range colorization specifies values of colors and thresholds strictly. This leads to following сonsequences:

1.No other colors appear (unlike in continuous colormaps), used colors are limited to those specified by COLORS.

2.Thresholds are applied as absolute values to input data. For example: NDVI data varies in range -1..1, so THRESHOLDS also have to be in this range, ubyte-type data (0..255) requires corresponding THRESHOLDS values, i.e. 0,100,127,201 etc.

Example query like ?COLORS=000000,ffffff,c4baa4,b4966c,a4824c&THRESHOLDS=0,0.3,0.6,0.9 colorizes NDVI data in the following way: pixel values from -1 to 0 are colorized in 000000 color, from 0 to 0.3 in ffffff, from 0.3 to 0.6 in c4baa4, from 0.6 to 0.9 in b4966c, from 0.9 to 1 in a4824c color.

COLORS and THRESHOLDS are used only in pair.

COLORS are specified as string of hexadecimals, separated by commas without spaces. Ex.: “b4966c,a4824c”.

THRESHOLDS are specified as string of digitals, separated by commas without spaces. Has to contain 1 less value than COLORS. Ex.: “0.07,0.1”

Note

Range colorization is used as default for NDVI, NDSI, NDWI.

Range colorization usage example

http

GET /api/render/L8/LC08_L1TP_040030_20171024_20171107_01_T1/(B5-B4)/(B5+B4)/11/379/755?COLORS=000000%2CFFFFFF%2Cc4baa4%2Cb4966c%2Ca4824c%2C94723c%2C7c9e2c%2C94b614%2C74aa04%2C64a204%2C549604%2C1c7204%2C045e04%2C044204%2C043a04%2C042604%2C021702%2C051505%2C041204&THRESHOLDS=0%2C0.03%2C0.07%2C0.1%2C0.13%2C0.17%2C0.2%2C0.25%2C0.3%2C0.4%2C0.45%2C0.576%2C0.68%2C0.737%2C0.788%2C0.803%2C0.83%2C0.853&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/LC08_L1TP_040030_20171024_20171107_01_T1/(B5-B4)/(B5+B4)/11/379/755?COLORS=000000%2CFFFFFF%2Cc4baa4%2Cb4966c%2Ca4824c%2C94723c%2C7c9e2c%2C94b614%2C74aa04%2C64a204%2C549604%2C1c7204%2C045e04%2C044204%2C043a04%2C042604%2C021702%2C051505%2C041204&THRESHOLDS=0%2C0.03%2C0.07%2C0.1%2C0.13%2C0.17%2C0.2%2C0.25%2C0.3%2C0.4%2C0.45%2C0.576%2C0.68%2C0.737%2C0.788%2C0.803%2C0.83%2C0.853&api_key=XXX'

http

GET /api/render/L8/LC80440342015224LGN00/NDVI/11/328/794?COLORS=000000%2Cffffff%2Cc4baa4%2Cb4966c%2Ca4824c&THRESHOLDS=0%2C0.3%2C0.6%2C0.9&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/LC80440342015224LGN00/NDVI/11/328/794?COLORS=000000%2Cffffff%2Cc4baa4%2Cb4966c%2Ca4824c&THRESHOLDS=0%2C0.3%2C0.6%2C0.9&api_key=XXX'

http

GET /api/render/NAIP/fl/2015/100cm/rgbir/27080/m_2708055_se_17_1_20160104/R*1/16/18173/27625?COLORS=000000%2Cffffff%2Cc4baa4%2Cb4966c%2Ca4824c&THRESHOLDS=0%2C100%2C127%2C255&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/NAIP/fl/2015/100cm/rgbir/27080/m_2708055_se_17_1_20160104/R*1/16/18173/27625?COLORS=000000%2Cffffff%2Cc4baa4%2Cb4966c%2Ca4824c&THRESHOLDS=0%2C100%2C127%2C255&api_key=XXX'