Docs section update. (#94)

- remove old TM2 articles - update all categories (generate, host, style, website, raster) - switch categories - use Generate own map as `Docs` root - a reference to a `mobile-app` page - update text - format Markdown --------- Co-authored-by: Jiří Komárek <[email protected]>
openmaptiles · May 10, 2024 · 5b3f3cd · 5b3f3cd
1 parent 734b601
commit 5b3f3cd
Show file tree

Hide file tree

Showing 23 changed files with 384 additions and 391 deletions.
diff --git a/_data/categories.json b/_data/categories.json
@@ -1,4 +1,14 @@
 [
+  {
+    "id": "generate",
+    "title": "Generate Vector Tiles",
+    "desc": "Use the open process and tools to create the vector tiles yourself."
+  },
+  {
+    "id": "host",
+    "title": "Hosting Map Tiles",
+    "desc": "Tutorials how to set up different tileservers and hosting the vector tiles yourself."
+  },
   {
     "id": "style",
     "title": "Style your Map",
@@ -9,16 +19,6 @@
     "title": "Display Map",
     "desc": "Display vector tiles in a web client using either MapTiler SDK JS, MapLibre GL, Leaflet, Tangram or OpenLayers."
   },
-  {
-    "id": "host",
-    "title": "Hosting Map Tiles",
-    "desc": "Tutorials how to set up different tileservers and hosting the vector tiles yourself."
-  },
-  {
-    "id": "generate",
-    "title": "Generate Vector Tiles",
-    "desc": "Use the open process and tools to create the vector tiles yourself."
-  },
   {
     "id": "mobile",
     "title": "Maps in a Mobile App",

diff --git a/about.html b/about.html
@@ -19,7 +19,7 @@
       ready-to-use packages containing vector tiles for the whole planet,
       individual countries and major cities. Downloaded map tiles can be
       displayed on websites with <a href="/viewers/">JavaScript viewers</a>,
-      used in native <a href="/mobile/">mobile applications</a>
+      used in native <a href="/mobile-app/">mobile applications</a>
       on Android and iOS (even offline), or turned into traditional
       raster tiles or high-resolution images for printing.</p>
 

diff --git a/docs/generate/create-custom-extract.md b/docs/generate/create-custom-extract.md
@@ -3,19 +3,18 @@ layout: docs
 category: generate
 order: 4
 title: Create custom map extract
-description: Create custom map extract of an area of your choice
+description: Create a custom map extract of an area of your choice
 ---
 
-If you need an extract which is not included on the [downloads page](http://openmaptiles.org/downloads), you need to download the planet file and create your own extract.
+If you need an extract that is not included on the [downloads page](http://openmaptiles.org/downloads), you need to download the planet file and create your own MBTiles extract. If you need a smaller area, then it is available as OSM.PBF extract, e.g., on [Geofabrik](https://geofabrik.de/). Extracting could be done before importing into a database.
 
 ## Preparation
 
-1. [Download map tiles of the entire world](https://data.maptiler.com/downloads/planet/).
-2. Install [tilelive](https://github.com/mapbox/tilelive) and [MBTiles support](https://github.com/mapbox/node-mbtiles).
+[Download map tiles of the entire world](https://data.maptiler.com/downloads/planet/)
 
-```bash
-npm install -g @mapbox/tilelive @mapbox/mbtiles
-```
+or 
+
+[Download OpenStreetMap extract](https://download.geofabrik.de/).
 
 ## Choose your Bounding Box
 
@@ -24,15 +23,31 @@ npm install -g @mapbox/tilelive @mapbox/mbtiles
 
 ![Choose Bounding Box](/media/choose-bounding-box.png)
 
-## Create Extract
+## Create MBTiles Extract
 
-To create an extract, use the `tilelive-copy` utility. It takes a bounding box and a MBTiles file as input and creates an extract clipped to the bounding box.
+To create an extract, use the [`mbtiles-tools copy`](https://github.com/openmaptiles/openmaptiles-tools/blob/master/bin/mbtiles-tools) utility included in [openmaptiles-tools](https://github.com/openmaptiles/openmaptiles-tools/) docker. It takes a bounding box and a MBTiles file as input and creates an extract clipped to the bounding box.
 
-Replace the bounding box in the following command with your bounding box.
+Replace the bounding box and center zoom in the following command with your bounding box.
 
 ```bash
-tilelive-copy \
-    --minzoom=0 --maxzoom=14 \
-    --bounds="5.9559,45.818,10.4921,47.8084" \
-    planet.mbtiles my-extract-for-switzerland.mbtiles
+make bash
+
+export CENTER_ZOOM=5
+
+mbtiles-tools copy ./data/tiles.mbtiles ./data/smaller_tiles.mbtiles \
+        --reset \
+        --auto-minmax \
+        --bbox=16.2882,49.0093,16.9248,49.4175
+```
+
+## Create OSM.PBF Extract
+
+Creating extract from OSM.PBF, use the `osmconvert` tool included in [openmaptiles-tools](https://github.com/openmaptiles/openmaptiles-tools/) docker. It takes a bounding box and an OSM.PBF file as input and creates an extract clipped to the bounding box.
+
+```bash
+make bash
+
+osmconvert ./data/planet.osm.pbf \
+        -b=-14.53,28.89,43.21,59.8 \
+        -o=./data/part_europe.osm.pbf
 ```
diff --git a/docs/generate/custom-vector-from-postgis.md b/docs/generate/custom-vector-from-postgis.md
@@ -1,75 +1,81 @@
 ---
 layout: docs
 category: generate
-order: 2
+order: 3
 title: Custom vector tiles from PostGIS
 description: Custom Vector Tiles from PostGIS
 ---
 
-You can combine OpenMapTiles with your custom vector data saved in **PostGIS** database (there is the separate article for [data stored in **ShapeFile or GeoJSON**](/docs/generate/custom-vector-from-shapefile-geojson/)). The easiest way is to convert your data into vector tiles and then [combine it with standard OpenMapTiles source in a map style](https://openmaptiles.org/docs/raster/custom-raster/#prepare-map-style). The big advantage of this approach is that you don't need to generate the whole OpenMapTiles schema which is quite time-consuming.
+You can combine OpenMapTiles with your custom vector data saved in **PostGIS** database (there is a separate article for [data stored in **Shapefile or GeoJSON**](/docs/generate/custom-vector-from-shapefile-geojson/)). The easiest way is to convert your data into vector tiles and then [combine it with a standard OpenMapTiles source in a map style](https://openmaptiles.org/docs/raster/custom-raster/#prepare-map-style). The big advantage of this approach is that you don't need to generate the whole OpenMapTiles schema, which is quite time-consuming.
 
+This approach is a bit more complicated to set up than in the case of [data stored in Shapefile or GeoJSON](/docs/generate/custom-vector-from-shapefile-geojson/). On the other hand, it gives you even bigger control over tiles generation and you can use SQL syntax a lot of people are familiar with.
 
-# Create vector tiles from PostGIS
+## Before importing the data into PostGIS
 
-This approach is a bit more complicated to set up then in the case of [data stored in ShapeFile or GeoJSON](/docs/generate/custom-vector-from-shapefile-geojson/). On the other hand, it gives you even bigger control over tiles generation and you can use SQL syntax a lot of people is familiar with.
-
-### Before importing the data into PostGIS
-First, you need to install Docker and Docker Compose and to clone OpenMapTiles repository as [described here](/docs/generate/generate-openmaptiles/) (space and memory requirements are not so high in this case).
-
-Add `data` directory as another volume of postgres service in `docker-compose.yml`:
-```yml
-services:
-  postgres:
-    image: "openmaptiles/postgis:2.3"
-    volumes:
-    - pgdata:/var/lib/postgresql/data
-    - ./data:/data
-    ...
-```
+First, you need to install Docker and Docker Compose and clone the OpenMapTiles repository as [described here](/docs/generate/generate-openmaptiles/) (space and memory requirements are not so high in this case).
 
 Run the database container:
+
 ```bash
 docker-compose up -d postgres
 ```
 
-### Import the data into PostGIS
-Move your data into `data/` directory and ensure it was set to EPSG:3857 coordinate system. You can use ogr2ogr for transformation:
+or
+
 ```bash
-ogr2ogr -f "ESRI ShapeFile" your_data_in_3857.shp -t_srs EPSG:3857 your_data.shp
+make start-db
 ```
 
-Files inside `data/` directory are visible from Docker container. Get into the postgres container:
-```
-docker-compose run --rm postgres bash
-```
+## Import the data into PostGIS
 
-and import your data into PostgreSQL database by [shp2pgsql utility](http://postgis.net/docs/manual-2.3/using_postgis_dbmanagement.html#shp2pgsql_usage):
+Move your data into `data/` directory. Modify command where `"./data/name.shp"` replace with the name of the Shapefile and `"name"` is the name of the table in PostgreSQL
+
+```bash
+docker-compose run --rm openmaptiles-tools sh -c \
+  'ogr2ogr \
+    -f "PostgreSQL" \
+    PG:"dbname=openmaptiles user=openmaptiles password=openmaptiles host=postgres port=5435" \
+    "./data/name.shp" \
+    -s_srs EPSG:3035 \
+    -t_srs EPSG:3857 \
+    -lco OVERWRITE=YES \
+    -lco GEOMETRY_NAME=geometry \
+    -overwrite \
+    -nln "name" \
+    -nlt GEOMETRY \
+    --config PG_USE_COPY YES'
 ```
-shp2pgsql -s 3857 -I -g geometry /data/your_data_in_3857.shp your_table_name > /data/your_data.sql
-PGPASSWORD=openmaptiles psql --host=postgres --port=5432 --dbname=openmaptiles --username=openmaptiles -f /data/your_data.sql | grep -v "INSERT 0 1"
+
+To check if the data was imported correctly, you can run:
+
+```bash
+make list-tables
 ```
 
-Inside the container, you can run
+or connect to the PostgreSQL container and check it from inside:
+
 ```bash
-psql postgresql://openmaptiles@postgres/openmaptiles
+make psql
+
+\dt
 ```
-to get into the database and check if the data was imported correctly.
 
 Run `exit` to exit from a container.
 
+## Configure OpenMapTiles
 
-### Configure OpenMapTiles
+The next step is to configure the OpenMapTiles project to generate tiles from your data. Basically, you need to
 
-The next step is to configure OpenMapTiles project to generate tiles from your data. Basically, you need to
 - create layer definition of your data
 - change `openmaptiles.yaml` so that it contains only your layer(s)
-- create `data/docker-compose-config.yml` with zoom range and the bounding box of generated tiles
+- change `.env` with zoom range and the bounding box of generated tiles
 
+### Create custom layer definition
 
-#### Create custom layer definition
-The layer definition might be the most complicated step depending on how many logic you want to implement. The very simple example consists of two files:
+The layer definition might be the most complicated step, depending on how much logic you want to implement. The very simple example consists of two files:
 
 **layers/pubtran/pubtran.yaml:**
+
 ```yml
 layer:
   id: "pubtran"
@@ -89,7 +95,9 @@ layer:
 schema:
   - ./layer.sql
 ```
+
 **layers/pubtran/layer.sql:**
+
 ```sql
 CREATE OR REPLACE FUNCTION layer_pubtran(bbox geometry, zoom_level int)
 RETURNS TABLE(geometry geometry, custom_attribute text) AS $$
@@ -98,17 +106,19 @@ RETURNS TABLE(geometry geometry, custom_attribute text) AS $$
     WHERE geometry && bbox;
 $$ LANGUAGE SQL IMMUTABLE;
 ```
+
 For a better understanding of this example, check the [documentation](https://github.com/openmaptiles/openmaptiles-tools#define-your-own-layer) to get inspiration in defining your own [OpenMapTiles layers](https://github.com/openmaptiles/openmaptiles/tree/master/layers) used in production.
 
-#### Change openmaptiles.yaml
+### Change openmaptiles.yaml
 
 Change `openmaptiles.yaml` to contain only your layer(s). It may look like this:
+
 ```yml
 tileset:
   layers:
     - layers/pubtran/pubtran.yaml
   name: OpenMapTiles
-  version: 3.3.0
+  version: 3.15.0
   id: pubtran
   description: "Sample tileset of Prague Public Transportation"
   attribution: '<a href="http://opendata.praha.eu" target="_blank">&copy; OpenStreetMap contributors</a>'
@@ -120,43 +130,46 @@ tileset:
     datasource:
       srid: 900913
 ```
+
 You should change at least `attribution` and `center` properties.
 
-#### Create data/docker-compose-config.yml
-Create `data/docker-compose-config.yml` with zoom range and bounding box of generated tiles:
+### Edit .env
+
+Edit `.env` with zoom range and bounding box of generated tiles:
+
 ```yml
-version: "2"
-services:
-  generate-vectortiles:
-    environment:
-      BBOX: "14.224435,49.941898,14.706787,50.177433"
-      OSM_MAX_TIMESTAMP : "2017-04-19T20:14:29Z"
-      OSM_AREA_NAME: "prague"
-      MIN_ZOOM: "0"
-      MAX_ZOOM: "14"
+BBOX=14.224435,49.941898,14.706787,50.177433
+
+MIN_ZOOM=0
+MAX_ZOOM=14
 ```
+
 You can get the bounding box easily with [http://boundingbox.klokantech.com/](http://boundingbox.klokantech.com/).
 
-#### Generate your tiles
+### Generate your tiles
 
 Run these commands to create/update other configuration files needed for generating:
+
 ```bash
-docker run -v $(pwd):/tileset openmaptiles/openmaptiles-tools make clean
-docker run -v $(pwd):/tileset openmaptiles/openmaptiles-tools make
-docker-compose run --rm import-sql
+make clean
+make
+make import-sql
 ```
 
-Finally generate your tiles:
+Finally, generate your tiles:
+
 ```bash
-docker-compose -f docker-compose.yml -f ./data/docker-compose-config.yml  run --rm generate-vectortiles
+make generate-tiles-pg
 ```
 
 Your MBTiles file is now in `data/tiles.mbtiles`. You can preview it using [TileServer-GL](/docs/host/tileserver-gl/):
+
 ```bash
-docker run -it -v $(pwd):/data -p 8080:80 maptiler/tileserver-gl data/tiles.mbtiles
+make start-tileserver
 ```
-<img src='/img/custom-vector-tileserver-gl2.png' alt='Data preview with TileServer-GL' />
 
+<img src='/img/custom-vector-tileserver-gl2.png' alt='Data preview with TileServer-GL' />
 
 ## Combine your vector tiles with OpenMapTiles
-After creating vector tiles, you can combine them with the standard OpenMapTiles layer in one map style. It can be done in the same way as in case of [raster tiles](/docs/raster/custom-raster/#prepare-map-style).
+
+After creating vector tiles, you can combine them with the standard OpenMapTiles layer in one map style. It can be done in the same way as in the case of [raster tiles](/docs/raster/custom-raster/#prepare-map-style).
diff --git a/docs/generate/custom-vector-from-shapefile-geojson.md b/docs/generate/custom-vector-from-shapefile-geojson.md
@@ -1,40 +1,47 @@
 ---
 layout: docs
 category: generate
-order: 1
-title: Custom vector tiles from GeoJSON or ShapeFile
-description: Custom Vector Tiles from GeoJSON or ShapeFile using open-source tools
+order: 2
+title: Custom vector tiles from GeoJSON or Shapefile
+description: Custom Vector Tiles from GeoJSON or Shapefile using open-source tools
 redirect_from: /docs/generate/custom-vector/
 ---
 
-You can combine OpenMapTiles with your custom vector data saved in **ShapeFile** or **GeoJSON** format (there is the separate article for [data stored in **PostGIS** database](/docs/generate/custom-vector-from-postgis/)). The easiest way is to convert your data into vector tiles and then [combine it with standard OpenMapTiles source in a map style](https://openmaptiles.org/docs/raster/custom-raster/#prepare-map-style). The big advantage of this approach is that you don't need to generate the whole OpenMapTiles schema which is quite time-consuming.
+You can combine OpenMapTiles with your custom vector data saved in **Shapefile** or **GeoJSON** format (there is a separate article for [data stored in **PostGIS** database](/docs/generate/custom-vector-from-postgis/)). The easiest way is to convert your data into vector tiles and then [combine it with a standard OpenMapTiles source in a map style](https://openmaptiles.org/docs/raster/custom-raster/#prepare-map-style). The big advantage of this approach is that you don't need to generate the whole OpenMapTiles schema which is quite time-consuming.
 
-# Create vector tiles from GeoJSON or ShapeFile
+## Preparation
 
-On Linux and macOS, you can use a command-line tool [**tippecanoe**](https://github.com/mapbox/tippecanoe) from Mapbox. See [installation instructions](https://www.mapbox.com/help/large-data-tippecanoe/#install-tippecanoe-and-gdal).
+On Linux and macOS, you can use a command-line tool [**tippecanoe**](https://github.com/felt/tippecanoe) originally from Mapbox. See [installation instructions](https://github.com/felt/tippecanoe?tab=readme-ov-file#installation).
+
+Before using tippecanoe, you need to transform your data into the EPSG:4326 coordinate system. You can use for example `ogr2ogr` utility which is part of [gdal](http://www.gdal.org/):
 
-Before using tippecanoe, you need to transform your data into EPSG:4326 coordinate system. You can use for example `ogr2ogr` utility which is part of [gdal](http://www.gdal.org/):
 ```bash
 ogr2ogr -f GeoJSON your_data_in_4326.json -t_srs EPSG:4326 your_data.shp
 ```
 
-Having your data in correct coordinate system, you can do the conversion using tippecanoe. The most simple use case is:
+## Generate the Vector Tiles
+
+Having your data in a correct coordinate system, you can do the conversion using tippecanoe. The most simple use case is:
+
 ```bash
-tippecanoe -o your_data.mbtiles your_data_in_4326.json
+tippecanoe -o tiles.mbtiles your_data_in_4326.json
 ```
 
-It will convert your data into MBTiles for zoom levels 0 to 14. Tippecanoe enables much more sophisticated options including layer and attribute management, dropping features, generalization, and more. See [documentation](https://github.com/mapbox/tippecanoe#options).
+It will convert your data into MBTiles for zoom levels 0 to 14. Tippecanoe enables much more sophisticated options, including layer and attribute management, dropping features, generalization, and more. See [documentation](https://github.com/felt/tippecanoe?tab=readme-ov-file#cookbook).
 
 You can visually check the generated MBTiles file using [TileServer-GL](/docs/host/tileserver-gl/):
+
 ```bash
-docker run -it -v $(pwd):/data -p 8080:80 maptiler/tileserver-gl your_data.mbtiles
+make start-tileserver
 ```
 
 Data preview with TileServer-GL:
 <img src='/img/custom-vector-tileserver-gl.png' alt='Data preview with TileServer-GL' />
 
 ## Combine your vector tiles with OpenMapTiles
+
 After creating vector tiles, you can combine them with the standard OpenMapTiles layer in one map style. It can be done in the same way as in case of [raster tiles](/docs/raster/custom-raster/#prepare-map-style).
 
 ## User-friendly software
+
 Alternatively, you can use commercial [map tiling software](https://www.maptiler.com/desktop/) with a user-friendly GUI to generate your vector data overlay.