Struct PMTilesReader 

pub struct PMTilesReader {
    pub data_reader: Arc<DataReader>,
    pub header: HeaderV3,
    pub internal_compression: TileCompression,
    pub leaves_bytes: Arc<Blob>,
    pub leaves_cache: Cache<ByteRange, Arc<EntriesV3>>,
    pub tilejson: TileJSON,
    pub metadata: TileSourceMetadata,
    pub root_bytes_uncompressed: Blob,
    pub root_entries: Arc<EntriesV3>,
}

Re‑exports the container registry and common open/write helpers. Reader for PMTiles v3 containers.

Parses the header and directory blobs, merges embedded TileJSON, computes a tile pyramid by traversing directory entries, and exposes tiles via the TileSource interface.

Fields

data_reader: Arc<DataReader>

Underlying byte source used to read header, directories, and tile data.

header: HeaderV3

Parsed PMTiles v3 header with byte ranges, counts, and compression flags.

internal_compression: TileCompression

Compression algorithm used for internal metadata/directories (e.g., gzip).

leaves_bytes: Arc<Blob>

Raw (compressed) concatenated blob of all leaf directories.

leaves_cache: Cache<ByteRange, Arc<EntriesV3>>

Decompression cache mapping leaf directory byte ranges to parsed entries. Concurrent loads of the same range dedup automatically; distinct ranges decompress in parallel.

tilejson: TileJSON

Merged TileJSON metadata extracted from the PMTiles metadata range.

metadata: TileSourceMetadata

Runtime parameters (tile format, compression, tile pyramid) advertised by this reader.

root_bytes_uncompressed: Blob

Uncompressed root directory blob.

root_entries: Arc<EntriesV3>

Parsed entries of the root directory (shared across queries).

Implementations

impl PMTilesReader

pub async fn open(path: &Path, runtime: TilesRuntime) -> Result<PMTilesReader>

Open a PMTiles container from an absolute filesystem path.

Validates and opens a DataReaderFile, then delegates to PMTilesReader::open_data.

Errors

Returns an error if the file cannot be opened.

pub async fn open_data( data_reader: DataReader, _runtime: TilesRuntime, ) -> Result<PMTilesReader>

where Self: Sized,

Open a PMTiles container from an existing DataReader.

Reads the v3 header, decompresses and parses the metadata (TileJSON) and root directory, prepares leaf directory bytes, computes the tile pyramid, and initializes caches for fast lookups.

Errors

Returns an error if reading or decompression fails, or if the header/dirs are invalid.

pub fn tile_entries(&self) -> Result<EntriesV3>

Decode and return the root directory entries (EntriesV3).

Trait Implementations

impl Debug for PMTilesReader

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TileSource for PMTilesReader

fn metadata(&self) -> &TileSourceMetadata

Returns the current reader parameters (tile format, compression, tile pyramid).

fn tilejson(&self) -> &TileJSON

Returns the parsed and merged TileJSON metadata.

fn tile<'life0, 'life1, 'async_trait>( &'life0 self, coord: &'life1 TileCoord, ) -> Pin<Box<dyn Future<Output = Result<Option<Tile>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch a tile by XYZ coordinate.

Converts the coordinate to a Hilbert tile ID, then traverses up to three levels of PMTiles directories to locate the tile. Leaf directories are cached to avoid repeated decompression. Returns Ok(None) if the tile does not exist.

fn source_type(&self) -> Arc<SourceType>

Returns the source type (container format, processor name, or composite).

fn tile_pyramid<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Arc<TilePyramid>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Gets the actual tile pyramid for this source.

fn tile_stream<'life0, 'async_trait>( &'life0 self, bbox: TileBBox, ) -> Pin<Box<dyn Future<Output = Result<TileStream<'static, Tile>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Asynchronously streams all tiles within the given bounding box.

fn tile_size_stream<'life0, 'async_trait>( &'life0 self, bbox: TileBBox, ) -> Pin<Box<dyn Future<Output = Result<TileStream<'static, u32>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Streams the stored byte sizes of all tiles within the given bounding box.

fn tile_coord_stream<'life0, 'async_trait>( &'life0 self, bbox: TileBBox, ) -> Pin<Box<dyn Future<Output = Result<TileStream<'static, ()>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Streams which tile coordinates exist within the given bounding box.

fn boxed(self) -> Box<dyn TileSource>

where Self: Sized + 'static,

Converts self into a boxed trait object for dynamic dispatch.

fn into_shared(self) -> SharedTileSource

where Self: Sized + 'static,

Converts self into a shared reference for concurrent access.

impl TilesReader for PMTilesReader

fn open_reader<'async_trait>( reader: DataReader, runtime: TilesRuntime, ) -> Pin<Box<dyn Future<Output = Result<SharedTileSource>> + Send + 'async_trait>>

Opens a tile container from the provided DataReader source.

fn supports_data_reader() -> bool

Returns true when the reader can open from a generic DataReader source (e.g. for HTTP). File-only readers (MBTiles, TAR) return false.

fn open_path<'life0, 'async_trait>( path: &'life0 Path, runtime: TilesRuntime, ) -> Pin<Box<dyn Future<Output = Result<SharedTileSource>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Opens a tile container from the file or directory at path.