mapbox / mapbox/tippecanoe

Explain basic concepts like "detail"

Open
#195 5 comments 3 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
3.1k
Forks
430
PR merge metrics
No merged PRs in 30d

Description

It would be helpful if there was an introductory paragraph or two explaining the basic concepts. In particular, I can't really work out what "detail" means, or what a number like 7 or 12 means. Is it something like the bits of precision for coordinates within the tile? Hence detail 1 would mean every point is mapped onto one of four locations?

Some other terms that it would be helpful to define up front:
- zoom
- maxzoom/minzoom/base zoom
- drop

Here's some text that may serve as a starter:
### How it works

Tippecanoe loads the source GeoJSON file, then generates a number of vector tiles in PBF format from the minimum to maximum zoom level (default: 0-14). It tries to keep each tile as small as possible by dropping points, simplifying lines and polygons, and sometimes dropping lines or polygons. In order to allow data to be hosted by Mapbox, it tries to keep each tile under 500kB and under 200k features. Working from the "base zoom" level (which defaults to the maximum), it drops exponentially features at lower zooms, defaulting to 2.5x more per zoom level.

Getting the right balance of tile size, overall file size and visual quality is tricky and may take some trial and error. There are many settings to control this. In particular:
- if you are rendering points with sizes greater than 1px, pass the width as X in `-rgX` and `-bgX`
- remove unneeded attributes with `-x` or `-y`
- reduce tile size at the cost of spatial accuracy with '-d`,`-D`,`-m`

Contributor guide

Open the contributing guide

Research direction

Use the proposed “How it works” text as the starting point for the introductory documentation. Define detail, zoom, maxzoom/minzoom/base zoom, and drop, including what the numeric values mean; the work is done when a newcomer can understand these concepts and the listed settings without guessing.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.