VersaTiles

VersaTiles is a Rust-based tool for processing and serving tile data efficiently. It supports multiple tile formats and offers functionalities for seamless tile handling.

Table of Contents

• Installation
  • Linux
  • MacOS
  • NixOS
  • Docker
  • Building with Cargo
  • Building from Source
• Usage
  • Convert Tiles
  • Serve Tiles
  • VersaTiles Pipeline Language
• Repository Structure
• Using as a Library
• Additional Information
• Contributing
• License

Installation

Linux

Install VersaTiles using the provided installation script ( that downloads the correct precompiled binary):

curl -Ls "https://github.com/versatiles-org/versatiles-rs/raw/main/helpers/install-unix.sh" | bash

MacOS

Install VersaTiles via Homebrew:

brew tap versatiles-org/versatiles
brew install versatiles

NixOS

VersaTiles is available via nixpkgs (starting from version 24.05). Add this snippet to configuration.nix:

environment.systemPackages = with pkgs; [ versatiles ];

Alternatively, use it in a shell environment:

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  buildInputs = with pkgs; [ versatiles ];
}

Find more details on Nix search.

Docker

Pull the latest Docker image for easy deployment:

docker pull versatiles-org/versatiles

Building with Cargo

Ensure you have Rust installed, then run:

cargo install versatiles

Building from Source

Clone the repository and build VersaTiles manually:

git clone https://github.com/versatiles-org/versatiles-rs.git
cd versatiles-rs
cargo build --bin versatiles --release
cp ./target/release/versatiles /usr/local/bin/

Usage

Run versatiles to see available commands:

Usage: versatiles [OPTIONS] <COMMAND>

Commands:
  convert  Convert between different tile containers
  probe    Show information about a tile container
  serve    Serve tiles via HTTP
  help     Show detailed help

Convert Tiles

Convert between different tile formats, e.g. from *.tar to *.versatiles:

versatiles convert satellite_tiles.tar satellite_tiles.versatiles

Serve Tiles

Serve tiles over HTTP:

versatiles serve satellite_tiles.versatiles

VersaTiles Pipeline Language

The VersaTiles Pipeline Language (VPL) allows you to define tile-processing pipelines. Operations include merging multiple tile sources, filtering, and modifying tile content.

Example of combining multiple vector tile sources:

from_overlayed [
   from_container filename="world.versatiles",
   from_container filename="europe.versatiles" | filter_zoom min=5,
   from_container filename="germany.versatiles"
]

More details can be found in versatiles_pipeline/README.md.

Repository Structure

Code

• /versatiles/ - Main library and binary
• /versatiles_container/ - Handles tile containers (*.versatiles, *.mbtiles, *.pmtiles, etc.)
• /versatiles_core/ - Core data types and utilities
• /versatiles_derive/ - Derive macros for the library
• /versatiles_geometry/ - Handles geometric data (OSM, GeoJSON, vector tiles, etc.)
• /versatiles_image/ - Manages image data (PNG, JPEG, WEBP)
• /versatiles_pipeline/ - VersaTiles Pipeline for efficient tile processing

Helpers

• /docker/ - Dockerfile for Linux builds
• /helpers/ - Scripts for checking, building, testing, and releasing
• /testdata/ - Test files for validation

Using as a Library

VersaTiles can be used as a command-line tool or integrated into Rust projects as a library. Check out crates.io and docs.rs for more details.

Additional Information

For advanced usage, guides, and detailed documentation, visit the official documentation.

Contributing

VersaTiles is actively developed, and contributions are welcome! If you find bugs, need features, or want to contribute, please check the GitHub repository and submit an issue or pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.