Skip to content

FilterVectorize service specifications


icon


Service Description

The Filter and Vectorize Discrete Raster (FilterVectorize) is an asset based service that provides the options to Filter and/or Vectorize a discrete raster. The service can be used for post-processing the products obtained from an on-demand service to remove isolated pixels, or noise, from the classification output. Typical post-classification workflow consists of filtering a classified raster (e.g. a binary mask from a change detection service) for the purpose to make the classified raster smoother and simplify its conversion to polygon vector.

cover

Figure 1 - K-Means unsupervised classification (3 class) from dual pol Sentinel-1 GRD calibrated data acquired over Lokoja, Nigeria during the Oct 2022 flood event. Results after spatial filtering and conversion to vector.

The service has 3 possible execution modes:

  1. Filter: applies only a spatial filter of input classified raster

  2. Vectorize: converts only to vector the input classified raster

  3. Filter and Vectorize: employs first spatial filtering on input classified raster and later does the conversion of the filtered raster into vector.

Input of the FilterVectorize is a classified single band raster. Service output depends on the execution mode and is made of filtered discrete raster and or a polygon vector.

Filter

Filter employs the Sieve algorithm to filter clusters of pixels having size smaller than a provided threshold (size as number of pixels) and replaces them with the pixel value of the largest neighbour polygon. The Sieve spatial filter is often used to simplify a classified image having a large amount of small areas. When filtering a classified image (e.g. unsupervised classified map from K-means or a binary change mask from CVA) the Sieve filter removes isolated classified pixels using blob grouping and keeps only clusters of contiguous pixels above the minimal area unit. The spatial filtering of input raster is built with the GDAL Sieve utility1.

CLASSIFIED IMAGE BEFORE FILTERING

Figure 01

Figure 2 - Classified raster from the K-means Unsupervised classifier (K-Means) service using a pair of dual-pol Sentinel-1 GRD calibrated datasets.

CLASSIFIED IMAGE AFTER FILTERING

Figure 02

Figure 3 - Filtered K-Means classified raster using the Sieve spatial filter with a size threshold of 10 pixels.

Vectorize

Vectorize creates vector polygons for all connected regions of pixels in the raster sharing a common pixel value. Vector polygons are made by grouping adjoining pixels that were assigned to a feature or a class in the classified raster. The service allows the user to select the discrete raster values to be polygonized. This step is based on the GDAL Polygonize utility2.

Warning

Avoid converting noisy or large rasters with Vectorize. When possible, subset your classified image into a smaller AOI or employ a sufficient spatial filtering on it. A conversion of a large or noisy raster may result into a very large vector file (tens or hundreds of Mb) which is difficult to be handled inside or outside the platform (e.g. in a GIS software).

Note

This service can be used only with classified rasters (with a limited number of pixel values).

Figure 01

Figure 4 - Polygon vector derived from a binary change mask obtained with the Change Vector Analysis (CVA) service.

Shape and size of the resulting polygons depends on the pixel size of the input raster.

Note

If you scale a raster feature with a zoom out in the map, it will lose quality and look more blurry/pixilated since an interpolation method (nearest neighbour, average, etc.) is employed. Instead, a vector feature can be scaled to any size without losing quality and thus always printed out in the map clearly.

Warning

A maximum and minimum zoom level is set when visualizing a vector feature in the map.

Input

Input of the FilterVectorize is a single band asset representing a classified raster (e.g. unsupervised classified map from K-means or a binary map from HOTSPOT, CVA, IRIS, IRMAD or HASARD Single or Dual Image).

Parameters

The FilterVectorize service requires a specified number of mandatory and optional parameters. The list of service parameters are listed in the table below.

Parameter Description Required Default value
Input discrete raster Input product reference to discrete single band asset (e.g. a binary change mask or a classification map) YES
Service mode The service has 3 possible modes: Filter, Vectorize, Filter and Vectorize. YES Filter
Filter threshold Filter out from raster clusters of pixels smaller than a provided threshold. Threshold as cluster size in pixels (e.g. 10 means filtering clusters made of up to 10 pixels). Only for "Filter" or "Filter and Vectorize" modes. YES*
Raster discrete values list to vectorize Insert here a single (e.g. 1) or a list (1,2) of DN values to vectorize NO

Table 1 - Service parameters for the FilterVectorize processor.

