Classification Area (cl_stats)

The API allows you to calculate the area (m2) that belongs to a particular class inside of an ​​the area of interest (AOI). The user sets the AOI, the spectral index for the analysis and the threshold values ​​of the classes. For example, for a selected area of ​​interest (AOI), you can find out the area of ​​the flooded lands, the area of the forests damaged by wildfire etc by providing the range of values of the spectral index that outlines those conditions.

Example request

Example. NDVI for Sentinel-2:

{
    "type": "cl_stats",
    "params": {
            "bm_type": "ndvi",
            "scene_id": "S2-14-S-PC-2018-11-16-0",
            "bbox": [-96.84478282928468, 33.450671759652316, -96.82169437408447, 33.47798810260578],
            "thresholds": [[-1, 0], [0.05, 0.3], [0.3, 1]],
            "reference": "ref_1539359837"
    }
}
param type:(required) Operation name. Value is ‘mt_stats’.
param params:(required) Request parameters.
param params.bm_type:
 (required) Band math expression based on which the statistics are computed. Exactly one expression has to be specified.
param params.scene_id:
 (required) Scene id in (“L8-LC80110312016028LGN00”, “S2-19-T-CG-2017-7-9-0”, “MODIS-12-04-2017204-2017213034223” etc).
param params.bbox:
 (optional, either bbox or geometry must be set) Bounding box in EPSG:4326; order: westing, southing, easting, northing (i.e. minx, miny, maxx, maxy). If neither geometry nor bbox were provided, then process a full scene.
param params.geometry:
 (optional, either bbox or geometry must be set) A GeoJSON representation of a geometry describing the AOI. Supported geometry types: “Polygon”, “MultiPolygon”. If neither geometry nor bbox were provided, then process a full scene.
param params.cropper_ref:
 (optional) A resource id of a GeoJSON representation of a geometry saved into data base using API cropper
param params.reference:
 (optional) Unique id to assign to the request.
param params.thresholds:
 (optional; either threshold ot clustering_ref must be specified) This fields describes the edges of the classes. Format:[[float_min, float_max],…,[float_min, float_max]]. The first element of the range must be less than or equal to the second. All but the last (righthand-most) bin is half-open. In other words, if bins is: [1, 2, 3, 4], then the first bin is [1, 2) (including 1, but excluding 2) and the second [2, 3). The last bin, however, is [3, 4], which includes 4.
param params.clustering_ref:
 (optional; either threshold ot clustering_ref must be specified) Identificator of clustering options saved via clustering_options API. Set clustering_ref to calculate statistics over clustering layer. Note: if no AOI provided, then stats shall be calculated for the area defined when saving clustering options. AOI should lay within the area defined when saving clustering options.
param params.exclude_cover_pixels:
 (optional; boolean; only for Sentinel-2) enable/disable cloud masking using MSK_CLOUDS_B00.gml for statistics calculation; for details refer to Cloud Masking Options; by default - false
param params.cloud_masking_level:
 (optional; integer; only for Sentinel-2) enable advanced cloud masking for Sentinel-2 using SCL band of product L2A. Valid values: 1 (high probability clouds), 2 (medium + high probability clouds), 3 (medium + high probability + thin cirrus clouds). For details refer to Cloud Masking Options; by default - null (advanced cloud masking is disabled)
param change_detection_with:
 (optional) Scene id of a scene to calculate change detection with. If set, then areas shall be calculated upon the change detection layer.

Example response

Example on NDVI for Landsat 8:

{
    "task_type": "finish",
    "reference": "ref_1539359837",
    "token": "d5d9ffc3525bfecd63fd8fd097888a575597ebd9",
    "result_url": null,
    "result": [{
            "edges": [-1, 0],
            "area": 9600.0
    }, {
            "edges": [0.05, 0.3],
            "area": 1613600.0
    }, {
            "edges": [0.3, 1],
            "area": 4878000.0
    }],
    "client_id": 24,
    "type": "mt_stats",
    "hash_id": null
}
param type:Operation name. Value is ‘cl_stats’
param reference:
 Unique id to assign to the request
param token:User’s AUTH token
param result_url:
 null
param result:Area of each class presented in params.thresholds in units of the scene’s coordinate system. Format: [{“area”: float_class_area, “edges”: [float_min, float_max]}]
param client_id:
 User’s AUTH id
