versatiles-org/versatiles-rsPublic

NotificationsYou must be signed in to change notification settings
Fork9
Star276

Core Rust implementation of the VersaTiles toolkit for converting, validating, and serving map tiles in multiple formats.

License

MIT license

276 stars 9 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 3,049 Commits
.cargo		.cargo
.github		.github
docker		docker
scripts		scripts
testdata		testdata
versatiles		versatiles
versatiles_container		versatiles_container
versatiles_core		versatiles_core
versatiles_derive		versatiles_derive
versatiles_geometry		versatiles_geometry
versatiles_image		versatiles_image
versatiles_node		versatiles_node
versatiles_pipeline		versatiles_pipeline
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.markdownlintignore		.markdownlintignore
.prettierignore		.prettierignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
README.md		README.md
RELEASING.md		RELEASING.md
codecov.yml		codecov.yml
lefthook.yml		lefthook.yml
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml

Repository files navigation

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.

Installation

Linux

Install VersaTiles using the providedinstallation script (that downloads the correctprecompiled binary):

curl -Ls"https://github.com/versatiles-org/versatiles-rs/releases/latest/download/install-unix.sh"| sudo sh

MacOS

Install VersaTiles viaHomebrew:

brew tap versatiles-org/versatilesbrew install versatiles

NixOS

VersaTiles is available vianixpkgs (starting from version 24.05):

Add this snippet toconfiguration.nix:

environment.systemPackages=withpkgs;[versatiles];

Alternatively, use it in a shell environment:

{pkgs ?import<nixpkgs>{}}:pkgs.mkShell{buildInputs=withpkgs;[versatiles];}

Find more details onNix search.

Docker

Pull the latestDocker image for easy deployment:

docker pull versatiles-org/versatiles

npm (Node.js)

Install the Node.js bindings for use in JavaScript/TypeScript projects:

npm install @versatiles/versatiles-rs

Prerelease Versions

Test upcoming features with prerelease tags:

# Alpha (bleeding edge)npm install @versatiles/versatiles-rs@alpha# Beta (feature complete, testing)npm install @versatiles/versatiles-rs@beta# Release Candidate (final testing)npm install @versatiles/versatiles-rs@rc

See all available versions:

npm view @versatiles/versatiles-rs versions

Building with Cargo

Ensure you haveRust 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.gitcd versatiles-rscargo build --bin versatiles --releasecp ./target/release/versatiles /usr/local/bin/

Quick Start

Get started with VersaTiles in 3 steps:

1. Verify Installation

versatiles --version

2. Download Sample Data

# Download a small region (Berlin, ~60MB)versatiles convert --bbox=13.0,52.3,13.8,52.7 --bbox-border=3 https://download.versatiles.org/osm.versatiles berlin.versatiles

3. Explore Your Data

# View tile informationversatiles probe berlin.versatiles# Serve tiles locallyversatiles serve berlin.versatiles# Access at http://localhost:8080

Common Workflows

Convert tile formats:

versatiles convert input.mbtiles output.versatiles

Filter by zoom level:

versatiles convert --min-zoom=5 --max-zoom=12 input.versatiles output.versatiles

Extract a region:

versatiles convert --bbox=13.0,52.3,13.8,52.7 world.versatiles berlin.versatiles

Usage

Core Concepts

VersaTiles works withtile containers - files or directories containing map tiles organized by zoom level (z), column (x), and row (y).

Supported formats:

.versatiles - Native format (best compression, fastest access)
.mbtiles - SQLite-based (widely compatible)
.pmtiles - Cloud-optimized single-file format
.tar - Simple archive format
Directories - Folder structure:z/x/y.ext

Remote access: VersaTiles can read remote.versatiles and.pmtiles files via HTTPS:

versatiles serve https://download.versatiles.org/osm.versatiles

Commands

Runversatiles 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  dev      Developer tools (unstable)  help     Show detailed help

convert - Convert Between Tile Formats

Convert tiles between formats, filter by region or zoom, and transform coordinates.

Basic conversion:

versatiles convert input.mbtiles output.versatiles

Advanced options:

