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:

FeatureNeedsWhen missing
GeoParquet readOGR Parquet driver (GDAL 3.5+)DuckDB engine if installed, else a message
GeoParquet write with bbox covering and spatial sortParquet driver with GDAL 3.9+written without the covering, with a log line
Overture extract, GDAL engineParquet driver and /vsicurl/DuckDB engine
PMTiles exportOGR PMTiles driver with create (GDAL 3.8+)export disabled with the reason
Spatial SQL, DuckDB enginePython package duckdb with the spatial extensionOGR 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

  1. 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.
  2. Collection. Filled from /collections. Collections that cannot be read anonymously are disabled with the reason in the tooltip: on Earth Search, landsat-c2-l2 lives in the requester-pays bucket usgs-landsat (HTTP 403 without AWS credentials); use the Planetary Computer for Landsat.
  3. Extent. Map canvas, a layer's extent or a rectangle drawn on the map.
  4. 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 100 A(F∩Q)/A(Q)100\,A(F \cap Q)/A(Q) for footprint FF and search box QQ, 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 −0.1-0.1) 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):

RecipeBands (STAC eo common names)Notes
True colourred, green, blue
False colour (NIR)nir, red, greenvegetation 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 bandCopernicus DEM; a hillshade layer is added on top
Single bandany assettype 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:

TypeThemeDefault columnsSize guard
building, building_partbuildingsid, names.primary, subtype, class, height, num_floors, min_height, roof_shape, is_underground, sources25 km225\,\mathrm{km}^{2}
placeplacesid, names.primary, categories.primary, confidence, websites, addresses, brand400 km2400\,\mathrm{km}^{2}
segment, connectortransportationsegment: id, subtype, class, names.primary, subclass, speed_limits; connector: id100 km2100\,\mathrm{km}^{2}
division, division_area, division_boundarydivisionsid, subtype, names.primary, country, region, admin_level, classnone

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:

TemplateWhat it does
count_byrow count per value of a column
points_in_polygonspoints per polygon (spatial join with ST_Intersects)
area_length_by_classarea or length per class in a metric CRS (ST_Transform to the working UTM zone)
nearestnearest feature of a second table
grid_countcounts on a square grid with floor(x / size)
profileattribute 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.

ParameterLabelTypeMeaning and default
EXTENTStudy extentextentRequired.
CATALOGSTAC catalogueenumEarth Search (default), Microsoft Planetary Computer, or Custom STAC API URL.
CUSTOM_URLCustom STAC API URLstringUsed when the catalogue is Custom; must start with https://.
COLLECTIONCollection idstringDefault sentinel-2-c1-l2a.
STARTStart datestringYYYY-MM-DD; empty = open start.
ENDEnd datestringYYYY-MM-DD; empty = open end (end of day).
MAX_CLOUDMaximum cloud covernumberPercent, default 20; 100 sends no cloud filter.
MAX_ITEMSMaximum itemsintegerHard cap across pages, default 100.
SORTOrder (advanced)enumCloud ascending then newest (default), or newest first.
ITEMSItems in the mosaicintegerBest N items, default 1.
RECIPEBand recipeenumTrue colour (default), false colour NIR, agriculture, urban, DEM.
TYPEOverture feature typeenumbuilding (default) or any type of table 3.3.
RELEASEOverture releasestringEmpty = latest.
ENGINEOverture engineenumAuto, GDAL, DuckDB.
FILELocal Overture GeoParquet filefileOptional; skips the catalogue.
MINZOOM / MAXZOOMPMTiles zoomsintegerDefault 12 and 15.
OUTPUT_FOLDEROutput folderfolderReceives every file.
FEATURESOverture featuresfeature sinkThe extracted features.
OutputMeaning
REPORT, RASTER, PARQUET, PMTILES, FOOTPRINTS, SQL_CSVPaths of the files written (empty when a stage was skipped).
ITEMS_FOUND, FEATURE_COUNT, ADDRESSED_TILESSTAC items returned, Overture features, PMTiles addressed tiles.

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).

