Crate versatiles_container 

VersaTiles Container: read, convert, and write tile containers.

This crate exposes a small set of building blocks to work with map tile containers:

• a registry that maps file extensions to readers/writers,
• reader traits and adapters to stream tiles,
• writer traits to serialize tiles,
• utilities like caching and streaming combinators.

It is designed for runtime composition: readers are object‑safe and can be wrapped by adapters (e.g. bbox filters, axis flips, compression overrides) and then written out with the appropriate writer inferred from the output path.

Quick start

use versatiles_container::*;
use versatiles_core::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Open a source container via the registry
    let runtime = TilesRuntime::default();
    let reader = runtime.reader_from_str("../testdata/berlin.mbtiles").await?;

    // Optionally adapt the reader: limit to a tile pyramid, keep compression as-is
    let params = TilesConverterParameters {
        tile_pyramid: Some(TilePyramid::new_full_up_to(8)),
        ..Default::default()
    };
    let reader = Arc::new(Box::new(TilesConvertReader::new_from_reader(reader, params).await?) as Box<dyn TileSource>);

    // Write to a target path; format is inferred from the extension
    let output = std::env::temp_dir().join("example.versatiles");
    runtime.write_to_path(reader, &output).await?;
    Ok(())
}

Features

• cli: enables human‑readable probing of containers and tiles.
• test: helpers for integration tests in downstream crates.

See also

• ContainerRegistry: register custom reader/writer implementations at runtime
• TileSource, TilesWriter: object‑safe traits for IO
• TilesConvertReader, convert_tiles_container: convenience conversion helpers

Re-exports

pub use cache::*;

pub use progress::*;

pub use runtime::*;

Modules

cache

Caching subsystem for VersaTiles.

progress

runtime

Re‑exports progress tracking and event bus types. Runtime configuration and services for tile processing operations

Structs

ContainerRegistry

Re‑exports reader/writer traits, converters, and auxiliary types. Registry mapping file extensions to async tile container readers and writers.

DataSource

Re‑exports reader/writer traits, converters, and auxiliary types. Represents a parsed input specification which may include a driver prefix (like mbtiles:). It can resolve standard input (-) into an in-memory Blob and derives the effective extension that determines which reader to pick.

DirectoryReader

Re‑exports the container registry and common open/write helpers. A reader for tiles stored in a directory structure.

DirectoryTileSink

Re‑exports the container registry and common open/write helpers. A tile sink that writes pre-compressed blobs to a directory tree.

DirectoryWriter

Re‑exports the container registry and common open/write helpers. Writes a directory-based tile pyramid along with a compressed TileJSON (tiles.json[.<br|gz>]).

MBTilesReader

Re‑exports the container registry and common open/write helpers. Reader for MBTiles (SQLite) containers.

MBTilesTileSink

Re‑exports the container registry and common open/write helpers. A tile sink that writes pre-compressed blobs into an MBTiles SQLite database.

MBTilesWriter

Re‑exports the container registry and common open/write helpers. Writer for MBTiles (SQLite) containers.

PMTilesReader

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

PMTilesWriter

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

TarTileSink

Re‑exports the container registry and common open/write helpers. A tile sink that writes pre-compressed blobs into a .tar archive.

TarTilesReader

Re‑exports the container registry and common open/write helpers. Reader for tiles stored inside a tar archive.

TarTilesWriter

Re‑exports the container registry and common open/write helpers.

Tile

Re‑exports reader/writer traits, converters, and auxiliary types. A lazy tile container that can hold either an encoded blob or decoded content.

TileProcessor

Re‑exports reader/writer traits, converters, and auxiliary types. Base struct for tile processors that wrap a single upstream source.

TileSourceMetadata

Re‑exports reader/writer traits, converters, and auxiliary types. Metadata describing the output characteristics of a tile source.

TilesConvertReader

Re‑exports reader/writer traits, converters, and auxiliary types. Reader adapter that applies coordinate transforms, bbox filtering, and optional compression changes on-the-fly.

TilesConverterParameters

Re‑exports reader/writer traits, converters, and auxiliary types. Parameters that control how tiles are transformed during reading/conversion.

Traversal

Represents a traversal strategy for iterating over tile bounding boxes.

TraversalSize

Represents allowed sizes of a block of tiles The size is represented as log2(size). For example, TraversalSize { max: 6 } represents block of sizes up to 64 tiles.

VersaTilesReader

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

VersaTilesSink

Re‑exports the container registry and common open/write helpers. A tile sink that buffers tiles to temporary files and assembles a .versatiles container on finish.

VersaTilesWriter

Re‑exports the container registry and common open/write helpers. Writer for .versatiles containers.

Enums

DataLocation

Re‑exports reader/writer traits, converters, and auxiliary types. A flexible location of data used across I/O code.

SourceType

Re‑exports reader/writer traits, converters, and auxiliary types. Distinguishes between different tile source types.

TileContent

Re‑exports reader/writer traits, converters, and auxiliary types. Decoded tile content (raster or vector).

TraversalOrder

Strategies for ordering tiles when traversing a tile pyramid.

TraversalTranslationStep

Represents a single operation during traversal translation from one traversal configuration to another.

Traits

TileSink

Re‑exports reader/writer traits, converters, and auxiliary types. Push-model interface for writing individual tiles to a container in any order.

TileSource

Re‑exports reader/writer traits, converters, and auxiliary types. Unified object-safe interface for reading or processing tiles.

TileSourceTraverseExt

Extension trait providing traversal with higher-rank trait bounds (HRTBs).

TilesReader

Re‑exports reader/writer traits, converters, and auxiliary types. Interface for opening tile containers from paths or data readers.

TilesWriter

Re‑exports reader/writer traits, converters, and auxiliary types. Object‑safe interface for writing tiles from a reader into a container format.

Functions

convert_tiles_container

Re‑exports reader/writer traits, converters, and auxiliary types. Converts tiles from the given reader and writes them to path using the provided runtime.

convert_tiles_container_to_str

Re‑exports reader/writer traits, converters, and auxiliary types. Converts tiles from the given reader and writes them to a string destination.

deduplicating_tile_sink

Re‑exports reader/writer traits, converters, and auxiliary types. Wrap a tile sink so that each coordinate is written at most once.

open_tile_sink

Re‑exports reader/writer traits, converters, and auxiliary types. Open a tile sink based on the destination’s file extension.

translate_traversals

Translates traversal steps from a reading traversal configuration to a writing traversal configuration.

Type Aliases

SharedTileSource

Re‑exports reader/writer traits, converters, and auxiliary types. Shared ownership of a tile source for concurrent access.