{"id":16691133,"url":"https://github.com/daniel-j-h/rusayo-maps","last_synced_at":"2025-03-13T20:47:06.466Z","repository":{"id":249850443,"uuid":"823820914","full_name":"daniel-j-h/rusayo-maps","owner":"daniel-j-h","description":"Putting the Rusayo Camps on the map","archived":false,"fork":false,"pushed_at":"2024-07-23T16:33:30.000Z","size":23002,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-20T16:30:18.080Z","etag":null,"topics":["maplibre","missing-maps","protomaps"],"latest_commit_sha":null,"homepage":"https://daniel-j-h.github.io/rusayo-maps/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daniel-j-h.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-03T19:39:15.000Z","updated_at":"2024-12-07T10:58:39.000Z","dependencies_parsed_at":"2024-07-23T19:44:03.838Z","dependency_job_id":null,"html_url":"https://github.com/daniel-j-h/rusayo-maps","commit_stats":null,"previous_names":["daniel-j-h/rusayo-maps"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-j-h%2Frusayo-maps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-j-h%2Frusayo-maps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-j-h%2Frusayo-maps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-j-h%2Frusayo-maps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-j-h","download_url":"https://codeload.github.com/daniel-j-h/rusayo-maps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243482850,"owners_count":20297897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["maplibre","missing-maps","protomaps"],"created_at":"2024-10-12T16:07:01.519Z","updated_at":"2025-03-13T20:47:06.438Z","avatar_url":"https://github.com/daniel-j-h.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Missing Maps\n\nThis is an experiment for the Missing Maps folks to put the Rusayo Camps on the map.\n\n## How It Works\n\nThe main idea is to self-host an interactive map of mostly static data and everything around it: to democratize map making.\nWe use this repository's Github Pages as a static file host but any static file host will do that can serve files via HTTP.\n\nWe host the following files\n- The [Protomaps](https://protomaps.com) vector tile `.pmtiles` files contain geographic vector data e.g. building outlines\n- The `index.html` contains the web site and renders the vector data with [Maplibre](https://maplibre.org) e.g. to style buildings in gray\n- The `.pbf` files are map fonts encoded in signed distance field format (SDF) for the map to display text using the Noto fonts\n- The `.woff2` files are web fonts used in the `index.html` web site matching the Noto fonts used by the map\n\nFor an overview and a deep dive I recommend reading through the following two articles, respectively\n- [Maplibre + Protomaps: now's the time to get involved!](https://www.openstreetmap.org/user/daniel-j-h/diary/402706)\n- [Everything You Wanted to Know About Vector Tiles (But Were Afraid to Ask)](https://www.openstreetmap.org/user/daniel-j-h/diary/404061)\n\n\n## How to reproduce\n\nThe following tries to summarize the thinking process behind creating this self-hosted map project.\nIt's created from various bits and pieces which are all documented quite well on their own, but a bigger picture of how it all fits together is often missing; below we try to provide that overview.\n\n### Create a base map\n\nTo visualize building outlines from OpenStreetMap we need a base map to put them on: think a map with place names, country borders, and more for the area we are interested in.\n\nThere are various ways to generate a base map\n1. We can generate a base map from OpenStreetMap using [tilemaker](https://github.com/systemed/tilemaker) or [planetiler](https://github.com/onthegomap/planetiler) on an `.osm.pbf` OpenStreetMap snapshot e.g. from [Geofabrik](https://download.geofabrik.de). This will allow us to decide what data goes into the base map and therefore into the vector tiles we want to style later on. The downside is that it's quite an effort to run this out.\n2. The Protomaps folks are creating a global base map from OpenStreetMap data on a daily basis and are bundling vector tile data up in a single `.pmtiles` file. We can use their pmtiles extract command line utility to download a basemap for the area we are interested in.\n\nTo download a `.pmtiles` base map for an area we are interested in go to [geojson.io](https://geojson.io), draw a region polygon, and save it as `basemap.geojson`\n\nUse the `pmtiles extract` command line utility installed from [here](https://github.com/protomaps/go-pmtiles) or use the following command to run it from a docker image\n\n    docker run -it --rm --pull=always -e TMPDIR=/d/out -v $(pwd):/d ghcr.io/protomaps/go-pmtiles:main extract https://build.protomaps.com/20240701.pmtiles /d/basemap.pmtiles --region /d/basemap.geojson --minzoom 11\n\nThis will download the base map vector tile data and save it as `basemap.pmtiles` file.\nRead the `pmtiles extract` documentation [here](https://github.com/protomaps/go-pmtiles?tab=readme-ov-file#create-a-pmtiles-archive-from-a-larger-one) for more options.\n\nWe can visualize this `basemap.pmtiles` file using\n- Maplibre and the Protomaps protocol in an `index.html`\n- One of the base map themes from https://github.com/protomaps/basemaps to style the vector tile data e.g. the \"white\" style, and\n- The map fonts from https://github.com/protomaps/basemaps-assets to make sure the map can render text such as place names\n\nTo make Maplibre understand `.pmtiles` vector tile files add\n\n```javascript\nconst protocol = new pmtiles.Protocol();\nmaplibregl.addProtocol(\"pmtiles\", protocol.tile);\n```\n\nTo add the base map vector tile data to a Maplibre map add\n\n```javascript\nsources: {\n  basemap: {\n    type: \"vector\",\n    url: \"pmtiles://basemap.pmtiles\",\n    attribution: \"© \u003ca href='https://openstreetmap.org'\u003eOpenStreetMap\u003c/a\u003e\",\n  }\n}\n```\nTo style the base map vector tile data add with the \"white\" base map theme add\n\n```javascript\nlayers: protomaps_themes_base.default(\"basemap\", \"white\"),\n```\n\nTo point Maplibre to the Noto signed distance field (SDF) Noto font `.pbf` files for text rendering add\n\n```javascript\nstyle: {\n  glyphs: \"assets/sdf/{fontstack}/{range}.pbf\",\n}\n```\n\n\n### Create use case tiles\n\nVisualizing the base map we notice very small buildings not showing up.\nThe Protomaps base map is meant as a high-level overview map and does not include very small structures such as buildings below a certain area threshold.\n\nFor our custom use case of visualizing the latest buildings from OpenStreetMap we can do the following\n1. Extract the latest building outlines from OpenStreetMap\n2. Create a second `.pmtiles` file containing building outline vector data\n3. Add that data to the map and style it accodringly on top of the base map\n\nTo extract building outlines from OpenStreetMap we have two options\n1. Use the `osmium extract` tool to extract all buildings from an OpenStreetMap snapshot and then use `tippecanoe` to turn those building outlines into a `.pmtiles` file, or\n2. Use e.g. `tilemaker` on an OpenStreetMap snapshot to create a `.pmtiles` file\n\nTo get to an OpenStreetMap snapshot with the latest buildings, download a small `.osm.pbf` file from [Geofabrik](http://download.geofabrik.de) either manually or with `curl`\n\n```bash\ncurl --proto '=https' --tlsv1.3 -sSfO https://download.geofabrik.de/africa/congo-democratic-republic-latest.osm.pbf\n```\n\nWe can cut out the small area we are interested in using `osmium extract` from the [osmium tools](https://osmcode.org/osmium-tool/)\n\n    osmium extract -p basemap.geojson congo-democratic-republic-latest.osm.pbf -o basemap.osm.pbf --set-bounds\n\nTo extract all buildings we can use `osmium tags-filter` and filter all ways (\"w\") with tag \"building=yes\"\n\n    osmium tags-filter -o geom.osm.pbf basemap.osm.pbf w/building=yes\n\nTo generate vector tiles in `.pmtiles` format from the small area of buildings we can use [tippecanoe](https://github.com/felt/tippecanoe)\n\n    osmium export geom.osm.pbf -f geojsonseq | tippecanoe -o buildings.pmtiles -f\n\nTo debug the `.pmtiles` files we can drop the them into the [Protomaps PMTiles viewer for debugging](https://protomaps.github.io/PMTiles/)\n\nAdd this second `.pmtiles` vector tile data source to the map as with the base map above and style it accordingly.\n\nNote: the base map already comes with building data and the base map theme comes with a layer styling them; that's why it's better to remove the high-level buildings layer that comes with the base map and only show the buildings layer we just created\n\n```javascript\nmap.on(\"load\", function() {\n  map.removeLayer(\"buildings\");\n\n  // ...\n}\n```\n\n\n### Styling and Interactivity\n\nWith a base map and a use case (i.e. building) data source, we can style the map data and bring in interactivity e.g. flying to locations.\n\nThe following documentation helps\n1. https://maplibre.org/maplibre-style-spec/sources/ for data sources such as Vector or GeoJSON data sources\n2. https://maplibre.org/maplibre-style-spec/layers/ for styling data and the concept of layers, a bit similar to CSS\n3. https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/ the map's Javascript API e.g. to `map.flyTo` locations\n4. https://maplibre.org/maplibre-gl-js/docs/examples/ Examples for inspiration and code snippets to get started\n\n\n## Summary\n\nData\n1. [Geofabrik](https://download.geofabrik.de) provides OpenStreetMap snapshots in `.osm.pbf` format\n2. [protomaps/basemaps-assets](https://github.com/protomaps/basemaps-assets) provides Noto map fonts ready to use\n\nTools\n1. [`osmium extract`](https://docs.osmcode.org/osmium/latest/osmium-extract.html) works on OpenStreetMap snapshot `.osm.pbf` files to cut out smaller areas\n2. [`osmium tags-filter`](https://docs.osmcode.org/osmium/latest/osmium-tags-filter.html) works on OpenStreetMap snapshot `.osm.pbf` files to filter for specific tags\n3. [`tippecanoe`](https://github.com/felt/tippecanoe) works on vector data e.g. in GeoJSON or `.osm.pbf` format to create Protomaps vector tiles `.pmtiles` files\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-j-h%2Frusayo-maps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-j-h%2Frusayo-maps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-j-h%2Frusayo-maps/lists"}