ParameterLabelTypeMeaning and default
EXTENTSearch extentextentRequired.
CATALOGSTAC catalogueenumEarth Search (default), Microsoft Planetary Computer, or Custom STAC API URL.
CUSTOM_URLCustom STAC API URLstringUsed when the catalogue is Custom; must start with https://.
COLLECTIONCollection idstringDefault sentinel-2-c1-l2a.
STARTStart datestringYYYY-MM-DD; empty = open start.
ENDEnd datestringYYYY-MM-DD; empty = open end (end of day).
MAX_CLOUDMaximum cloud covernumberPercent, default 20; 100 sends no cloud filter.
MAX_ITEMSMaximum itemsintegerHard cap across pages, default 100.
SORTOrder (advanced)enumCloud ascending then newest (default), or newest first.
OUTPUTSTAC footprintsfeature sinkPolygons.
OutputMeaning
MATCHEDItems matched (-1 when the API does not report it).
RETURNEDItems returned.
MEDIAN_CLOUDMedian cloud cover of the returned items (%).
AREA_KM2Spherical area of the search box, eq. (1).
REQUESTSRequests sent.
STRATEGYcql2, 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.

ParameterLabelTypeMeaning and default
EXTENTExtentextentRequired; the clip extent in clip mode.
CATALOGSTAC catalogueenumEarth Search (default), Microsoft Planetary Computer, or Custom STAC API URL.
CUSTOM_URLCustom STAC API URLstringUsed when the catalogue is Custom; must start with https://.
COLLECTIONCollection idstringDefault sentinel-2-c1-l2a.
STARTStart datestringYYYY-MM-DD; empty = open start.
ENDEnd datestringYYYY-MM-DD; empty = open end (end of day).
MAX_CLOUDMaximum cloud covernumberPercent, default 20; 100 sends no cloud filter.
MAX_ITEMSMaximum itemsintegerHard cap across pages, default 100.
SORTOrder (advanced)enumCloud ascending then newest (default), or newest first.
ITEMSItems in the mosaicintegerDefault 1.
RECIPEBand recipeenumSee table 3.2.
BANDBand for the single-band recipestringAsset key or common name.
MODEModeenumStream (VRT, default) or clip and save (COG).
RESOLUTIONTarget resolutionnumberIn the raster CRS units; 0 = full resolution.
BUDGET_MBByte budget for a clipnumberDefault 500 MB.
OUTPUTCompositefile.vrt for stream, .tif for clip.
OutputMeaning
OUTPUTPath of the VRT or COG.
LEVELOverview level used (0 = full resolution).
BYTESEstimated bytes read (upper bound).
ITEMS_USEDItems 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)).

ParameterLabelTypeMeaning and default
RASTERRaster layerrasterOptional.
SOURCERaster path or URLstringOverrides the layer.
EXTENTWindow extentextentOptional; for the byte estimate.
RESOLUTIONTarget resolutionnumber0 = full resolution.
OUTPUTCOG checkstable sinkcheck, result (pass/warn/fail), detail.
OutputMeaning
IS_COG1 when GDAL reports the COG layout or the checks pass.
WIDTH, HEIGHT, BANDSSize.
OVERVIEWSOverview levels.
FAILSFailed checks.
LEVELOverview level for the resolution.
TILES, BYTESWindow cost.
COMPRESSIONCompression.

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.

ParameterLabelTypeMeaning and default
RASTER / SOURCERasterraster or stringAs for the inspection.
EXTENTClip extentextentRequired.
RESOLUTIONTarget resolutionnumberPicks the overview level; 0 = full resolution.
COMPRESSIONCompressionenumDEFLATE (default), ZSTD, LZW, NONE.
OUTPUTClipped COGfile.tif
OutputMeaning
OUTPUTPath.
LEVELOverview level used.
WIDTH, HEIGHTSize in pixels.
IS_COG1 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).

ParameterLabelTypeMeaning and default
TYPEFeature typeenumTypes of table 3.3.
EXTENTExtentextentRequired.
RELEASEReleasestringEmpty = latest.
ENGINEEngineenumAuto, GDAL, DuckDB.
CLIPKeep ruleenumIntersects (default) or centroid.
CAP_KM2Size guard (advanced)number0 = the type default.
FILELocal Overture GeoParquet filefileOptional.
OUTPUTOverture featuresfeature sink
OutputMeaning
COUNTFeatures.
FILES_READFiles read.
AREA_KM2Extent area, eq. (1).
RELEASE_USED, ENGINE_USED, LICENCERelease, 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.