param task_type:
 “finish”
param hash_id:null

Example request - Clustering Layer

Example. Clustering of NDVI for Sentinel-2:

Request:

{
    "type": "cl_stats",
    "params": {
            "bm_type": "ndvi",
            "scene_id": "S2-14-S-PC-2018-11-16-0",
        "clustering_ref": "a44108be3d8b800ef6f7425ebd7f5dcc",
            "bbox": [-96.84478282928468, 33.450671759652316, -96.82169437408447, 33.47798810260578],
            "reference": "ref_1539359837"
    }
}

Response:

{
    "download_id": 24,
    "task_id": "e93c715b-62b8-471a-86db-39b2f754e816",
    "reference": "ref_1539359837",
    "token": "xxxxxxxxxxxxxxx",
    "result_url": null,
    "result": [{
        "class": 1,
        "color": "#a50026",
        "area": 5678608.52
    }, {
        "class": 2,
        "color": "#fef7b2",
        "area": 839301.97
    }, {
        "class": 3,
        "color": "#0c7f43",
        "area": 0.0
    }],
    "client_id": 24,
    "type": "cl_stats",
    "task_type": "finish",
    "hash_id": null
}
param type:Operation name. Value is ‘cl_stats’
param reference:
 Unique id to assign to the request
param token:User’s AUTH token
param result_url:
 null
param result:Area of each class presented in clustering layer in m2. Format: [{“area”: float_class_area, “class”: int, “color”: hex_color}]
param client_id:
 User’s AUTH id
param download_id:
 User’s AUTH id
param task_type:
 “finish”
param hash_id:null
param task_id:task id

Example request - Difference Layer

Example. Difference of default index for Sentinel-2:

For default indices (“ndvi”, “ndwi” etc) thresholds are optional. If no thresholds provided, then the default one shall be used. In case the default thresholds are used, response shall contain additional fields - color and label

Request:

{
        "type": "cl_stats",
            "params": {
                    "bm_type": "ndvi",
                    "scene_id": "S2-14-S-QE-2018-12-28-0",
                    "change_detection_with": "S2-14-S-QE-2018-12-23-0",
                    "geometry": {
                            "type": "Polygon",
                            "coordinates": [
                                    [
                                            [-96.223755, 35.666222],
                                            [-96.157837, 35.706377],
                                            [-96.17981, 35.874585],
                                            [-96.010895, 35.781057],
                                            [-95.789795, 35.824494],
                                            [-95.932617, 35.705262],
                                            [-95.800781, 35.612651],
                                            [-96.002655, 35.619349],
                                            [-96.086426, 35.465144],
                                            [-96.133118, 35.620466],
                                            [-96.345978, 35.598136],
                                            [-96.223755, 35.666222]
                                    ]
                            ]
                    },
                    "reference": "test_cl_stats"
            }
}

Response:

{
        "download_id": 24,
        "task_id": "05c82128-a14b-4897-9152-22428463735b",
        "reference": "test_cl_stats",
        "token": "404ddfb8cdd1aff0393ad6385407986694e929b6",
        "result_url": null,
        "result": [{
            "color": "#a50026",
            "edges": ["min", -0.48],
            "label": "----",
            "area": 18000.0
        }, {
            "color": "#f7864e",
            "edges": [-0.48, -0.36],
            "label": "---",
            "area": 107200.0
        }, {
            "color": "#fef7b4",
            "edges": [-0.36, -0.24],
            "label": "--",
            "area": 762800.0
        }, {
            "color": "#9dd569",
            "edges": [-0.24, -0.12],
            "label": "-",
            "area": 4876800.0
        }, {
            "color": "#0c7f43",
            "edges": [-0.12, "max"],
            "label": "neutral",
            "area": 752780400.0
        }],
        "client_id": 24,
        "type": "cl_stats",
        "task_type": "finish",
        "hash_id": null
}

Example. Difference of custom index for Sentinel-2:

Request:

{
        "type": "cl_stats",
            "params": {
                    "bm_type": "ndvi-0.5",
                    "scene_id": "S2-14-S-QE-2018-12-28-0",
                    "change_detection_with": "S2-14-S-QE-2018-12-23-0",
                    "geometry": {
                            "type": "Polygon",
                            "coordinates": [
                                    [
                                            [-96.223755, 35.666222],
                                            [-96.157837, 35.706377],
                                            [-96.17981, 35.874585],
                                            [-96.010895, 35.781057],
                                            [-95.789795, 35.824494],
                                            [-95.932617, 35.705262],
                                            [-95.800781, 35.612651],
                                            [-96.002655, 35.619349],
                                            [-96.086426, 35.465144],
                                            [-96.133118, 35.620466],
                                            [-96.345978, 35.598136],
                                            [-96.223755, 35.666222]
                                    ]
                            ]
                    },
                    "thresholds": [[-0.2, -0.1], [-0.1, 0.0], [0.0, 0.1], [0.1, 0.2]],
                    "reference": "test_cl_stats"
            }
}

Response:

{
    "download_id": 24,
    "task_id": "f638c33d-6b75-486a-9c63-4774c6d1dc98",
    "reference": "test_cl_stats",
    "token": "404ddfb8cdd1aff0393ad6385407986694e929b6",
    "result_url": null,
    "result": [{
        "edges": [-0.2, -0.1],
        "area": 10937600.0
    }, {
        "edges": [-0.1, 0],
        "area": 292799200.0
    }, {
        "edges": [0, 0.1],
        "area": 408756000.0
    }, {
        "edges": [0.1, 0.2],
        "area": 36519200.0
    }],
    "client_id": 24,
    "type": "cl_stats",
    "task_type": "finish",
    "hash_id": null
}
param type:Operation name. Value is ‘cl_stats’
param reference:
 Unique id to assign to the request
param token:User’s AUTH token
param result_url:
 null
param result:Area of each class presented in difference layer in m2. Format: [{“area”: float_class_area, “label”: str, “color”: hex_color, “edges”: [[float_min, float_max]]}]
param client_id:
 User’s AUTH id
param download_id:
 User’s AUTH id
param task_type:
 “finish”
param hash_id:null
param task_id:task id

Cloud Masking Options

There is an option to exclude cloud pixels during statistics calculation for Sentinel-2 via parameters exclude_cover_pixels and cloud_masking_level (see Classification Area (cl_stats)).

When exclude_cover_pixels option is enabled, then cloud masks are used, which are provided along with Sentinel-2 L1C product hosted on AWS S3. Example: https://sentinel-s2-l1c.s3.eu-central-1.amazonaws.com/tiles/13/T/GE/2018/7/20/0/qi/MSK_CLOUDS_B00.gml These masks feature two types of clouds: “OPAQUE” and “CIRRUS”. Only “OPAQUE” clouds are masked in statistics calculation.

When cloud_masking_level option is enabled, then cloud masks are built from SCL band of Sentinel-2 L2A if L2A product is available. For documentation on SCL band please refer to Classification Mask Generation. Possible values of cloud_masking_level:

1 - mask high probability clouds

2 - mask medium + high probability clouds

3 - mask medium + high probability + thin cirrus clouds

The best results are achieved when combining both SCL and GML cloud masks during statistics calculation.

Example. Cloud masking with both GML and SCL

Request:
{
    "type":"cl_stats",
    "params":{
        "bm_type":"ndvi",
        "scene_id":"S2L2A-14-S-PC-2018-12-31-0",
        "bbox":[
            -96.84478282928468,
            33.450671759652316,
            -96.82169437408447,
            33.47798810260578
        ],
        "thresholds":[[-1, 0], [0.05, 0.3], [0.3, 1]],
        "cloud_masking_level":3,
        "exclude_cover_pixels":true,
        "reference":"ref_1539359837"
    }
}
Response:
{
    "download_id": 24,
    "task_id": "bf8436cc-b861-45a5-8513-55c379ce7fde",
    "reference": "test_cl_stats",
    "token": "404ddfb8cdd1aff0393ad6385407986694e929b6",
    "result_url": null,
    "result": [
        {
            "edges":[-1, 0],
            "area":2400.0
        },
        {
            "edges":[0.05, 0.3],
            "area":12800.0
        },
        {
            "edges":[0.3, 1],
            "area":76800.0
        },
        {
            "cloud":6518400.0
        }
    ],
    "client_id": 24,
    "type": "cl_stats",
    "task_type": "finish",
    "hash_id": null
}

To result added { “cloud”: 6518400.0 } as last element of list. It is area of cloud pixels in sq. m.