pmtiles

Documentation

Index

• Constants
• func BboxRegion(bbox string) (orb.MultiPolygon, error)
• func Convert(logger *log.Logger, input string, output string, deduplicate bool, ...) error
• func CreateTileJSON(header HeaderV3, metadataBytes []byte, tileURL string) ([]byte, error)
• func Extract(_ *log.Logger, bucketURL string, key string, minzoom int8, maxzoom int8, ...) error
• func IDToZxy(i uint64) (uint8, uint32, uint32)
• func Makesync(logger *log.Logger, cliVersion string, file string, blockSizeKb int, ...) error
• func MergeRanges(ranges []srcDstRange, overfetch float32) (*list.List, uint64)
• func NormalizeBucketKey(bucket string, prefix string, key string) (string, string, error)
• func ParentID(i uint64) uint64
• func RelevantEntries(bitmap *roaring64.Bitmap, maxzoom uint8, dir []EntryV3) ([]EntryV3, []EntryV3)
• func SetBuildInfo(version, commit, date string)
• func Show(_ *log.Logger, bucketURL string, key string, showMetadataOnly bool, ...) error
• func Sync(logger *log.Logger, oldVersion string, newVersion string, dryRun bool) error
• func UnmarshalRegion(data []byte) (orb.MultiPolygon, error)
• func Upload(logger *log.Logger, input string, bucket string, key string, ...) error
• func Verify(_ *log.Logger, file string) error
• func ZxyToID(z uint8, x uint32, y uint32) uint64
• type Bucket
  • func OpenBucket(ctx context.Context, bucketURL string, bucketPrefix string) (Bucket, error)
• type BucketAdapter
  • func (ba BucketAdapter) Close() error
  • func (ba BucketAdapter) NewRangeReader(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)
  • func (ba BucketAdapter) NewRangeReaderEtag(ctx context.Context, key string, offset, length int64, etag string) (io.ReadCloser, string, int, error)
• type Compression
• type EntryV3
• type FileBucket
  • func NewFileBucket(path string) *FileBucket
  • func (b FileBucket) Close() error
  • func (b FileBucket) NewRangeReader(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)
  • func (b FileBucket) NewRangeReaderEtag(_ context.Context, key string, offset, length int64, etag string) (io.ReadCloser, string, int, error)
• type HTTPBucket
  • func (b HTTPBucket) Close() error
  • func (b HTTPBucket) NewRangeReader(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)
  • func (b HTTPBucket) NewRangeReaderEtag(ctx context.Context, key string, offset, length int64, etag string) (io.ReadCloser, string, int, error)
• type HTTPClient
• type HeaderV3
• type RefreshRequiredError
  • func (m *RefreshRequiredError) Error() string
• type Server
  • func NewServer(bucketURL string, prefix string, logger *log.Logger, cacheSize int, ...) (*Server, error)
  • func NewServerWithBucket(bucket Bucket, _ string, logger *log.Logger, cacheSize int, cors string, ...) (*Server, error)
  • func (server *Server) Get(ctx context.Context, path string) (int, map[string]string, []byte)
  • func (server *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) int
  • func (server *Server) Start()
• type TileType
• type Zxy

Constants

const (
	UnknownCompression Compression = 0
	NoCompression                  = 1
	Gzip                           = 2
	Brotli                         = 3
	Zstd                           = 4
)

const (
	UnknownTileType TileType = 0
	Mvt                      = 1
	Png                      = 2
	Jpeg                     = 3
	Webp                     = 4
	Avif                     = 5
)

const HeaderV3LenBytes = 127

HeaderV3LenBytes is the fixed-size binary header size.

Functions

func BboxRegion

func BboxRegion(bbox string) (orb.MultiPolygon, error)

BboxRegion parses a bbox string into an orb.MultiPolygon region.

func Convert

func Convert(logger *log.Logger, input string, output string, deduplicate bool, tmpfile *os.File) error

Convert an existing archive on disk to a new PMTiles specification version 3 archive.

