Documentation
¶
Overview ¶
Package pmtiles reads and writes PMTiles version 3 archives, and extracts the part of one that covers a bounding box and a zoom range (#2068).
It exists rather than github.com/protomaps/go-pmtiles because the platform fetches a basemap through its own HTTP client (internal/outbound, so the fetch is traced and counted) and writes the result straight into object storage. go-pmtiles' Extract opens its source with http.DefaultClient and writes to a local file path, and its one package imports the Google Cloud, Azure and SQLite SDKs. The format is small: a 127-byte header, varint directories, and tile data addressed by Hilbert tile id.
The specification is https://github.com/protomaps/PMTiles/blob/main/spec/v3/spec.md.
Index ¶
- Constants
- Variables
- func DecodeMetadata(raw []byte, c Compression) (map[string]any, error)
- func SerializeDirectory(entries []Entry, c Compression) ([]byte, error)
- func ZxyToID(z uint8, x, y uint32) uint64
- type Bounds
- type Compression
- type Entry
- type Header
- type Plan
- type Range
- type Request
- type Source
- type TileType
Constants ¶
const HeaderLen = 127
HeaderLen is the fixed size of a version 3 header.
const MaxZoom = 15
MaxZoom is the deepest zoom an extract may ask for. Tile ids are uint64 and the specification allows deeper, but no basemap is built past 15 and the cover's work grows with the zoom.
const RootFetchLen = 16384
RootFetchLen is how much of an archive holds its header and root directory: the specification requires both inside the first 16 KiB, so one read of this length answers both.
Variables ¶
var ErrNoOverlap = errors.New("pmtiles: the requested area or zooms are not in the source archive")
ErrNoOverlap is returned when the request's box or zooms share nothing with the source archive.
var ErrNotPMTiles = errors.New("pmtiles: not a PMTiles version 3 archive")
ErrNotPMTiles is returned for bytes that do not begin a version 3 archive.
Functions ¶
func DecodeMetadata ¶
func DecodeMetadata(raw []byte, c Compression) (map[string]any, error)
DecodeMetadata decodes an archive's metadata section.
func SerializeDirectory ¶
func SerializeDirectory(entries []Entry, c Compression) ([]byte, error)
SerializeDirectory encodes entries, which must be in tile id order, under the given internal compression.
Types ¶
type Bounds ¶
type Bounds struct {
MinLon float64 `json:"min_lon"`
MinLat float64 `json:"min_lat"`
MaxLon float64 `json:"max_lon"`
MaxLat float64 `json:"max_lat"`
}
Bounds is a bounding box in degrees.
type Compression ¶
type Compression uint8
Compression is the compression of an archive's directories, metadata or tiles.
const ( CompressionUnknown Compression = 0 CompressionNone Compression = 1 CompressionGzip Compression = 2 CompressionBrotli Compression = 3 CompressionZstd Compression = 4 )
The compressions the specification defines.
type Entry ¶
Entry is one directory entry. RunLength 0 marks a pointer to a leaf directory, whose Offset is relative to the archive's leaf section; otherwise Offset is relative to the tile data section and the entry addresses RunLength consecutive tile ids holding the same content.
func ParseDirectory ¶
func ParseDirectory(data []byte, c Compression) ([]Entry, error)
ParseDirectory decodes one directory as stored, under the archive's internal compression.
type Header ¶
type Header struct {
RootOffset uint64
RootLength uint64
MetadataOffset uint64
MetadataLength uint64
LeafOffset uint64
LeafLength uint64
TileDataOffset uint64
TileDataLength uint64
AddressedTiles uint64
TileEntries uint64
TileContents uint64
Clustered bool
InternalCompression Compression
TileCompression Compression
TileType TileType
MinZoom uint8
MaxZoom uint8
MinLonE7 int32
MinLatE7 int32
MaxLonE7 int32
MaxLatE7 int32
CenterZoom uint8
CenterLonE7 int32
CenterLatE7 int32
}
Header is a version 3 header. Bounds and center are in degrees times 10^7, as the format stores them.
func ParseHeader ¶
ParseHeader reads the header from the first HeaderLen bytes of an archive.
type Plan ¶
type Plan struct {
// contains filtered or unexported fields
}
Plan is an extract whose directories are built and whose size is known, and whose tile data has not yet been copied. Planning reads the source's header, metadata and the directories that address the requested tiles; writing reads the tiles.
func (*Plan) Metadata ¶
Metadata returns the source archive's metadata, decoded: the JSON object the format stores, which for a Protomaps build carries its attribution, schema version and OpenStreetMap replication time.
func (*Plan) WriteTo ¶
func (p *Plan) WriteTo(ctx context.Context, src Source, w io.Writer, progress func(written uint64)) error
WriteTo writes the extract to w: the header, directories and metadata, then every tile content copied from src in the extract's order. progress, when set, is called with the bytes written so far after each read is written.
type Range ¶
Range is a half-open run of tile ids, [Start, End).
func Cover ¶
Cover returns the tile ids a box touches at every zoom from minZoom to maxZoom, as sorted, merged ranges.
A Hilbert curve visits each quadtree cell's tiles consecutively, so a cell entirely inside the box is one range, and the cover recurses only along the box's edge: the number of ranges grows with the box's perimeter in tiles, not its area.
Source Files