Colorization API
Default colormap colorizationβ
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).
Example of Render Sentinel2 image with NDSI index and viridis colormap:
https://api-connect.eos.com/api/render/S2/36/U/XU/2016/5/2/0/NDSI/10/611/354?COLORMAP=viridis&api_key=<your_api_key>
To check the list of all available colormaps use:
HTTP Requestβ
GET `https://api-connect.eos.com/api/render/colormap/ALL?api_key=<your_api_key>`
Request Parametersβ
| Request Path Parameter | Value | Description |
|---|---|---|
| api_key | <your_api_key> | (Required) Apikey retrieved from developer portal |
| INCLUDE_TYPE | [true, false] | (bool) return information about colormap as object {name: type}; default - false |
| TYPE | [βcontinuousβ, βdiscreteβ] | filtering colormap list in response by type; default - without filtering (all colormaps) |
The resulting colormap value is used in Download requests to obtain images.
For example, you can try to use an example for download visual
Read more about predefined colormaps on Matplotlib portal
Examples for colormap requestβ
Example 1 - Request without additional parameters
Example 2 - Request with the additional parameter TYPE
Example 3 - Request with the additional parameters INCLUDE TYPE and TYPE
Example 1β
Request without additional parameters
curl --location --request GET 'https://api-connect.eos.com/api/render/colormap/ALL?api_key=<your_api_key>'
Response
{
"colormap_list": [
"Accent",
"Accent_r",
"Blues",
"Blues_r",
"BrBG",
"BrBG_r",
"BuGn",
"BuGn_r",
"BuPu",
"BuPu_r",
"CMRmap",
"CMRmap_r",
"Dark2",
"Dark2_r",
"GnBu",
"GnBu_r",
"Greens",
"Greens_r",
"Greys",
"Greys_r",
"OrRd",
"OrRd_r",
"Oranges",
"Oranges_r",
"PRGn",
"PRGn_r",
"Paired",
"Paired_r",
"Pastel1",
"Pastel1_r",
"Pastel2",
"Pastel2_r",
"PiYG",
"PiYG_r",
"PuBu",
"PuBuGn",
"PuBuGn_r",
"PuBu_r",
"PuOr",
"PuOr_r",
"PuRd",
"PuRd_r",
"Purples",
"Purples_r",
"RdBu",
"RdBu_r",
"RdGy",
"RdGy_r",
"RdPu",
"RdPu_r",
"RdYlBu",
"RdYlBu_r",
"RdYlGn",
"RdYlGn_r",
"Reds",
"Reds_r",
"Set1",
"Set1_r",
"Set2",
"Set2_r",
"Set3",
"Set3_r",
"Spectral",
"Spectral_r",
"Wistia",
"Wistia_r",
"YlGn",
"YlGnBu",
"YlGnBu_r",
"YlGn_r",
"YlOrBr",
"YlOrBr_r",
"YlOrRd",
"YlOrRd_r",
"afmhot",
"afmhot_r",
"autumn",
"autumn_r",
"binary",
"binary_r",
"bone",
"bone_r",
"brg",
"brg_r",
"bwr",
"bwr_r",
"cividis",
"cividis_r",
"cool",
"cool_r",
"coolwarm",
"coolwarm_r",
"copper",
"copper_r",
"cubehelix",
"cubehelix_r",
"flag",
"flag_r",
"gist_earth",
"gist_earth_r",
"gist_gray",
"gist_gray_r",
"gist_heat",
"gist_heat_r",
"gist_ncar",
"gist_ncar_r",
"gist_rainbow",
"gist_rainbow_r",
"gist_stern",
"gist_stern_r",
"gist_yarg",
"gist_yarg_r",
"gnuplot",
"gnuplot2",
"gnuplot2_r",
"gnuplot_r",
"gray",
"gray_r",
"hot",
"hot_r",
"hsv",
"hsv_r",
"inferno",
"inferno_r",
"jet",
"jet_r",
"magma",
"magma_r",
"nipy_spectral",
"nipy_spectral_r",
"ocean",
"ocean_r",
"pink",
"pink_r",
"plasma",
"plasma_r",
"prism",
"prism_r",
"rainbow",
"rainbow_r",
"seismic",
"seismic_r",
"spring",
"spring_r",
"summer",
"summer_r",
"tab10",
"tab10_r",
"tab20",
"tab20_r",
"tab20b",
"tab20b_r",
"tab20c",
"tab20c_r",
"terrain",
"terrain_r",
"twilight",
"twilight_r",
"twilight_shifted",
"twilight_shifted_r",
"viridis",
"viridis_r",
"winter",
"winter_r"
]
}
Example 2β
Request with the additional parameter TYPE
curl --location --request GET 'https://api-connect.eos.com/api/render/colormap/ALL?TYPE=continuous&api_key=<your_api_key>'
Response
{
"colormap_list": [
"gist_stern",
"PuOr",
"GnBu",
"YlOrRd_r",
"plasma_r",
"RdGy_r",
"twilight_r",
"PuBu",
"gnuplot",
"bone_r",
"PuRd",
"Purples",
"coolwarm",
"CMRmap_r",
"YlGnBu",
"hot_r",
"RdYlBu",
"summer_r",
"viridis_r",
"BrBG_r",
"Oranges_r",
"magma",
"gist_yarg",
"gray_r",
"flag",
"brg",
"coolwarm_r",
"gist_heat_r",
"Wistia_r",
"hsv_r",
"afmhot",
"gnuplot2",
"jet_r",
"twilight_shifted_r",
"BuGn",
"BuGn_r",
"YlGn_r",
"PuBuGn_r",
"Reds",
"GnBu_r",
"binary_r",
"Greys_r",
"Wistia",
"cool",
"gray",
"terrain_r",
"RdYlGn",
"PiYG",
"BrBG",
"PuRd_r",
"cubehelix_r",
"PRGn",
"Blues_r",
"autumn_r",
"Purples_r",
"nipy_spectral_r",
"PuBuGn",
"PuBu_r",
"RdYlBu_r",
"cividis_r",
"hsv",
"RdBu_r",
"YlOrBr_r",
"gist_stern_r",
"inferno_r",
"cool_r",
"plasma",
"Oranges",
"inferno",
"CMRmap",
"copper_r",
"seismic",
"gist_ncar_r",
"YlOrRd",
"spring_r",
"gnuplot_r",
"YlOrBr",
"gist_earth_r",
"prism",
"OrRd",
"terrain",
"gist_ncar",
"seismic_r",
"RdGy",
"YlGnBu_r",
"binary",
"cividis",
"autumn",
"gnuplot2_r",
"RdPu_r",
"magma_r",
"RdYlGn_r",
"RdBu",
"bone",
"twilight",
"twilight_shifted",
"rainbow",
"copper",
"gist_yarg_r",
"viridis",
"gist_gray",
"Greys",
"gist_gray_r",
"summer",
"Greens_r",
"bwr_r",
"OrRd_r",
"pink",
"ocean_r",
"winter_r",
"PRGn_r",
"Reds_r",
"bwr",
"gist_earth",
"pink_r",
"PuOr_r",
"hot",
"ocean",
"rainbow_r",
"YlGn",
"flag_r",
"Greens",
"Spectral_r",
"gist_heat",
"cubehelix",
"prism_r",
"RdPu",
"Spectral",
"spring",
"BuPu_r",
"PiYG_r",
"afmhot_r",
"nipy_spectral",
"winter",
"BuPu",
"gist_rainbow_r",
"Blues",
"jet",
"gist_rainbow",
"brg_r"
]
}
Example 3β
Request with the additional parameters INCLUDE TYPE and TYPE
curl --location --request GET 'https://api-connect.eos.com/api/render/colormap/ALL?INCLUDE_TYPE=1&TYPE=discrete&api_key=<your_api_key>'
Response
{
"colormap_list": [
{ "Accent": "discrete" },
{ "Accent_r": "discrete" },
{ "Dark2": "discrete" },
{ "Dark2_r": "discrete" },
{ "Paired": "discrete" },
{ "Paired_r": "discrete" },
{ "Pastel1": "discrete" },
{ "Pastel1_r": "discrete" },
{ "Pastel2": "discrete" },
{ "Pastel2_r": "discrete" },
{ "Set1": "discrete" },
{ "Set1_r": "discrete" },
{ "Set2": "discrete" },
{ "Set2_r": "discrete" },
{ "Set3": "discrete" },
{ "Set3_r": "discrete" },
{ "Vega10": "discrete" },
{ "Vega10_r": "discrete" },
{ "Vega20": "discrete" },
{ "Vega20_r": "discrete" },
{ "Vega20b": "discrete" },
{ "Vega20b_r": "discrete" },
{ "Vega20c": "discrete" },
{ "Vega20c_r": "discrete" },
{ "tab10": "discrete" },
{ "tab10_r": "discrete" },
{ "tab20": "discrete" },
{ "tab20_r": "discrete" },
{ "tab20b": "discrete" },
{ "tab20b_r": "discrete" },
{ "tab20c": "discrete" },
{ "tab20c_r": "discrete" }
]
}
Predefined colormapsβ
NDVI: colormap_id:a9bc6eceeef2a13bb88a7f641dca3aa0, levels:-1,1
NDRE - colormap_id:a9bc6eceeef2a13bb88a7f641dca3aa0&MIN_MAX=-1.0,1.0
MSAVI - colormap_id:5792d8fc39a4598f8a2c67b300982076&MIN_MAX=-1,1
NDMI - colormap_id:a53f2c53d3cbc1d424c35ac8dc883644&MIN_MAX=-1,1
1. For getting NDVI data you can useβ
"colormap": "a9bc6eceeef2a13bb88a7f641dca3aa0"
"levels": "-1,1"
{
"colors": [
[
-1.0,
"#ad0028"
],
[
0.05,
"#c5142a"
],
[
0.1,
"#e02d2c"
],
[
0.15,
"#ef4c3a"
],
[
0.2,
"#fe6c4a"
],
[
0.25,
"#ff8d5a"
],
[
0.3,
"#ffab69"
],
[
0.35,
"#ffc67d"
],
[
0.4,
"#ffe093"
],
[
0.45,
"#ffefab"
],
[
0.5,
"#fdfec2"
],
[
0.55,
"#eaf7ac"
],
[
0.6,
"#d5ef94"
],
[
0.65,
"#b9e383"
],
[
0.7,
"#9bd873"
],
[
0.75,
"#77ca6f"
],
[
0.8,
"#53bd6b"
],
[
0.85,
"#14aa60"
],
[
0.9,
"#009755"
],
[
0.95,
"#007e47"
],
[
1.0,
"#007e47"
]
],
"type": "discrete",
"thresholds_type": "absolute",
"colors_quantity": 21
}
2. For getting MSAVI data you can useβ
"colormap": "5792d8fc39a4598f8a2c67b300982076"
"levels": "-1,1"
{
"colors": [
[
-1.0,
"#ad0028"
],
[
0.0,
"#fe6c4a"
],
[
0.02,
"#ff8d5a"
],
[
0.04,
"#ffab69"
],
[
0.06,
"#ffc67d"
],
[
0.08,
"#ffe093"
],
[
0.1,
"#ffefab"
],
[
0.12,
"#fdfec2"
],
[
0.15,
"#eaf7ac"
],
[
0.17,
"#d5ef94"
],
[
0.2,
"#b9e383"
],
[
0.22,
"#9bd873"
],
[
0.25,
"#77ca6f"
],
[
0.27,
"#53bd6b"
],
[
0.3,
"#14aa60"
],
[
0.35,
"#009755"
],
[
0.4,
"#007e47"
],
[
0.5,
"#00673a"
],
[
0.6,
"#005530"
],
[
0.7,
"#004728"
],
[
1.0,
"#004728"
]
],
"type": "discrete",
"thresholds_type": "absolute",
"colors_quantity": 21
}
3. For getting RECI data you can useβ
"colormap": "fb5d32c26f571d52ea663a4a8f1e38e0"
"levels": "0,10"
{
"colors": [
[
0.0,
"#a50026"
],
[
0.5,
"#bc1626"
],
[
1.0,
"#d62f26"
],
[
1.5,
"#e54d34"
],
[
2.0,
"#f46d43"
],
[
2.5,
"#f88e52"
],
[
3.0,
"#fcac60"
],
[
3.5,
"#fdc675"
],
[
4.0,
"#fee08b"
],
[
4.5,
"#feefa5"
],
[
5.0,
"#fefebd"
],
[
5.5,
"#ecf7a5"
],
[
6.0,
"#d9ef8b"
],
[
6.5,
"#bfe37a"
],
[
7.0,
"#a4d869"
],
[
7.5,
"#84ca66"
],
[
8.0,
"#66bd63"
],
[
8.5,
"#3faa59"
],
[
9.0,
"#19974f"
],
[
9.5,
"#0c7e42"
],
[
10.0,
"#0c7e42"
]
],
"type": "discrete",
"thresholds_type": "absolute",
"colors_quantity": 21
}
5. For getting NDMI data you can useβ
"colormap": "a53f2c53d3cbc1d424c35ac8dc883644"
"levels": "0,1"
{
"colors": [
[
-1,
"#af998c"
],
[
-0.9,
"#b49e95"
],
[
-0.8,
"#baa49e"
],
[
-0.7,
"#bfaaa8"
],
[
-0.6,
"#c5b0b2"
],
[
-0.5,
"#cbb6bc"
],
[
-0.4,
"#d0bbc5"
],
[
-0.3,
"#d6c1cf"
],
[
-0.2,
"#cbb9d2"
],
[
-0.1,
"#baadd3"
],
[
0,
"#a8a0d5"
],
[
0.1,
"#9894d6"
],
[
0.2,
"#8788d7"
],
[
0.3,
"#767bd8"
],
[
0.4,
"#646ed9"
],
[
0.5,
"#5362da"
],
[
0.6,
"#4356db"
],
[
0.7,
"#3249dc"
],
[
0.8,
"#213ddd"
],
[
0.9,
"#0f30de"
],
[
1,
"#0f30de"
]
],
"type": "discrete",
"thresholds_type": "absolute",
"colors_quantity": 21
}
Creating custom colormapβ
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:
- Hexadecimal string. Ex. : β#f33a67β.
- 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β:
Colormap mechanics explanationβ
Continuous colormap with specified RGB colors [0.0, β#ff0000β], [0.5, β#00ff00β], [1.0, β#0000ffβ]. It has 256 colors
Discrete colormap with the same RGB colors:
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.
Custom colormap with absolute thresholds like [0, β#ff9900β, 0.06, β#ffcc00β, β¦., 1, β#336600β] is applied as follows:
The color is applied to pixels with the value from threshold-color pair and to all pixels with a value higher than specified up to the next specified threshold and color value, i.e. [0.52, β#ff0000β, 0.7, β#ffffffβ] - the #ff0000 color is applied to all pixels in range 0.52 (including) - 0.7 (excluding).
Π‘olors on the edges (first and last threshold-color pairs) are applied to all pixels with values outside the ranges specified by colormap - the color from the first pair with the lowest threshold value is applied to all pixels with values below the specified one. Likewise, the color from the last pair, with the highest specified threshold, is applied to all pixels with values above that threshold.
For colormap [0, β#ff9900β, 0.06, β#ffcc00β, 0.1, β#ffff66β, 0.2, β#ffff99β, 0.52, β#ff0000β, 0.7, β#ffffffβ, 1, β#336600β] color #ff9900 will be applied not only to pixel values in range 0 - 0.06, but also to those below 0. The color #336600 will be applied to all pixel values from 1 and higher. This is relevant for indices that have values outside the range -1..1, i.e. RECI.
If you want to create your own colormap, than the following API can be used:
HTTP Requestβ
POST 'https://api-connect.eos.com/api/render/colormap/?api_key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"colors": [[number, "color Hex Code"],
[number, "color Hex Code"],
.........................,
[number, "color Hex Code"]],
"type": "colormap_type"
}'
Request Parametersβ
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
| Request Body Parameter | Description |
|---|---|
| colors | (required) list of colormap colors |
| type | (optional) colormap type [discrete or continuous], by default - continuous |
| thresholds_type | (optional) 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 |
HTTP Responseβ
The above request returns the following JSON with the colormap ID
{"id": "color identifier"}
Examplesβ
Request
curl --location --request POST 'https://api-connect.eos.com/api/render/colormap/?api_key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"colors": [[0.0, "#ff0000"],
[0.1, "#00ff00"],
[0.9, "#ff00ff"],
[1.0, "#0000ff"]],
"type": "continuous"
}'
Response
{"id": "435c34ac345084527cc712e382d8c082"}
Get information about colormapβ
HTTP Requestβ
GET 'https://api-connect.eos.com/api/render/colormap/<colormap_id>?api_key=<your_api_key>'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
| colormap_id | (Required) colormap ID |
HTTP Responseβ
{
"colors": [
[
0.0,
"#ff0000"
],
[
0.1,
"#00ff00"
],
[
0.9,
"#ff00ff"
],
[
1.0,
"#0000ff"
]
],
"type": "continuous",
"thresholds_type": "relative",
"colors_quantity": 4
}
Response parametersβ
| Parameter | Description |
|---|---|
| colors | list of colormap colors |
| type | colormap type |
| thresholds_type | indicates of thresholds type |
| colors_quantity | number of using colors |
Examplesβ
request
curl --location --request GET 'https://api-connect.eos.com/api/render/colormap/435c34ac345084527cc712e382d8c082?api_key=<your_api_key>'
Response
{
"colors": [
[
0.0,
"#ff0000"
],
[
0.1,
"#00ff00"
],
[
0.9,
"#ff00ff"
],
[
1.0,
"#0000ff"
]
],
"type": "continuous",
"thresholds_type": "relative",
"colors_quantity": 4
}
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 digits, separated by commas without spaces. Have to contain 1 less value than COLORS. Ex.: β0.07,0.1β. THRESHOLDS must be specified in ascending order, from the lowest to the highest value. Ex.: β-0.48,-0.36,-0.24,-0.12β.
Range colorization is used as default for NDVI, NDSI, NDWI.
Usage exampleβ
Range colorization at Imagery APIβ
curl -i -X POST 'https://api-connect.eos.com/api/gdw/api?api_key=<your_api_key>' \
-H "Content-Type:application/json" \
-d \
'{
"type":"jpeg",
"params":{
"view_id":"S2/35/U/QR/2019/10/30/0",
"cropper_ref":"da2b157e9ab359f9d55ef7db38c8b7d2",
"bm_type":"(NIR-RED)/(NIR+RED)",
"name_alias":"ndre",
"reference":"21077010",
"px_size":5,
"calibrate":1,
"colors":[
"B40030",
"B00015",
"AC0500",
"A81F00",
"A43700",
"A04E00",
"9C6400",
"987900",
"948C00",
"819000",
"688C00",
"508800",
"3A8400",
"248000",
"107C00",
"007802",
"007413",
"007024",
"006C33",
"006842"
],
"thresholds":[
0.05,
0.11,
0.16,
0.2,
0.26,
0.32,
0.37,
0.42,
0.47,
0.53,
0.58,
0.63,
0.68,
0.74,
0.79,
0.84,
0.89,
0.95,
1
],
"format":"tiff"
}
}'