From 7b5069f2f6b99fc07de62c04692d36dd815527d6 Mon Sep 17 00:00:00 2001 From: Eric Fischer Date: Fri, 13 Jan 2017 15:57:52 -0800 Subject: [PATCH] Start writing some documentation --- README.md | 30 ++++++++++++++++++++++++++++++ man/tippecanoe.1 | 37 ++++++++++++++++++++++++++++++++++++- 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c3222df..a7630b4 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,36 @@ resolution is obtained than by using a smaller _maxzoom_ or _detail_. * -pt or --no-tiny-polygon-reduction: Don't combine the area of very small polygons into small squares that represent their combined area. * -q or --quiet: Work quietly instead of reporting progress +### Filters + + * -C _command_ or --prefilter=_command_: Specify a shell filter command to be run at the start of assembling each tile + * -c _command_ or --postfilter=_command_: Specify a shell filter command to be run at the end of assembling each tile + +The pre- and post-filter commands allow you to do optional filtering or transformation on the features of each tile +as it is created. They are shell commands, run with the zoom level, X, and Y as the `$1`, `$2`, and `$3` arguments. + +The features are provided to the filter +as a series of newline-delimited GeoJSON objects on the standard input, and `tippecanoe` expects to read another +set of GeoJSON features from the filter's standard output. + +The prefilter receives the features at the highest available resolution, before line simplification, +polygon topology repair, gamma calculation, dynamic feature dropping, or other internal processing. +The postfilter receives the features at tile resolution, after simplification, cleaning, and dropping. + +The layer name is provided as part of the `tippecanoe` element of the feature and must be passed through +to keep the feature in its correct layer. In the case of the prefilter, the `tippecanoe` element may also +contain `index`, `sequence`, and `extent` elements, which must be passed through for internal operations like +`--drop-densest-as-needed`, `--drop-smallest-as-needed`, and `--preserve-input-order` to work. + +#### Examples: + + * Make a tileset of the Natural Earth countries to zoom level 5, and also copy the GeoJSON features + to files in a `tiles/z/x/y.geojson` directory hierarchy. + +``` +tippecanoe -o countries.mbtiles -z5 -C 'mkdir -p tiles/$1/$2; tee tiles/$1/$2/$3.geojson' ne_10m_admin_0_countries.json +``` + Example ------- diff --git a/man/tippecanoe.1 b/man/tippecanoe.1 index bfbda4e..08f07c8 100644 --- a/man/tippecanoe.1 +++ b/man/tippecanoe.1 @@ -188,6 +188,41 @@ which may not be what you want. .IP \(bu 2 \-q or \-\-quiet: Work quietly instead of reporting progress .RE +.SS Filters +.RS +.IP \(bu 2 +\-C \fIcommand\fP or \-\-prefilter=\fIcommand\fP: Specify a shell filter command to be run at the start of assembling each tile +.IP \(bu 2 +\-c \fIcommand\fP or \-\-postfilter=\fIcommand\fP: Specify a shell filter command to be run at the end of assembling each tile +.RE +.PP +The pre\- and post\-filter commands allow you to do optional filtering or transformation on the features of each tile +as it is created. They are shell commands, run with the zoom level, X, and Y as the \fB\fC$1\fR, \fB\fC$2\fR, and \fB\fC$3\fR arguments. +.PP +The features are provided to the filter +as a series of newline\-delimited GeoJSON objects on the standard input, and \fB\fCtippecanoe\fR expects to read another +set of GeoJSON features from the filter's standard output. +.PP +The prefilter receives the features at the highest available resolution, before line simplification, +polygon topology repair, gamma calculation, dynamic feature dropping, or other internal processing. +The postfilter receives the features at tile resolution, after simplification, cleaning, and dropping. +.PP +The layer name is provided as part of the \fB\fCtippecanoe\fR element of the feature and must be passed through +to keep the feature in its correct layer. In the case of the prefilter, the \fB\fCtippecanoe\fR element may also +contain \fB\fCindex\fR, \fB\fCsequence\fR, and \fB\fCextent\fR elements, which must be passed through for internal operations like +\fB\fC\-\-drop\-densest\-as\-needed\fR, \fB\fC\-\-drop\-smallest\-as\-needed\fR, and \fB\fC\-\-preserve\-input\-order\fR to work. +.SS Examples: +.RS +.IP \(bu 2 +Make a tileset of the Natural Earth countries to zoom level 5, and also copy the GeoJSON features +to files in a \fB\fCtiles/z/x/y.geojson\fR directory hierarchy. +.RE +.PP +.RS +.nf +tippecanoe \-o countries.mbtiles \-z5 \-C 'mkdir \-p tiles/$1/$2; tee tiles/$1/$2/$3.geojson' ne_10m_admin_0_countries.json +.fi +.RE .SH Example .PP .RS @@ -315,7 +350,7 @@ Linux: .PP .RS .nf -sudo apt\-get install libsqlite3\-dev zlib1g\-dev +sudo apt\-get install build\-essential libsqlite3\-dev zlib1g\-dev .fi .RE .PP