mosaic metadata minzoom/maxzoom for stac collections

[underchemist]

MOSAIC_STRICT_ZOOM=TRUE implies that tile requests for zoom levels outside those defined by mosaic metadata minzoom/maxzoom values. In practice, a request to

GET /collections/stac-collections/WMTSCapabilities.xml

for a collection with a render object e.g. "renders": {"viz": {"assets": ["cog"], "minmax_zoom": [15, 20]}}... titiler.pgstac will correctly produce XYZ tile urls with minzoom and maxzoom parameters. However the MosaicTilerFactory.tile from titiler.mosaic.factory only checks against the minzoom/maxzoom values in the backend https://github.com/developmentseed/titiler/blob/9fe66665a43f05267107307ae9a0fa54bc3ece80/src/titiler/mosaic/titiler/mosaic/factory.py#L624, defaulting to the TMS minzoom/maxzoom if not set (specifically for titiler.pgstac

titiler-pgstac/titiler/pgstac/backend.py

Line 66 in 97861a4

def minzoom(self) -> int: # type: ignore [override]

).

I would expect that the /tiles endpoint would use any minzoom or maxzoom to override any values defined in the mosaic metadata. If that's not intended, how should I handle the case where I want to restrict tile requests for a stac collection? It's not clear to me how update the mosaic metadata for the registered mosaic id for a stac collection.

[vincentsarago]

@underchemist thanks for the issue

your assessment in right, within the tile() method we don't have access to the min/max zooms stored in the metadata (pgstac). We choose this to avoid making a call to the database on every PGSTACBackend initialization.

That's said we could change this (and make it optional, controlled by en environment variable)

[vincentsarago]

🤔 I'm not quite sure to understand.

when you register a mosaic, you can add metadata minzoom/maxzoom which should then be picked up by the .tile() method

we cannot override those at tile() call because we wanted to avoid adding more parameter to the tile endpoint and also it kinda doesn't make sense to call /tiles/10/.../...?maxzoom=8

[underchemist]

I believe that titiler-pgstac automatically registers a mosaic for each STAC collection. For example

curl http://localhost:8081/collections/stac-collection/info
{
  "search": {
    "hash": "d78869c6e5f7885d9778094947eb0047",
    "search": {
      "collections": [
        "stac-collection"
      ],
      "filter-lang": "cql2-json"
    },
    "lastused": "2026-05-06T17:54:55.067720Z",
    "usecount": 165,
    "metadata": { ... }
}

is there a way to modify this registered mosaic for a given stac collection? I suppose I can do so directly in pgstac. Do you have any other suggestions?

it kinda doesn't make sense to call /tiles/10/.../...?maxzoom=8

I kind of agree but in practice if a tile client e.g. QGIS opens WMTSCapabilities.xml document for a collection with several high resolution assets spread across a large extent it would be good if there was a way to prevent tile generation at low zoom levels. Even if using /collections/{collection id}/items/{item id}/tiles in the case where several tiles layers are to be loaded at different scales it's possible to run into issues when panning and zooming around.

Thanks @vincentsarago

[vincentsarago]

just to be clear, you use case is:

• user calls /collections/{collectionId}/WMTSCapabilities.xml endpoint
• the collection itself doesn't have any render or the user want to add a custom layer (render) by passing query-parameters
• you want to the user to be able to specify minzoom/maxzoom for a specific TileMatrixSet (or for all)

In this case we could update https://github.com/developmentseed/titiler/blob/9fe66665a43f05267107307ae9a0fa54bc3ece80/src/titiler/extensions/titiler/extensions/wmts.py#L132-L158 to accept a custom query-parameter

• /collections/{collectionId}/WMTSCapabilities.xml?minzoom=0&maxzoom=10 (define min/maxzoom for all the TMS)
• /collections/{collectionId}/WMTSCapabilities.xml?minzoom=WebMercatorQuad::0&maxzoom=WebMercatorQuad=10

[underchemist]

The scenario

• User calls /collections/{collectionId}/WMTSCapabilities.xml endpoint
• The collection does have a render, specifying minmax_zoom https://github.com/stac-extensions/render#render-object.
• The ResourceURL element created contains a template XYZ tile url with minzoom and maxzoom query parameters.

However titiler-pgstac doesn't support those parameters and only checks against the values defined in the mosaic metadata.
I suppose that titiler does use minzoom/maxzoom to restrict the TileMatrix elements. In QGIS at least I don't observe that that prevents any tile requests outside the specified zoom levels.

I tried the following in pgstac:

psql -c "select hash, metadata from searches where search->'collections' ? 'noaa-emergency-response';"

 c6a2d2317252e19ffc3ace41070c813c | {}
 13c34ae9cef1561179da54d3bf465837 | {"name": "Mosaic for 'noaa-emergency-response' Collection", "type": "mosaic", "bounds": [-180.0, -90.0, 180.0, 90.0], "defaults": {"cog": {"assets": ["cog"], "maxzoom": 15, "minzoom": 14}}}

psql -c "update searches set metadata = metadata || '{\"minzoom\": 10, \"maxzoom\"
: 18}'::jsonb where hash='13c34ae9cef1561179da54d3bf465837';"