ParameterLabelTypeMeaning and default
SOURCEGeoParquet file or URLstringRequired.
OUTPUTColumnstable sinkcolumn, type.
OutputMeaning
ROWS, ROW_GROUPSCounts.
COVERING1 when a bbox covering is declared.
SIZE_BYTESFile size.
GEO_VERSION, PRIMARY_COLUMN, ENCODING, CRS, BBOXgeo 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).

ParameterLabelTypeMeaning and default
SOURCEGeoParquet file or URLstringRequired.
EXTENTOnly features in this extentextentOptional.
COLUMNSColumnsstringComma separated; empty = all.
OUTPUTGeoParquet featuresfeature sink
OutputMeaning
COUNTFeatures 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+.

ParameterLabelTypeMeaning and default
INPUTInput layervectorRequired.
COMPRESSIONCompressionenumZSTD (default), SNAPPY, GZIP, NONE.
COVERINGWrite a bbox covering columnbooleanDefault on.
SORTSort features by bboxbooleanDefault on.
ROW_GROUP_SIZERow group sizeintegerDefault 65 536.
OUTPUTGeoParquet filefile.parquet
OutputMeaning
ROWS, ROW_GROUPSOf the written file; row groups = ⌈rows / row group size⌉.
COVERING_WRITTEN1 when the covering was written.
GEO_VERSIONGeoParquet 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.

ParameterLabelTypeMeaning and default
LAYERSTablesvector layersRequired.
NAMESTable namesstringComma separated, in layer order.
SQLSQLstringOne statement.
ENGINEEngineenumAuto (DuckDB when installed), DuckDB, OGR SQLite.
SAFESafe modebooleanDefault on: read-only statements only.
METRICReproject geographic layers to UTMbooleanFor metric ST_Area and ST_Length.
MAX_ROWSMaximum rows of a table result (advanced)integerDefault 1 000 000.
OUTPUTSQL resultfeature sink
OutputMeaning
ROWSRows of the result.
ENGINE_USEDduckdb 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.

ParameterLabelTypeMeaning and default
EXTENTExtentextentRequired.
MINZOOMMinimum zoomintegerDefault 0.
MAXZOOMMaximum zoomintegerDefault 14.
OUTPUTTile plantable sinkzoom, x0, y0, x1, y1, tiles.
OutputMeaning
TOTALTiles 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)).

ParameterLabelTypeMeaning and default
LAYERSLayersvector layersEach becomes a tile layer.
MINZOOM / MAXZOOMZoomsintegerDefault 0 and 14.
SIMPLIFICATIONSimplification (advanced)numberTile pixels; 0 = none.
MAX_FEATURESMaximum features per tile (advanced)integerDefault 200 000.
NAME, ATTRIBUTIONArchive metadatastringOptional.
OUTPUTPMTiles archivefile.pmtiles
OutputMeaning
SPEC_VERSION, TILE_TYPEFrom the header (3, mvt).
ADDRESSED_TILES, TILE_CONTENTSTile counts.
SIZE_BYTESArchive size.
BOUNDSW, S, E, N in degrees.

Capabilities of this QGIS zero2cloudnative:capabilities

Group: 7 Environment

The capability matrix of the Environment page as a table.

ParameterLabelTypeMeaning and default
PROBE_DUCKDBLoad the DuckDB spatial extensionbooleanMay download it once.
OUTPUTCapabilitiestable sinkfeature, available (1/0/NULL), detail.
OutputMeaning
GDAL_VERSIONGDAL 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 λ\lambda the longitudes and φ\varphi the latitudes in radians:

Equation (1): Spherical area of a longitude/latitude box

A=R2 (λ2−λ1) (sin⁡φ2−sin⁡φ1),R=6 371 008.8 m(1)A = R^{2}\,(\lambda_{2}-\lambda_{1})\,(\sin\varphi_{2}-\sin\varphi_{1}),\quad R = 6\,371\,008.8\ \mathrm{m} \tag{1}