Option	Description	Example
`--min-zoom`,`--max-zoom`	Filter zoom levels	`--min-zoom=5 --max-zoom=12`
`--bbox`	Extract region (lon_min,lat_min,lon_max,lat_max)	`--bbox=13.0,52.3,13.8,52.7`
`--bbox-border`	Add border tiles around bbox	`--bbox-border=3`
`--compress`	Set compression (gzip, brotli, zstd)	`--compress=brotli`
`--tile-format`	Convert tile format (png, jpg, webp, avif, pbf)	`--tile-format=webp`
`--swap-xy`	Swap X/Y coordinates (z/x/y → z/y/x)	`--swap-xy`
`--flip-y`	Flip tiles vertically	`--flip-y`

Real-world examples:

# Extract city region from world tilesversatiles convert --bbox=13.0,52.3,13.8,52.7 \  world.versatiles berlin.versatiles# Compress tiles with maximum compressionversatiles convert --compress=brotli \  uncompressed.tar compressed.versatiles# Convert image format for smaller file sizeversatiles convert --tile-format=webp \  tiles.mbtiles tiles-webp.versatiles# Fix coordinate system (TMS to XYZ)versatiles convert --flip-y \  tms-tiles.mbtiles xyz-tiles.versatiles# Remote conversion with zoom filteringversatiles convert --min-zoom=1 --max-zoom=10 \  https://download.versatiles.org/osm.versatiles \  local-osm-filtered.versatiles

probe - Inspect Tile Containers

Analyze tile containers to understand their contents and structure.

Basic usage:

versatiles probe tiles.versatiles

Depth levels:

Level	Flag	Scans	Use Case
1	`-d`	Container metadata	Quick info (zoom range, tile format)
2	`-dd`	All tile coordinates	Find actual tile coverage
3	`-ddd`	Tile contents	Analyze tile sizes, validate data

Examples:

# Quick metadata checkversatiles probe tiles.versatiles -d# Find actual zoom range with tilesversatiles probe tiles.versatiles -dd# Deep inspection with tile statisticsversatiles probe tiles.versatiles -ddd# Probe remote containerversatiles probe https://download.versatiles.org/osm.versatiles -d

serve - HTTP Tile Server

Run a local or production tile server with advanced configuration.

Basic usage:

versatiles serve tiles.versatiles# Access at http://localhost:8080

Server options:

Option	Description	Default
`-i, --ip`	Bind IP address	0.0.0.0
`-p, --port`	Port number	8080
`-c, --config`	YAML configuration file	-
`--minimal-recompression`	Fast serving (less compression)	false
`--disable-api`	Disable`/api` endpoints	false

Custom tile IDs:

Assign custom IDs to tile sources using bracket or hash syntax:

# Bracket prefix: [id]sourceversatiles serve [osm]tiles.versatiles# Bracket suffix: source[id]versatiles serve tiles.versatiles[osm]# Hash syntax: source#idversatiles serve tiles.versatiles#osm

Access tiles at:http://localhost:8080/{id}/{z}/{x}/{y}.{ext}

Static content serving:

# Serve tar archive at rootversatiles serve -s"static.tar.br" tiles.versatiles# Serve with custom prefixversatiles serve -s"[/assets]static.tar.gz" tiles.versatiles# Access: http://localhost:8080/assets/...# Multiple static sources (first match wins)versatiles serve \  -s"[/styles]styles.tar.br" \  -s"[/fonts]fonts.tar.gz" \  tiles.versatiles

Supported static formats:.tar,.tar.gz,.tar.br, directories

Remote serving:

# Serve remote tiles directlyversatiles serve https://download.versatiles.org/osm.versatiles# Mix local and remote sourcesversatiles serve \  [local]local.versatiles \  [osm]https://download.versatiles.org/osm.versatiles

Configuration file:

For production deployments, use YAML configuration (seeConfiguration section):

versatiles serve -c production.yaml

For a full description of all configuration options:

versatileshelp config

dev - Developer Tools (Unstable)

Experimental tools for tile analysis and debugging.

measure-tile-sizes - Generate a visual heatmap of tile sizes:

versatiles dev measure-tile-sizes tiles.versatiles output.png# With optionsversatiles dev measure-tile-sizes \  --level=14 \  --scale=4 \  tiles.versatiles output.png

Output: PNG image where brightness = 10*log2(tile_size). Use to identify large tiles or data quality issues.

