ExternalVendorCode/tippecanoe
1
0
Fork 0
mirror of https://github.com/mapbox/tippecanoe.git synced 2025-06-12 12:28:14 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Reorder and reword documentation

Browse Source
This commit is contained in:
Eric Fischer
2017-09-07 15:34:55 -07:00
parent 84a6aa6d73
commit a2d12f178f
2 changed files with 108 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
README.md
View File

@ -41,7 +41,7 @@ Usage
----- -----
```sh ```sh
$ tippecanoe -o file.mbtiles [file.json file.geobuf ...] $ tippecanoe -o file.mbtiles [options] [file.json file.geobuf ...]
``` ```
If no files are specified, it reads GeoJSON from the standard input. If no files are specified, it reads GeoJSON from the standard input.
@ -52,23 +52,39 @@ You can concatenate multiple GeoJSON features or files together,
and it will parse out the features and ignore whatever other objects and it will parse out the features and ignore whatever other objects
it encounters. it encounters.
Docker Image Try this first
------------ --------------
A tippecanoe Docker image can be built from source and executed as a task to If you aren't sure what options to use, try this:
automatically install dependencies and allow tippecanoe to run on any system
supported by Docker.
```docker ```sh
$ docker build -t tippecanoe:latest . $ tippecanoe -o out.mbtiles -zg --drop-densest-as-needed in.geojson
$ docker run -it --rm \
-v /tiledata:/data \
tippecanoe:latest \
tippecanoe --output=/data/output.mbtiles /data/example.geojson
``` ```
The commands above will build a Docker image from the source and compile the The `-zg` option will make Tippecanoe choose a maximum zoom level that should be
latest version. The image supports all tippecanoe flags and options. high enough to reflect the precision of the original data. (If it turns out still
not to be as detailed as you want, use `-z` manually with a higher number.)
If the tiles come out too big, the `--drop-densest-as-needed` option will make
Tippecanoe try dropping what should be the least visible features at each zoom level.
(If it drops too many features, use `-x` to leave out some feature attributes that
you didn't really need.)
Examples
--------
Create a tileset of TIGER roads for Alameda County, to zoom level 13, with a custom layer name and description:
```sh
$ tippecanoe -o alameda.mbtiles -l alameda -n "Alameda County from TIGER" -z13 tl_2014_06001_roads.json
```
Create a tileset of all TIGER roads, at only zoom level 12, but with higher detail than normal,
with a custom layer name and description, and leaving out the `LINEARID` and `RTTYP` attributes:
```
$ cat tiger/tl_2014_*_roads.json | tippecanoe -o tiger.mbtiles -l roads -n "All TIGER roads, one zoom" -z12 -Z12 -d14 -x LINEARID -x RTTYP
```
Options Options
------- -------
@ -116,7 +132,7 @@ If your input is formatted as newline-delimited GeoJSON, use `-P` to make input
### Parallel processing of input ### Parallel processing of input
* `-P` or `--read-parallel`: Use multiple threads to read different parts of each input file at once. * `-P` or `--read-parallel`: Use multiple threads to read different parts of each GeoJSON input file at once.
This will only work if the input is line-delimited JSON with each Feature on its This will only work if the input is line-delimited JSON with each Feature on its
own line, because it knows nothing of the top-level structure around the Features. Spurious "EOF" error own line, because it knows nothing of the top-level structure around the Features. Spurious "EOF" error
messages may result otherwise. messages may result otherwise.
@ -127,6 +143,8 @@ If the input file begins with the [RFC 8142](https://tools.ietf.org/html/rfc8142
parallel processing of input will be invoked automatically, splitting at record separators rather parallel processing of input will be invoked automatically, splitting at record separators rather
than at all newlines. than at all newlines.
Parallel processing will also be automatic if the input file is in Geobuf format.
### Projection of input ### Projection of input
* `-s` _projection_ or `--projection=`_projection_: Specify the projection of the input data. Currently supported are `EPSG:4326` (WGS84, the default) and `EPSG:3857` (Web Mercator). In general you should use WGS84 for your input files if at all possible. * `-s` _projection_ or `--projection=`_projection_: Specify the projection of the input data. Currently supported are `EPSG:4326` (WGS84, the default) and `EPSG:3857` (Web Mercator). In general you should use WGS84 for your input files if at all possible.
@ -142,8 +160,8 @@ than at all newlines.
### Tile resolution ### Tile resolution
* `-d` _detail_ or `--full-detail=`_detail_: Detail at max zoom level (default 12, for tile resolution of 4096) * `-d` _detail_ or `--full-detail=`_detail_: Detail at max zoom level (default 12, for tile resolution of 2^12=4096)
* `-D` _detail_ or `--low-detail=`_detail_: Detail at lower zoom levels (default 12, for tile resolution of 4096) * `-D` _detail_ or `--low-detail=`_detail_: Detail at lower zoom levels (default 12, for tile resolution of 2^12=4096)
* `-m` _detail_ or `--minimum-detail=`_detail_: Minimum detail that it will try if tiles are too big at regular detail (default 7) * `-m` _detail_ or `--minimum-detail=`_detail_: Minimum detail that it will try if tiles are too big at regular detail (default 7)
All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^32) of the size of Earth, All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^32) of the size of Earth,
@ -166,7 +184,7 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_.
Example: to find the Natural Earth countries with low `scalerank` but high `LABELRANK`: Example: to find the Natural Earth countries with low `scalerank` but high `LABELRANK`:
``` ```
tippecanoe -o filtered.mbtiles -j '{ "ne_10m_admin_0_countries": [ "all", [ "<", "scalerank", 3 ], [ ">", "LABELRANK", 5 ] ] }' ne_10m_admin_0_countries.geojson tippecanoe -z5 -o filtered.mbtiles -j '{ "ne_10m_admin_0_countries": [ "all", [ "<", "scalerank", 3 ], [ ">", "LABELRANK", 5 ] ] }' ne_10m_admin_0_countries.geojson
``` ```
### Dropping a fixed fraction of features by zoom level ### Dropping a fixed fraction of features by zoom level
@ -297,17 +315,6 @@ Environment
Tippecanoe ordinarily uses as many parallel threads as the operating system claims that CPUs are available. Tippecanoe ordinarily uses as many parallel threads as the operating system claims that CPUs are available.
You can override this number by setting the `TIPPECANOE_MAX_THREADS` environmental variable. You can override this number by setting the `TIPPECANOE_MAX_THREADS` environmental variable.
Example
-------
```sh
$ tippecanoe -o alameda.mbtiles -l alameda -n "Alameda County from TIGER" -z13 tl_2014_06001_roads.json
```
```
$ cat tiger/tl_2014_*_roads.json | tippecanoe -o tiger.mbtiles -l roads -n "All TIGER roads, one zoom" -z12 -Z12 -d14 -x LINEARID -x RTTYP
```
GeoJSON extension GeoJSON extension
----------------- -----------------
@ -437,6 +444,24 @@ sudo apt-get install -y g++-5
export CXX=g++-5 export CXX=g++-5
``` ```
Docker Image
------------
A tippecanoe Docker image can be built from source and executed as a task to
automatically install dependencies and allow tippecanoe to run on any system
supported by Docker.
```docker
$ docker build -t tippecanoe:latest .
$ docker run -it --rm \
-v /tiledata:/data \
tippecanoe:latest \
tippecanoe --output=/data/output.mbtiles /data/example.geojson
```
The commands above will build a Docker image from the source and compile the
latest version. The image supports all tippecanoe flags and options.
Examples Examples
------ ------