Source: Moritz 2000.

Tile indexes follow the WebMercatorQuad tile matrix set (the OSM slippy-map convention). Latitude is clamped to ±85.0511287798∘\pm 85.0511287798^{\circ}, xx and yy to [0,n−1][0, n-1]; a point on a tile edge belongs to the east or south tile:

Equation (2): Web Mercator tile index (WebMercatorQuad)

n=2z,x=⌊λ+180∘360∘ n⌋,y=⌊1−ln⁡(tan⁡φ+sec⁡φ)/π2 n⌋(2)n = 2^{z},\quad x = \left\lfloor \frac{\lambda + 180^{\circ}}{360^{\circ}}\, n \right\rfloor,\quad y = \left\lfloor \frac{1 - \ln(\tan\varphi + \sec\varphi)/\pi}{2}\, n \right\rfloor \tag{2}

Source: OGC 17-083r4.

A PMTiles v3 archive addresses tile (z,x,y)(z, x, y) by the number of tiles of all lower zooms plus the Hilbert curve index hz(x,y)h_{z}(x, y) on the 2z×2z2^{z} \times 2^{z} grid. The header is 127 bytes, starts with the magic PMTiles and the version byte 3, and stores bounds and centre as integers ×107\times 10^{7}:

Equation (3): PMTiles v3 tile id

id(z,x,y)=∑i=0z−14i+hz(x,y)=4z−13+hz(x,y)(3)\mathrm{id}(z,x,y) = \sum_{i=0}^{z-1} 4^{i} + h_{z}(x,y) = \frac{4^{z}-1}{3} + h_{z}(x,y) \tag{3}

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 DN\mathrm{DN} stay raw:

Equation (4): Physical value from raster:bands

v=DN⋅scale+offset(4)v = \mathrm{DN}\cdot \mathrm{scale} + \mathrm{offset} \tag{4}

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:

A pixel window with offset (x,y)(x, y) and size w×hw \times h on blocks of bw×bhb_w \times b_h touches TT tiles per band; with NbandsN_{\mathrm{bands}} bands of ss bytes per sample the uncompressed bytes read are bounded by BB:

Equation (5): Tiles touched by a pixel window

T=(⌊x+w−1bw⌋−⌊xbw⌋+1)(⌊y+h−1bh⌋−⌊ybh⌋+1)(5)T = \left(\left\lfloor \frac{x+w-1}{b_w} \right\rfloor - \left\lfloor \frac{x}{b_w} \right\rfloor + 1\right)\left(\left\lfloor \frac{y+h-1}{b_h} \right\rfloor - \left\lfloor \frac{y}{b_h} \right\rfloor + 1\right) \tag{5}

Source: OGC 21-026.

Equation (6): Uncompressed upper bound of the bytes read

B≤T bw bh Nbands s(6)B \le T\, b_w\, b_h\, N_{\mathrm{bands}}\, s \tag{6}

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 [W,E]×[S,N][W, E] \times [S, N] 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 (cx,cy)(c_x, c_y) lies in the half-open box, so adjacent tiles never share a feature:

Equation (7): Centroid rule of a tiled download