Warning

The Filter threshold parameter is mandatory only for Filter and Filter and Vectorize modes. To be left blank in the Vectorize mode.

Input discrete raster

Product reference to the input single-band asset. This asset must come from discrete data (e.g. a raster representing a classified image map into classes). Examples of input single-band assets are unsupervised classified maps from K-Means or binary maps from HOTSPOT, CVA, HASARD Dual Image, HASARD Single Image, IRIS, IRMAD, or S2-Cloudless. It represents the source raster file from which polygons are derived. Being the service conceived to work only with single-band assets, the first band is used to build the polygons from.

Discrete rasters are either binary mask or classification images with discrete DN values (e.g. 0,1,2,3). Currently this type of raster is offered in the ESA Charter Mapper as single-band assets for:

  • cloud masks 0=no-clouds, 1=clouds (CLM binary mask from S2-Cloudless),

  • binary change maps 0=no-change, 1=change (CVA, HASARD, HOTSPOT, IRIS, IRMAD),

  • classification maps into N classes 0=class_1, 1=class_2, 2=class_3, etc. (K-Means).

Thus admitted inputs are only certain single band asset as the ones listed below:

  • cva_change_detection asset from CVA service (more details here),

  • flood-mask asset from HASARD Dual Image service (more details here),

  • hotspot asset from HOTSPOT service (more details here),

  • Kmeans_unsupervised_classifier asset from K-means service (more details here),

  • iris-change-mask asset from IRIS service (more details here),

  • irmad_change_detection asset from IRMAD service (more details here),

  • s2cloudless_clm asset from S2-Cloudless service (more details here).

Service mode

In this mandatory parameter the user shall select one of the 3 possible execution modes: Filter, Vectorize, Filter and Vectorize.

Image-001

Filter threshold

In this parameter the user shall specify a threshold size in pixels (e.g. 10 pixels) to be used in the Sieve Spatial Filtering. As an example 10 means filtering clusters of pixels having size up to 10 pixels.

  • Minimum value: 0 -> raster is not filtered at all.

  • Default: 10 -> reasonable value

  • Maximum: N -> there is not a maximum. The higher the number is the bigger is the aggregated number of class clusters

Note

Threshold value shall be a positive integer number.

Warning

Only for Filter or Filter and Vectorize modes.

Raster discrete values list to vectorize (optional)

With this last optional parameter the user can define what are the DN values to be considered when converting the raster to vector. Such values shall be inserted as a list of comma-separaed positive integers (e.g. 1,2 to have only these raster DNs converted to polygons).

Note

Inserted Values shall be >= the minimum and <= the maximum of single band asset values.

Warning

Only for Vectorize or Filter and Vectorize modes.

Outputs

According to the chosen execution mode, the FilterVectorize processor can provide as output the following products:

  • In the Filter mode the output is a STAC Item with a single band asset representing the filtered raster in COG format.

  • In the Vectorize mode the output is the converted polygon vector in GeoJSON (.json)3 and FlatGeoBuf (.fgb)4 formats.

  • In Filter and Vectorize mode the service generates both raster and vector outputs.

FilterVectorize Product Specifications can be found in the below tables.

Attribute Value / description
Description Filtered classified raster
File Name filtered
Geospatial Data Type Raster
Data Type Native (e.g. 8bit)
Band 1
Format COG
Projection Native
Fill Value Native (e.g. 0 for binary mask)
Attribute Value / description
Description Polygon vector converted from input filtered or not filtered single band classified raster
Short Name result
Geospatial Data Type Vector
Vector Data Type Polygon
Feature properties DN values of source raster
Format GeoJson, FlatGeoBuf
Projection EPSG:3857 - WGS 84 / Pseudo-Mercator

  1. GDAL Sieve Filter and its implementation in QGIS software, GDAL documentation, available at https://gdal.org and at https://docs.qgis.org

  2. GDAL Polygonize and its implementation in QGIS software, GDAL documentation, available at https://gdal.org and at https://docs.qgis.org

  3. GeoJSON, a format for encoding a variety of geographic data structures. Available at: https://geojson.org/

  4. FlatGeoBuf A performant binary encoding for geographic data based on flatbuffers that can hold a collection of Simple Features including circular interpolations as defined by SQL-MM Part 3. Available at: https://flatgeobuf.org/