export-outline - Export tile coverage as GeoJSON:

versatiles dev export-outline tiles.versatiles coverage.geojson# Specify zoom level (default: max zoom)versatiles dev export-outline --level=10 tiles.versatiles coverage.geojson

Output: GeoJSON polygon showing which areas have tiles. Useful for visualizing coverage in QGIS/Mapbox.

print-tilejson - Print TileJSON metadata:

# Compact JSONversatiles dev print-tilejson tiles.versatiles# Pretty-printed JSONversatiles dev print-tilejson -p tiles.versatiles

Output: Standard TileJSON 3.0.0 format with attribution, bounds, zoom levels, etc.

help - Detailed Help Topics

Get detailed help for specific topics:

# Pipeline language referenceversatileshelp pipeline# Configuration file referenceversatileshelp config# Raw markdown output (for documentation)versatileshelp pipeline --raw

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_merged_vector [   from_container filename="world.versatiles",   from_container filename="europe.versatiles" | filter level_min=5,   from_container filename="germany.versatiles"]

More details can be found inversatiles_pipeline/README.md.

Configuration

For production deployments, use YAML configuration files for fine-grained control over the tile server.

Basic Configuration

server:ip:0.0.0.0port:8080minimal_recompression:false# true = faster, larger responsesdisable_api:false# true = disable /api endpointstiles:  -name:osmsrc:"./tiles/osm.versatiles"  -name:satellitesrc:"https://tiles.example.com/sat.versatiles"static:  -src:"./static"prefix:"/"

Start with config:

versatiles serve -c config.yaml

Key Features

CORS Configuration - Control cross-origin access:

cors:allowed_origins:    -"https://example.org"# Exact domain    -"*.dev.example.org"# Subdomain wildcard    -"https://example.*"# TLD wildcard    -"/^https://.*\\.example\\.org$/"# Regex patternmax_age_seconds:86400

Custom Response Headers - Add caching and CDN headers:

extra_response_headers:Cache-Control:"public, max-age=86400, immutable"Surrogate-Control:"max-age=604800"# For VarnishCDN-Cache-Control:"max-age=604800"# For CDNs

Multiple Tile Sources - Serve multiple tile sets:

tiles:# Local file  -name:citysrc:"./city.versatiles"# Remote HTTPS  -name:osmsrc:"https://download.versatiles.org/osm.versatiles"# MBTiles format  -name:elevationsrc:"./terrain.mbtiles"# VPL pipeline (processed on-the-fly)  -name:processedsrc:"./pipeline.vpl"

Access tiles at:http://localhost:8080/{name}/{z}/{x}/{y}.{ext}

Static Content - Serve styles, fonts, and sprites:

static:# Tar archive at root  -src:"./static.tar.br"prefix:"/"# Directory at custom path  -src:"./public"prefix:"/assets"

Supported formats: directories,.tar,.tar.gz,.tar.br

Complete Example

server:ip:0.0.0.0port:8080minimal_recompression:falsecors:allowed_origins:    -"https://myapp.com"    -"*.myapp.dev"max_age_seconds:86400extra_response_headers:Cache-Control:"public, max-age=86400"tiles:  -name:basemapsrc:"https://download.versatiles.org/osm.versatiles"  -name:satellitesrc:"./satellite.mbtiles"static:  -src:"./styles.tar.br"prefix:"/styles"  -src:"./fonts.tar.gz"prefix:"/fonts"

Full Reference

For complete configuration documentation, see:

versatiles/CONFIG.md - Full reference (auto-generated)

Or run:

versatileshelp config

Environment Variables

VersaTiles supports the following environment variables:

VERSATILES_CACHE_DIR - Enable disk-based tile caching. This is useful if you want to convert large tile sets with thefrom_gdal_raster VPL operation but have limited memory. Example:VERSATILES_CACHE_DIR=/tmp/versatiles_cache

Example usage:

# In one lineVERSATILES_CACHE_DIR=/var/cache/versatiles versatiles serve tiles.versatiles# orexport VERSATILES_CACHE_DIR=/tmp/versatiles_cacheversatiles serve https://download.versatiles.org/osm.versatiles

GDAL support

versatiles supports GDAL since v1.0.0. However, this is still experimental.

Building with GDAL support

