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(TilesConvertReader::new_from_reader(reader, params).await?);

    // 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(())
}

Four traits, two axes

Reading and writing are each split in two, which is easier to hold onto as a grid than as four separate names:

	Open a container	Move the tiles
Read	TilesReader — a path or a DataReader becomes a source	TileSource — the tiles, object‑safe, wrappable by adapters
Write	TilesWriter — serialise a whole source in one pass	TileSink — take tiles one at a time, shared across threads

The read row is a pipeline: a TilesReader opens something and hands back a TileSource, and everything downstream — adapters, the server, the VPL pipeline — only ever sees the source.

The write row is a choice, and it is the one worth understanding. A TilesWriter is handed the entire source and writes the file its own way, which is what versatiles convert uses. A TileSink is the opposite: it is wrapped in an Arc, shared by several threads, and fed tiles in whatever order they finish — which is what versatiles mosaic needs, because it composites tiles as they are produced.

Which formats do what

Format	Read	Write whole	Write incrementally
.versatiles	✓	✓	✓
.mbtiles	✓	✓	✓
.tar	✓	✓	✓
directory	✓	✓	✓
.pmtiles	✓	✓	—

PMTiles is the one gap, and it follows from the format rather than from an omission: a clustered archive stores its tiles ordered by Hilbert index, so the order cannot be known until every tile is in. PMTilesWriter gets there by reordering through a temporary file, which a sink — receiving tiles as they arrive, with no idea what is still coming — cannot do. Writing PMTiles therefore goes through the registry, not through open_tile_sink.

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
• open_tile_sink: pick a TileSink from a destination path
• TilesConvertReader, convert_tiles_container: convenience conversion helpers

Re-exports

pub use cache::*;

pub use probe::*;

pub use progress::*;

pub use runtime::*;

Modules

cache

Caching subsystem for VersaTiles.

probe

Container analysis: what a probe works out, as data rather than as output.

progress

Progress reporting.

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.

RemappedTileSource

Re‑exports reader/writer traits, converters, and auxiliary types. Presents a source under relabelled tile coordinates.

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. Writes a source into an uncompressed .tar archive of tile files.

Tile

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

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.

TraversalTranslation

How a source traversing one way can feed a writer requiring another.

TraversalTranslationStep

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

Constants

DEFAULT_TILE_COUNT_LIMIT

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

TILE_COUNT_LIMIT_ENV

Re‑exports reader/writer traits, converters, and auxiliary types. Environment variable overriding DEFAULT_TILE_COUNT_LIMIT; 0 disables the check.

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).

TileStreamErrorExt

Re‑exports reader/writer traits, converters, and auxiliary types. Routes per-tile failures to the runtime instead of unwrapping them.

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 a source into a container at path, applying cp.

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.

resolve_tile_count_limit

Re‑exports reader/writer traits, converters, and auxiliary types. The tile-count limit in force, from TILE_COUNT_LIMIT_ENV or DEFAULT_TILE_COUNT_LIMIT. 0 maps to u64::MAX, i.e. no limit.

translate_traversals

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

translation_between

Decides how (or whether) read can feed write, without doing the work.

Type Aliases

SharedTileSource

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