83
man/tippecanoe.1
View File

@ -37,7 +37,7 @@ $ brew install tippecanoe
.PP .PP
.RS .RS
.nf .nf
$ tippecanoe \-o file.mbtiles [file.json file.geobuf ...] $ tippecanoe \-o file.mbtiles [options] [file.json file.geobuf ...]
.fi .fi
.RE .RE
.PP .PP
@ -48,24 +48,42 @@ The GeoJSON features need not be wrapped in a FeatureCollection.
You can concatenate multiple GeoJSON features or files together, You can concatenate multiple GeoJSON features or files together,
and it will parse out the features and ignore whatever other objects and it will parse out the features and ignore whatever other objects
it encounters. it encounters.
.SH Docker Image .SH Try this first
.PP .PP
A tippecanoe Docker image can be built from source and executed as a task to If you aren't sure what options to use, try this:
automatically install dependencies and allow tippecanoe to run on any system
supported by Docker.
.PP .PP
.RS .RS
.nf .nf
$ docker build \-t tippecanoe:latest . $ tippecanoe \-o out.mbtiles \-zg \-\-drop\-densest\-as\-needed in.geojson
$ docker run \-it \-\-rm \\
\-v /tiledata:/data \\
tippecanoe:latest \\
tippecanoe \-\-output=/data/output.mbtiles /data/example.geojson
.fi .fi
.RE .RE
.PP .PP
The commands above will build a Docker image from the source and compile the The \fB\fC\-zg\fR option will make Tippecanoe choose a maximum zoom level that should be
latest version. The image supports all tippecanoe flags and options. high enough to reflect the precision of the original data. (If it turns out still
not to be as detailed as you want, use \fB\fC\-z\fR manually with a higher number.)
.PP
If the tiles come out too big, the \fB\fC\-\-drop\-densest\-as\-needed\fR option will make
Tippecanoe try dropping what should be the least visible features at each zoom level.
(If it drops too many features, use \fB\fC\-x\fR to leave out some feature attributes that
you didn't really need.)
.SH Examples
.PP
Create a tileset of TIGER roads for Alameda County, to zoom level 13, with a custom layer name and description:
.PP
.RS
.nf
$ tippecanoe \-o alameda.mbtiles \-l alameda \-n "Alameda County from TIGER" \-z13 tl_2014_06001_roads.json
.fi
.RE
.PP
Create a tileset of all TIGER roads, at only zoom level 12, but with higher detail than normal,
with a custom layer name and description, and leaving out the \fB\fCLINEARID\fR and \fB\fCRTTYP\fR attributes:
.PP
.RS
.nf
$ cat tiger/tl_2014_*_roads.json | tippecanoe \-o tiger.mbtiles \-l roads \-n "All TIGER roads, one zoom" \-z12 \-Z12 \-d14 \-x LINEARID \-x RTTYP
.fi
.RE
.SH Options .SH Options
.PP .PP
There are a lot of options. A lot of the time you won't want to use any of them There are a lot of options. A lot of the time you won't want to use any of them
@ -122,7 +140,7 @@ specified, the files are all merged into the single named layer, even if they tr
.SS Parallel processing of input .SS Parallel processing of input
.RS .RS
.IP \(bu 2 .IP \(bu 2
\fB\fC\-P\fR or \fB\fC\-\-read\-parallel\fR: Use multiple threads to read different parts of each input file at once. \fB\fC\-P\fR or \fB\fC\-\-read\-parallel\fR: Use multiple threads to read different parts of each GeoJSON input file at once.
This will only work if the input is line\-delimited JSON with each Feature on its This will only work if the input is line\-delimited JSON with each Feature on its
own line, because it knows nothing of the top\-level structure around the Features. Spurious "EOF" error own line, because it knows nothing of the top\-level structure around the Features. Spurious "EOF" error
messages may result otherwise. messages may result otherwise.
@ -133,6 +151,8 @@ rather than a stream that can only be read sequentially.
If the input file begins with the RFC 8142 \[la]https://tools.ietf.org/html/rfc8142\[ra] record separator, If the input file begins with the RFC 8142 \[la]https://tools.ietf.org/html/rfc8142\[ra] record separator,
parallel processing of input will be invoked automatically, splitting at record separators rather parallel processing of input will be invoked automatically, splitting at record separators rather
than at all newlines. than at all newlines.
.PP
Parallel processing will also be automatic if the input file is in Geobuf format.
.SS Projection of input .SS Projection of input
.RS .RS
.IP \(bu 2 .IP \(bu 2
@ -154,9 +174,9 @@ specified maximum zoom and to any levels added beyond that.
.SS Tile resolution .SS Tile resolution
.RS .RS
.IP \(bu 2 .IP \(bu 2
\fB\fC\-d\fR \fIdetail\fP or \fB\fC\-\-full\-detail=\fR\fIdetail\fP: Detail at max zoom level (default 12, for tile resolution of 4096) \fB\fC\-d\fR \fIdetail\fP or \fB\fC\-\-full\-detail=\fR\fIdetail\fP: Detail at max zoom level (default 12, for tile resolution of 2
.IP \(bu 2 .IP \(bu 2
\fB\fC\-D\fR \fIdetail\fP or \fB\fC\-\-low\-detail=\fR\fIdetail\fP: Detail at lower zoom levels (default 12, for tile resolution of 4096) \fB\fC\-D\fR \fIdetail\fP or \fB\fC\-\-low\-detail=\fR\fIdetail\fP: Detail at lower zoom levels (default 12, for tile resolution of 2
.IP \(bu 2 .IP \(bu 2
\fB\fC\-m\fR \fIdetail\fP or \fB\fC\-\-minimum\-detail=\fR\fIdetail\fP: Minimum detail that it will try if tiles are too big at regular detail (default 7) \fB\fC\-m\fR \fIdetail\fP or \fB\fC\-\-minimum\-detail=\fR\fIdetail\fP: Minimum detail that it will try if tiles are too big at regular detail (default 7)
.RE .RE
@ -188,7 +208,7 @@ Example: to find the Natural Earth countries with low \fB\fCscalerank\fR but hig
.PP .PP
.RS .RS
.nf .nf
tippecanoe \-o filtered.mbtiles \-j '{ "ne_10m_admin_0_countries": [ "all", [ "<", "scalerank", 3 ], [ ">", "LABELRANK", 5 ] ] }' ne_10m_admin_0_countries.geojson tippecanoe \-z5 \-o filtered.mbtiles \-j '{ "ne_10m_admin_0_countries": [ "all", [ "<", "scalerank", 3 ], [ ">", "LABELRANK", 5 ] ] }' ne_10m_admin_0_countries.geojson
.fi .fi
.RE .RE
.SS Dropping a fixed fraction of features by zoom level .SS Dropping a fixed fraction of features by zoom level
@ -363,19 +383,6 @@ tippecanoe \-o roads.mbtiles \-c 'if [ $1 \-lt 11 ]; then grep "\\"MTFCC\\": \\"
.PP .PP
Tippecanoe ordinarily uses as many parallel threads as the operating system claims that CPUs are available. Tippecanoe ordinarily uses as many parallel threads as the operating system claims that CPUs are available.
You can override this number by setting the \fB\fCTIPPECANOE_MAX_THREADS\fR environmental variable. You can override this number by setting the \fB\fCTIPPECANOE_MAX_THREADS\fR environmental variable.
.SH Example
.PP
.RS
.nf
$ tippecanoe \-o alameda.mbtiles \-l alameda \-n "Alameda County from TIGER" \-z13 tl_2014_06001_roads.json
.fi
.RE
.PP
.RS
.nf
$ cat tiger/tl_2014_*_roads.json | tippecanoe \-o tiger.mbtiles \-l roads \-n "All TIGER roads, one zoom" \-z12 \-Z12 \-d14 \-x LINEARID \-x RTTYP
.fi
.RE
.SH GeoJSON extension .SH GeoJSON extension
.PP .PP
Tippecanoe defines a GeoJSON extension that you can use to specify the minimum and/or maximum zoom level Tippecanoe defines a GeoJSON extension that you can use to specify the minimum and/or maximum zoom level
@ -519,6 +526,24 @@ sudo apt\-get install \-y g++\-5
export CXX=g++\-5 export CXX=g++\-5
.fi .fi
.RE .RE
.SH Docker Image
.PP
A tippecanoe Docker image can be built from source and executed as a task to
automatically install dependencies and allow tippecanoe to run on any system
supported by Docker.
.PP
.RS
.nf
$ docker build \-t tippecanoe:latest .
$ docker run \-it \-\-rm \\
\-v /tiledata:/data \\
tippecanoe:latest \\
tippecanoe \-\-output=/data/output.mbtiles /data/example.geojson
.fi
.RE
.PP
The commands above will build a Docker image from the source and compile the
latest version. The image supports all tippecanoe flags and options.
.SH Examples .SH Examples
.PP .PP
Check out some examples of maps made with tippecanoe \[la]MADE_WITH.md\[ra] Check out some examples of maps made with tippecanoe \[la]MADE_WITH.md\[ra]