From 79b73e63179c0bd2ea1096f4749c0048e9153962 Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Tue, 11 Apr 2017 17:24:15 -0700 Subject: [PATCH] Call out the most useful options at the start --- README.md | 34 +++++++++++++++++++++++++--------- man/tippecanoe.1 | 42 +++++++++++++++++++++++++++++------------- 2 files changed, 54 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 2ba519c6..6abf4d44 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,22 @@ it encounters. Options ------- +There are a lot of options. A lot of the time you won't want to use any of them +other than `-o` _output_`.mbtiles` to name the output file, and probably `-f` to +delete the file that already exists with that name. + +If you are mapping point features, you will often want to use `-Bg` to automatically choose +a base zoom level for dot dropping. If that doesn't work out for you, try +`-r1 --drop-fraction-as-needed` to turn off the normal dot dropping and instead +only drop features if the tiles get too big. + +If you are mapping points or polygons, you will often want to use `--drop-densest-as-needed` +to drop some of them if necessary to make the low zoom levels work. + +If your features have a lot of attributes, use `-y` to keep only the ones you really need. + +If your input is formatted as newline-delimited GeoJSON, use `-P` to make input parsing a lot faster. + ### Names of layers and tileset description and attribution * `-l` _name_ or `--layer=`_name_: Layer name (default "file" if source is file.json or output is file.mbtiles). If there are multiple input files @@ -100,7 +116,7 @@ All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^3 or about 1cm, is the smallest distinguishable distance. If _maxzoom_ + _detail_ > 32, no additional resolution is obtained than by using a smaller _maxzoom_ or _detail_. -### Feature attributes +### Filtering feature attributes * `-x` _name_ or `--exclude=`_name_: Exclude the named properties from all features * `-y` _name_ or `--include=`_name_: Include the named properties in all features, excluding all those not explicitly named @@ -119,7 +135,7 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. * `-al` or `--drop-lines`: Let "dot" dropping at lower zooms apply to lines too * `-ap` or `--drop-polygons`: Let "dot" dropping at lower zooms apply to polygons too -### Dropping a fraction of features to reduce tile size +### Dropping a fraction of features to keep under tile size limits * `-as` or `--drop-densest-as-needed`: If a tile is too large, try to reduce it to under 500K by increasing the minimum spacing between features. The discovered spacing applies to the entire zoom level. * `-ad` or `--drop-fraction-as-needed`: Dynamically drop some fraction of features from each zoom level to keep large tiles under the 500K size limit. (This is like `-pd` but applies to the entire zoom level, not to each tile.) @@ -157,13 +173,6 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. * `-ac` or `--coalesce`: Coalesce adjacent line and polygon features that have the same properties. You probably don't want to use this. * `-ar` or `--reverse`: Try reversing the directions of lines to make them coalesce and compress better. You probably don't want to use this. -### Tile sizes - - * `-M` _bytes_ or `--maximum-tile-bytes=`_bytes_: Use the specified number of _bytes_ as the maximum compressed tile size instead of 500K. - * `-pf` or `--no-feature-limit`: Don't limit tiles to 200,000 features - * `-pk` or `--no-tile-size-limit`: Don't limit tiles to 500K bytes - * `-pC` or `--no-tile-compression`: Don't compress the PBF vector tile data. - ### Adding calculated attributes * `-ag` or `--calculate-feature-density`: Add a new attribute, `tippecanoe_feature_density`, to each feature, to record how densely features are spaced in that area of the tile. You can use this attribute in the style to produce a glowing effect where points are densely packed. It can range from 0 in the sparsest areas to 255 in the densest. @@ -172,6 +181,13 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. * `-aw` or `--detect-longitude-wraparound`: Detect when adjacent points within a feature jump to the other side of the world, and try to fix the geometry. +### Setting or disabling tile size limits + + * `-M` _bytes_ or `--maximum-tile-bytes=`_bytes_: Use the specified number of _bytes_ as the maximum compressed tile size instead of 500K. + * `-pf` or `--no-feature-limit`: Don't limit tiles to 200,000 features + * `-pk` or `--no-tile-size-limit`: Don't limit tiles to 500K bytes + * `-pC` or `--no-tile-compression`: Don't compress the PBF vector tile data. + ### Temporary storage * `-t` _directory_ or `--temporary-directory=`_directory_: Put the temporary files in _directory_. diff --git a/man/tippecanoe.1 b/man/tippecanoe.1 index a28ec927..1abff630 100644 --- a/man/tippecanoe.1 +++ b/man/tippecanoe.1 @@ -49,6 +49,22 @@ You can concatenate multiple GeoJSON features or files together, and it will parse out the features and ignore whatever other objects it encounters. .SH Options +.PP +There are a lot of options. A lot of the time you won't want to use any of them +other than \fB\fC\-o\fR \fIoutput\fP\fB\fC\&.mbtiles\fR to name the output file, and probably \fB\fC\-f\fR to +delete the file that already exists with that name. +.PP +If you are mapping point features, you will often want to use \fB\fC\-Bg\fR to automatically choose +a base zoom level for dot dropping. If that doesn't work out for you, try +\fB\fC\-r1 \-\-drop\-fraction\-as\-needed\fR to turn off the normal dot dropping and instead +only drop features if the tiles get too big. +.PP +If you are mapping points or polygons, you will often want to use \fB\fC\-\-drop\-densest\-as\-needed\fR +to drop some of them if necessary to make the low zoom levels work. +.PP +If your features have a lot of attributes, use \fB\fC\-y\fR to keep only the ones you really need. +.PP +If your input is formatted as newline\-delimited GeoJSON, use \fB\fC\-P\fR to make input parsing a lot faster. .SS Names of layers and tileset description and attribution .RS .IP \(bu 2 @@ -110,7 +126,7 @@ rather than a stream that can only be read sequentially. All internal math is done in terms of a 32\-bit tile coordinate system, so 1/(2 of the size of Earth, or about 1cm, is the smallest distinguishable distance. If \fImaxzoom\fP + \fIdetail\fP > 32, no additional resolution is obtained than by using a smaller \fImaxzoom\fP or \fIdetail\fP\&. -.SS Feature attributes +.SS Filtering feature attributes .RS .IP \(bu 2 \fB\fC\-x\fR \fIname\fP or \fB\fC\-\-exclude=\fR\fIname\fP: Exclude the named properties from all features @@ -136,7 +152,7 @@ compensate for the larger marker, or \fB\fC\-Bf\fR\fInumber\fP to allow at most .IP \(bu 2 \fB\fC\-ap\fR or \fB\fC\-\-drop\-polygons\fR: Let "dot" dropping at lower zooms apply to polygons too .RE -.SS Dropping a fraction of features to reduce tile size +.SS Dropping a fraction of features to keep under tile size limits .RS .IP \(bu 2 \fB\fC\-as\fR or \fB\fC\-\-drop\-densest\-as\-needed\fR: If a tile is too large, try to reduce it to under 500K by increasing the minimum spacing between features. The discovered spacing applies to the entire zoom level. @@ -193,17 +209,6 @@ the line or polygon within one tile unit of its proper location. You can probabl .IP \(bu 2 \fB\fC\-ar\fR or \fB\fC\-\-reverse\fR: Try reversing the directions of lines to make them coalesce and compress better. You probably don't want to use this. .RE -.SS Tile sizes -.RS -.IP \(bu 2 -\fB\fC\-M\fR \fIbytes\fP or \fB\fC\-\-maximum\-tile\-bytes=\fR\fIbytes\fP: Use the specified number of \fIbytes\fP as the maximum compressed tile size instead of 500K. -.IP \(bu 2 -\fB\fC\-pf\fR or \fB\fC\-\-no\-feature\-limit\fR: Don't limit tiles to 200,000 features -.IP \(bu 2 -\fB\fC\-pk\fR or \fB\fC\-\-no\-tile\-size\-limit\fR: Don't limit tiles to 500K bytes -.IP \(bu 2 -\fB\fC\-pC\fR or \fB\fC\-\-no\-tile\-compression\fR: Don't compress the PBF vector tile data. -.RE .SS Adding calculated attributes .RS .IP \(bu 2 @@ -214,6 +219,17 @@ the line or polygon within one tile unit of its proper location. You can probabl .IP \(bu 2 \fB\fC\-aw\fR or \fB\fC\-\-detect\-longitude\-wraparound\fR: Detect when adjacent points within a feature jump to the other side of the world, and try to fix the geometry. .RE +.SS Setting or disabling tile size limits +.RS +.IP \(bu 2 +\fB\fC\-M\fR \fIbytes\fP or \fB\fC\-\-maximum\-tile\-bytes=\fR\fIbytes\fP: Use the specified number of \fIbytes\fP as the maximum compressed tile size instead of 500K. +.IP \(bu 2 +\fB\fC\-pf\fR or \fB\fC\-\-no\-feature\-limit\fR: Don't limit tiles to 200,000 features +.IP \(bu 2 +\fB\fC\-pk\fR or \fB\fC\-\-no\-tile\-size\-limit\fR: Don't limit tiles to 500K bytes +.IP \(bu 2 +\fB\fC\-pC\fR or \fB\fC\-\-no\-tile\-compression\fR: Don't compress the PBF vector tile data. +.RE .SS Temporary storage .RS .IP \(bu 2