mirror of
https://github.com/mapbox/tippecanoe.git
synced 2025-01-21 12:05:05 +00:00
use md2man to generate man page
This commit is contained in:
Tom MacWright
parent
22471ab5be
commit
142ea37e17
5
Makefile
5
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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
208
man/tippecanoe.1
Normal file
208
man/tippecanoe.1
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user