Due to the numerous combinations of operating systems, package managers and GDAL versions, we must streamline this ecosystem. If you require GDAL support, we recommend the following:

Build GDAL locally by running./scripts/install-gdal.sh. This will build and install GDAL in the subfolder./.toolchain/gdal
Buildversatiles with the featuresgdal. We recommend using the scripts./scripts/build_debug.sh and./scripts/build_release.sh.

Development

VersaTiles is built with Rust and includes Node.js bindings (NAPI-RS).

Prerequisites

Required:

Rust 1.92+ (installation)
Node.js 20+ (for Node.js bindings)

Optional:

Lefthook - Pre-commit hooks
GDAL 3.x - For GDAL support (build instructions)

Setup

# Clone repositorygit clone https://github.com/versatiles-org/versatiles-rs.gitcd versatiles-rs# Build debug versioncargo build --bin versatiles# Run testscargotest# Run binary./target/debug/versatiles --version

Development Workflow

Running All Checks

Verify code quality before committing:

./scripts/check.sh

This runs:

Rust: formatting (rustfmt), linting (clippy), type-checking, tests, doc tests
Node.js: formatting (Prettier), linting (ESLint), type-checking (TypeScript), tests (Vitest)

Quick Fixes

Rust:

# Auto-formatcargo fmt# Auto-fix clippy warningscargo clippy --fix# Run specific testscargotest raster_overscalecargotest --package versatiles_pipeline

Node.js:

cd versatiles_node# Auto-fix all issuesnpm run fix# Individual tasksnpm run format# Prettiernpm run lint:fix# ESLint auto-fixnpm run typecheck# TypeScript checknpmtest# Vitest

Building

Debug build (fast compilation, slow execution):

cargo build --bin versatiles# Output: ./target/debug/versatiles

Release build (slow compilation, fast execution):

cargo build --bin versatiles --release# Output: ./target/release/versatiles

With GDAL support:

# Build GDAL first./scripts/install-gdal.sh# Build with GDAL features./scripts/build_release.sh

Testing

# All testscargotest# Specific packagecargotest --package versatiles_corecargotest --package versatiles_pipeline# Specific testcargotest raster_overscale# With outputcargotest -- --nocapture# Ignored tests (long-running)cargotest -- --ignored

Documentation

# Generate docscargo doc --no-deps --open# Test docscargotest --doc

Pre-commit Hooks (Recommended)

InstallLefthook for automatic quality checks:

# macOSbrew install lefthook# Linuxcurl -fsSL https://raw.githubusercontent.com/evilmartians/lefthook/main/install.sh| sh# Windowsscoop install lefthook# Enable hookslefthook install

Hook behavior:

pre-commit: Fast checks (formatting, basic linting)
pre-push: Full checks (all tests, clippy, type-checking)

Skip hooks when needed:

# Skip pre-commitLEFTHOOK=0 git commit -m"message"# Skip pre-pushgit push --no-verify

Node.js Bindings Development

Seeversatiles_node/CONTRIBUTING.md for detailed workflow.

Quick reference:

cd versatiles_node# Install dependenciesnpm install# Build Rust bindingsnpm run build# Build debug (faster compilation)npm run build:debug# Run testsnpmtest# Full check before commitnpm run check

Contributing

We welcome contributions! Please:

Fork and create a feature branch:
```
git checkout -b feature/my-feature
```
Make changes and test:
```
./scripts/check.sh
```
Commit with clear messages:
```
git commit -m"feat: add new feature"
```
Push and create pull request:
```
git push origin feature/my-feature
```

Commit message format:

feat: New feature
fix: Bug fix
docs: Documentation only
style: Formatting, no code change
refactor: Code restructuring
test: Adding tests
chore: Maintenance tasks

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

Dependencies of the versatiles packages:

---config:  layout: elk---flowchart TB    versatiles --> versatiles_container    versatiles --> versatiles_core    versatiles --> versatiles_derive    versatiles --> versatiles_geometry    versatiles --> versatiles_image    versatiles --> versatiles_pipeline    versatiles_container --> versatiles_core    versatiles_container --> versatiles_derive    versatiles_container --> versatiles_geometry    versatiles_container --> versatiles_image    versatiles_core --> versatiles_derive    versatiles_geometry --> versatiles_core    versatiles_geometry --> versatiles_derive    versatiles_image --> versatiles_core    versatiles_image --> versatiles_derive    versatiles_node --> versatiles    versatiles_node --> versatiles_container    versatiles_node --> versatiles_core    versatiles_pipeline --> versatiles_container    versatiles_pipeline --> versatiles_core    versatiles_pipeline --> versatiles_derive    versatiles_pipeline --> versatiles_geometry    versatiles_pipeline --> versatiles_image