UPDATE 1

But checking the search hashes again a new mosaic is registered

psql -c "select hash, metadata from searches where search->'collections' ? 'noaa-emergency-response';"
 c6a2d2317252e19ffc3ace41070c813c | {}
 ef80c952ead8fefb55ceeb0308134eac | {"name": "Mosaic for 'noaa-emergency-response' Collection", "type": "mosaic", "bounds": [-180.0, -90.0, 180.0, 90.0], "maxzoom": 18, "minzoom": 10, "defaults": {"cog": {"assets": ["cog"], "maxzoom": 15, "minzoom": 14}}}
 13c34ae9cef1561179da54d3bf465837 | {"name": "Mosaic for 'noaa-emergency-response' Collection", "type": "mosaic", "bounds": [-180.0, -90.0, 180.0, 90.0], "defaults": {"cog": {"assets": ["cog"], "maxzoom": 15, "minzoom": 14}}}

and noaa-emergency-response collection is still tied to the 13c34ae9cef1561179da54d3bf465837

curl http://localhost:8081/collections/noaa-emergency-response/info
{
  "search": {
    "hash": "13c34ae9cef1561179da54d3bf465837",
    "search": {
      "collections": [
        "noaa-emergency-response"
      ],
      "filter-lang": "cql2-json"
    },
...
  },
}

is that expected?

[vincentsarago]

there is a cache on top of the /collections endpoint https://github.com/stac-utils/titiler-pgstac/blob/main/titiler/pgstac/dependencies.py#L48-L72 so yes it's expected.

[underchemist]

Right. I would expect that restarting the titiler app to wipe the cache would help with this then.

I think my understanding is this then re MOSAIC_STRICT_ZOOM

• titiler-pgstac only enforces strict zoom level check based on the the mosaic definition
• requests to /collections/{collection id}/tiles will look up the mosaic definition based on the hash associated with the collection id. For example say for collection noaa-emergency-response the associated search hash is abc.
• updating an existing metadata definition will result in a new mosaic hash (I suppose the hash is generated from the contents of the search/metadata object itself?) say the new search hash is def.
• Subsequent calls to /collections/{collection id}/tiles will continue to refer to the default mosaic definition hash abc. Even if the row for hash abc is removed from pgstac, it will be re-registered on next call to any /collections/{collection id} path due to the get_collection_id depenency.

So in my use case I would need to use searches/{search id}/tiles endpoint with mosaic definition that defines minzoom and maxzoom.

[vincentsarago]

So in my use case I would need to use searches/{search id}/tiles endpoint with mosaic definition that defines minzoom and maxzoom.

Yeah, I think developmentseed/titiler#1391 will fix your issue tbh

[underchemist]

thanks for the help! would developmentseed/titiler#1389 be a good starting point, barring the note about per TMS specific parameter?