Improve docs with recommended use cases for novice users

[nyurik]

A common type of questions for Martin is when to use what, and in what way. We need an intro section in the book that covers:

• Concept of a base map vs "the story" data layers
• Explain that creating tiles on the fly from a DB is usually too slow for the base map, but good for the data layers
• Recommends planetiler as a way to pre-generate base map
• Mention serving from pmtiles/mbtiles
• Mention nginx proxy as a good way to combine tile serving and static file serving (i.e. web site)
  ...?

[CptHolzschnauz]

May I add to the tasklist to complete the missing part of the example for "Functions with Query Parameters" from the actual docs

Function with Query Parameters

Users may add a query parameter to pass additional parameters to the function.

TODO: Modify this example to actually use the query parameters.

[kai-tub]

I would also like to add that I am trying to figure out how to use Martin but am failing to get it up and running with Postgis. :/
It would be nice to have a "complete" minimal example that includes some minimal SQL code to generate a point/polygon and then how to view it in QGIS.

[CptHolzschnauz]

I would also like to add that I am trying to figure out how to use Martin but am failing to get it up and running with Postgis. :/ It would be nice to have a "complete" minimal example that includes some minimal SQL code to generate a point/polygon and then how to view it in QGIS.

You mean just regular points from a geometry in psql without psql functions?

[kai-tub]

You mean just regular points from a geometry in psql without psql functions?

Sorry, I don't quite get what you mean.

For example, on the quick start qgis page, it assumes that a table world_cities exists, but it doesn't provide any information whatsoever about the schema.
It would be helpful to see a single SQL file that generates the table with dummy data.
Similar to the PostGIS introduction to geometry tutorial

CREATE TABLE dummy (name varchar, geom geometry);

INSERT INTO dummy VALUES
  ('Point', 'POINT(0 0)'),
  ('Linestring', 'LINESTRING(0 0, 1 1, 2 1, 2 2)'),
  ('Polygon', 'POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'),
  ('PolygonWithHole', 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 1 2, 2 2, 2 1, 1 1))'),
  ('Collection', 'GEOMETRYCOLLECTION(POINT(2 0),POLYGON((0 0, 1 0, 1 1, 0 1, 0 0)))');

SELECT name, ST_AsText(geom) FROM dummy;

But with the correct CRS information

[CptHolzschnauz]

I understand. I assume you are a beginner, so:

Basically Martin serves tiles for maps from PSQL data type geometry, eg. points.
In a map viewer of any type (Eg. QGIS, MapLibre) this source can be added as a layer (Eg Standalone or over a map)

Short manual (with a ref to my setup)

