Contrast Stretching. API Intensity Range

Contrast enhancement, sometimes called radiometric enhancement or histogram modification, is the most basic but also the most effective technique to optimise the image contrast and brightness for visualisation or to highlight information in particular DN ranges.

This section describes an API designed to calculate minimum and maximum intensity values of the input image, such that they can be used to enhance contrast of the image by means of min-max linear stretching.

API Intensity Range

Calculate intensity gange values for specified scene bands, complemented with cloud coverage value.

GET /(sensor)/ir/(scene_id)/(bands)
Parameters:
  • sensor – abbreviation for the name of the sensor (See Table of sensor name abbreviations)
  • scene_id – scene’s identificator. scene_id is constructed by removing the short-name-of-the-sensor prefix from the view_id returned by the Search API. Examples: “10/S/EG/2017/3/1/0”, “LE70420362017095EDC00”, “115/S1A_IW_GRDH_1SDV_20161201T141548_20161201T141617_014187_016EBB_F627” etc
  • bands – band combination expression
Query Parameters:
 
  • method – (optional) method to calculate min/max (‘mean’, ‘cc’, ‘minmax’, ‘histogram’). (Default: ‘cc’)
  • min – (optional) (only for method=cc) lower threshold. (Default: 2)
  • max – (optional) (only for method=cc) upper threshold. (Default: 98)
  • multi – (optional) (only for method=mean) std multiplier. (Default: 0)
  • cloud – (optional) enable cloud correction (1 - enable, 0 - disable). (Default: 1)
  • BBOX – (optional) extent in lat/lon; order: w, s, e, n. (Default: scene extent)
  • only_opaque_cloud – (optional) consider only opaque cloud when calculating the cloud cover (cloud=1): 1 - enable, 0 - disable. Takes no effect if cloud=0. (Defaults: 1 - Sentinel-2, 0 - other sensors)
  • cropper_ref – (optional) AOI reference from Cropper API; only image data that falls into AOI is included in the IR calculation. (See Cropper API)
  • api_key – (required) user’s API key

Examples

Landsat 8 - True Color

http

GET /api/render/L8/ir/LC80440342015304LGN00/B4,B3,B2?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/L8/ir/LC80440342015304LGN00/B4,B3,B2?api_key=XXX'

Sentinel-2 Custom Band Combination

http

GET /api/render/S2/ir/36/U/XU/2016/5/2/0/(B08-B04)/(B08+B04)?CALIBRATE=1&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/S2/ir/36/U/XU/2016/5/2/0/(B08-B04)/(B08+B04)?CALIBRATE=1&api_key=XXX'

MODIS

http

GET /api/render/MODIS/ir/08/05/2017067/2017076074010/B01,B04,B03?method=minmax&api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/MODIS/ir/08/05/2017067/2017076074010/B01,B04,B03?method=minmax&api_key=XXX'

Cloud Correction

Cloud correction is available only with cumulative cut method (method=cc). If cloud=1, then

\(max = max - cloudCover * 0.75\)

Sentinel-2

Cloud cover percent is calculated using MSK_CLOUDS_B00.gml stored by the provider on AWS. There are two types of clouds defined in these masks: cirrus and opaque. If only_opaque_cloud == 1, then only opaque clouds are considered when calculating the cloud cover, otherwise both opaque and cirrus clouds (i.e., cloud ∪ cirrus) are considered. Default is only_opaque_cloud = 1. If IR is requested for a full scene and only_opaque_cloud = 0, then cloud cover percent is taken from metadata (tileInfo.json, see cloudyPixelPercentage).

Landsat 8

Cloud cover percent is calculated using quality assessment band (BQA, see https://landsat.usgs.gov/qualityband). There are two types of cloud confidence defined in BQA: cirrus (bits 12 & 13) and cloud (bits 14 & 15). If only_opaque_cloud = 1, then only opaque clouds (i.e. {x ∈ cloud | x ∉ cirrus}) are considered when calculating the cloud cover, otherwise both opaque and cirrus clouds are considered (i.e., cloud ∪ cirrus). Default is only_opaque_cloud = 0. If IR is requested for a full scene and only_opaque_cloud = 0, then cloud cover percent is taken from metadata ({scene_id}_MTL.txt, see group = IMAGE_ATTRIBUTES / CLOUD_COVER).

Landsat 4, 5, 7

Cloud correction is avaliable for full scene only. Cloud cover percent is taken from metadata ({scene_id}_MTL.txt, see group = IMAGE_ATTRIBUTES / CLOUD_COVER).

MODIS

Clouds are already masked with NODATA.

CBERS4

Cloud masking is not supported.

NAIP

Cloud maskign is not supported.