From d669253da3a91b5640dfffde3f80b3a619f82652 Mon Sep 17 00:00:00 2001 From: Ryan Lambert Date: Sun, 7 May 2023 08:32:29 -0600 Subject: [PATCH] Add details about layers to docs. Updating tagged versions in docs to update with variable --- docs/README.md | 1 + docs/book.toml | 2 + docs/src/SUMMARY.md | 1 + docs/src/docker-build.md | 4 +- docs/src/layers.md | 237 ++++++++++++++++++++++++++++++++++++ docs/src/layersets.md | 9 +- docs/src/replication.md | 2 +- docs/src/troubleshooting.md | 2 +- 8 files changed, 250 insertions(+), 8 deletions(-) create mode 100644 docs/src/layers.md diff --git a/docs/README.md b/docs/README.md index efb9b5a..43c8079 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ Install mdbook. ```bash cargo install mdbook +cargo install mdbook-variables ``` Serve the book locally and open your default browser. diff --git a/docs/book.toml b/docs/book.toml index 4851da5..a1818e8 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -13,3 +13,5 @@ git-repository-url = "https://github.com/rustprooflabs/pgosm-flex" git-repository-icon = "fa-github" edit-url-template = "https://github.com/rustprooflabs/pgosm-flex/edit/main/docs/{path}" +[preprocessor.variables.variables] +pgosm_flex_version = "0.8.0" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 9eaec69..40bca26 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -10,6 +10,7 @@ - [Customize PgOSM Flex](./customizations.md) - [Common Customizations](./common-customization.md) - [Layersets](./layersets.md) + - [Layers](./layers.md) - [Configure Postgres](./configure-postgres.md) - [Processing Time](./performance.md) - [Query examples](./query.md) diff --git a/docs/src/docker-build.md b/docs/src/docker-build.md index 108bb5f..b7f0e6d 100644 --- a/docs/src/docker-build.md +++ b/docs/src/docker-build.md @@ -66,14 +66,14 @@ docker build -t rustprooflabs/pgosm-flex . Tag with version. ```bash -docker build -t rustprooflabs/pgosm-flex:0.6.2 . +docker build -t rustprooflabs/pgosm-flex:{{ pgosm_flex_version }} . ``` Push to Docker Hub. ```bash docker push rustprooflabs/pgosm-flex:latest -docker push rustprooflabs/pgosm-flex:0.6.2 +docker push rustprooflabs/pgosm-flex:{{ pgosm_flex_version }} ``` diff --git a/docs/src/layers.md b/docs/src/layers.md new file mode 100644 index 0000000..841042f --- /dev/null +++ b/docs/src/layers.md @@ -0,0 +1,237 @@ +# Layers + +This page documents the layers created by PgOSM Flex. The +[layerset](layersets.md) defined at runtime (to `docker exec`) +determines which tables are loaded, based on `layer_group`. + +The `amenity` `layer_group` has each of the three types of geometry +commonly associated, so has three tables: + +* `osm.amentiy_line` +* `osm.amentiy_point` +* `osm.amentiy_polygon` + +The definitive answer to "what is in a layer" is defined by the +associated Lua code under `flex-config/style/.lua` + +## Tables + +Using `--layerset=everything` creates 42 tables, 2 views, and 2 +materialized views. The following table lists the groups of +tables created with the types of layer it is. + + +| Layer Group | Layer Types | +|-------------|-------------| +| amenity | line, point, polygon | +| building | point, polygon | +| indoor | line, point, polygon | +| infrastructure | line, point, polygon | +| landuse | point, polygon | +| leisure | point, polygon | +| natural | line, point, polygon | +| place | line, point, polygon, *polygon_nested* | +| poi | line, point, polygon | +| public_transport | line, point, polygon | +| road | line, *major*, point, polygon | +| shop | point, polygon | +| tags | *Provides full JSONB tags* | +| traffic | line, point, polygon | +| unitable | *generic `geometry`* | +| water | line, point, polygon | + +## Views + +As PgOSM Flex matures (along with osm2pgsql's Flex output!) the +need for views is diminishing. The materialized view that will likely +remain is: + +* `osm.vplace_polygon_subdivide` + + + +The other views currently created in PgOSM Flex 0.8.x will +be removed in v0.9.0, see [issue #320](https://github.com/rustprooflabs/pgosm-flex/issues/320). + + +* `osm.vbuilding_all` +* `osm.vpoi_all` +* `osm.vshop_all` + + + +## Amenity + + +OpenStreetMap tags included: + +* amenity +* bench +* brewery + + +## Building + + +OpenStreetMap tags included: + +* building +* building:part +* door +* office + +Plus: Address only locations. + +See [issue #97](https://github.com/rustprooflabs/pgosm-flex/issues/97) +for more details about Address only locations. + + +## Indoor + +OpenStreetMap tags included: + +* indoor +* door +* entrance + +## Infrastructure + +OpenStreetMap tags included: + +* aeroway +* amenity +* emergency +* highway +* man_made +* power +* utility + + + +## Landuse + +OpenStreetMap tags included: + +* landuse + + +## Leisure + +OpenStreetMap tags included: + +* leisure + + +## Natural + +OpenStreetMap tags included: + +* natural + +Excludes water/waterway values. See [Water section](#water). + + +## Place + +OpenStreetMap tags included: + +* admin_level +* boundary +* place + + +## POI (Points of Interest) + +The POI layer overlaps many of the other existing layers, though with +slightly different definitions. e.g. only buildings with either a +name and/or operator are included. + +OpenStreetMap tags included: + +* building +* shop +* amenity +* leisure +* man_made +* tourism +* landuse +* natural +* historic + + +## Public Transport + +OpenStreetMap tags included: + +* public_transport +* aerialway +* railway + +Additional important tags considered, but not used for primary selection: + +* bus +* railway +* lightrail +* train +* highway + + +## Road + +OpenStreetMap tags included: + +* highway + +Additional important tags considered, but not used for primary selection: + +* maxspeed +* layer +* tunnel +* bridge +* access +* oneway + + +## Shop + +OpenStreetMap tags included: + +* shop +* amenity + + + +## Tags + +The `osm.tags` table stores all tags for all items loaded. + + +## Traffic + +OpenStreetMap tags included: + +* highway +* railway +* barrier +* traffic_calming +* amenity +* noexit + + + +## Unitable + +All data is stuffed into a generic `GEOMETRY` column. + + +## Water + +OpenStreetMap tags included: + +* natural +* waterway + +Uses specific `natural` types, attempts to avoid overlap +with the Natural layer. See the [Natural section](#natural). + + diff --git a/docs/src/layersets.md b/docs/src/layersets.md index 7c9ebd4..fe2bdbb 100644 --- a/docs/src/layersets.md +++ b/docs/src/layersets.md @@ -1,11 +1,12 @@ # PgOSM Flex layersets -A layerset defines one or more layers, where each layer includes -one or more tables and/or views. -Layers are defined by a matched pair of Lua and SQL scripts. For example, +A layerset defines one or more layers, where each layer +includes one or more tables and/or views. +See [layers](layers.md) for more details. +Layer groups are defined by a matched pair of Lua and SQL scripts. For example, the road layer is defined by `flex-config/style/road.lua` and -`flex-config/sql/road.sql`. +`flex-config/sql/road.sql`, and creates four (4) tables. Layersets are defined in `.ini` files. diff --git a/docs/src/replication.md b/docs/src/replication.md index e8c0310..7238f07 100644 --- a/docs/src/replication.md +++ b/docs/src/replication.md @@ -55,7 +55,7 @@ docker run --name pgosm -d --rm \ -v /etc/localtime:/etc/localtime:ro \ -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \ -p 5433:5432 \ - -d rustprooflabs/pgosm-flex:0.7.0 \ + -d rustprooflabs/pgosm-flex:{{ pgosm_flex_version }} \ -c max_connections=300 ``` diff --git a/docs/src/troubleshooting.md b/docs/src/troubleshooting.md index aee25bf..38e23e4 100644 --- a/docs/src/troubleshooting.md +++ b/docs/src/troubleshooting.md @@ -72,7 +72,7 @@ docker run --name pgosm -d --rm \ -v ~/pgosm-data:/app/output \ -v /etc/localtime:/etc/localtime:ro \ -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \ - -p 5433:5432 -d rustprooflabs/pgosm-flex:0.7.1 \ + -p 5433:5432 -d rustprooflabs/pgosm-flex:{{ pgosm_flex_version }} \ -c shared_buffers=1GB \ -c work_mem=50MB \ -c maintenance_work_mem=10GB \