From 142ea37e17b476145df87deadd45d69d3da2cefa Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Fri, 29 May 2015 12:06:41 -0400 Subject: [PATCH] use md2man to generate man page --- Makefile | 5 +- README.md | 3 +- man/tippecanoe.1 | 208 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+), 2 deletions(-) create mode 100644 man/tippecanoe.1 diff --git a/Makefile b/Makefile index 5046239..0021dcd 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,14 @@ PREFIX ?= /usr/local -all: tippecanoe enumerate decode +all: tippecanoe enumerate decode man/tippecanoe.1 install: tippecanoe mkdir -p $(PREFIX)/bin cp tippecanoe $(PREFIX)/bin/tippecanoe +man/tippecanoe.1: README.md + md2man-roff README.md > man/tippecanoe.1 + vector_tile.pb.cc vector_tile.pb.h: vector_tile.proto protoc --cpp_out=. vector_tile.proto diff --git a/README.md b/README.md index d2a3f0a..2022810 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,8 @@ Development Requires protoc (`brew install protobuf` or `apt-get install libprotobuf-dev` and `protobuf-compiler`), -and sqlite3 (`apt-get install libsqlite3-dev`). To build: +`md2man` (`gem install md2man`), and sqlite3 (`apt-get install libsqlite3-dev`). +To build: make diff --git a/man/tippecanoe.1 b/man/tippecanoe.1 new file mode 100644 index 0000000..b782eb3 --- /dev/null +++ b/man/tippecanoe.1 @@ -0,0 +1,208 @@ +.TH tippecanoe +.PP +Builds vector tilesets +\[la]https://www.mapbox.com/developers/vector-tiles/\[ra] from large collections of GeoJSON +\[la]http://geojson.org/\[ra] +features. This is a tool for making maps from huge datasets +\[la]MADE_WITH.md\[ra]\&. +.SH Intent +.PP +The goal of Tippecanoe is to enable making a scale\-independent view of your data, +so that at any level from the entire world to a single building, you can see +the density and texture of the data rather than a simplification from dropping +supposedly unimportant features or clustering or aggregating them. +.PP +If you give it all of OpenStreetMap and zoom out, it should give you back +something that looks like "All Streets +\[la]http://benfry.com/allstreets/map5.html\[ra]" +rather than something that looks like an Interstate road atlas. +.PP +If you give it all the building footprints in Los Angeles and zoom out +far enough that most individual buildings are no longer discernable, you +should still be able to see the extent and variety of development in every neighborhood, +not just the largest downtown buildings. +.PP +If you give it a collection of years of tweet locations, you should be able to +see the shape and relative popularity of every point of interest and every +significant travel corridor. +.SH Installation +.PP +The easiest way to install tippecanoe on OSX is with Homebrew +\[la]http://brew.sh/\[ra]: +.PP +.RS +.nf +$ brew install tippecanoe +.fi +.RE +.SH Usage +.PP +.RS +.nf +$ tippecanoe \-o file.mbtiles [file.json ...] +.fi +.RE +.PP +If no files are specified, it reads GeoJSON from the standard input. +If multiple files are specified, each is placed in its own layer. +.PP +The GeoJSON features need not be wrapped in a FeatureCollection. +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 +.RS +.IP \(bu 2 +\-l \fIname\fP: Layer name (default "file" if source is file.json or output is file.mbtiles). Only works if there is only one layer. +.IP \(bu 2 +\-n \fIname\fP: Human\-readable name (default file.json) +.RE +.SS File control +.RS +.IP \(bu 2 +\-o \fIfile\fP\&.mbtiles: Name the output file. +.IP \(bu 2 +\-f: Delete the mbtiles file if it already exists instead of giving an error +.RE +.SS Zoom levels and resolution +.RS +.IP \(bu 2 +\-z \fIzoom\fP: Base (maxzoom) zoom level (default 14) +.IP \(bu 2 +\-Z \fIzoom\fP: Lowest (minzoom) zoom level (default 0) +.IP \(bu 2 +\-d \fIdetail\fP: Detail at base zoom level (default 26\-basezoom, ~0.5m, for tile resolution of 4096 if \-z14) +.IP \(bu 2 +\-D \fIdetail\fP: Detail at lower zoom levels (default 10, for tile resolution of 1024) +.IP \(bu 2 +\-b \fIpixels\fP: Buffer size where features are duplicated from adjacent tiles (default 5) +.RE +.SS Properties +.RS +.IP \(bu 2 +\-x \fIname\fP: Exclude the named properties from all features +.IP \(bu 2 +\-y \fIname\fP: Include the named properties in all features, excluding all those not explicitly named +.IP \(bu 2 +\-X: Exclude all properties and encode only geometries +.RE +.SS Point simplification +.RS +.IP \(bu 2 +\-r \fIrate\fP: Rate at which dots are dropped at lower zoom levels (default 2.5) +.IP \(bu 2 +\-g \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. +.RE +.SS Doing less +.RS +.IP \(bu 2 +\-ps: Don't simplify lines +.IP \(bu 2 +\-pr: Don't reverse the direction of lines to make them coalesce better +.IP \(bu 2 +\-pc: Don't coalesce features with the same properties +.IP \(bu 2 +\-pf: Don't limit tiles to 200,000 features +.IP \(bu 2 +\-pk: Don't limit tiles to 500K bytes +.IP \(bu 2 +\-po: Don't reorder features to put the same properties in sequence +.IP \(bu 2 +\-pl: Let "dot" simplification apply to lines too +.RE +.SH Example +.PP +.RS +.nf +$ tippecanoe \-o alameda.mbtiles \-l alameda \-n "Alameda County from TIGER" \-z13 tl_2014_06001_roads.json +.fi +.RE +.PP +.RS +.nf +$ cat tiger/tl_2014_*_roads.json | tippecanoe \-o tiger.mbtiles \-l roads \-n "All TIGER roads, one zoom" \-z12 \-Z12 \-d14 \-x LINEARID \-x RTTYP +.fi +.RE +.SH Point styling +.PP +To provide a consistent density gradient as you zoom, the Mapbox Studio style needs to be +coordinated with the base zoom level and dot\-dropping rate. You can use this shell script to +calculate the appropriate marker\-width at high zoom levels to match the fraction of dots +that were dropped at low zoom levels. +.PP +If you used \fB\fC\-z\fR to change the base zoom level or \fB\fC\-r\fR to change the +dot\-dropping rate, replace them in the \fB\fCbasezoom\fR and \fB\fCrate\fR below. +.PP +.RS +.nf +awk 'BEGIN { + dotsize = 2; # up to you to decide + basezoom = 14; # tippecanoe \-z 14 + rate = 2.5; # tippecanoe \-r 2.5 + print " marker\-line\-width: 0;"; + print " marker\-ignore\-placement: true;"; + print " marker\-allow\-overlap: true;"; + print " marker\-width: " dotsize ";"; + for (i = basezoom + 1; i <= 22; i++) { + print " [zoom >= " i "] { marker\-width: " (dotsize * exp(log(sqrt(rate)) * (i \- basezoom))) "; }"; + } + exit(0); +}' +.fi +.RE +.SH Geometric simplifications +.PP +At every zoom level, line and polygon features are subjected to Douglas\-Peucker +simplification to the resolution of the tile. +.PP +For point features, it drops 1/2.5 of the dots for each zoom level above the base. +I don't know why 2.5 is the appropriate number, but the densities of many different +data sets fall off at about this same rate. You can use \-r to specify a different rate. +.PP +You can use the gamma option to thin out especially dense clusters of points. +For any area that where dots are closer than one pixel together (at whatever zoom level), +a gamma of 3, for example, will reduce these clusters to the cube root of their original density. +.PP +For line features, it drops any features that are too small to draw at all. +This still leaves the lower zooms too dark (and too dense for the 500K tile limit, +in some places), so I need to figure out an equitable way to throw features away. +.PP +Any polygons that are smaller than a minimum area (currently 9 square subpixels) will +have their probability diffused, so that some of them will be drawn as a square of +this minimum size and others will not be drawn at all, preserving the total area that +all of them should have had together. +.PP +Features in the same tile that share the same type and attributes are coalesced +together into a single geometry. You are strongly encouraged to use \-x to exclude +any unnecessary properties to reduce wasted file size. +.PP +If a tile is larger than 500K, it will try encoding that tile at progressively +lower resolutions before failing if it still doesn't fit. +.SH Development +.PP +Requires protoc (\fB\fCbrew install protobuf\fR or +\fB\fCapt\-get install libprotobuf\-dev\fR and \fB\fCprotobuf\-compiler\fR), +and sqlite3 (\fB\fCapt\-get install libsqlite3\-dev\fR). To build: +.PP +.RS +.nf +make +.fi +.RE +.PP +and perhaps +.PP +.RS +.nf +make install +.fi +.RE +.SH Examples +.PP +Check out some examples of maps made with tippecanoe +\[la]MADE_WITH.md\[ra] +.SH Name +.PP +The name is a joking reference +\[la]http://en.wikipedia.org/wiki/Tippecanoe_and_Tyler_Too\[ra] to making tiles.