Crate pmtiles 

PMTiles (for Rust)

This crate implements the PMTiles v3 spec, originally created by Brandon Liu for Protomaps.

Features

• Opening and validating PMTile archives
• Querying tiles
• Backends supported:
  • Async mmap (Tokio) for local files
  • Async http and https (Reqwest + Tokio) for URLs
  • Async s3 (Rust-S3 + Tokio) for S3-compatible buckets
  • Async s3/azure/gcp/fs/http/mem/custom (object_store)
• Creating PMTile archives

Plans & TODOs

• Documentation and example code
• Support conversion to and from MBTiles + x/y/z
• Support additional backends (sync mmap and http at least)
• Support additional async styles (e.g., async-std)

PRs welcome!

Usage examples

Reading from a local PMTiles file

use bytes::Bytes;
use pmtiles::{AsyncPmTilesReader, TileCoord};

async fn get_tile(z: u8, x: u32, y: u32) -> Option<Bytes> {
  let file = "example.pmtiles";
  // Use `new_with_cached_path` for better performance
  let reader = AsyncPmTilesReader::new_with_path(file).await.unwrap();
  let coord = TileCoord::new(z, x, y).unwrap();
  reader.get_tile(coord).await.unwrap()
}

Reading from a URL with a simple directory cache

This example uses a simple hashmap-based cache to optimize reads from a PMTiles source. The same caching is available for all other methods. Note that HashMapCache is a rudimentary cache without eviction. You may want to build a more sophisticated cache for production use by implementing the DirectoryCache trait.

use bytes::Bytes;
use pmtiles::{AsyncPmTilesReader, HashMapCache, TileCoord};
use pmtiles::reqwest::Client;  // Re-exported Reqwest crate

async fn get_tile(z: u8, x: u32, y: u32) -> Option<Bytes> {
  let cache = HashMapCache::default();
  let client = Client::builder().use_rustls_tls().build().unwrap();
  let url = "https://protomaps.github.io/PMTiles/protomaps(vector)ODbL_firenze.pmtiles";
  let reader = AsyncPmTilesReader::new_with_cached_url(cache, client, url).await.unwrap();
  let coord = TileCoord::new(z, x, y).unwrap();
  reader.get_tile(coord).await.unwrap()
}

Reading from an S3 bucket with a directory cache

AWS client configuration is fairly none-trivial to document here. See AWS SDK documentation for more details.

use bytes::Bytes;
use pmtiles::{AsyncPmTilesReader, HashMapCache, TileCoord};
use pmtiles::aws_sdk_s3::Client; // Re-exported AWS SDK S3 client

async fn get_tile(client: Client, z: u8, x: u32, y: u32) -> Option<Bytes> {
  let cache = HashMapCache::default();
  let bucket = "https://s3.example.com".to_string();
  let key = "example.pmtiles".to_string();
  let reader = AsyncPmTilesReader::new_with_cached_client_bucket_and_path(cache, client, bucket, key).await.unwrap();
  let coord = TileCoord::new(z, x, y).unwrap();
  reader.get_tile(coord).await.unwrap()
}

Writing to a PMTiles file

use pmtiles::{PmTilesWriter, TileType, TileCoord};
use std::fs::File;

let file = File::create("example.pmtiles").unwrap();
let mut writer = PmTilesWriter::new(TileType::Mvt).create(file).unwrap();
let coord = TileCoord::new(0, 0, 0).unwrap();
writer.add_tile(coord, &[/*...*/]).unwrap();
writer.finalize().unwrap();

Development

• This project is easier to develop with just, a modern alternative to make. Install it with cargo install just.
• To get a list of available commands, run just.
• To run tests, use just test.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.

Test Data License

Some PMTile fixtures copied from official PMTiles repository.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports

pub use aws_sdk_s3;

pub use reqwest;

pub use s3;

pub use tilejson;

Structs

AsyncPmTilesReader

An asynchronous reader for PMTiles archives.

AwsS3Backend

Backend for reading PMTiles from AWS S3.

DirEntry

An entry in the PMTiles directory, representing a tile or a range of tiles.

DirEntryCoordsIter

Iterator over tile coordinates in a directory entry.

Directory

A directory of tile entries in a PMTiles file.

HashMapCache

A simple HashMap-based implementation of a PMTiles directory cache.

Header

The header of a PMTiles file, containing metadata about the tiles.

HttpBackend

Backend for reading PMTiles over HTTP.

MmapBackend

Backend for reading PMTiles from a memory-mapped file.

MokaCache

Provides an implementation of DirectoryCache using the moka crate.

NoCache

A cache that does not cache anything.

ObjectStoreBackend

Backend implementation using the object_store crate for unified storage access.

PmTilesStreamWriter

PMTiles streaming writer.

PmTilesWriter

Builder for creating a new writer.

S3Backend

Backend for reading PMTiles from S3.

TileCoord

Represents a tile coordinate in the PMTiles format.

TileId

Represents a unique identifier for a tile in the PMTiles format.

Enums

Compression

Supported compression types for PMTiles data.

DirCacheResult

Result of a directory cache lookup.

PmtError

Errors that can occur while reading PMTiles files.

TileType

Supported tile types for PMTiles.

Constants

MAX_TILE_ID

Maximum valid Tile ID in the PMTiles format.

MAX_ZOOM

Maximum valid Tile Zoom level in the PMTiles format.

PYRAMID_SIZE_BY_ZOOM

The pre-computed sizes of the tile pyramid for each zoom level. The size at zoom level z (array index) is equal to the number of tiles before that zoom level.

Traits

AsyncBackend

A trait for asynchronous backends that can read data from a PMTiles source.

DirectoryCache

A cache for PMTiles directories.

Type Aliases

PmtResult

A specialized Result type for PMTiles operations.