versatiles_container

Read, convert, and write tile containers for VersaTiles.

Overview

versatiles_container provides the I/O layer for working with map tile containers in multiple formats. It offers a unified interface for reading from and writing to various tile storage formats through a registry-based system with runtime composition.

This crate is designed for flexibility: readers are object-safe and can be wrapped by adapters (bbox filters, axis flips, compression overrides) before being written with the appropriate writer.

Supported Formats

• .versatiles: Native VersaTiles container format
• .mbtiles: MBTiles (SQLite-based)
• .pmtiles: PMTiles (cloud-optimized)
• .tar: TAR archives
• Directories: Tile files in directory structures

Features

• Format Registry: Automatic reader/writer selection based on file extension
• Stream Processing: Efficient tile streaming with minimal memory overhead
• Runtime Composition: Chain adapters to transform tile streams (filtering, compression, coordinate transforms)
• Caching: Built-in tile and metadata caching
• Progress Tracking: Monitor conversion progress with event bus

Usage

cargo add versatiles_container versatiles_core

Or see crates.io/crates/versatiles_container for version info and docs.rs/versatiles_container for API documentation.

Example

use versatiles_container::*;
use versatiles_core::*;

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

    // Optionally adapt the reader: limit to a bbox pyramid
    let params = TilesConverterParameters {
        bbox_pyramid: Some(TileBBoxPyramid::new_full_up_to(8)),
        ..Default::default()
    };
    let reader = Box::new(TilesConvertReader::new_from_reader(reader, params)?);

    // Write to a target path; format is inferred from the extension
    runtime.write_to_path(reader, "output.versatiles").await?;
    Ok(())
}

API Documentation

For detailed API documentation, see docs.rs/versatiles_container.

Part of VersaTiles

This crate is part of the VersaTiles project, a toolbox for working with map tile containers in various formats.

For the complete toolset including CLI tools and servers, see the main VersaTiles repository.

License

MIT License - see LICENSE for details.