From bb365bde4450cfd94714f39a3a3476cf242b711c Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Tue, 11 Apr 2017 16:32:32 -0700 Subject: [PATCH 1/6] Reformatting README --- README.md | 66 +++++++++++++++++++++++++++---------------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index d9b80788..5db8f94a 100644 --- a/README.md +++ b/README.md @@ -57,23 +57,23 @@ Options ### Naming - * -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 - specified, the files are all merged into the single named layer, even if they try to specify individual names with -L. - * -L _name_:_file.json_ or --named-layer=_name_:_file.json_: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like -L _name_:<(cat dir/*.json) to specify a layer name for the output of streamed input. - * -n _name_ or --name=_name_: Human-readable name for the tileset (default file.json) - * -A _text_ or --attribution=_text_: Attribution (HTML) to be shown with maps that use data from this tileset. - * -N _description_ or --description=_description_: Description for the tileset (default file.mbtiles) + * `-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 + specified, the files are all merged into the single named layer, even if they try to specify individual names with `-L`. + * `-L` _name_`:`_file.json_ or `--named-layer=`_name_`:`_file.json_: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like `-L` _name_`:<(cat dir/*.json)` to specify a layer name for the output of streamed input. + * `-n` _name_ or `--name=`_name_: Human-readable name for the tileset (default file.json) + * `-A` _text_ or `--attribution=`_text_: Attribution (HTML) to be shown with maps that use data from this tileset. + * `-N` _description_ or `--description=`_description_: Description for the tileset (default file.mbtiles) ### File control - * -o _file_.mbtiles or --output=_file_.mbtiles: Name the output file. - * -e _directory_ or --output-directory=_directory_: Write tiles to the specified *directory* instead of to an mbtiles file. - * -f or --force: Delete the mbtiles file if it already exists instead of giving an error - * -F or --allow-existing: Proceed (without deleting existing data) if the metadata or tiles table already exists + * `-o` _file_`.mbtiles` or `--output=`_file_`.mbtiles`: Name the output file. + * `-e` _directory_ or `--output-to-directory`=_directory_: Write tiles to the specified *directory* instead of to an mbtiles file. + * `-f` or `--force`: Delete the mbtiles file if it already exists instead of giving an error + * `-F` or `--allow-existing`: Proceed (without deleting existing data) if the metadata or tiles table already exists or if metadata fields can't be set - * -t _directory_ or --temporary-directory=_directory_: Put the temporary files in _directory_. + * `-t` _directory_ or `--temporary-directory=`_directory_: Put the temporary files in _directory_. If you don't specify, it will use `/tmp`. - * -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 input file at once. 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 messages may result otherwise. @@ -82,18 +82,18 @@ Options ### Zoom levels and resolution - * -z _zoom_ or --maximum-zoom=_zoom_: Maxzoom: the highest zoom level for which tiles are generated (default 14) - * -Z _zoom_ or --minimum-zoom=_zoom_: Minzoom: the lowest zoom level for which tiles are generated (default 0) - * -B _zoom_ or --base-zoom=_zoom_: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). - If you use -Bg, it will guess a zoom level that will keep at most 50,000 features in the densest tile. - You can also specify a marker-width with -Bg*width* to allow fewer features in the densest tile to - compensate for the larger marker, or -Bf*number* to allow at most *number* features in the densest tile. - * -d _detail_ or --full-detail=_detail_: Detail at max zoom level (default 12, for tile resolution of 4096) - * -D _detail_ or --low-detail=_detail_: Detail at lower zoom levels (default 12, for tile resolution of 4096) - * -m _detail_ or --minimum-detail=_detail_: Minimum detail that it will try if tiles are too big at regular detail (default 7) - * -b _pixels_ or --buffer=_pixels_: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"--1/256th of the tile width or height. (default 5) - * -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). - * -M _bytes_ or --maximum-tile-bytes=_bytes_: Use the specified number of _bytes_ as the maximum compressed tile size instead of 500K. + * `-z` _zoom_ or `--maximum-zoom=`_zoom_: Maxzoom: the highest zoom level for which tiles are generated (default 14) + * `-Z` _zoom_ or `--minimum-zoom=`_zoom_: Minzoom: the lowest zoom level for which tiles are generated (default 0) + * `-B` _zoom_ or `--base-zoom=`_zoom_: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). + If you use `-Bg`, it will guess a zoom level that will keep at most 50,000 features in the densest tile. + You can also specify a marker-width with `-Bg`*width* to allow fewer features in the densest tile to + compensate for the larger marker, or `-Bf`*number* to allow at most *number* features in the densest tile. + * `-d` _detail_ or `--full-detail=`_detail_: Detail at max zoom level (default 12, for tile resolution of 4096) + * `-D` _detail_ or `--low-detail=`_detail_: Detail at lower zoom levels (default 12, for tile resolution of 4096) + * `-m` _detail_ or `--minimum-detail=`_detail_: Minimum detail that it will try if tiles are too big at regular detail (default 7) + * `-b` _pixels_ or `--buffer=`_pixels_: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"—1/256th of the tile width or height. (default 5) + * `-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). + * `-M` _bytes_ or `--maximum-tile-bytes=`_bytes_: Use the specified number of _bytes_ as the maximum compressed tile size instead of 500K. All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^32) of the size of Earth, or about 1cm, is the smallest distinguishable distance. If _maxzoom_ + _detail_ > 32, no additional @@ -101,21 +101,21 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. ### Properties - * -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 - * -X or --exclude-all: Exclude all properties and encode only geometries + * `-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 + * `-X` or `--exclude-all`: Exclude all properties and encode only geometries ### Point simplification - * -r _rate_ or --drop-rate=_rate_: Rate at which dots are dropped at zoom levels below basezoom (default 2.5). - If you use -rg, it will guess a drop rate that will keep at most 50,000 features in the densest tile. - You can also specify a marker-width with -rg*width* to allow fewer features in the densest tile to - compensate for the larger marker, or -rf*number* to allow at most *number* features in the densest tile. - * -g _gamma_ or --gamma=_gamma_: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number. + * `-r` _rate_ or `--drop-rate=`_rate_: Rate at which dots are dropped at zoom levels below basezoom (default 2.5). + If you use `-rg`, it will guess a drop rate that will keep at most 50,000 features in the densest tile. + You can also specify a marker-width with `-rg`*width* to allow fewer features in the densest tile to + compensate for the larger marker, or `-rf`*number* to allow at most *number* features in the densest tile. + * `-g` _gamma_ or `--gamma=_gamma`_: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number. ### Line and polygon simplification - * -S _scale_ or --simplification=_scale_: Multiply the tolerance for line and polygon simplification by _scale_. The standard tolerance tries to keep + * `-S` _scale_ or `--simplification=`_scale_: Multiply the tolerance for line and polygon simplification by _scale_. The standard tolerance tries to keep the line or polygon within one tile unit of its proper location. You can probably go up to about 10 without too much visible difference. ### Doing more From 63ea7bdc4e96adfdee5989f7839110cc18c5ccc9 Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Tue, 11 Apr 2017 16:51:56 -0700 Subject: [PATCH 2/6] Try to reorder options into some more readable organization --- README.md | 121 +++++++++++++++---------- man/tippecanoe.1 | 224 ++++++++++++++++++++++++++--------------------- 2 files changed, 199 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 5db8f94a..6b86348c 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ it encounters. Options ------- -### Naming +### 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 specified, the files are all merged into the single named layer, even if they try to specify individual names with `-L`. @@ -64,15 +64,16 @@ Options * `-A` _text_ or `--attribution=`_text_: Attribution (HTML) to be shown with maps that use data from this tileset. * `-N` _description_ or `--description=`_description_: Description for the tileset (default file.mbtiles) -### File control +### Output tileset * `-o` _file_`.mbtiles` or `--output=`_file_`.mbtiles`: Name the output file. * `-e` _directory_ or `--output-to-directory`=_directory_: Write tiles to the specified *directory* instead of to an mbtiles file. * `-f` or `--force`: Delete the mbtiles file if it already exists instead of giving an error * `-F` or `--allow-existing`: Proceed (without deleting existing data) if the metadata or tiles table already exists or if metadata fields can't be set - * `-t` _directory_ or `--temporary-directory=`_directory_: Put the temporary files in _directory_. - If you don't specify, it will use `/tmp`. + +### Parallel processing of input + * `-P` or `--read-parallel`: Use multiple threads to read different parts of each input file at once. 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 @@ -80,7 +81,7 @@ Options Performance will be better if the input is a named file that can be mapped into memory rather than a stream that can only be read sequentially. -### Zoom levels and resolution +### Zoom levels * `-z` _zoom_ or `--maximum-zoom=`_zoom_: Maxzoom: the highest zoom level for which tiles are generated (default 14) * `-Z` _zoom_ or `--minimum-zoom=`_zoom_: Minzoom: the lowest zoom level for which tiles are generated (default 0) @@ -88,12 +89,13 @@ Options If you use `-Bg`, it will guess a zoom level that will keep at most 50,000 features in the densest tile. You can also specify a marker-width with `-Bg`*width* to allow fewer features in the densest tile to compensate for the larger marker, or `-Bf`*number* to allow at most *number* features in the densest tile. + +### Tile resolution + * `-d` _detail_ or `--full-detail=`_detail_: Detail at max zoom level (default 12, for tile resolution of 4096) * `-D` _detail_ or `--low-detail=`_detail_: Detail at lower zoom levels (default 12, for tile resolution of 4096) * `-m` _detail_ or `--minimum-detail=`_detail_: Minimum detail that it will try if tiles are too big at regular detail (default 7) - * `-b` _pixels_ or `--buffer=`_pixels_: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"—1/256th of the tile width or height. (default 5) * `-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). - * `-M` _bytes_ or `--maximum-tile-bytes=`_bytes_: Use the specified number of _bytes_ as the maximum compressed tile size instead of 500K. All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^32) of the size of Earth, or about 1cm, is the smallest distinguishable distance. If _maxzoom_ + _detail_ > 32, no additional @@ -105,51 +107,76 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. * `-y` _name_ or `--include=`_name_: Include the named properties in all features, excluding all those not explicitly named * `-X` or `--exclude-all`: Exclude all properties and encode only geometries -### Point simplification +### Dropping a fixed fraction of features by zoom level * `-r` _rate_ or `--drop-rate=`_rate_: Rate at which dots are dropped at zoom levels below basezoom (default 2.5). If you use `-rg`, it will guess a drop rate that will keep at most 50,000 features in the densest tile. You can also specify a marker-width with `-rg`*width* to allow fewer features in the densest tile to compensate for the larger marker, or `-rf`*number* to allow at most *number* features in the densest tile. + * `-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 + + * `-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.) + * `-an` or `--drop-smallest-as-needed`: Dynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features. + * `-pd` or `--force-feature-limit`: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like `-ad` but applies to each tile individually, not to the entire zoom level.) + +### Dropping tightly overlapping features + * `-g` _gamma_ or `--gamma=_gamma`_: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number. + * `-aG` or `--increase-gamma-as-needed`: If a tile is too large, try to reduce it to under 500K by increasing the `-g` gamma. The discovered gamma applies to the entire zoom level. ### Line and polygon simplification * `-S` _scale_ or `--simplification=`_scale_: Multiply the tolerance for line and polygon simplification by _scale_. The standard tolerance tries to keep the line or polygon within one tile unit of its proper location. You can probably go up to about 10 without too much visible difference. + * `-ps` or `--no-line-simplification`: Don't simplify lines and polygons + * `-pS` or `--simplify-only-low-zooms`: Don't simplify lines and polygons at maxzoom (but do simplify at lower zooms) + * `-pt` or `--no-tiny-polygon-reduction`: Don't combine the area of very small polygons into small squares that represent their combined area. -### Doing more +### Controlling clipping to tile boundaries - * -ac or --coalesce: Coalesce adjacent line and polygon features that have the same properties. - Note that when overlapping polygons are coalesced, the overlapping region is treated as a hole, - which may not be what you want. - * -ar or --reverse: Try reversing the directions of lines to make them coalesce and compress better - * -ao or --reorder: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce - * -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 - * -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. - * -ab or --detect-shared-borders: In the manner of [TopoJSON](https://github.com/mbostock/topojson/wiki/Introduction), detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. - * -aG or --increase-gamma-as-needed: If a tile is too large, try to reduce it to under 500K by increasing the `-g` gamma. The discovered gamma applies to the entire zoom level. - * -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.) - * -an or --drop-smallest-as-needed: Dynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features. - * -aL or --grid-low-zooms: At all zoom levels below _maxzoom_, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably `-D8`. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. - * -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. - -### Doing less - - * -ps or --no-line-simplification: Don't simplify lines - * -pS or --simplify-only-low-zooms: Don't simplify lines at maxzoom (but do simplify at lower zooms) - * -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 - * -pd or --force-feature-limit: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like `-ad` but applies to each tile individually, not to the entire zoom level.) - * -pi or --preserve-input-order: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot-dropping is still geographic, which means it also undoes -ao). - * -pp or --no-polygon-splitting: This no longer has any effect. + * `-b` _pixels_ or `--buffer=`_pixels_: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"—1/256th of the tile width or height. (default 5) * -pc or --no-clipping: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons. * -pD or --no-duplication: As with --no-clipping, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. - * -pt or --no-tiny-polygon-reduction: Don't combine the area of very small polygons into small squares that represent their combined area. - * -pC or --no-tile-compression: Don't compress the PBF vector tile data. - * -q or --quiet: Work quietly instead of reporting progress + +### Attempts to improve shared polygon boundaries + + * `-ab` or `--detect-shared-borders`: In the manner of [TopoJSON](https://github.com/mbostock/topojson/wiki/Introduction), detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. + * `-aL` or `--grid-low-zooms`: At all zoom levels below _maxzoom_, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably `-D8`. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. + +### Reordering features within each tile + + * `-pi` or `--preserve-input-order`: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot-dropping is still geographic, which means it also undoes -ao). + * `-ao` or `--reorder`: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce + * `-ac` or `--coalesce`: Coalesce adjacent line and polygon features that have the same properties. + * `-ar` or `--reverse`: Try reversing the directions of lines to make them coalesce and compress better + +### 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. + +### Trying to correct bad source geometry + + * `-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. + +### Temporary storage + + * `-t` _directory_ or `--temporary-directory=`_directory_: Put the temporary files in _directory_. + If you don't specify, it will use `/tmp`. + +### Progress indicator + + * `-q` or `--quiet`: Work quietly instead of reporting progress Environment ----------- @@ -320,12 +347,12 @@ the same tiles, the layers or tiles are merged. The options are: - * -o *out.mbtiles*: Write the new tiles to the specified .mbtiles file - * -f: Remove *out.mbtiles* if it already exists - * -c *match.csv*: Use *match.csv* as the source for new attributes to join to the features. The first line of the file should be the key names; the other lines are values. The first column is the one to match against the existing features; the other columns are the new data to add. - * -x *key*: Remove attributes of type *key* from the output. You can use this to remove the field you are matching against if you no longer need it after joining, or to remove any other attributes you don't want. - * -i: Only include features that matched the CSV. - * -pk: Don't skip tiles larger than 500K. + * `-o` *out.mbtiles*: Write the new tiles to the specified .mbtiles file + * `-f`: Remove *out.mbtiles* if it already exists + * `-c` *match*`.csv`: Use *match*`.csv` as the source for new attributes to join to the features. The first line of the file should be the key names; the other lines are values. The first column is the one to match against the existing features; the other columns are the new data to add. + * `-x` *key*: Remove attributes of type *key* from the output. You can use this to remove the field you are matching against if you no longer need it after joining, or to remove any other attributes you don't want. + * `-i`: Only include features that matched the CSV. + * `-pk`: Don't skip tiles larger than 500K. Because tile-join just copies the geometries to the new .mbtiles without processing them (except to rescale the extents if necessary), @@ -409,7 +436,7 @@ resolutions. ### Options - * -t _projection_: Specify the projection of the output data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator). - * -z _maxzoom_: Specify the highest zoom level to decode from the tileset - * -Z _minzoom_: Specify the lowest zoom level to decode from the tileset - * -l _layer_: Decode only layers with the specified names. (Multiple `-l` options can be specified.) + * `-t` _projection_: Specify the projection of the output data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator). + * `-z` _maxzoom_: Specify the highest zoom level to decode from the tileset + * `-Z` _minzoom_: Specify the lowest zoom level to decode from the tileset + * `-l` _layer_: Decode only layers with the specified names. (Multiple `-l` options can be specified.) diff --git a/man/tippecanoe.1 b/man/tippecanoe.1 index 37a44683..8a3628c0 100644 --- a/man/tippecanoe.1 +++ b/man/tippecanoe.1 @@ -49,65 +49,64 @@ 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 -.SS Naming +.SS Names of layers and tileset description and attribution .RS .IP \(bu 2 -\-l \fIname\fP or \-\-layer=\fIname\fP: Layer name (default "file" if source is file.json or output is file.mbtiles). If there are multiple input files -specified, the files are all merged into the single named layer, even if they try to specify individual names with \-L. +\fB\fC\-l\fR \fIname\fP or \fB\fC\-\-layer=\fR\fIname\fP: Layer name (default "file" if source is file.json or output is file.mbtiles). If there are multiple input files +specified, the files are all merged into the single named layer, even if they try to specify individual names with \fB\fC\-L\fR\&. .IP \(bu 2 -\-L \fIname\fP:\fIfile.json\fP or \-\-named\-layer=\fIname\fP:\fIfile.json\fP: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like \-L \fIname\fP:<(cat dir/*.json) to specify a layer name for the output of streamed input. +\fB\fC\-L\fR \fIname\fP\fB\fC:\fR\fIfile.json\fP or \fB\fC\-\-named\-layer=\fR\fIname\fP\fB\fC:\fR\fIfile.json\fP: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like \fB\fC\-L\fR \fIname\fP\fB\fC:<(cat dir/*.json)\fR to specify a layer name for the output of streamed input. .IP \(bu 2 -\-n \fIname\fP or \-\-name=\fIname\fP: Human\-readable name for the tileset (default file.json) +\fB\fC\-n\fR \fIname\fP or \fB\fC\-\-name=\fR\fIname\fP: Human\-readable name for the tileset (default file.json) .IP \(bu 2 -\-A \fItext\fP or \-\-attribution=\fItext\fP: Attribution (HTML) to be shown with maps that use data from this tileset. +\fB\fC\-A\fR \fItext\fP or \fB\fC\-\-attribution=\fR\fItext\fP: Attribution (HTML) to be shown with maps that use data from this tileset. .IP \(bu 2 -\-N \fIdescription\fP or \-\-description=\fIdescription\fP: Description for the tileset (default file.mbtiles) +\fB\fC\-N\fR \fIdescription\fP or \fB\fC\-\-description=\fR\fIdescription\fP: Description for the tileset (default file.mbtiles) .RE -.SS File control +.SS Output tileset .RS .IP \(bu 2 -\-o \fIfile\fP\&.mbtiles or \-\-output=\fIfile\fP\&.mbtiles: Name the output file. +\fB\fC\-o\fR \fIfile\fP\fB\fC\&.mbtiles\fR or \fB\fC\-\-output=\fR\fIfile\fP\fB\fC\&.mbtiles\fR: Name the output file. .IP \(bu 2 -\-e \fIdirectory\fP or \-\-output\-directory=\fIdirectory\fP: Write tiles to the specified \fIdirectory\fP instead of to an mbtiles file. +\fB\fC\-e\fR \fIdirectory\fP or \fB\fC\-\-output\-to\-directory\fR=\fIdirectory\fP: Write tiles to the specified \fIdirectory\fP instead of to an mbtiles file. .IP \(bu 2 -\-f or \-\-force: Delete the mbtiles file if it already exists instead of giving an error +\fB\fC\-f\fR or \fB\fC\-\-force\fR: Delete the mbtiles file if it already exists instead of giving an error .IP \(bu 2 -\-F or \-\-allow\-existing: Proceed (without deleting existing data) if the metadata or tiles table already exists +\fB\fC\-F\fR or \fB\fC\-\-allow\-existing\fR: Proceed (without deleting existing data) if the metadata or tiles table already exists or if metadata fields can't be set +.RE +.SS Parallel processing of input +.RS .IP \(bu 2 -\-t \fIdirectory\fP or \-\-temporary\-directory=\fIdirectory\fP: Put the temporary files in \fIdirectory\fP\&. -If you don't specify, it will use \fB\fC/tmp\fR\&. -.IP \(bu 2 -\-P or \-\-read\-parallel: 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 input file at once. 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 messages may result otherwise. Performance will be better if the input is a named file that can be mapped into memory rather than a stream that can only be read sequentially. .RE -.SS Zoom levels and resolution +.SS Zoom levels .RS .IP \(bu 2 -\-z \fIzoom\fP or \-\-maximum\-zoom=\fIzoom\fP: Maxzoom: the highest zoom level for which tiles are generated (default 14) +\fB\fC\-z\fR \fIzoom\fP or \fB\fC\-\-maximum\-zoom=\fR\fIzoom\fP: Maxzoom: the highest zoom level for which tiles are generated (default 14) .IP \(bu 2 -\-Z \fIzoom\fP or \-\-minimum\-zoom=\fIzoom\fP: Minzoom: the lowest zoom level for which tiles are generated (default 0) +\fB\fC\-Z\fR \fIzoom\fP or \fB\fC\-\-minimum\-zoom=\fR\fIzoom\fP: Minzoom: the lowest zoom level for which tiles are generated (default 0) .IP \(bu 2 -\-B \fIzoom\fP or \-\-base\-zoom=\fIzoom\fP: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). -If you use \-Bg, it will guess a zoom level that will keep at most 50,000 features in the densest tile. -You can also specify a marker\-width with \-Bg\fIwidth\fP to allow fewer features in the densest tile to -compensate for the larger marker, or \-Bf\fInumber\fP to allow at most \fInumber\fP features in the densest tile. +\fB\fC\-B\fR \fIzoom\fP or \fB\fC\-\-base\-zoom=\fR\fIzoom\fP: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). +If you use \fB\fC\-Bg\fR, it will guess a zoom level that will keep at most 50,000 features in the densest tile. +You can also specify a marker\-width with \fB\fC\-Bg\fR\fIwidth\fP to allow fewer features in the densest tile to +compensate for the larger marker, or \fB\fC\-Bf\fR\fInumber\fP to allow at most \fInumber\fP features in the densest tile. +.RE +.SS Tile resolution +.RS .IP \(bu 2 -\-d \fIdetail\fP or \-\-full\-detail=\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 4096) .IP \(bu 2 -\-D \fIdetail\fP or \-\-low\-detail=\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 4096) .IP \(bu 2 -\-m \fIdetail\fP or \-\-minimum\-detail=\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) .IP \(bu 2 -\-b \fIpixels\fP or \-\-buffer=\fIpixels\fP: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"\-\-1/256th of the tile width or height. (default 5) -.IP \(bu 2 -\-s \fIprojection\fP or \-\-projection=\fIprojection\fP: Specify the projection of the input data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator). -.IP \(bu 2 -\-M \fIbytes\fP or \-\-maximum\-tile\-bytes=\fIbytes\fP: Use the specified number of \fIbytes\fP as the maximum compressed tile size instead of 500K. +\fB\fC\-s\fR \fIprojection\fP or \fB\fC\-\-projection=\fR\fIprojection\fP: Specify the projection of the input data. Currently supported are \fB\fCEPSG:4326\fR (WGS84, the default) and \fB\fCEPSG:3857\fR (Web Mercator). .RE .PP All internal math is done in terms of a 32\-bit tile coordinate system, so 1/(2 of the size of Earth, @@ -116,85 +115,112 @@ resolution is obtained than by using a smaller \fImaxzoom\fP or \fIdetail\fP\&. .SS Properties .RS .IP \(bu 2 -\-x \fIname\fP or \-\-exclude=\fIname\fP: Exclude the named properties from all features +\fB\fC\-x\fR \fIname\fP or \fB\fC\-\-exclude=\fR\fIname\fP: Exclude the named properties from all features .IP \(bu 2 -\-y \fIname\fP or \-\-include=\fIname\fP: Include the named properties in all features, excluding all those not explicitly named +\fB\fC\-y\fR \fIname\fP or \fB\fC\-\-include=\fR\fIname\fP: Include the named properties in all features, excluding all those not explicitly named .IP \(bu 2 -\-X or \-\-exclude\-all: Exclude all properties and encode only geometries +\fB\fC\-X\fR or \fB\fC\-\-exclude\-all\fR: Exclude all properties and encode only geometries .RE -.SS Point simplification +.SS Dropping a fixed fraction of features by zoom level .RS .IP \(bu 2 -\-r \fIrate\fP or \-\-drop\-rate=\fIrate\fP: Rate at which dots are dropped at zoom levels below basezoom (default 2.5). -If you use \-rg, it will guess a drop rate that will keep at most 50,000 features in the densest tile. -You can also specify a marker\-width with \-rg\fIwidth\fP to allow fewer features in the densest tile to -compensate for the larger marker, or \-rf\fInumber\fP to allow at most \fInumber\fP features in the densest tile. +\fB\fC\-r\fR \fIrate\fP or \fB\fC\-\-drop\-rate=\fR\fIrate\fP: Rate at which dots are dropped at zoom levels below basezoom (default 2.5). +If you use \fB\fC\-rg\fR, it will guess a drop rate that will keep at most 50,000 features in the densest tile. +You can also specify a marker\-width with \fB\fC\-rg\fR\fIwidth\fP to allow fewer features in the densest tile to +compensate for the larger marker, or \fB\fC\-rf\fR\fInumber\fP to allow at most \fInumber\fP features in the densest tile. .IP \(bu 2 -\-g \fIgamma\fP or \-\-gamma=\fIgamma\fP: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number. +\fB\fC\-al\fR or \fB\fC\-\-drop\-lines\fR: Let "dot" dropping at lower zooms apply to lines too +.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 +.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. +.IP \(bu 2 +\fB\fC\-ad\fR or \fB\fC\-\-drop\-fraction\-as\-needed\fR: Dynamically drop some fraction of features from each zoom level to keep large tiles under the 500K size limit. (This is like \fB\fC\-pd\fR but applies to the entire zoom level, not to each tile.) +.IP \(bu 2 +\fB\fC\-an\fR or \fB\fC\-\-drop\-smallest\-as\-needed\fR: Dynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features. +.IP \(bu 2 +\fB\fC\-pd\fR or \fB\fC\-\-force\-feature\-limit\fR: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like \fB\fC\-ad\fR but applies to each tile individually, not to the entire zoom level.) +.RE +.SS Dropping tightly overlapping features +.RS +.IP \(bu 2 +\fB\fC\-g\fR \fIgamma\fP or \fB\fC\-\-gamma=_gamma\fR_: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number. +.IP \(bu 2 +\fB\fC\-aG\fR or \fB\fC\-\-increase\-gamma\-as\-needed\fR: If a tile is too large, try to reduce it to under 500K by increasing the \fB\fC\-g\fR gamma. The discovered gamma applies to the entire zoom level. .RE .SS Line and polygon simplification .RS .IP \(bu 2 -\-S \fIscale\fP or \-\-simplification=\fIscale\fP: Multiply the tolerance for line and polygon simplification by \fIscale\fP\&. The standard tolerance tries to keep +\fB\fC\-S\fR \fIscale\fP or \fB\fC\-\-simplification=\fR\fIscale\fP: Multiply the tolerance for line and polygon simplification by \fIscale\fP\&. The standard tolerance tries to keep the line or polygon within one tile unit of its proper location. You can probably go up to about 10 without too much visible difference. +.IP \(bu 2 +\fB\fC\-ps\fR or \fB\fC\-\-no\-line\-simplification\fR: Don't simplify lines and polygons +.IP \(bu 2 +\fB\fC\-pS\fR or \fB\fC\-\-simplify\-only\-low\-zooms\fR: Don't simplify lines and polygons at maxzoom (but do simplify at lower zooms) +.IP \(bu 2 +\fB\fC\-pt\fR or \fB\fC\-\-no\-tiny\-polygon\-reduction\fR: Don't combine the area of very small polygons into small squares that represent their combined area. .RE -.SS Doing more +.SS Controlling clipping to tile boundaries .RS .IP \(bu 2 -\-ac or \-\-coalesce: Coalesce adjacent line and polygon features that have the same properties. -Note that when overlapping polygons are coalesced, the overlapping region is treated as a hole, -which may not be what you want. -.IP \(bu 2 -\-ar or \-\-reverse: Try reversing the directions of lines to make them coalesce and compress better -.IP \(bu 2 -\-ao or \-\-reorder: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce -.IP \(bu 2 -\-al or \-\-drop\-lines: Let "dot" dropping at lower zooms apply to lines too -.IP \(bu 2 -\-ap or \-\-drop\-polygons: Let "dot" dropping at lower zooms apply to polygons too -.IP \(bu 2 -\-ag or \-\-calculate\-feature\-density: Add a new attribute, \fB\fCtippecanoe_feature_density\fR, 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. -.IP \(bu 2 -\-ab or \-\-detect\-shared\-borders: In the manner of TopoJSON \[la]https://github.com/mbostock/topojson/wiki/Introduction\[ra], detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. -.IP \(bu 2 -\-aG or \-\-increase\-gamma\-as\-needed: If a tile is too large, try to reduce it to under 500K by increasing the \fB\fC\-g\fR gamma. The discovered gamma applies to the entire zoom level. -.IP \(bu 2 -\-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. -.IP \(bu 2 -\-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 \fB\fC\-pd\fR but applies to the entire zoom level, not to each tile.) -.IP \(bu 2 -\-an or \-\-drop\-smallest\-as\-needed: Dynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features. -.IP \(bu 2 -\-aL or \-\-grid\-low\-zooms: At all zoom levels below \fImaxzoom\fP, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably \fB\fC\-D8\fR\&. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. -.IP \(bu 2 -\-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. -.RE -.SS Doing less -.RS -.IP \(bu 2 -\-ps or \-\-no\-line\-simplification: Don't simplify lines -.IP \(bu 2 -\-pS or \-\-simplify\-only\-low\-zooms: Don't simplify lines at maxzoom (but do simplify at lower zooms) -.IP \(bu 2 -\-pf or \-\-no\-feature\-limit: Don't limit tiles to 200,000 features -.IP \(bu 2 -\-pk or \-\-no\-tile\-size\-limit: Don't limit tiles to 500K bytes -.IP \(bu 2 -\-pd or \-\-force\-feature\-limit: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like \fB\fC\-ad\fR but applies to each tile individually, not to the entire zoom level.) -.IP \(bu 2 -\-pi or \-\-preserve\-input\-order: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot\-dropping is still geographic, which means it also undoes \-ao). -.IP \(bu 2 -\-pp or \-\-no\-polygon\-splitting: This no longer has any effect. +\fB\fC\-b\fR \fIpixels\fP or \fB\fC\-\-buffer=\fR\fIpixels\fP: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"—1/256th of the tile width or height. (default 5) .IP \(bu 2 \-pc or \-\-no\-clipping: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons. .IP \(bu 2 \-pD or \-\-no\-duplication: As with \-\-no\-clipping, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. +.RE +.SS Attempts to improve shared polygon boundaries +.RS .IP \(bu 2 -\-pt or \-\-no\-tiny\-polygon\-reduction: Don't combine the area of very small polygons into small squares that represent their combined area. +\fB\fC\-ab\fR or \fB\fC\-\-detect\-shared\-borders\fR: In the manner of TopoJSON \[la]https://github.com/mbostock/topojson/wiki/Introduction\[ra], detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. .IP \(bu 2 -\-pC or \-\-no\-tile\-compression: Don't compress the PBF vector tile data. +\fB\fC\-aL\fR or \fB\fC\-\-grid\-low\-zooms\fR: At all zoom levels below \fImaxzoom\fP, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably \fB\fC\-D8\fR\&. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. +.RE +.SS Reordering features within each tile +.RS .IP \(bu 2 -\-q or \-\-quiet: Work quietly instead of reporting progress +\fB\fC\-pi\fR or \fB\fC\-\-preserve\-input\-order\fR: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot\-dropping is still geographic, which means it also undoes \-ao). +.IP \(bu 2 +\fB\fC\-ao\fR or \fB\fC\-\-reorder\fR: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce +.IP \(bu 2 +\fB\fC\-ac\fR or \fB\fC\-\-coalesce\fR: Coalesce adjacent line and polygon features that have the same properties. +.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 +.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 +\fB\fC\-ag\fR or \fB\fC\-\-calculate\-feature\-density\fR: Add a new attribute, \fB\fCtippecanoe_feature_density\fR, 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. +.RE +.SS Trying to correct bad source geometry +.RS +.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 Temporary storage +.RS +.IP \(bu 2 +\fB\fC\-t\fR \fIdirectory\fP or \fB\fC\-\-temporary\-directory=\fR\fIdirectory\fP: Put the temporary files in \fIdirectory\fP\&. +If you don't specify, it will use \fB\fC/tmp\fR\&. +.RE +.SS Progress indicator +.RS +.IP \(bu 2 +\fB\fC\-q\fR or \fB\fC\-\-quiet\fR: Work quietly instead of reporting progress .RE .SH Environment .PP @@ -375,17 +401,17 @@ the same tiles, the layers or tiles are merged. The options are: .RS .IP \(bu 2 -\-o \fIout.mbtiles\fP: Write the new tiles to the specified .mbtiles file +\fB\fC\-o\fR \fIout.mbtiles\fP: Write the new tiles to the specified .mbtiles file .IP \(bu 2 -\-f: Remove \fIout.mbtiles\fP if it already exists +\fB\fC\-f\fR: Remove \fIout.mbtiles\fP if it already exists .IP \(bu 2 -\-c \fImatch.csv\fP: Use \fImatch.csv\fP as the source for new attributes to join to the features. The first line of the file should be the key names; the other lines are values. The first column is the one to match against the existing features; the other columns are the new data to add. +\fB\fC\-c\fR \fImatch\fP\fB\fC\&.csv\fR: Use \fImatch\fP\fB\fC\&.csv\fR as the source for new attributes to join to the features. The first line of the file should be the key names; the other lines are values. The first column is the one to match against the existing features; the other columns are the new data to add. .IP \(bu 2 -\-x \fIkey\fP: Remove attributes of type \fIkey\fP from the output. You can use this to remove the field you are matching against if you no longer need it after joining, or to remove any other attributes you don't want. +\fB\fC\-x\fR \fIkey\fP: Remove attributes of type \fIkey\fP from the output. You can use this to remove the field you are matching against if you no longer need it after joining, or to remove any other attributes you don't want. .IP \(bu 2 -\-i: Only include features that matched the CSV. +\fB\fC\-i\fR: Only include features that matched the CSV. .IP \(bu 2 -\-pk: Don't skip tiles larger than 500K. +\fB\fC\-pk\fR: Don't skip tiles larger than 500K. .RE .PP Because tile\-join just copies the geometries to the new .mbtiles without processing them @@ -484,11 +510,11 @@ resolutions. .SS Options .RS .IP \(bu 2 -\-t \fIprojection\fP: Specify the projection of the output data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator). +\fB\fC\-t\fR \fIprojection\fP: Specify the projection of the output data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator). .IP \(bu 2 -\-z \fImaxzoom\fP: Specify the highest zoom level to decode from the tileset +\fB\fC\-z\fR \fImaxzoom\fP: Specify the highest zoom level to decode from the tileset .IP \(bu 2 -\-Z \fIminzoom\fP: Specify the lowest zoom level to decode from the tileset +\fB\fC\-Z\fR \fIminzoom\fP: Specify the lowest zoom level to decode from the tileset .IP \(bu 2 -\-l \fIlayer\fP: Decode only layers with the specified names. (Multiple \fB\fC\-l\fR options can be specified.) +\fB\fC\-l\fR \fIlayer\fP: Decode only layers with the specified names. (Multiple \fB\fC\-l\fR options can be specified.) .RE From 5ec6ce17436a5e1fc63e246d5fcf5cdc2506fac0 Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Tue, 11 Apr 2017 17:00:28 -0700 Subject: [PATCH 3/6] Continue to reorder and clarify options --- README.md | 37 ++++++++++++++++++++----------------- man/tippecanoe.1 | 45 ++++++++++++++++++++++++--------------------- 2 files changed, 44 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 6b86348c..f7993a54 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ Options * `-e` _directory_ or `--output-to-directory`=_directory_: Write tiles to the specified *directory* instead of to an mbtiles file. * `-f` or `--force`: Delete the mbtiles file if it already exists instead of giving an error * `-F` or `--allow-existing`: Proceed (without deleting existing data) if the metadata or tiles table already exists - or if metadata fields can't be set + or if metadata fields can't be set. You probably don't want to use this. ### Parallel processing of input @@ -81,27 +81,26 @@ Options Performance will be better if the input is a named file that can be mapped into memory rather than a stream that can only be read sequentially. +### 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). + ### Zoom levels * `-z` _zoom_ or `--maximum-zoom=`_zoom_: Maxzoom: the highest zoom level for which tiles are generated (default 14) * `-Z` _zoom_ or `--minimum-zoom=`_zoom_: Minzoom: the lowest zoom level for which tiles are generated (default 0) - * `-B` _zoom_ or `--base-zoom=`_zoom_: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). - If you use `-Bg`, it will guess a zoom level that will keep at most 50,000 features in the densest tile. - You can also specify a marker-width with `-Bg`*width* to allow fewer features in the densest tile to - compensate for the larger marker, or `-Bf`*number* to allow at most *number* features in the densest tile. ### Tile resolution * `-d` _detail_ or `--full-detail=`_detail_: Detail at max zoom level (default 12, for tile resolution of 4096) * `-D` _detail_ or `--low-detail=`_detail_: Detail at lower zoom levels (default 12, for tile resolution of 4096) * `-m` _detail_ or `--minimum-detail=`_detail_: Minimum detail that it will try if tiles are too big at regular detail (default 7) - * `-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). All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^32) of the size of Earth, 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_. -### Properties +### 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 @@ -113,6 +112,10 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. If you use `-rg`, it will guess a drop rate that will keep at most 50,000 features in the densest tile. You can also specify a marker-width with `-rg`*width* to allow fewer features in the densest tile to compensate for the larger marker, or `-rf`*number* to allow at most *number* features in the densest tile. + * `-B` _zoom_ or `--base-zoom=`_zoom_: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). + If you use `-Bg`, it will guess a zoom level that will keep at most 50,000 features in the densest tile. + You can also specify a marker-width with `-Bg`*width* to allow fewer features in the densest tile to + compensate for the larger marker, or `-Bf`*number* to allow at most *number* features in the densest tile. * `-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 @@ -121,12 +124,12 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. * `-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.) * `-an` or `--drop-smallest-as-needed`: Dynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features. - * `-pd` or `--force-feature-limit`: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like `-ad` but applies to each tile individually, not to the entire zoom level.) + * `-pd` or `--force-feature-limit`: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like `-ad` but applies to each tile individually, not to the entire zoom level.) You probably don't want to use this. ### Dropping tightly overlapping features * `-g` _gamma_ or `--gamma=_gamma`_: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number. - * `-aG` or `--increase-gamma-as-needed`: If a tile is too large, try to reduce it to under 500K by increasing the `-g` gamma. The discovered gamma applies to the entire zoom level. + * `-aG` or `--increase-gamma-as-needed`: If a tile is too large, try to reduce it to under 500K by increasing the `-g` gamma. The discovered gamma applies to the entire zoom level. You probably want to use `--drop-densest-as-needed` instead. ### Line and polygon simplification @@ -136,23 +139,23 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. * `-pS` or `--simplify-only-low-zooms`: Don't simplify lines and polygons at maxzoom (but do simplify at lower zooms) * `-pt` or `--no-tiny-polygon-reduction`: Don't combine the area of very small polygons into small squares that represent their combined area. +### Attempts to improve shared polygon boundaries + + * `-ab` or `--detect-shared-borders`: In the manner of [TopoJSON](https://github.com/mbostock/topojson/wiki/Introduction), detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. + * `-aL` or `--grid-low-zooms`: At all zoom levels below _maxzoom_, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably `-D8`. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. You probably don't want to use this. + ### Controlling clipping to tile boundaries * `-b` _pixels_ or `--buffer=`_pixels_: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"—1/256th of the tile width or height. (default 5) * -pc or --no-clipping: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons. * -pD or --no-duplication: As with --no-clipping, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. -### Attempts to improve shared polygon boundaries - - * `-ab` or `--detect-shared-borders`: In the manner of [TopoJSON](https://github.com/mbostock/topojson/wiki/Introduction), detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. - * `-aL` or `--grid-low-zooms`: At all zoom levels below _maxzoom_, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably `-D8`. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. - ### Reordering features within each tile * `-pi` or `--preserve-input-order`: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot-dropping is still geographic, which means it also undoes -ao). - * `-ao` or `--reorder`: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce - * `-ac` or `--coalesce`: Coalesce adjacent line and polygon features that have the same properties. - * `-ar` or `--reverse`: Try reversing the directions of lines to make them coalesce and compress better + * `-ao` or `--reorder`: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce. You probably don't want to use this. + * `-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 diff --git a/man/tippecanoe.1 b/man/tippecanoe.1 index 8a3628c0..3d91e3a4 100644 --- a/man/tippecanoe.1 +++ b/man/tippecanoe.1 @@ -73,7 +73,7 @@ specified, the files are all merged into the single named layer, even if they tr \fB\fC\-f\fR or \fB\fC\-\-force\fR: Delete the mbtiles file if it already exists instead of giving an error .IP \(bu 2 \fB\fC\-F\fR or \fB\fC\-\-allow\-existing\fR: Proceed (without deleting existing data) if the metadata or tiles table already exists -or if metadata fields can't be set +or if metadata fields can't be set. You probably don't want to use this. .RE .SS Parallel processing of input .RS @@ -85,17 +85,17 @@ messages may result otherwise. Performance will be better if the input is a named file that can be mapped into memory rather than a stream that can only be read sequentially. .RE +.SS Projection of input +.RS +.IP \(bu 2 +\fB\fC\-s\fR \fIprojection\fP or \fB\fC\-\-projection=\fR\fIprojection\fP: Specify the projection of the input data. Currently supported are \fB\fCEPSG:4326\fR (WGS84, the default) and \fB\fCEPSG:3857\fR (Web Mercator). +.RE .SS Zoom levels .RS .IP \(bu 2 \fB\fC\-z\fR \fIzoom\fP or \fB\fC\-\-maximum\-zoom=\fR\fIzoom\fP: Maxzoom: the highest zoom level for which tiles are generated (default 14) .IP \(bu 2 \fB\fC\-Z\fR \fIzoom\fP or \fB\fC\-\-minimum\-zoom=\fR\fIzoom\fP: Minzoom: the lowest zoom level for which tiles are generated (default 0) -.IP \(bu 2 -\fB\fC\-B\fR \fIzoom\fP or \fB\fC\-\-base\-zoom=\fR\fIzoom\fP: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). -If you use \fB\fC\-Bg\fR, it will guess a zoom level that will keep at most 50,000 features in the densest tile. -You can also specify a marker\-width with \fB\fC\-Bg\fR\fIwidth\fP to allow fewer features in the densest tile to -compensate for the larger marker, or \fB\fC\-Bf\fR\fInumber\fP to allow at most \fInumber\fP features in the densest tile. .RE .SS Tile resolution .RS @@ -105,14 +105,12 @@ compensate for the larger marker, or \fB\fC\-Bf\fR\fInumber\fP to allow at most \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) .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) -.IP \(bu 2 -\fB\fC\-s\fR \fIprojection\fP or \fB\fC\-\-projection=\fR\fIprojection\fP: Specify the projection of the input data. Currently supported are \fB\fCEPSG:4326\fR (WGS84, the default) and \fB\fCEPSG:3857\fR (Web Mercator). .RE .PP 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 Properties +.SS 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 @@ -129,6 +127,11 @@ If you use \fB\fC\-rg\fR, it will guess a drop rate that will keep at most 50,00 You can also specify a marker\-width with \fB\fC\-rg\fR\fIwidth\fP to allow fewer features in the densest tile to compensate for the larger marker, or \fB\fC\-rf\fR\fInumber\fP to allow at most \fInumber\fP features in the densest tile. .IP \(bu 2 +\fB\fC\-B\fR \fIzoom\fP or \fB\fC\-\-base\-zoom=\fR\fIzoom\fP: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). +If you use \fB\fC\-Bg\fR, it will guess a zoom level that will keep at most 50,000 features in the densest tile. +You can also specify a marker\-width with \fB\fC\-Bg\fR\fIwidth\fP to allow fewer features in the densest tile to +compensate for the larger marker, or \fB\fC\-Bf\fR\fInumber\fP to allow at most \fInumber\fP features in the densest tile. +.IP \(bu 2 \fB\fC\-al\fR or \fB\fC\-\-drop\-lines\fR: Let "dot" dropping at lower zooms apply to lines too .IP \(bu 2 \fB\fC\-ap\fR or \fB\fC\-\-drop\-polygons\fR: Let "dot" dropping at lower zooms apply to polygons too @@ -142,14 +145,14 @@ compensate for the larger marker, or \fB\fC\-rf\fR\fInumber\fP to allow at most .IP \(bu 2 \fB\fC\-an\fR or \fB\fC\-\-drop\-smallest\-as\-needed\fR: Dynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features. .IP \(bu 2 -\fB\fC\-pd\fR or \fB\fC\-\-force\-feature\-limit\fR: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like \fB\fC\-ad\fR but applies to each tile individually, not to the entire zoom level.) +\fB\fC\-pd\fR or \fB\fC\-\-force\-feature\-limit\fR: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like \fB\fC\-ad\fR but applies to each tile individually, not to the entire zoom level.) You probably don't want to use this. .RE .SS Dropping tightly overlapping features .RS .IP \(bu 2 \fB\fC\-g\fR \fIgamma\fP or \fB\fC\-\-gamma=_gamma\fR_: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number. .IP \(bu 2 -\fB\fC\-aG\fR or \fB\fC\-\-increase\-gamma\-as\-needed\fR: If a tile is too large, try to reduce it to under 500K by increasing the \fB\fC\-g\fR gamma. The discovered gamma applies to the entire zoom level. +\fB\fC\-aG\fR or \fB\fC\-\-increase\-gamma\-as\-needed\fR: If a tile is too large, try to reduce it to under 500K by increasing the \fB\fC\-g\fR gamma. The discovered gamma applies to the entire zoom level. You probably want to use \fB\fC\-\-drop\-densest\-as\-needed\fR instead. .RE .SS Line and polygon simplification .RS @@ -163,6 +166,13 @@ the line or polygon within one tile unit of its proper location. You can probabl .IP \(bu 2 \fB\fC\-pt\fR or \fB\fC\-\-no\-tiny\-polygon\-reduction\fR: Don't combine the area of very small polygons into small squares that represent their combined area. .RE +.SS Attempts to improve shared polygon boundaries +.RS +.IP \(bu 2 +\fB\fC\-ab\fR or \fB\fC\-\-detect\-shared\-borders\fR: In the manner of TopoJSON \[la]https://github.com/mbostock/topojson/wiki/Introduction\[ra], detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. +.IP \(bu 2 +\fB\fC\-aL\fR or \fB\fC\-\-grid\-low\-zooms\fR: At all zoom levels below \fImaxzoom\fP, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably \fB\fC\-D8\fR\&. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. You probably don't want to use this. +.RE .SS Controlling clipping to tile boundaries .RS .IP \(bu 2 @@ -172,23 +182,16 @@ the line or polygon within one tile unit of its proper location. You can probabl .IP \(bu 2 \-pD or \-\-no\-duplication: As with \-\-no\-clipping, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. .RE -.SS Attempts to improve shared polygon boundaries -.RS -.IP \(bu 2 -\fB\fC\-ab\fR or \fB\fC\-\-detect\-shared\-borders\fR: In the manner of TopoJSON \[la]https://github.com/mbostock/topojson/wiki/Introduction\[ra], detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually. -.IP \(bu 2 -\fB\fC\-aL\fR or \fB\fC\-\-grid\-low\-zooms\fR: At all zoom levels below \fImaxzoom\fP, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably \fB\fC\-D8\fR\&. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data. -.RE .SS Reordering features within each tile .RS .IP \(bu 2 \fB\fC\-pi\fR or \fB\fC\-\-preserve\-input\-order\fR: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot\-dropping is still geographic, which means it also undoes \-ao). .IP \(bu 2 -\fB\fC\-ao\fR or \fB\fC\-\-reorder\fR: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce +\fB\fC\-ao\fR or \fB\fC\-\-reorder\fR: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce. You probably don't want to use this. .IP \(bu 2 -\fB\fC\-ac\fR or \fB\fC\-\-coalesce\fR: Coalesce adjacent line and polygon features that have the same properties. +\fB\fC\-ac\fR or \fB\fC\-\-coalesce\fR: Coalesce adjacent line and polygon features that have the same properties. You probably don't want to use this. .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 +\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 From ab300c20805a60e2b48fa19b72d2ffef8978afde Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Tue, 11 Apr 2017 17:06:01 -0700 Subject: [PATCH 4/6] Forgot to format a few more options --- README.md | 6 +++--- man/tippecanoe.1 | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index f7993a54..2ba519c6 100644 --- a/README.md +++ b/README.md @@ -147,12 +147,12 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. ### Controlling clipping to tile boundaries * `-b` _pixels_ or `--buffer=`_pixels_: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"—1/256th of the tile width or height. (default 5) - * -pc or --no-clipping: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons. - * -pD or --no-duplication: As with --no-clipping, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. + * `-pc` or `--no-clipping`: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons. + * `-pD` or `--no-duplication`: As with `--no-clipping`, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. ### Reordering features within each tile - * `-pi` or `--preserve-input-order`: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot-dropping is still geographic, which means it also undoes -ao). + * `-pi` or `--preserve-input-order`: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot-dropping is still geographic, which means it also undoes `-ao`). * `-ao` or `--reorder`: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce. You probably don't want to use this. * `-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. diff --git a/man/tippecanoe.1 b/man/tippecanoe.1 index 3d91e3a4..a28ec927 100644 --- a/man/tippecanoe.1 +++ b/man/tippecanoe.1 @@ -178,14 +178,14 @@ the line or polygon within one tile unit of its proper location. You can probabl .IP \(bu 2 \fB\fC\-b\fR \fIpixels\fP or \fB\fC\-\-buffer=\fR\fIpixels\fP: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"—1/256th of the tile width or height. (default 5) .IP \(bu 2 -\-pc or \-\-no\-clipping: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons. +\fB\fC\-pc\fR or \fB\fC\-\-no\-clipping\fR: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons. .IP \(bu 2 -\-pD or \-\-no\-duplication: As with \-\-no\-clipping, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. +\fB\fC\-pD\fR or \fB\fC\-\-no\-duplication\fR: As with \fB\fC\-\-no\-clipping\fR, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features. .RE .SS Reordering features within each tile .RS .IP \(bu 2 -\fB\fC\-pi\fR or \fB\fC\-\-preserve\-input\-order\fR: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot\-dropping is still geographic, which means it also undoes \-ao). +\fB\fC\-pi\fR or \fB\fC\-\-preserve\-input\-order\fR: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot\-dropping is still geographic, which means it also undoes \fB\fC\-ao\fR). .IP \(bu 2 \fB\fC\-ao\fR or \fB\fC\-\-reorder\fR: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce. You probably don't want to use this. .IP \(bu 2 From 79b73e63179c0bd2ea1096f4749c0048e9153962 Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Tue, 11 Apr 2017 17:24:15 -0700 Subject: [PATCH 5/6] 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 From f4677d5de160ba6c7d02be55926dfe96554e3542 Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Wed, 12 Apr 2017 10:16:43 -0700 Subject: [PATCH 6/6] Reorganize input and layer options --- README.md | 22 +++++++++++++--------- man/tippecanoe.1 | 33 +++++++++++++++++++-------------- 2 files changed, 32 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 8d34a588..6d43444b 100644 --- a/README.md +++ b/README.md @@ -71,15 +71,6 @@ If your features have a lot of attributes, use `-y` to keep only the ones you re 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 - specified, the files are all merged into the single named layer, even if they try to specify individual names with `-L`. - * `-L` _name_`:`_file.json_ or `--named-layer=`_name_`:`_file.json_: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like `-L` _name_`:<(cat dir/*.json)` to specify a layer name for the output of streamed input. - * `-n` _name_ or `--name=`_name_: Human-readable name for the tileset (default file.json) - * `-A` _text_ or `--attribution=`_text_: Attribution (HTML) to be shown with maps that use data from this tileset. - * `-N` _description_ or `--description=`_description_: Description for the tileset (default file.mbtiles) - ### Output tileset * `-o` _file_`.mbtiles` or `--output=`_file_`.mbtiles`: Name the output file. @@ -88,6 +79,19 @@ If your input is formatted as newline-delimited GeoJSON, use `-P` to make input * `-F` or `--allow-existing`: Proceed (without deleting existing data) if the metadata or tiles table already exists or if metadata fields can't be set. You probably don't want to use this. +### Tileset description and attribution + + * `-n` _name_ or `--name=`_name_: Human-readable name for the tileset (default file.json) + * `-A` _text_ or `--attribution=`_text_: Attribution (HTML) to be shown with maps that use data from this tileset. + * `-N` _description_ or `--description=`_description_: Description for the tileset (default file.mbtiles) + +### Input files and layer names + + * _name_`.json` or _name_`.geojson`: Read the named GeoJSON input file into a layer called _name_. + * `-l` _name_ or `--layer=`_name_: Use the specified layer name instead of deriving a name from the input filename or output tileset. If there are multiple input files + specified, the files are all merged into the single named layer, even if they try to specify individual names with `-L`. + * `-L` _name_`:`_file.json_ or `--named-layer=`_name_`:`_file.json_: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like `-L` _name_`:<(cat dir/*.json)` to specify a layer name for the output of streamed input. + ### Parallel processing of input * `-P` or `--read-parallel`: Use multiple threads to read different parts of each input file at once. diff --git a/man/tippecanoe.1 b/man/tippecanoe.1 index 5f24eb7d..6feb9fb7 100644 --- a/man/tippecanoe.1 +++ b/man/tippecanoe.1 @@ -65,20 +65,6 @@ to drop some of them if necessary to make the low zoom levels work. 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 -\fB\fC\-l\fR \fIname\fP or \fB\fC\-\-layer=\fR\fIname\fP: Layer name (default "file" if source is file.json or output is file.mbtiles). If there are multiple input files -specified, the files are all merged into the single named layer, even if they try to specify individual names with \fB\fC\-L\fR\&. -.IP \(bu 2 -\fB\fC\-L\fR \fIname\fP\fB\fC:\fR\fIfile.json\fP or \fB\fC\-\-named\-layer=\fR\fIname\fP\fB\fC:\fR\fIfile.json\fP: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like \fB\fC\-L\fR \fIname\fP\fB\fC:<(cat dir/*.json)\fR to specify a layer name for the output of streamed input. -.IP \(bu 2 -\fB\fC\-n\fR \fIname\fP or \fB\fC\-\-name=\fR\fIname\fP: Human\-readable name for the tileset (default file.json) -.IP \(bu 2 -\fB\fC\-A\fR \fItext\fP or \fB\fC\-\-attribution=\fR\fItext\fP: Attribution (HTML) to be shown with maps that use data from this tileset. -.IP \(bu 2 -\fB\fC\-N\fR \fIdescription\fP or \fB\fC\-\-description=\fR\fIdescription\fP: Description for the tileset (default file.mbtiles) -.RE .SS Output tileset .RS .IP \(bu 2 @@ -91,6 +77,25 @@ specified, the files are all merged into the single named layer, even if they tr \fB\fC\-F\fR or \fB\fC\-\-allow\-existing\fR: Proceed (without deleting existing data) if the metadata or tiles table already exists or if metadata fields can't be set. You probably don't want to use this. .RE +.SS Tileset description and attribution +.RS +.IP \(bu 2 +\fB\fC\-n\fR \fIname\fP or \fB\fC\-\-name=\fR\fIname\fP: Human\-readable name for the tileset (default file.json) +.IP \(bu 2 +\fB\fC\-A\fR \fItext\fP or \fB\fC\-\-attribution=\fR\fItext\fP: Attribution (HTML) to be shown with maps that use data from this tileset. +.IP \(bu 2 +\fB\fC\-N\fR \fIdescription\fP or \fB\fC\-\-description=\fR\fIdescription\fP: Description for the tileset (default file.mbtiles) +.RE +.SS Input files and layer names +.RS +.IP \(bu 2 +\fIname\fP\fB\fC\&.json\fR or \fIname\fP\fB\fC\&.geojson\fR: Read the named GeoJSON input file into a layer called \fIname\fP\&. +.IP \(bu 2 +\fB\fC\-l\fR \fIname\fP or \fB\fC\-\-layer=\fR\fIname\fP: Use the specified layer name instead of deriving a name from the input filename or output tileset. If there are multiple input files +specified, the files are all merged into the single named layer, even if they try to specify individual names with \fB\fC\-L\fR\&. +.IP \(bu 2 +\fB\fC\-L\fR \fIname\fP\fB\fC:\fR\fIfile.json\fP or \fB\fC\-\-named\-layer=\fR\fIname\fP\fB\fC:\fR\fIfile.json\fP: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like \fB\fC\-L\fR \fIname\fP\fB\fC:<(cat dir/*.json)\fR to specify a layer name for the output of streamed input. +.RE .SS Parallel processing of input .RS .IP \(bu 2