1. Ctreate a database with PostGIS enabled (I use https://postgresapp.com on my mac for dev, postgis enabled, no PW)
2. Create a table with a geometry data type column (Mine is called position_geo) and other columns (for example desc for a descibtion of that point as a text field)
3. Fill data into the table. (I use PGAdmin for UI. A point in the position_geo is for example looks like 0101000020E6100000CE6CBD812E1F2140168AE694CFAC4740. With PGAdmin you can diplay geometries directly with click on the map symbol)

3. Adjust the Martin config file to serve the geometry point as point (What else ;=) and add the desc text field to that point.

 tables:
    loc:
      # ID of the MVT layer (optional, defaults to table name)
      layer_id: loc

      # Table schema (required)
      schema: your_schema_name

      # Table name (required)
      table: location

      # Geometry SRID (required)
      srid: 4326

      # Geometry column name (required)
      geometry_column: position_geo

      # Feature id column name
      #id_column: uuid

      # An integer specifying the minimum zoom level
      minzoom: 0

      # An integer specifying the maximum zoom level. MUST be >= minzoom
      maxzoom: 30

      # The maximum extent of available map tiles. Bounds MUST define an area
      # covered by all zoom levels. The bounds are represented in WGS:84
      # latitude and longitude values, in the order left, bottom, right, top.
      # Values may be integers or floating point numbers.
      bounds: [ -180.0, -90.0, 180.0, 90.0 ]

      # Tile extent in tile coordinate space
      extent: 4096

      # Buffer distance in tile coordinate space to optionally clip geometries
      buffer: 64

      # Boolean to control if geometries should be clipped or encoded as is
      clip_geom: true

      # Geometry type
      geometry_type: GEOMETRY

      # List of columns, that should be encoded as tile properties (required)
      properties:
        desc: text

3. Start Martin
4. Use a viewer with that source. For example MapLibre:

const MAPTILER_KEY = 'Your Key';
       const map = new maplibregl.Map({
           style: `js/style.json`,
           center: [8.55, 47.36],
           zoom: 11,
           pitch: 45,
           bearing: -17.6,
           container: 'map',
           antialias: true,
           attributionControl: false
       });

map.on('load', async () => {
// Add MArtin server as source
map.addSource('locations', {
               type: 'vector',
               tiles: ['http://localhost:3000/loc/{z}/{x}/{y}']
           });
//Add a layer with the MArtin source

map.addLayer({
               id: 'pois_circle_layer',
               type: 'circle',
               source: 'locations',
               'source-layer': 'loc',
               'paint': {
                   'circle-radius': {
                       'base': 1.75,
                       'stops': [
                           [13, 1.5],
                           [15, 8],
                           [19, 20],
                           [22, 35]
                       ]
                   },

..etc

Important is:
source: 'locations',
'source-layer': 'loc',

loc is the name from the Martin config file, remember
tables:
loc:

now with that point is served with field desc (and any more fields as you declare in the Martin config)
You may add

 map.on('click', function (e) {
            const features = map.queryRenderedFeatures(e.point, { layers: ['pois_circle_layer'] });

            // Check if any features are found
            if (features.length > 0) {
                // Select the first and only the first feature
                const feature = features[0];

                // Display only the properties of the first feature
                document.getElementById('features').innerHTML = JSON.stringify(
                    feature.properties,
                    null,
                    2
                );
            } else {
                // Clear the display if no features are found
                document.getElementById('features').innerHTML = "No features found";
            }
        }); 

To make it visible by clicking on that point in the map.

Hope this helps

PS: To create GEOM points out of regular lat/lng you can use
UPDATE your_table SET geom = ST_SetSRID(ST_MakePoint(longitude, latitude), 4326);

[nyurik]

Awesome writeup @CptHolzschnauz! Perhaps we should add it to the docs somehow?

One thing that might improve GIS DB usage in a huge way: i highly recommend dbeaver - because it has special handling of the GIS primitives: it shows them as readable WKT (even when it is stored as WKB), and when clicked, it actually uses a built-in browser component to visualize it as a geometry on top of OSM or satellite view.

[CptHolzschnauz]

Thanks a bunch, that was just some notes ;=)..nah, for the docs it should be a complete step-by-step, I'll try to do this when I find time to contribute to this wonderful software.
dbeaver topic: You can do the same (as described) with PGAdmin which is 100% open source and free. I don't like this kind of teaser software where you need to pay for some functions after you get used to the tool.

[CommanderStorm]

After the last push, we now have these docs in a variety of places:

• https://maplibre.org/martin/recipe-basemap-postgis.html

  • Explain that creating tiles on the fly from a DB is usually too slow for the base map, but good for the data layers
  • Recommends planetiler as a way to pre-generate base map
  • Concept of a base map vs "the story" data layers

• https://maplibre.org/martin/sources-tiles.html

  • Concept of a base map vs "the story" data layers
  • Mention serving from pmtiles/mbtiles

• https://maplibre.org/martin/run-with-reverse-proxy.html

  • Mention nginx proxy as a good way to combine tile serving and static file serving (i.e. web site)

Unsure how intuitive this is and if an extra exposition page is nessesary.