Working with Statistics¶

Intro¶

Titiler allows you to get statistics and summaries of your data without having to load the entire dataset yourself. These statistics can be summaries of entire COG files, STAC items, or individual parts of the file, specified using GeoJSON.

Below, we will go over some of the statistical endpoints in Titiler - /info and /statistics.

(Note: these examples will be using the /cog endpoint, but everything is also available for /stac and /mosaicjson unless otherwise noted)

In [16]:

# setup
import httpx
import json

titiler_endpoint = (
    "https://titiler.xyz"  # Developmentseed Demo endpoint. Please be kind.
)
cog_url = "https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif"

# setup import httpx import json titiler_endpoint = ( "https://titiler.xyz" # Developmentseed Demo endpoint. Please be kind. ) cog_url = "https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif"

Info¶

The /info endpoint returns general metadata about the image/asset.

• Bounds
• CRS
• Band metadata, such as names of the bands and their descriptions
• Number of bands in the image
• Overview levels
• Image width and height

In [ ]:

r = httpx.get(
    f"{titiler_endpoint}/cog/info",
    params={
        "url": cog_url,
    },
).json()

print(json.dumps(r))

r = httpx.get( f"{titiler_endpoint}/cog/info", params={ "url": cog_url, }, ).json() print(json.dumps(r))

Statistics¶

For even more statistics of the image, you can use the /statistics endpoint. This includes even more info, including:

• Summary statistics about overall pixel values, such min, max, mean, and count
• Histogram of the pixel values
• Percentiles

Statistics are generated both for the image as a whole and for each band individually.

In [ ]:

r = httpx.get(
    f"{titiler_endpoint}/cog/statistics",
    params={
        "url": cog_url,
    },
).json()

print(json.dumps(r))

r = httpx.get( f"{titiler_endpoint}/cog/statistics", params={ "url": cog_url, }, ).json() print(json.dumps(r))

This endpoint is far more configurable than /info. You can specify which bands to analyse, how to generate the histogram, and pre-process the image.

For example, if you wanted to get the statistics of the VARI of the image you can use the expression parameter to conduct simple band math:

In [ ]:

r = httpx.get(
    f"{titiler_endpoint}/cog/statistics",
    params={
        "url": cog_url,
        "expression": "(b2-b1)/(b1+b2-b3)",  # expression for the VARI
        "histogram_range": "-1,1",
    },
).json()

print(json.dumps(r))

r = httpx.get( f"{titiler_endpoint}/cog/statistics", params={ "url": cog_url, "expression": "(b2-b1)/(b1+b2-b3)", # expression for the VARI "histogram_range": "-1,1", }, ).json() print(json.dumps(r))

Alternatively, if you would like to get statistics for only a certain area, you can specify an area via a feature or a feature collection.

(Note: this endpoint is not available in the mosaicjson endpoint, only /cog and /stac)

In [5]:

mahebourg = """
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "coordinates": [
          [
            [
              57.70358910197049,
              -20.384114558699935
            ],
            [
              57.68564920588395,
              -20.384114558699935
            ],
            [
              57.68209507552771,
              -20.39855066753664
            ],
            [
              57.68666467170024,
              -20.421074640746554
            ],
            [
              57.70341985766697,
              -20.434397129770545
            ],
            [
              57.72999121319131,
              -20.42392955694521
            ],
            [
              57.70358910197049,
              -20.384114558699935
            ]
          ]
        ],
        "type": "Polygon"
      }
    }
  ]
}
"""

mahebourg = """ { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": {}, "geometry": { "coordinates": [ [ [ 57.70358910197049, -20.384114558699935 ], [ 57.68564920588395, -20.384114558699935 ], [ 57.68209507552771, -20.39855066753664 ], [ 57.68666467170024, -20.421074640746554 ], [ 57.70341985766697, -20.434397129770545 ], [ 57.72999121319131, -20.42392955694521 ], [ 57.70358910197049, -20.384114558699935 ] ] ], "type": "Polygon" } } ] } """

In [ ]:

# NOTE: This is a POST request, unlike all other requests in this example
r = httpx.post(
    f"{titiler_endpoint}/cog/statistics",
    data=mahebourg,
    params={
        "url": cog_url,
        "max_size": 1024,
    },
    timeout=20,
).json()

print(json.dumps(r))

# NOTE: This is a POST request, unlike all other requests in this example r = httpx.post( f"{titiler_endpoint}/cog/statistics", data=mahebourg, params={ "url": cog_url, "max_size": 1024, }, timeout=20, ).json() print(json.dumps(r))

In [ ]: