Skip to content

Titiler widget

As specified on the Tile layers features section, the Geobrowser can show on the map all the features exposing tiled services, such as WMS and Titiler. This section briefly describes the Titiler service and illustrates the geobrowser widget taking advantage of Titiler API.

Intro on Titiler


Titiler, pronounced tee-tiler (ti is the diminutive version of the french petit which means small), is a lightweight application (FastAPI) focused on creating web map tiles dynamically from Cloud Optimized GeoTIFF, STAC or MosaicJSON.

Some Features:

  • Cloud Optimized GeoTIFF support;
  • SpatioTemporal Asset Catalog support;
  • Virtual mosaic support (via MosaicJSON);
  • Multiple projections (see TileMatrixSets) via morecantile;
  • JPEG / JP2 / PNG / WEBP / GTIFF / NumpyTile output format support;
  • OGC WMTS support;
  • Automatic OpenAPI documentation (FastAPI builtin);
  • Example of AWS Lambda / ECS deployment (via CDK).

For more info, see:

Titiler layer and Geobrowser

On the Geobrowser, a feature exposing a Titiler tiled layer is represented on the results panel with the "Earth icon". If visible the layer is displayed on the map like any raster layer.


Opening the feature details panel, an additional widget called "Titiler options" is shown in the feature's details, inside the colllapsible section "Layer styling".


From this widget users can manipulate the titiler api options to see the layer in different ways and styles. More precisely, users can:

  • choose one asset or select an assets combination;
  • set and expression or select a predefinite color map (for one asset)
  • set the histogram min and max value;
  • apply a formula for color representation;


By clicking on the "Apply" button all the options will be applied, and the layer will be directly updated on the map, storing the options for the current session.

STAC and assets concept

The visualization and the options of a Titiler layer is basing on the concept of Asset, defined on the STAC specification. The SpatioTemporal Asset Catalog (STAC) specification provides a common language to describe a range of geospatial information, so it can more easily be indexed and discovered. A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and time.

For more info, see:

Any feature containing a Titiler data has a set of assets (imagery, SAR, overviews, electro-optical reflectances, spectral indexes and so on); users can choose a single asset to view on the map, or a band-combination of three assets, mapped on the three RGB channel (Red, Green, Blue).

Single asset options

The single asset tab allow users to select one asset from the feature's available assets. If the asset is represented by a mono-band source, by default a grayscale image will be plotted.


There are 2 options:

  • Expression: a mathematical expression to combine more bands in one. For example, if we have these band [red, green, blue, nir] a possible expression could be (red-green)/nir.
  • Color map: a select input containing a predefinite set of color mapping functions, only for mono-band assets.

Assets combination options

The assets combination tab allow users to select three assets for the three RGB band and combine them. This tab doesn't have any option.


General options

Other useful options, common for both single asset or assets combination, are histogram min/max and color formula.

Histogram min/max

These two numerical inputs are used to define a range of minimum and maximum values of the digital number of the asset selected.

On the EO context, there are several types of assets, each of them has a predefinite corresponding scale, as described in Table 1.

type description Unit Bit depth Scaling factor Valid Range
overview RGBA color composite Unitless Uint8 1 [0,255]
reflectance TOA or BOA reflectance for VIS, RE and SWIR CBNs (e.g. blue, nir) Unitless Uint16 0.0001 [0,10000]
brightness temperature TOA or BOA brightness temperature for LWIR CBNs (e.g lwir11) K Uint16 0.01
spectral index Spectral index as normalized difference of multiple CBN (e.g. NDVI) Unitless Float32 1 [-1,1]
sigma nought Sigma nought for L-, C-, X-band SAR data in each polarization (e.g. sigma0-HH-db) dB Float32 1

Table 1 - Description, Unit, Bit depth, Scaling factors, and valid ranges for the multiple types of assets available in the ESA Charter Mapper.

Color formula

With the color formula, it's possible to apply basic color-oriented image operations to the titiler image layer. The syntax is based on the rio-color plugin for the Cloud Optimized GeoTIFF in TiTiler and is the following:

Gamma RGB 1 Saturation 1 Sigmoidal RGB 3 0.5

where \(Gamma\), \(Saturation\) and \(Sigmoidal\) are the parameters described in Table 2.

Color formula (rio-color color corrections)
Correction Parameter Type Description Default values
Gamma bands string Bands to which apply gamma correction. Use “RGB” for the three channels, “R” (or G, B) for single red-channel (or green-, blue-). RGB
proportion float Gamma correction is a nonlinear operation that adjusts the image's channel values pixel-by-pixel according to a power-law. A value of gamma greater/lower than 1.0 lightens/darkens the image. proportion=0 results in a grayscale image, proportion=1 results in an identical image, proportion=2 is likely way too saturated. Reasonable gamma values range from 0.8 to 2.4. 1
Sigmoidal bands string Bands to which apply sigmoidal correction. Use “RGB” for the three channels, “R” (or G, B) for single red-channel (or green-, blue-). RGB
contrast integer Enhances the intensity differences between the lighter and darker elements of the image. For example, contrast=0 is none, contrast=3 is typical and contrast=20 is a lot. 3
bias float [0,1] Threshold level for the contrast function to center on (typically centered at 0.5). bias>0.5 darkens the image. 0.5
Saturation value float It applies saturation to an RGB array (in LCH color space). Multiply saturation by proportion in LCH color space to adjust the intensity of color in the image. As saturation increases, colors appear more "pure." As saturation decreases, colors appear more "washed-out." 1

Table 2 - Default values for Color Formulas used for the generation of browse images in the PE (Credits: Rio-Color in GitHub). Such parameters are the ones available in the Rio Color color formula expression for COG in TiTiler.

For more information, see

Histogram visualization

A feature exposing a Titiler tiled layer can include a detailed histogram information for each asset, if available. The histogram provides the distribution of the pixel values. The space of pixel values is splitted in 256 buckets, and for each bucket is calculated the number of pixel inside of it. With these data is possible to plot an histogram, allowing the user to:

  • See the distribution of pixel values;
  • Get the exact amount of pixel inside a bucket range;
  • Set the histogram min/max value directly from a histogram interaction;
  • Perform an vertical cut (by considering only the 99% of buckets in ascending order) to better show the histogram with a vertical stretch;
  • Perform an horizontal cumulative cut ([2%-98%] of distribution), by a visual stretching of the histogram and by setting the right histogram min/max values.

If a single asset with single band is selected, only one histogram function is plotted.

In this example an histogram is shown for the nir08 asset (single asset with single band):


By hovering the mouse on the graph it's possible to check out the amount of pixel for each pixel value range, as shown on this example:


By dragging the range slider on the bottom of the graph it's possible to visually change histogram min/max values (it's always possible to manually change them from the min/max input fields):


Notice that when the histogram min/max is changed on the sliders, the changes are directly performed and the layer automatically updated, whereas users must click on the apply button if the min/max values are changed from the input fields.



Notice that to enable changing min and max values in each RGB channel of an overview the option "Use the same min/max value for all channels" shall not be checked.

For multiple assets (or single asset with multiple bands) there are 3 histogram functions plotted, for the three RGB channels. Users can see the values for each bucket range and for each asset/band.

In this image there is an example of plotting multiple RGB assets histogram.


For multiple assets is also possible to separately set the histogram min/max, for each asset. The histogram min/max can be set by visual dragging of the sliders or by manual editing min/max input fields:


As shown above, full color ranges could not be optimized for a better layer visualization. It's possible to perform an auto select of the min/max value by a 2%-98% cumulative count cut, by clicking on the relative button:


The same applies for the vertical stretching:


The reset button resets the graph view.


Notice that for multiple asset the histogram is plotted only if all three channels are selected.

Crop and export image

For titiler layers it is possible to select an area of the layer on the map and download it as a cropped image. Supported export formats are PNG, JPEG and GeoTIFF. The GeoTIFF format also contains spatial metadata, so it's possible to import the downloaded geoTiff directly on other GIS applications, like QGIS. The crop export maintains all the current visulisation settings applied to the image e.g. through the asset selection, histogram, color map and so on. It exports the portion of the image exactly as it is shown on the map. The crop export is limited in terms of resolution (max 2000px * 2000px).

From the relative feature's details panel users must click on the "Crop" button to export a crop from a titiler layer.


After clicking on the crop button a drawing interaction will be opened. Users can draw a rectangle around the layer to represent the area to export.


As shown above, a little modal dialog is open. It's possible to define the size of the output image and the format. Users can also redefine the drawn bounding box, to have a more precise crop area:


By clicking on the Download button the image will be downloaded (or opened in a new window, depending on the browser and on the selected format).