Skip to content

Commit 0572d63

Browse files
acalcuttacalcutt
committed
Update README.md
1 parent 7122b9e commit 0572d63

File tree

1 file changed

+168
-70
lines changed

1 file changed

+168
-70
lines changed

‎README.md‎

Lines changed: 168 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,40 @@
11
# Contour Generator
22

3-
Generates contour tiles in Mapbox Vector Tile (MVT) format from terrain raster-dem data using [maplibre-contour](https://github.com/onthegomap/maplibre-contour). It allows `maplibre-contour` to work with PMTiles (local or HTTP) when the `demUrl` is prefixed with `pmtiles://` and outputs to local MVT tiles.
4-
5-
This script outputs tile files in the `<outputDir>/z/x/y.pbf` format and generates a `<outputDir>/metadata.json` file. These files can be imported using [mbutil](https://github.com/mapbox/mbutil). For example, to import the tiles into an mbtiles file using mbutil, the syntax would be: `mb-util --image_format=pbf <outputDir> output.mbtiles`.
3+
This tool generates contour lines from terrain raster-dem and outputs them as Mapbox Vector Tiles (MVT). It uses [maplibre-contour](https://github.com/onthegomap/maplibre-contour) and supports various raster-dem sources, including PMTiles (local or HTTP), MBTiles (local) when the `demUrl` is prefixed accordingly. The output is a set of MVT tiles in a standard `z/x/y.pbf` directory structure, along with a `metadata.json` file. These tiles can be easily imported into an MBTiles file using tools like `mbutil` (e.g., `mb-util --image_format=pbf <outputDir> output.mbtiles`).
4+
5+
# Installation and Usage
6+
7+
You can install and use `contour-generator` in several ways:
8+
9+
* **Globally via npm:** This is the most convenient way to use the command-line interface directly.
10+
```bash
11+
npm install -g contour-generator
12+
```
13+
Once installed globally, you can execute the command as:
14+
```bash
15+
contour-generator <function> [options]
16+
```
17+
18+
* **Locally from source:** If you have cloned the repository or downloaded the source.
19+
```bash
20+
git clone https://github.com/acalcutt/contour-generator.git
21+
cd contour-generator
22+
npm install
23+
```
24+
After installation, you can run the script using:
25+
```bash
26+
node . <function> [options]
27+
```
28+
29+
* **Via Docker:** For isolated execution without local dependencies.
30+
```bash
31+
docker run --rm -v $(pwd):/data wifidb/contour-generator <function> [options]
32+
```
633

734
# Script Parameters
835

936
Generates contour tiles based on specified function and parameters.
1037

11-
Docker Usage: `docker run --rm -v $(pwd):/data wifidb/contour-generator <function> [options]`
12-
Local Usage: `node . <function> [options]`
13-
NPM Globally Installed: `contour-generator <function> [options]`
14-
1538
## Functions:
1639

1740
* `pyramid`: Generates contours for a parent tile and all child tiles up to a specified max zoom level.
@@ -20,7 +43,7 @@ NPM Globally Installed: `contour-generator <function> [options]`
2043

2144
## General Options
2245

23-
* `--demUrl <string>`: The URL of the DEM source (e.g., `pmtiles://<http or local file path>` or a tile URL pattern like `https://<zxyPattern>`).
46+
* `--demUrl <string>`: The URL of the DEM source (e.g., `pmtiles://<http or local file path>`, `mbtiles://<local file path>`, or a tile URL pattern like `https://<zxyPattern>`).
2447
* `--encoding <string>`: The encoding of the source DEM tiles (e.g., `'terrarium'`, `'mapbox'`). (default: `mapbox`)
2548
* `--sourceMaxZoom <number>`: The maximum zoom level of the source DEM. (default: `8`)
2649
* `--increment <number>`: The contour increment value to extract. Use `0` for default thresholds.
@@ -53,92 +76,81 @@ NPM Globally Installed: `contour-generator <function> [options]`
5376
* `--maxy <number>`: The maximum Y coordinate of the bounding box. (Required)
5477
* `--outputMinZoom <number>`: The minimum zoom level of the output tile pyramid. (default: `5`)
5578

56-
# Use with Docker
57-
58-
This image is published to Docker Hub as [wifidb/contour-generator](https://hub.docker.com/r/wifidb/contour-generator).
59-
60-
The docker image wifidb/contour-generator can be used for generating tiles in different ways.
79+
# Install globally via npm
80+
```
81+
npm install -g contour-generator
82+
```
6183

62-
## Docker Examples:
84+
# Global npm Examples:
6385

64-
pyramid function (using Docker w/pmtiles https source):
86+
pyramid function (Run Locally w/pmtiles https source):
6587
```
6688
# View Help
67-
docker run -it -v $(pwd):/data wifidb/contour-generator pyramid --help
89+
contour-generator pyramid --help
6890
6991
# Example
70-
docker run -it -v $(pwd):/data wifidb/contour-generator \
71-
pyramid \
72-
--z 9 \
73-
--x 272 \
74-
--y 179 \
75-
--demUrl "pmtiles://https://acalcutt.github.io/contour_generator/test_data/terrain-tiles.pmtiles" \
76-
--sourceMaxZoom 12 \
77-
--encoding mapbox \
78-
--increment 0 \
79-
--outputDir "/data/output_pyramid" \
80-
--outputMaxZoom 15 \
81-
-v
82-
83-
# Test View Area #9/47.2542/11.5426
92+
contour-generator pyramid \
93+
--z 9 \
94+
--x 272 \
95+
--y 179 \
96+
--demUrl "pmtiles://https://acalcutt.github.io/contour_generator/test_data/terrain-tiles.pmtiles" \
97+
--sourceMaxZoom 12 \
98+
--encoding mapbox \
99+
--increment 0 \
100+
--outputDir "./output_pyramid" \
101+
--outputMaxZoom 15 \
102+
-v
103+
104+
#Test View Area #9/47.2542/11.5426
84105
```
85106

86-
zoom function (using Docker w/pmtiles local source):
107+
zoom function (Run Locally w/pmtiles local source):
87108
```
88109
# View Help
89-
docker run -it -v $(pwd):/data wifidb/contour-generator zoom --help
110+
contour-generator zoom --help
90111
91-
# Downlad example test data into your local directory
112+
# Downlad the test data into your local directory
92113
wget https://github.com/acalcutt/contour_generator/releases/download/test_data/JAXA_2024_terrainrgb_z0-Z7_webp.pmtiles
93114
94-
# Example
95-
docker run -it -v $(pwd):/data wifidb/contour-generator \
96-
zoom \
97-
--demUrl "pmtiles:///data/JAXA_2024_terrainrgb_z0-Z7_webp.pmtiles" \
98-
--outputDir "/data/output_zoom" \
99-
--sourceMaxZoom 7 \
100-
--encoding mapbox \
101-
--outputMinZoom 5 \
102-
--outputMaxZoom 7 \
103-
--increment 100 \
104-
--processes 8 \
105-
--blankTileNoDataValue 0 \
106-
--blankTileSize 512 \
107-
--blankTileFormat webp \
108-
-v
109-
110-
# Test View Area #5/47.25/11.54
115+
#Example
116+
contour-generator zoom \
117+
--demUrl "pmtiles://./JAXA_2024_terrainrgb_z0-Z7_webp.pmtiles" \
118+
--outputDir "./output_zoom" \
119+
--sourceMaxZoom 7 \
120+
--encoding mapbox \
121+
--outputMinZoom 5 \
122+
--outputMaxZoom 7 \
123+
--increment 100 \
124+
--processes 8 \
125+
-v
126+
127+
# Test View Area #5/47.25/11.54
111128
# Note: some "No tile returned for" messages are normal with this JAXA dataset since there are areas without tiles
112129
```
113130

114-
bbox function (using Docker w/zxyPattern source):
131+
bbox function (Run Locally w/zxyPattern source):
115132
```
116133
# View Help
117-
docker run -it -v $(pwd):/data wifidb/contour-generator bbox --help
134+
contour-generator bbox --help
118135
119136
# Example
120-
docker run -it -v $(pwd):/data wifidb/contour-generator \
121-
bbox \
122-
--minx -73.51 \
123-
--miny 41.23 \
124-
--maxx -69.93 \
125-
--maxy 42.88 \
126-
--demUrl "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png" \
127-
--sourceMaxZoom 15 \
128-
--encoding terrarium \
129-
--increment 50 \
130-
--outputMinZoom 5 \
131-
--outputMaxZoom 10 \
132-
--outputDir "/data/output_bbox" \
133-
-v
137+
contour-generator bbox \
138+
--minx -73.51 \
139+
--miny 41.23 \
140+
--maxx -69.93 \
141+
--maxy 42.88 \
142+
--demUrl "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png" \
143+
--sourceMaxZoom 15 \
144+
--encoding terrarium \
145+
--increment 50 \
146+
--outputMinZoom 5 \
147+
--outputMaxZoom 10 \
148+
--outputDir "./output_bbox" \
149+
-v
134150
135151
# Test View Area #5/44.96/-73.35
136152
```
137153

138-
Important Notes:
139-
140-
The -v ```$(pwd):/data``` part of the docker run command maps your local working directory ```$(pwd)``` to ```/data``` inside the Docker container. Therefore, your DEM file must be located in the ```/data``` directory inside of the docker image, and the output directory must also be in the ```/data``` directory.
141-
142154
# Install Locally from git
143155
```
144156
git clone https://github.com/acalcutt/contour-generator.git
@@ -216,6 +228,92 @@ bbox function (Run Locally w/zxyPattern source):
216228
# Test View Area #5/44.96/-73.35
217229
```
218230

231+
# Use with Docker
232+
233+
This image is published to Docker Hub as [wifidb/contour-generator](https://hub.docker.com/r/wifidb/contour-generator).
234+
235+
The docker image wifidb/contour-generator can be used for generating tiles in different ways.
236+
237+
## Docker Examples:
238+
239+
pyramid function (using Docker w/pmtiles https source):
240+
```
241+
# View Help
242+
docker run -it -v $(pwd):/data wifidb/contour-generator pyramid --help
243+
244+
# Example
245+
docker run -it -v $(pwd):/data wifidb/contour-generator \
246+
pyramid \
247+
--z 9 \
248+
--x 272 \
249+
--y 179 \
250+
--demUrl "pmtiles://https://acalcutt.github.io/contour_generator/test_data/terrain-tiles.pmtiles" \
251+
--sourceMaxZoom 12 \
252+
--encoding mapbox \
253+
--increment 0 \
254+
--outputDir "/data/output_pyramid" \
255+
--outputMaxZoom 15 \
256+
-v
257+
258+
# Test View Area #9/47.2542/11.5426
259+
```
260+
261+
zoom function (using Docker w/pmtiles local source):
262+
```
263+
# View Help
264+
docker run -it -v $(pwd):/data wifidb/contour-generator zoom --help
265+
266+
# Downlad example test data into your local directory
267+
wget https://github.com/acalcutt/contour_generator/releases/download/test_data/JAXA_2024_terrainrgb_z0-Z7_webp.pmtiles
268+
269+
# Example
270+
docker run -it -v $(pwd):/data wifidb/contour-generator \
271+
zoom \
272+
--demUrl "pmtiles:///data/JAXA_2024_terrainrgb_z0-Z7_webp.pmtiles" \
273+
--outputDir "/data/output_zoom" \
274+
--sourceMaxZoom 7 \
275+
--encoding mapbox \
276+
--outputMinZoom 5 \
277+
--outputMaxZoom 7 \
278+
--increment 100 \
279+
--processes 8 \
280+
--blankTileNoDataValue 0 \
281+
--blankTileSize 512 \
282+
--blankTileFormat webp \
283+
-v
284+
285+
# Test View Area #5/47.25/11.54
286+
# Note: some "No tile returned for" messages are normal with this JAXA dataset since there are areas without tiles
287+
```
288+
289+
bbox function (using Docker w/zxyPattern source):
290+
```
291+
# View Help
292+
docker run -it -v $(pwd):/data wifidb/contour-generator bbox --help
293+
294+
# Example
295+
docker run -it -v $(pwd):/data wifidb/contour-generator \
296+
bbox \
297+
--minx -73.51 \
298+
--miny 41.23 \
299+
--maxx -69.93 \
300+
--maxy 42.88 \
301+
--demUrl "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png" \
302+
--sourceMaxZoom 15 \
303+
--encoding terrarium \
304+
--increment 50 \
305+
--outputMinZoom 5 \
306+
--outputMaxZoom 10 \
307+
--outputDir "/data/output_bbox" \
308+
-v
309+
310+
# Test View Area #5/44.96/-73.35
311+
```
312+
313+
Important Notes:
314+
315+
The -v ```$(pwd):/data``` part of the docker run command maps your local working directory ```$(pwd)``` to ```/data``` inside the Docker container. Therefore, your DEM file must be located in the ```/data``` directory inside of the docker image, and the output directory must also be in the ```/data``` directory.
316+
219317
# Test Data License Information
220318
AWS mapzen terrarium tiles: https://registry.opendata.aws/terrain-tiles/
221319
JAXA AW3D30: https://earth.jaxa.jp/en/data/policy/

0 commit comments

Comments
 (0)