cx∈[W,E),cy∈[S,N)(7)c_x \in [W, E),\quad c_y \in [S, N) \tag{7}

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 W=27.12∘W = 27.12^{\circ}, S=38.41∘S = 38.41^{\circ}, E=27.14∘E = 27.14^{\circ}, N=38.43∘N = 38.43^{\circ}.

  1. Area and guard. With R=6 371 008.8R = 6\,371\,008.8 m, λ2−λ1=0.02∘\lambda_{2}-\lambda_{1} = 0.02^{\circ} and sin⁡38.43∘−sin⁡38.41∘\sin 38.43^{\circ} - \sin 38.41^{\circ}, equation (1) gives A=3.8749 km2A = 3.8749\,\mathrm{km}^{2}, below the 25 km225\,\mathrm{km}^{2} building guard, so the Overture download is allowed.
  2. Catalog. Earth Search, sentinel-2-c1-l2a, July 2026, cloud ≤20 %\le 20\,\%. 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.
  3. Imagery. True colour, Stream (VRT). Sentinel-2 L2A bands carry scale 10−410^{-4} and offset −0.1-0.1; a digital number of 1000 is shown as 1000⋅10−4−0.1=0.01000 \cdot 10^{-4} - 0.1 = 0.0 reflectance and 3000 as 0.20.2 (equation (6)). For a clip, a window of 300×300300 \times 300 px at offset (100,100)(100, 100) on 256×256256 \times 256 blocks touches T=(1−0+1)(1−0+1)=4T = (1 - 0 + 1)(1 - 0 + 1) = 4 tiles (equation (4)); for one UInt16 band equation (5) bounds the read at 4⋅256⋅256⋅1⋅2=524 2884 \cdot 256 \cdot 256 \cdot 1 \cdot 2 = 524\,288 bytes.
  4. 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).
  5. GeoParquet. Export the buildings with ZSTD, covering and sort by bbox; the inspector shows GeoParquet 1.1, WKB, EPSG:4326 and the row groups.
  6. SQL. The count_by template on subtype gives the building count per subtype.
  7. PMTiles. Zoom 12 to 16. Equation (2) gives the tile plan {12: 2, 13: 2, 14: 6, 15: 12, 16: 24}\{12{:}\ 2,\ 13{:}\ 2,\ 14{:}\ 6,\ 15{:}\ 12, \ 16{:}\ 24\}, 46 tiles in total; the point 27.1428 E, 38.4237 N lies in tile (9427,6295)(9427, 6295) at zoom 14. The first tile ids of equation (3) are 0 for (0,0,0)(0,0,0), 1 to 4 for zoom 1 and 5 for (2,0,0)(2, 0, 0).

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 symptomWhat to do
The area is above the size guardZoom in, draw a smaller rectangle, or raise the guard (Processing: CAP_KM2).
HTTP 403 on Landsat from Earth SearchThe bucket is requester-pays; search the Planetary Computer instead.
HTTP 409 on a Planetary Computer blobThe 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 slowlyPress Cancel; the request is aborted at once. Lower the HTTP timeout on the Environment page to give up sooner.
PMTiles export is disabledThis GDAL has no PMTiles writer (GDAL 3.8+); see the Environment page.
Write statements are offSafe mode is on; turn it off to run statements other than SELECT.
Remote Overture views need the DuckDB engineInstall DuckDB or use the Overture page instead.

9. References

  1. GDAL/OGR contributors (2025). GDAL/OGR Geospatial Data Abstraction software Library. Open Source Geospatial Foundation. https://gdal.org
  2. GeoParquet contributors (2024). GeoParquet Specification, version 1.1.0. https://geoparquet.org/releases/v1.1.0/
  3. Microsoft (2024). planetary-computer Python SDK, planetary_computer/sas.py (SAS token signing). https://github.com/microsoft/planetary-computer-sdk-for-python
  4. Moritz, H. (2000). Geodetic Reference System 1980. Journal of Geodesy 74(1), 128-133. https://doi.org/10.1007/s001900050278
  5. Open Geospatial Consortium (2022). OGC Two Dimensional Tile Matrix Set and Tile Set Metadata Standard, version 2.0, OGC 17-083r4 (WebMercatorQuad).
  6. Open Geospatial Consortium (2023). OGC Cloud Optimized GeoTIFF Standard, version 1.0, OGC 21-026.
  7. Open Geospatial Consortium (2024). Common Query Language (CQL2), OGC 21-065r2.
  8. Overture Maps Foundation (2026). Overture Maps schema documentation and release STAC catalogue. https://docs.overturemaps.org; https://stac.overturemaps.org
  9. Protomaps (2024). PMTiles Version 3 Specification. https://github.com/protomaps/PMTiles/blob/main/spec/v3/spec.md
  10. QGIS Development Team (2026). QGIS Geographic Information System. Open Source Geospatial Foundation Project. https://qgis.org
  11. STAC API Specification (2023). Item Search, version 1.0.0; Filter extension (CQL2-JSON) and Query extension. https://github.com/radiantearth/stac-api-spec
  12. STAC Extensions (2023). Raster Extension Specification v1.1.0 (raster:bands scale, offset, nodata). https://github.com/stac-extensions/raster