Explain basic concepts like "detail"
- 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
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