02CloudNative - Cloud-Native Data Studio
User manual for version 0.1.1 · QGIS 3.28 to 4.x · GPL-2.0-or-later · geophilo.com/zero2cloudnative · GitLab
1. Overview
02CloudNative carries one study through the cloud-native geodata chain inside QGIS: find (STAC catalogues, the Overture release catalogue), inspect and stream or clip (Cloud Optimized GeoTIFF checks, a byte budget, scale- and offset-correct band composites), store (GeoParquet 1.1 with a bbox covering), query (spatial SQL over layers, files and remote Parquet) and publish (vector PMTiles). Every output records its source URLs, release, licence and retrieval time. The work is available in a dock with seven pages and as thirteen Processing algorithms; both call the same core functions.
All bounding boxes sent to catalogues are WGS 84 longitude/latitude (EPSG:4326, axis order lon, lat). A map extent in any CRS is transformed with densified edges, so a projected rectangle maps to the smallest longitude/latitude box that contains it; boxes that cross the antimeridian are refused in this version. Areas used for size guards are spherical (eq. (1)), never the area of a box measured in degrees.
All HTTP goes through the QGIS network manager, so the proxy and authentication settings of QGIS apply. No API keys or accounts are needed.
2. Install and requirements
Install from Plugins > Manage and Install Plugins (search 02CloudNative) or from the release zip with Install from ZIP. GDAL features are probed when the plugin runs, never assumed from the QGIS version:
| Feature | Needs | When missing |
|---|---|---|
| GeoParquet read | OGR Parquet driver (GDAL 3.5+) | DuckDB engine if installed, else a message |
| GeoParquet write with bbox covering and spatial sort | Parquet driver with GDAL 3.9+ | written without the covering, with a log line |
| Overture extract, GDAL engine | Parquet driver and /vsicurl/ | DuckDB engine |
| PMTiles export | OGR PMTiles driver with create (GDAL 3.8+) | export disabled with the reason |
| Spatial SQL, DuckDB engine | Python package duckdb with the spatial extension | OGR SQLite dialect (SpatiaLite functions when GDAL has them) |
DuckDB is optional. On OSGeo4W install the package python3-duckdb; elsewhere install
the duckdb Python package into the Python that QGIS uses. Its extensions are downloaded
from extensions.duckdb.org on first use. The Environment page shows what your
install offers.
3. The studio, page by page
Open the studio with the toolbar button 02CloudNative studio or from the Plugins > 02CloudNative menu. The dock has an icon rail on the left; Help is pinned at the bottom. Long steps run as background tasks: the page shows a progress bar and a Cancel button and the dock stays responsive. Layers are added to a 02CloudNative group with one subgroup per page.
3.1 Catalog
- Catalogue. Earth Search (Element 84, public COGs on AWS), Microsoft Planetary Computer or a custom STAC API URL. Test requests the landing page and the conformance classes and reports the latency and whether the API declares the Filter (CQL2) or Query extension.
- Collection. Filled from
/collections. Collections that cannot be read anonymously are disabled with the reason in the tooltip: on Earth Search,landsat-c2-l2lives in the requester-pays bucketusgs-landsat(HTTP 403 without AWS credentials); use the Planetary Computer for Landsat. - Extent. Map canvas, a layer's extent or a rectangle drawn on the map.
- Filters. Date range, maximum cloud cover, maximum items, then Search.
The cloud filter is sent as a CQL2-JSON filter
({"op": "<=", "args": [{"property": "eo:cloud_cover"}, c]}) when the API declares the
Filter extension, as the Query extension ({"eo:cloud_cover": {"lte": c}}) otherwise, and
applied client-side when neither is declared. Paging follows the next links until the
maximum item count. Items are ordered by cloud cover ascending (items without a value last), then date
descending, then id ascending; this is also the mosaic order on the Imagery page.
KPI cards: items matched (when the API reports it), returned, median cloud cover, date span and the
spherical area of the search box (eq. (1)). Item cards show date, platform, the share of
the search box the item covers, a cloud gauge and a thumbnail loaded in the background; ticking a card
selects it for the Imagery page and highlights its footprint. The coverage is
for footprint and search box , with ellipsoidal areas on WGS 84
(QGIS QgsDistanceArea), never areas in square degrees; the footprints layer stores it in
cover_pct.
Try the offline demo (Catalogue card) writes two synthetic Sentinel-2-like scenes (red, green, blue and NIR COGs, EPSG:32635, 10 m, scale 0.0001, offset ) and an Overture-like building GeoParquet file into the session folder, lists the scenes as items, ticks the first and sets the GeoParquet path on the Parquet page. Nothing is downloaded; every later page works on these files.
3.2 Imagery
Choose a recipe (chips not available for the collection's bands are disabled):
| Recipe | Bands (STAC eo common names) | Notes |
|---|---|---|
| True colour | red, green, blue | |
| False colour (NIR) | nir, red, green | vegetation in red; Landsat publishes NIR as nir08, which stands in for nir when an item has no nir band |
| Agriculture (SWIR) | swir16, nir, blue | |
| Urban (SWIR) | swir22, swir16, red | |
| Elevation (DEM) | one band | Copernicus DEM; a hillshade layer is added on top |
| Single band | any asset | type or pick the asset |
Stream (VRT) writes a small VRT file whose bands point at the remote COGs through
/vsicurl/; QGIS reads only the tiles needed for the current view. Items of the same band are
mosaicked in the search order, so the less cloudy item is on top where items overlap. The
raster:bands scale and offset are written as VRT band scale and offset
(eq. (4)), so the stored data stay raw and identify tools show physical values.
Clip and save (COG) cuts the extent at an overview level and writes a local Cloud Optimized GeoTIFF
in the asset's CRS and pixel grid.
Check COG reads the header of every band asset of the recipe on the first item and lists the pass/warn/fail rows of the finest band (section 5.3), because the mosaic is built on the finest pixel grid (Sentinel-2: 10 m red, green, blue and nir; 20 m swir16 and swir22). It shows that output grid, the overview level chosen for the target resolution and the bytes a clip would read, summed over the bands (eq. (5), eq. (6)). The byte gauge compares that estimate with your limit (default 500 MB); a clip above the limit asks you to coarsen the resolution or shrink the extent. When the recipe, items, extent or target resolution changed after the last check, Load checks again before clipping, so the level and the limit always match what is written. Planetary Computer assets are signed with an anonymous SAS token per storage container, cached until five minutes before it expires.
A streamed Planetary Computer mosaic holds these tokens inside its VRT files, and they are valid for about an
hour; after that every tile read is refused (HTTP 403) and the layer stops drawing. The plugin therefore marks every
streamed Planetary Computer layer with the earliest token expiry (also VRTs written by the Processing algorithm and
layers of a project you open) and writes the expiry into the layer metadata, so it shows under Layer Properties
> Information and Metadata. While QGIS runs, a check once a minute re-signs a layer ten minutes before its tokens
expire: it fetches new tokens, writes the VRT files again as the next generation (mosaic.vrt,
mosaic.s1.vrt, mosaic.s2.vrt, ...) and points the layer at the new file, keeping its name,
style, metadata and properties. A new file name is needed because QGIS keeps a GDAL dataset open per path; earlier
generations stay in the folder, a few kilobytes each. To re-sign by hand, right-click the layer and choose
Re-sign Planetary Computer links, or press the button of the same name on this page. Automatic re-signing can be
switched off on the Environment page.
3.3 Overture
The release combo lists the releases of the Overture STAC catalogue
(https://stac.overturemaps.org/catalog.json) with the latest preselected. Tick the types to
download; each shows its geometry, licence and size guard:
| Type | Theme | Default columns | Size guard |
|---|---|---|---|
| building, building_part | buildings | id, names.primary, subtype, class, height, num_floors, min_height, roof_shape, is_underground, sources | |
| place | places | id, names.primary, categories.primary, confidence, websites, addresses, brand | |
| segment, connector | transportation | segment: id, subtype, class, names.primary, subclass, speed_limits; connector: id | |
| division, division_area, division_boundary | divisions | id, subtype, names.primary, country, region, admin_level, class | none |
The area gauge compares the spherical area of the extent (eq. (1)) with each type's guard; the download is refused before any request when a type is above it. The files of a type are selected by intersecting the extent with the per-file bboxes of the collection extent list, confirmed with each item's own bbox, and read with the bbox covering pushdown (GeoParquet 1.1; GDAL row-group statistics or DuckDB). An exact test then keeps a feature when its geometry intersects the extent, or, with the centroid rule, when its centroid falls in the half-open box (eq. (7)); the centroid rule assigns each feature to exactly one tile of a tiled download. Nested structs and lists are written as JSON text fields. Engines: GDAL (always available when GDAL has the Parquet driver), DuckDB, or Auto (DuckDB when installed). Outputs: memory layers, a GeoPackage or GeoParquet files. KPI cards give features, files read and seconds per type.
3.4 GeoParquet
Open takes a file or an https URL, shows an inspector card (GeoParquet version, primary geometry column, encoding, CRS, bbox, rows, row groups, covering yes/no, size) and opens the file as a layer, optionally only the features in the current map extent. Export writes any vector layer as GeoParquet 1.1 with a compression codec (ZSTD, Snappy, Gzip or none), a bbox covering column, a spatial sort by bbox and a row-group size; the written file is inspected afterwards.
3.5 SQL
The table list holds project layers, files (Parquet, GeoPackage, FlatGeobuf, GeoJSON) and, with DuckDB,
remote Overture views (s3://overturemaps-us-west-2/release/<release>/theme=<theme>/type=<type>/*).
The geometry column of every table is geom on both engines. The editor has a template menu:
| Template | What it does |
|---|---|
| count_by | row count per value of a column |
| points_in_polygons | points per polygon (spatial join with ST_Intersects) |
| area_length_by_class | area or length per class in a metric CRS (ST_Transform to the working UTM zone) |
| nearest | nearest feature of a second table |
| grid_count | counts on a square grid with floor(x / size) |
| profile | attribute profile (SUMMARIZE on DuckDB) |
Safe mode (on by default) runs only single statements that start with SELECT, WITH, EXPLAIN, DESCRIBE or
SUMMARIZE and contain no writing keyword (INSERT, UPDATE, DELETE, COPY, ATTACH, CREATE, DROP, INSTALL, LOAD, SET
and the like) outside string literals and quoted names; this also stops EXPLAIN ANALYZE COPY ... and
WITH ... INSERT, which DuckDB and SQLite would otherwise execute. Run executes in a background task; Cancel interrupts a DuckDB query at once and an OGR
query between result batches. The grid shows the first 200 rows; a result with a geometry column can be added as
a layer. Queries are kept in a per-project history.
3.6 PMTiles
Tick the layers to publish (each becomes a tile layer and can be renamed), set the zoom range and the
simplification, and read the tile plan: a bar per zoom with the number of Web Mercator tiles that cover the
layers' extent (eq. (2)). Export writes a PMTiles v3 archive of Mapbox Vector Tiles
through GDAL; the header card shows the spec version, tile type, zooms, bounds and tile counts read from the
written file's 127-byte header. Tiles are addressed by their Hilbert tile id (eq. (3)).
The attribution goes into the archive's JSON metadata (attribution, the key web maps display); left
empty, it takes the credit recorded on the source layers, for Overture layers
"© OpenStreetMap contributors, Overture Maps Foundation".
Add to map opens the archive as a vector layer.
3.7 Environment
The capability matrix lists GDAL, GeoParquet read and write, the bbox covering, the PMTiles writer, the COG driver, DuckDB and its spatial extension, each with a status dot. Check network requests each catalogue's conformance classes once and shows the latency. GDAL cache size and the HTTP timeout can be set here, and the GDAL cache cleared. Re-sign Planetary Computer links automatically (on by default) keeps streamed Planetary Computer layers readable after their tokens expire (section 3.2).
Cancel in the task strip stops a step at once, also in the middle of a request to a slow server: the request is aborted and no retry follows. Earlier results stay as they were.
3.8 Help
A short guide per page, the formats and specifications used, licence notes (Overture ODbL share-alike) and links to this manual and the repository.
4. Processing algorithms
The 02CloudNative provider in the Processing Toolbox has thirteen algorithms. Each algorithm calls the same core function as the matching dock page; outputs are not styled. File outputs get a .provenance.json sidecar. An extent parameter may be in any CRS; it is transformed to EPSG:4326 with densified edges.
Cloud-native study (full chain) zero2cloudnative:cloud_native_study
Group: 0 Full chain
Runs the whole chain for one extent and writes every output to one folder: STAC search (skipped when the collection is empty) with footprints in footprints.gpkg; COG checks and a VRT composite of the best items; one Overture type (size guard first) in overture.gpkg; the features as GeoParquet; spatial SQL counting the features per footprint (or in total) in sql_counts.csv; a PMTiles archive of the features; and report.html, a self-contained report with the KPIs, the COG checks, the outputs with their provenance and the formulas used.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
EXTENT | Study extent | extent | Required. |
CATALOG | STAC catalogue | enum | Earth Search (default), Microsoft Planetary Computer, or Custom STAC API URL. |
CUSTOM_URL | Custom STAC API URL | string | Used when the catalogue is Custom; must start with https://. |
COLLECTION | Collection id | string | Default sentinel-2-c1-l2a. |
START | Start date | string | YYYY-MM-DD; empty = open start. |
END | End date | string | YYYY-MM-DD; empty = open end (end of day). |
MAX_CLOUD | Maximum cloud cover | number | Percent, default 20; 100 sends no cloud filter. |
MAX_ITEMS | Maximum items | integer | Hard cap across pages, default 100. |
SORT | Order (advanced) | enum | Cloud ascending then newest (default), or newest first. |
ITEMS | Items in the mosaic | integer | Best N items, default 1. |
RECIPE | Band recipe | enum | True colour (default), false colour NIR, agriculture, urban, DEM. |
TYPE | Overture feature type | enum | building (default) or any type of table 3.3. |
RELEASE | Overture release | string | Empty = latest. |
ENGINE | Overture engine | enum | Auto, GDAL, DuckDB. |
FILE | Local Overture GeoParquet file | file | Optional; skips the catalogue. |
MINZOOM / MAXZOOM | PMTiles zooms | integer | Default 12 and 15. |
OUTPUT_FOLDER | Output folder | folder | Receives every file. |
FEATURES | Overture features | feature sink | The extracted features. |
| Output | Meaning |
|---|---|
REPORT, RASTER, PARQUET, PMTILES, FOOTPRINTS, SQL_CSV | Paths of the files written (empty when a stage was skipped). |
ITEMS_FOUND, FEATURE_COUNT, ADDRESSED_TILES | STAC items returned, Overture features, PMTiles addressed tiles. |
STAC search zero2cloudnative:stac_search
Group: 1 Catalog
Item Search for one collection over an extent, a date range and a cloud limit, with the filter strategy of section 3.1. The output footprints (EPSG:4326) carry id, collection, datetime, cloud, platform, epsg, catalog and rank (mosaic order).
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
EXTENT | Search extent | extent | Required. |
CATALOG | STAC catalogue | enum | Earth Search (default), Microsoft Planetary Computer, or Custom STAC API URL. |
CUSTOM_URL | Custom STAC API URL | string | Used when the catalogue is Custom; must start with https://. |
COLLECTION | Collection id | string | Default sentinel-2-c1-l2a. |
START | Start date | string | YYYY-MM-DD; empty = open start. |
END | End date | string | YYYY-MM-DD; empty = open end (end of day). |
MAX_CLOUD | Maximum cloud cover | number | Percent, default 20; 100 sends no cloud filter. |
MAX_ITEMS | Maximum items | integer | Hard cap across pages, default 100. |
SORT | Order (advanced) | enum | Cloud ascending then newest (default), or newest first. |
OUTPUT | STAC footprints | feature sink | Polygons. |
| Output | Meaning |
|---|---|
MATCHED | Items matched (-1 when the API does not report it). |
RETURNED | Items returned. |
MEDIAN_CLOUD | Median cloud cover of the returned items (%). |
AREA_KM2 | Spherical area of the search box, eq. (1). |
REQUESTS | Requests sent. |
STRATEGY | cql2, query or client. |
STAC composite (stream or clip) zero2cloudnative:stac_composite
Group: 2 Imagery
Searches like STAC search, takes the first N items in mosaic order and builds the recipe's band composite as a VRT (stream) or a clipped COG. Before any download the first band asset is inspected and the clip's bytes are estimated (eq. (6)); a clip above the byte budget stops with a message.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
EXTENT | Extent | extent | Required; the clip extent in clip mode. |
CATALOG | STAC catalogue | enum | Earth Search (default), Microsoft Planetary Computer, or Custom STAC API URL. |
CUSTOM_URL | Custom STAC API URL | string | Used when the catalogue is Custom; must start with https://. |
COLLECTION | Collection id | string | Default sentinel-2-c1-l2a. |
START | Start date | string | YYYY-MM-DD; empty = open start. |
END | End date | string | YYYY-MM-DD; empty = open end (end of day). |
MAX_CLOUD | Maximum cloud cover | number | Percent, default 20; 100 sends no cloud filter. |
MAX_ITEMS | Maximum items | integer | Hard cap across pages, default 100. |
SORT | Order (advanced) | enum | Cloud ascending then newest (default), or newest first. |
ITEMS | Items in the mosaic | integer | Default 1. |
RECIPE | Band recipe | enum | See table 3.2. |
BAND | Band for the single-band recipe | string | Asset key or common name. |
MODE | Mode | enum | Stream (VRT, default) or clip and save (COG). |
RESOLUTION | Target resolution | number | In the raster CRS units; 0 = full resolution. |
BUDGET_MB | Byte budget for a clip | number | Default 500 MB. |
OUTPUT | Composite | file | .vrt for stream, .tif for clip. |
| Output | Meaning |
|---|---|
OUTPUT | Path of the VRT or COG. |
LEVEL | Overview level used (0 = full resolution). |
BYTES | Estimated bytes read (upper bound). |
ITEMS_USED | Items in the mosaic. |
Inspect a Cloud Optimized GeoTIFF zero2cloudnative:cog_inspect
Group: 2 Imagery
The checks of section 5.3 on a raster layer, a local path, an https URL or an s3:// URL (read through /vsicurl/). Only the header is read. With an extent it also returns the tiles and bytes of the window that covers it (eq. (5), eq. (6)).
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
RASTER | Raster layer | raster | Optional. |
SOURCE | Raster path or URL | string | Overrides the layer. |
EXTENT | Window extent | extent | Optional; for the byte estimate. |
RESOLUTION | Target resolution | number | 0 = full resolution. |
OUTPUT | COG checks | table sink | check, result (pass/warn/fail), detail. |
| Output | Meaning |
|---|---|
IS_COG | 1 when GDAL reports the COG layout or the checks pass. |
WIDTH, HEIGHT, BANDS | Size. |
OVERVIEWS | Overview levels. |
FAILS | Failed checks. |
LEVEL | Overview level for the resolution. |
TILES, BYTES | Window cost. |
COMPRESSION | Compression. |
Clip to a Cloud Optimized GeoTIFF zero2cloudnative:cog_clip
Group: 2 Imagery
Cuts the pixel window covering the extent at an overview level and writes a COG. The window is snapped outward to whole pixels on the level's grid; there is no resampling. An extent in the raster CRS is used as given; any other CRS is transformed with densified edges.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
RASTER / SOURCE | Raster | raster or string | As for the inspection. |
EXTENT | Clip extent | extent | Required. |
RESOLUTION | Target resolution | number | Picks the overview level; 0 = full resolution. |
COMPRESSION | Compression | enum | DEFLATE (default), ZSTD, LZW, NONE. |
OUTPUT | Clipped COG | file | .tif |
| Output | Meaning |
|---|---|
OUTPUT | Path. |
LEVEL | Overview level used. |
WIDTH, HEIGHT | Size in pixels. |
IS_COG | 1 when the output passes the checks. |
Overture Maps extract zero2cloudnative:overture_extract
Group: 3 Overture
One Overture type for an extent, as on the Overture page (size guard, file selection, bbox pushdown, exact intersects or centroid test, eq. (7)). A local GeoParquet file skips the catalogue (cached downloads).
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
TYPE | Feature type | enum | Types of table 3.3. |
EXTENT | Extent | extent | Required. |
RELEASE | Release | string | Empty = latest. |
ENGINE | Engine | enum | Auto, GDAL, DuckDB. |
CLIP | Keep rule | enum | Intersects (default) or centroid. |
CAP_KM2 | Size guard (advanced) | number | 0 = the type default. |
FILE | Local Overture GeoParquet file | file | Optional. |
OUTPUT | Overture features | feature sink |
| Output | Meaning |
|---|---|
COUNT | Features. |
FILES_READ | Files read. |
AREA_KM2 | Extent area, eq. (1). |
RELEASE_USED, ENGINE_USED, LICENCE | Release, engine and licence id. |
Inspect GeoParquet zero2cloudnative:geoparquet_inspect
Group: 4 GeoParquet
Reads the geo metadata and the Parquet footer of a file or URL; no feature is read.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
SOURCE | GeoParquet file or URL | string | Required. |
OUTPUT | Columns | table sink | column, type. |
| Output | Meaning |
|---|---|
ROWS, ROW_GROUPS | Counts. |
COVERING | 1 when a bbox covering is declared. |
SIZE_BYTES | File size. |
GEO_VERSION, PRIMARY_COLUMN, ENCODING, CRS, BBOX | geo metadata. |
Read GeoParquet zero2cloudnative:geoparquet_read
Group: 4 GeoParquet
Reads a file or URL into a layer, optionally only the features intersecting an extent (row groups outside it are skipped when the file has a bbox covering).
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
SOURCE | GeoParquet file or URL | string | Required. |
EXTENT | Only features in this extent | extent | Optional. |
COLUMNS | Columns | string | Comma separated; empty = all. |
OUTPUT | GeoParquet features | feature sink |
| Output | Meaning |
|---|---|
COUNT | Features read. |
Write GeoParquet zero2cloudnative:geoparquet_write
Group: 4 GeoParquet
Writes a layer as GeoParquet 1.1 (WKB geometry, CRS as PROJJSON); the bbox covering and the spatial sort need GDAL 3.9+.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
INPUT | Input layer | vector | Required. |
COMPRESSION | Compression | enum | ZSTD (default), SNAPPY, GZIP, NONE. |
COVERING | Write a bbox covering column | boolean | Default on. |
SORT | Sort features by bbox | boolean | Default on. |
ROW_GROUP_SIZE | Row group size | integer | Default 65 536. |
OUTPUT | GeoParquet file | file | .parquet |
| Output | Meaning |
|---|---|
ROWS, ROW_GROUPS | Of the written file; row groups = ⌈rows / row group size⌉. |
COVERING_WRITTEN | 1 when the covering was written. |
GEO_VERSION | GeoParquet version. |
Spatial SQL zero2cloudnative:sql_query
Group: 5 SQL
One SQL statement over the input layers. Table names come from the layer names (lower case, letters, digits, underscores) or from the list you give; the geometry column is geom. A result with a geometry column becomes a layer in the tables' CRS, otherwise a table.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
LAYERS | Tables | vector layers | Required. |
NAMES | Table names | string | Comma separated, in layer order. |
SQL | SQL | string | One statement. |
ENGINE | Engine | enum | Auto (DuckDB when installed), DuckDB, OGR SQLite. |
SAFE | Safe mode | boolean | Default on: read-only statements only. |
METRIC | Reproject geographic layers to UTM | boolean | For metric ST_Area and ST_Length. |
MAX_ROWS | Maximum rows of a table result (advanced) | integer | Default 1 000 000. |
OUTPUT | SQL result | feature sink |
| Output | Meaning |
|---|---|
ROWS | Rows of the result. |
ENGINE_USED | duckdb or ogr. |
Web Mercator tile plan zero2cloudnative:tile_plan
Group: 6 PMTiles
Tiles per zoom that cover an extent (eq. (2)); the total bounds the tiles a PMTiles export addresses.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
EXTENT | Extent | extent | Required. |
MINZOOM | Minimum zoom | integer | Default 0. |
MAXZOOM | Maximum zoom | integer | Default 14. |
OUTPUT | Tile plan | table sink | zoom, x0, y0, x1, y1, tiles. |
| Output | Meaning |
|---|---|
TOTAL | Tiles over all zooms. |
Export vector PMTiles zero2cloudnative:pmtiles_export
Group: 6 PMTiles
Writes the layers into one PMTiles v3 archive of Mapbox Vector Tiles and reads its header back (eq. (3)).
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
LAYERS | Layers | vector layers | Each becomes a tile layer. |
MINZOOM / MAXZOOM | Zooms | integer | Default 0 and 14. |
SIMPLIFICATION | Simplification (advanced) | number | Tile pixels; 0 = none. |
MAX_FEATURES | Maximum features per tile (advanced) | integer | Default 200 000. |
NAME, ATTRIBUTION | Archive metadata | string | Optional. |
OUTPUT | PMTiles archive | file | .pmtiles |
| Output | Meaning |
|---|---|
SPEC_VERSION, TILE_TYPE | From the header (3, mvt). |
ADDRESSED_TILES, TILE_CONTENTS | Tile counts. |
SIZE_BYTES | Archive size. |
BOUNDS | W, S, E, N in degrees. |
Capabilities of this QGIS zero2cloudnative:capabilities
Group: 7 Environment
The capability matrix of the Environment page as a table.
| Parameter | Label | Type | Meaning and default |
|---|---|---|---|
PROBE_DUCKDB | Load the DuckDB spatial extension | boolean | May download it once. |
OUTPUT | Capabilities | table sink | feature, available (1/0/NULL), detail. |
| Output | Meaning |
|---|---|
GDAL_VERSION | GDAL version. |
5. Method and formulas
The equations are numbered as in the HTML run report.
5.1 Extents, areas and tiles
Size guards and the footprint KPI use the area of a longitude/latitude box on a sphere of the IUGG mean Earth radius, with the longitudes and the latitudes in radians:
Equation (1): Spherical area of a longitude/latitude box
Source: Moritz 2000.
Tile indexes follow the WebMercatorQuad tile matrix set (the OSM slippy-map convention). Latitude is clamped to , and to ; a point on a tile edge belongs to the east or south tile:
Equation (2): Web Mercator tile index (WebMercatorQuad)
Source: OGC 17-083r4.
A PMTiles v3 archive addresses tile by the number of tiles of all
lower zooms plus the Hilbert curve index on the grid. The header is
127 bytes, starts with the magic PMTiles and the version byte 3, and stores bounds and centre as
integers :
Equation (3): PMTiles v3 tile id
Source: Protomaps 2024.
5.2 STAC search and band composites
The cloud filter, paging and mosaic order are described in section 3.1. The request body is kept in the provenance record. Physical values follow the STAC raster extension; the scale and offset are written into the VRT so the stored digital numbers stay raw:
Equation (4): Physical value from raster:bands
Source: STAC raster extension.
Display uses a cumulative cut of 2 % to 98 % on the histogram of the coarsest overview, one overview read per band.
5.3 Cloud Optimized GeoTIFF checks and window cost
After OGC 21-026 and GDAL's COG validation script:
- tiled: block width and height smaller than the image and multiples of 16; warn when not 256 or 512;
- overviews: present when , each level half the previous ( px), tiled;
- layout: GDAL reports
LAYOUT=COG, otherwise the tile offsets increase (pass) or not (warn); - compression, nodata and CRS declared.
A pixel window with offset and size on blocks of touches tiles per band; with bands of bytes per sample the uncompressed bytes read are bounded by :
Equation (5): Tiles touched by a pixel window
Source: OGC 21-026.
Equation (6): Uncompressed upper bound of the bytes read
Source: OGC 21-026.
The overview chosen for a target resolution is the coarsest level whose pixel size is not larger than that resolution; level 0 is full resolution.
5.4 Overture extraction
Files are selected by intersecting the extent with the file bboxes (closed intervals, touching counts) and read with the bbox covering pushdown. The intersects rule keeps a feature whose geometry intersects the box. The centroid rule keeps a feature whose centroid lies in the half-open box, so adjacent tiles never share a feature:
Equation (7): Centroid rule of a tiled download
Source: Overture docs.
5.5 GeoParquet, SQL and PMTiles
GeoParquet is written through OGR with COMPRESSION, GEOMETRY_ENCODING=WKB,
WRITE_COVERING_BBOX=YES, SORT_BY_BBOX=YES and ROW_GROUP_SIZE; inspection reads
the geo key-value metadata (version, primary column, encoding, CRS as PROJJSON, bbox, covering). The SQL
workspace copies each layer to a temporary GeoParquet (DuckDB) or GeoPackage (OGR) on the worker thread; project
layers are never read from that thread. PMTiles are written by GDAL's PMTiles driver; the header is checked by the
plugin's own reader, which needs no GDAL.
6. Worked example
A study of the Konak district of İzmir, using the box , , , .
- Area and guard. With m, and , equation (1) gives , below the building guard, so the Overture download is allowed.
- Catalog. Earth Search,
sentinel-2-c1-l2a, July 2026, cloud . Earth Search declares the Filter extension, so the request carries the CQL2-JSON filter of section 3.1; the footprints layer shows the items in mosaic order. - Imagery. True colour, Stream (VRT). Sentinel-2 L2A bands carry scale and offset ; a digital number of 1000 is shown as reflectance and 3000 as (equation (6)). For a clip, a window of px at offset on blocks touches tiles (equation (4)); for one UInt16 band equation (5) bounds the read at bytes.
- Overture. Buildings, latest release, GDAL engine. On 14 Nov 2026 this box returned 9 092 buildings with 24 fields from one release file in 12.6 s (the time depends on the network).
- GeoParquet. Export the buildings with ZSTD, covering and sort by bbox; the inspector shows GeoParquet 1.1, WKB, EPSG:4326 and the row groups.
- SQL. The count_by template on
subtypegives the building count per subtype. - PMTiles. Zoom 12 to 16. Equation (2) gives the tile plan , 46 tiles in total; the point 27.1428 E, 38.4237 N lies in tile at zoom 14. The first tile ids of equation (3) are 0 for , 1 to 4 for zoom 1 and 5 for .
The same chain runs as the Processing algorithm Cloud-native study (full chain), which writes the files, their
provenance sidecars and report.html to one folder. The plugin's test suite runs it offline on generated data
(a fake STAC API, local COGs and an Overture-like GeoParquet with planted features).
7. Provenance and licences
Every output records source, urls, release, licence,
attribution, retrieved_utc, the query (for STAC the request body) and the plugin
version. Layers carry it in their metadata (rights, links, history); files get
<output>.provenance.json. Provenance records never hold a Planetary Computer token; only a streamed
VRT does, because GDAL reads the signed URLs from it (section 3.2).
Overture buildings, transportation and divisions are licensed ODbL-1.0, which is share-alike: a derived database you publish must stay under ODbL and credit "© OpenStreetMap contributors, Overture Maps Foundation". Overture places are CDLA-Permissive-2.0. Check each STAC collection's licence before you reuse imagery.
7.1 How to cite
Eminoğlu, Y. (2026). 02CloudNative - Cloud-Native Data Studio (version 0.1.1) [QGIS plugin]. https://gitlab.com/geophilo1/zero2cloudnative. https://doi.org/10.5281/zenodo.24263650. The DOI 10.5281/zenodo.24263650 always resolves to the latest version; version 0.1.1 has DOI https://doi.org/10.5281/zenodo.24263651. Machine-readable metadata: CITATION.cff.
8. Troubleshooting
| Message or symptom | What to do |
|---|---|
| The area is above the size guard | Zoom in, draw a smaller rectangle, or raise the guard (Processing: CAP_KM2). |
| HTTP 403 on Landsat from Earth Search | The bucket is requester-pays; search the Planetary Computer instead. |
| HTTP 409 on a Planetary Computer blob | The URL was not signed; the plugin signs it, so check that the catalogue is the Planetary Computer and retry. |
| A streamed Planetary Computer layer stops drawing after about an hour (HTTP 403 in the log) | Its tokens expired. Right-click the layer and choose Re-sign Planetary Computer links, or leave automatic re-signing on (Environment page). |
| A catalogue answers very slowly | Press Cancel; the request is aborted at once. Lower the HTTP timeout on the Environment page to give up sooner. |
| PMTiles export is disabled | This GDAL has no PMTiles writer (GDAL 3.8+); see the Environment page. |
| Write statements are off | Safe mode is on; turn it off to run statements other than SELECT. |
| Remote Overture views need the DuckDB engine | Install DuckDB or use the Overture page instead. |
9. References
- GDAL/OGR contributors (2025). GDAL/OGR Geospatial Data Abstraction software Library. Open Source Geospatial Foundation. https://gdal.org
- GeoParquet contributors (2024). GeoParquet Specification, version 1.1.0. https://geoparquet.org/releases/v1.1.0/
- Microsoft (2024). planetary-computer Python SDK, planetary_computer/sas.py (SAS token signing). https://github.com/microsoft/planetary-computer-sdk-for-python
- Moritz, H. (2000). Geodetic Reference System 1980. Journal of Geodesy 74(1), 128-133. https://doi.org/10.1007/s001900050278
- Open Geospatial Consortium (2022). OGC Two Dimensional Tile Matrix Set and Tile Set Metadata Standard, version 2.0, OGC 17-083r4 (WebMercatorQuad).
- Open Geospatial Consortium (2023). OGC Cloud Optimized GeoTIFF Standard, version 1.0, OGC 21-026.
- Open Geospatial Consortium (2024). Common Query Language (CQL2), OGC 21-065r2.
- Overture Maps Foundation (2026). Overture Maps schema documentation and release STAC catalogue. https://docs.overturemaps.org; https://stac.overturemaps.org
- Protomaps (2024). PMTiles Version 3 Specification. https://github.com/protomaps/PMTiles/blob/main/spec/v3/spec.md
- QGIS Development Team (2026). QGIS Geographic Information System. Open Source Geospatial Foundation Project. https://qgis.org
- STAC API Specification (2023). Item Search, version 1.0.0; Filter extension (CQL2-JSON) and Query extension. https://github.com/radiantearth/stac-api-spec
- STAC Extensions (2023). Raster Extension Specification v1.1.0 (raster:bands scale, offset, nodata). https://github.com/stac-extensions/raster