Helpers

/docker/ - Dockerfile for Linux builds
/testdata/ - Test files for validation
/scripts/ - Development and CI/CD automation scripts:

Script	Purpose
`build-debug.sh`	Build debug binary with GDAL
`build-release.sh`	Build release binary with GDAL support
`check.sh`	Run all checks (formatting, linting, tests Rust + Node.js)
`install-gdal.sh`	Install GDAL from source into`.toolchain/gdal`
`audit-unused-deps.sh`	Find unused dependencies
`build-docker-*.sh`	Build Docker images (GDAL, multi-platform)
`build-docs*.sh`	Generate documentation
`install-unix.sh`	Install VersaTiles binary on Unix platforms
`install-windows.ps1`	Install VersaTiles binary on Windows
`perf-benchmarks.sh`	Run performance benchmarks
`release-package.sh`	Create versioned releases
`sync-version.sh`	Synchronize versions across workspace
`test-coverage.sh`	Generate code coverage reports
`test-unix.sh`	Run tests on Unix platforms
`test-windows.ps1`	Run tests on Windows
`upgrade-deps.sh`	Update Rust dependencies to latest versions
`workflow-*.sh/ps1`	CI/CD workflow automation

Most commonly used:check.sh,build-release.sh,release-package.sh

Using as a Library

VersaTiles can be used as a command-line tool or integrated into Rust projects as a library. Check outcrates.io anddocs.rs for more details.

Additional Information

For advanced usage, guides, and detailed documentation, visit theofficial documentation.

For Maintainers

Creating a Release

SeeRELEASING.md for the complete release process.

Quick version:

# Interactive mode - select release type from menu./scripts/release-package.sh# Or use command-line argument./scripts/release-package.sh patch# or minor/major/alpha/beta/rc/dev# Push to trigger automated releasegit push origin main --follow-tags

The GitHub Actions workflow will automatically:

Build CLI binaries for 8 platforms (Linux gnu/musl x64/arm64, macOS x64/arm64, Windows x64/arm64)
Build NAPI-RS bindings for Node.js (8 platform-specific packages)
Publish to npmjs.com (@versatiles/versatiles-rs + 8 platform-specific packages)
Create GitHub release with CLI binaries
Trigger Docker and Homebrew updates

Contributing

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

License

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

About

Core Rust implementation of the VersaTiles toolkit for converting, validating, and serving map tiles in multiple formats.

versatiles.org

Releases104

v3.6.2 Latest

Feb 14, 2026

+ 103 releases

Sponsor this project

Learn more about GitHub Sponsors

Movatterモバイル変換

Uh oh!

License

versatiles-org/versatiles-rs

Folders and files

Latest commit

History

Repository files navigation

VersaTiles

Table of Contents

Installation

Linux

MacOS

NixOS

Docker

npm (Node.js)

Prerelease Versions

Building with Cargo

Building from Source

Quick Start

1. Verify Installation

2. Download Sample Data

3. Explore Your Data

Common Workflows

Usage

Core Concepts

Commands

convert - Convert Between Tile Formats

probe - Inspect Tile Containers

serve - HTTP Tile Server

dev - Developer Tools (Unstable)

help - Detailed Help Topics

VersaTiles Pipeline Language

Configuration

Basic Configuration

Key Features

Complete Example

Full Reference

Environment Variables

GDAL support

Building with GDAL support

Development

Prerequisites

Setup

Development Workflow

Running All Checks

Quick Fixes

Building

Testing

Documentation

Pre-commit Hooks (Recommended)

Node.js Bindings Development

Contributing

Repository Structure

Code

Helpers

Using as a Library

Additional Information

For Maintainers

Creating a Release

Contributing

License

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases104

Sponsor this project

Uh oh!

Uh oh!

Contributors7

Uh oh!

Languages