func CreateTileJSON

func CreateTileJSON(header HeaderV3, metadataBytes []byte, tileURL string) ([]byte, error)

CreateTileJSON returns TileJSON from an archive header+metadata and a given public tileURL.

func Extract

func Extract(_ *log.Logger, bucketURL string, key string, minzoom int8, maxzoom int8, regionFile string, bbox string, output string, downloadThreads int, overfetch float32, dryRun bool) error

Extract a smaller archive from local or remote archive. 1. Get the root directory (check that it is clustered) 2. Turn the input geometry into a relevance bitmap (using min(maxzoom, headermaxzoom)) 3. Get all relevant level 1 directories (if any) 4. Get all relevant level 2 directories (usually none) 5. With the existing directory + relevance bitmap, construct

• a new total directory (root + leaf directories)
• a sorted slice of byte ranges in the old file required

6. Merge requested ranges using an overfetch parametter 7. write the modified header 8. write the root directory. 9. get and write the metadata. 10. write the leaf directories (if any) 11. Get all tiles, and write directly to the output.

func IDToZxy

func IDToZxy(i uint64) (uint8, uint32, uint32)

IDToZxy converts a Hilbert TileID to (Z,X,Y) tile coordinates.

func Makesync

func Makesync(logger *log.Logger, cliVersion string, file string, blockSizeKb int, checksum string) error

func MergeRanges

func MergeRanges(ranges []srcDstRange, overfetch float32) (*list.List, uint64)

MergeRanges takes a slice of SrcDstRanges, that: * is non-contiguous, and is sorted by NewOffset * an Overfetch parameter

• overfetch = 0.2 means we can request an extra 20%
• overfetch = 1.00 means we can double our total transfer size

Return a slice of OverfetchRanges

Each OverfetchRange is one or more input ranges
input ranges are merged in order of smallest byte distance to next range
until the overfetch budget is consumed.
The slice is sorted by Length

func NormalizeBucketKey

func NormalizeBucketKey(bucket string, prefix string, key string) (string, string, error)

func ParentID

func ParentID(i uint64) uint64

ParentID efficiently finds a parent Hilbert TileID without converting to (Z,X,Y).

func RelevantEntries

func RelevantEntries(bitmap *roaring64.Bitmap, maxzoom uint8, dir []EntryV3) ([]EntryV3, []EntryV3)

RelevantEntries finds the intersection of a bitmap and a directory return sorted slice of entries, and slice of all leaf entries any runlengths > 1 will be "trimmed" to the relevance bitmap

func SetBuildInfo

func SetBuildInfo(version, commit, date string)

SetBuildInfo initializes static metrics with pmtiles version, git hash, and build time

func Show

func Show(_ *log.Logger, bucketURL string, key string, showMetadataOnly bool, showTilejson bool, publicURL string, showTile bool, z int, x int, y int) error

Show prints detailed information about an archive.

func Sync

func Sync(logger *log.Logger, oldVersion string, newVersion string, dryRun bool) error

func UnmarshalRegion

func UnmarshalRegion(data []byte) (orb.MultiPolygon, error)

UnmarshalRegion parses JSON bytes into an orb.MultiPolygon region.

func Upload

func Upload(logger *log.Logger, input string, bucket string, key string, maxConcurrency int) error

Upload a pmtiles archive to a bucket.

func Verify

func Verify(_ *log.Logger, file string) error

Verify that an archive's header statistics are correct, and that tiles are propertly ordered if clustered=true.

func ZxyToID

func ZxyToID(z uint8, x uint32, y uint32) uint64

ZxyToID converts (Z,X,Y) tile coordinates to a Hilbert TileID.

Types

type Bucket

type Bucket interface {
	Close() error
	NewRangeReader(ctx context.Context, key string, offset int64, length int64) (io.ReadCloser, error)
	NewRangeReaderEtag(ctx context.Context, key string, offset int64, length int64, etag string) (io.ReadCloser, string, int, error)
}

