Examples of TiPG usage and coordinates of generated tiles

[blaziq]

Hello,

I am working on EOEPCA Data Access building block tutorial and examples for Salvatore Pinto of ESA.

My first and most general question is: are there any working examples or close-to-real-life use cases how to actually use the TiPG component? The existing documentation lacks severely in that matter (unlike the TiTiler-PgSTAC - the raster counterpart). And there is nothing in the EOEPCA Deployment Guide or its accompanying Jupyter notebooks, either.

This is what I know so far:

• The REST API seems to be entirely read-only, HTTP GET is the only method supported for all endpoints. There is no way to add collections and items other than... creating a table or a function directly in the database with SQL (this feature is undocumented so I figured it out by myself). How is anyone going to be able to add / register a collection?
• The preexisting collections (right after installation) are indeed PostgreSQL functions which require arguments (not explained anywhere) and because of that are pretty much useless since I don't know what the args should be.
• I have managed to add some collections (countries, landsat_wrs and sentinel_mgrs), from TiPG Github and I have figured out a way to actually obtain an mvt vector tile from the vector service, by calling /vector/collections/<collection>/tiles/WebMercatorQuad/<z>/<x>/<y> with parameters x, y, z chosen with trial and error method, from the ranges given for the specified zoom level, for a single tile from a collection - or placeholders for the entire collection. I took the public.countries collection because it seems like the best way to present something meaningful to users. But, unlike with raster, there doesn't seem to be an easy way to overlay this over a map and when I'm trying, I'm getting weird results (see screenshots below). Apparently, the generated tile does not have coordinates that are recognizable to the renderer (the map is rendered using maplibre-gl).
• The output tile is in the Mapbox Vector Tile (MVT) format which I have problems with:
  • It cannot be easily displayed in the browser, other than using libs like the said maplibre-gl or some online viewers
  • I don't know any tools to extract metadata from the tile, most importantly the coordinates system and their values. From the URL used for generating the tile I assume it is Web Mercator EPSG:3857 but the collection itself i.e. the table in the database seems to have WGS84 EPSG:4326 (SELECT AddGeometryColumn('','countries','geom','4326','MULTIPOLYGON',2); in the SQL used to create the table). In the end, I don't know what is used in the final vector product, whether it was reprojected from 4326 to 3857 or how the coordinates can be used to overlay on a map.

(the URLs below are just examples and are not accessible from the internet as they are only in a private network)

• The first screenshot below is one tile generated from the URL https://81-d90edb2c79ac450dbd5ac068165226ac-lc.eoepca.ples.dedyn.io/vector/collections/public.countries/tiles/WebMercatorQuad/5/17/12?f=mvt
• If I use placeholders for z, x, y i.e. get tiles of the entire collection: https://81-d90edb2c79ac450dbd5ac068165226ac-lc.eoepca.ples.dedyn.io/vector/collections/public.countries/tiles/WebMercatorQuad/{z}/{x}/{y}?f=mvt I get the second screenshot which looks just fine
• If I, however, use placeholders for a different collection e.g. landsat_wrs (with only a few items over Greenland) https://81-d90edb2c79ac450dbd5ac068165226ac-lc.eoepca.ples.dedyn.io/vector/collections/public.landsat_wrs/tiles/WebMercatorQuad/{z}/{x}/{y}?f=mvt I get the mess which you can see in the third screenshot

Could you give me some hints how to use the TiPG vector component correctly and efficiently?

[vincentsarago]

Hi @blaziq

I'll try to answer each question

The existing documentation lacks severely in that matter (unlike the TiTiler-PgSTAC - the raster counterpart).

Any PR will be appreciated, we do have endpoints documentation over https://developmentseed.org/tipg/user_guide/endpoints/

The Endpoints created with TiPg application follows the OGC specification so it's you can find more information at https://ogcapi.ogc.org/features/ and https://ogcapi.ogc.org/tiles/

The REST API seems to be entirely read-only, HTTP GET is the only method supported for all endpoints. There is no way to add collections and items other than... creating a table or a function directly in the database with SQL (this feature is undocumented so I figured it out by myself). How is anyone going to be able to add / register a collection?

TiPG only implement the part 1 and 2 or the OGC Feature Spec, the Part 4 (Create, Replace, Update and Delete is still on a draft https://docs.ogc.org/DRAFTS/20-002r1.html), so you're write tipg does provide any POST endpoints: https://github.com/developmentseed/tipg?tab=readme-ov-file#ogc-specifications

The preexisting collections (right after installation) are indeed PostgreSQL functions which require arguments (not explained anywhere) and because of that are pretty much useless since I don't know what the args should be.

I agree this is not idea but sadly there are no specs to tell the users what are the required arguments. You can find the documentation for each function on Postgis doc: https://postgis.net/docs/ST_HexagonGrid.html

we do explain how the functions work in https://developmentseed.org/tipg/advanced/functions/#function-examples

SQL Function arguments will be exposed to the items API as query parameters. Any argument that does not have a default will be required and will return an error if not set as a query parameter. Functions should have a unique name. Function overloading by argument type is not currently supported.

If a function is defined to have z, x, or y parameters, those will be filled from the path parameters in requests to Tile endpoints. If a function has a bounds parameter, that will be populated by the Tile bounding box in requests to Tile endpoints. All other arguments will be filled from query parameters matching the name of the argument and cast to the appropriate types.

I have managed to add some collections (countries, landsat_wrs and sentinel_mgrs), from TiPG Github and I have figured out a way to actually obtain an mvt vector tile from the vector service, by calling /vector/collections//tiles/WebMercatorQuad/// with parameters x, y, z chosen with trial and error method, from the ranges given for the specified zoom level, for a single tile from a collection - or placeholders for the entire collection.

For each collection you can have a /viewer endpoint available

But, unlike with raster, there doesn't seem to be an easy way to overlay this over a map and when I'm trying, I'm getting weird results (see screenshots below). Apparently, the generated tile does not have coordinates that are recognizable to the renderer (the map is rendered using maplibre-gl).

This is likely a configuration issue on your HTML/JS code

I added an example in https://github.com/developmentseed/tipg/blob/main/examples/maplibre.html

The output tile is in the Mapbox Vector Tile (MVT) format which I have problems with:

Do you have any other format for vector tiles?

I don't know any tools to extract metadata from the tile, most importantly the coordinates system and their values

We usually use https://github.com/tilezen/mapbox-vector-tile

From the URL used for generating the tile I assume it is Web Mercator EPSG:3857 but the collection itself i.e. the table in the database seems to have WGS84 EPSG:4326 (SELECT AddGeometryColumn('','countries','geom','4326','MULTIPOLYGON',2); in the SQL used to create the table). In the end, I don't know what is used in the final vector product, whether it was reprojected from 4326 to 3857 or how the coordinates can be used to overlay on a map.

TiPG (PostGIS) will reproject dynamically any table to the output projection

I don't seems to be able to get any response from your URLs 🤷‍♂️

More than happy to review any PR to improve our documentation

[blaziq]

Hi @vincentsarago
Thanks for the reply. I will review all the links and examples and inform you of the outcome.