Bucket is an abstration over a gocloud or plain HTTP bucket.

func OpenBucket

func OpenBucket(ctx context.Context, bucketURL string, bucketPrefix string) (Bucket, error)

type BucketAdapter

type BucketAdapter struct {
	Bucket *blob.Bucket
}

func (BucketAdapter) Close

func (ba BucketAdapter) Close() error

func (BucketAdapter) NewRangeReader

func (ba BucketAdapter) NewRangeReader(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)

func (BucketAdapter) NewRangeReaderEtag

func (ba BucketAdapter) NewRangeReaderEtag(ctx context.Context, key string, offset, length int64, etag string) (io.ReadCloser, string, int, error)

type Compression

type Compression uint8

Compression is the compression algorithm applied to individual tiles (or none)

type EntryV3

type EntryV3 struct {
	TileID    uint64
	Offset    uint64
	Length    uint32
	RunLength uint32
}

EntryV3 is an entry in a PMTiles spec version 3 directory.

type FileBucket

type FileBucket struct {
	// contains filtered or unexported fields
}

FileBucket is a bucket backed by a directory on disk

func NewFileBucket

func NewFileBucket(path string) *FileBucket

NewFileBucket initializes a FileBucket and returns a new instance

func (FileBucket) Close

func (b FileBucket) Close() error

func (FileBucket) NewRangeReader

func (b FileBucket) NewRangeReader(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)

func (FileBucket) NewRangeReaderEtag

func (b FileBucket) NewRangeReaderEtag(_ context.Context, key string, offset, length int64, etag string) (io.ReadCloser, string, int, error)

type HTTPBucket

type HTTPBucket struct {
	// contains filtered or unexported fields
}

func (HTTPBucket) Close

func (b HTTPBucket) Close() error

func (HTTPBucket) NewRangeReader

func (b HTTPBucket) NewRangeReader(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)

func (HTTPBucket) NewRangeReaderEtag

func (b HTTPBucket) NewRangeReaderEtag(ctx context.Context, key string, offset, length int64, etag string) (io.ReadCloser, string, int, error)

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is an interface that lets you swap out the default client with a mock one in tests

type HeaderV3

type HeaderV3 struct {
	SpecVersion         uint8
	RootOffset          uint64
	RootLength          uint64
	MetadataOffset      uint64
	MetadataLength      uint64
	LeafDirectoryOffset uint64
	LeafDirectoryLength uint64
	TileDataOffset      uint64
	TileDataLength      uint64
	AddressedTilesCount uint64
	TileEntriesCount    uint64
	TileContentsCount   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
}

HeaderV3 is a binary header for PMTiles specification version 3.

type RefreshRequiredError

type RefreshRequiredError struct {
	StatusCode int
}

RefreshRequiredError is an error that indicates the etag has chanced on the remote file

func (*RefreshRequiredError) Error

func (m *RefreshRequiredError) Error() string

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is an HTTP server for tiles and metadata.

func NewServer

func NewServer(bucketURL string, prefix string, logger *log.Logger, cacheSize int, cors string, publicURL string) (*Server, error)

NewServer creates a new pmtiles HTTP server.

func NewServerWithBucket

func NewServerWithBucket(bucket Bucket, _ string, logger *log.Logger, cacheSize int, cors string, publicURL string) (*Server, error)

NewServerWithBucket creates a new HTTP server for a gocloud Bucket.

func (*Server) Get

func (server *Server) Get(ctx context.Context, path string) (int, map[string]string, []byte)

Get a response for the given path. Return status code, HTTP headers, and body.

func (*Server) ServeHTTP

func (server *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) int

Serve an HTTP response from the archive

func (*Server) Start

func (server *Server) Start()

Start the server HTTP listener.

type TileType

type TileType uint8

TileType is the format of individual tile contents in the archive.

type Zxy

type Zxy struct {
	Z uint8
	X uint32
	Y uint32
}

Zxy coordinates of a single tile (zoom, column, row)