https://github.com/versatiles-org/versatiles-rs
VersaTiles - A toolbox for converting, checking and serving map tiles in various formats.
https://github.com/versatiles-org/versatiles-rs
map openstreetmap rust tiles vector-tiles
Last synced: 2 months ago
JSON representation
VersaTiles - A toolbox for converting, checking and serving map tiles in various formats.
- Host: GitHub
- URL: https://github.com/versatiles-org/versatiles-rs
- Owner: versatiles-org
- License: mit
- Created: 2023-01-25T17:15:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-11T10:45:21.000Z (3 months ago)
- Last Synced: 2025-04-11T12:02:29.292Z (3 months ago)
- Topics: map, openstreetmap, rust, tiles, vector-tiles
- Language: Rust
- Homepage: https://versatiles.org
- Size: 27 MB
- Stars: 225
- Watchers: 5
- Forks: 6
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://crates.io/crates/versatiles)
[](https://crates.io/crates/versatiles)
[](https://codecov.io/gh/versatiles-org/versatiles-rs)
[](https://github.com/versatiles-org/versatiles-rs/actions/workflows/ci.yml)
[](LICENSE)
# 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](#installation)
- [Linux](#linux)
- [MacOS](#macos)
- [NixOS](#nixos)
- [Docker](#docker)
- [Building with Cargo](#building-with-cargo)
- [Building from Source](#building-from-source)
- [Usage](#usage)
- [Convert Tiles](#convert-tiles)
- [Serve Tiles](#serve-tiles)
- [VersaTiles Pipeline Language](#versatiles-pipeline-language)
- [Repository Structure](#repository-structure)
- [Using as a Library](#using-as-a-library)
- [Additional Information](#additional-information)
- [Contributing](#contributing)
- [License](#license)
---
## Installation
### Linux
Install VersaTiles using the provided [installation script](https://github.com/versatiles-org/versatiles-rs/blob/main/helpers/install-unix.sh) ( that downloads the correct [precompiled binary](https://github.com/versatiles-org/versatiles-rs/releases/latest/)):
```sh
curl -Ls "https://github.com/versatiles-org/versatiles-rs/raw/main/helpers/install-unix.sh" | bash
```
### MacOS
Install VersaTiles via [Homebrew](https://docs.versatiles.org/guides/install_versatiles#homebrew-for-macos):
```sh
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`:
```nix
environment.systemPackages = with pkgs; [ versatiles ];
```
Alternatively, use it in a shell environment:
```nix
{ pkgs ? import {} }:
pkgs.mkShell {
buildInputs = with pkgs; [ versatiles ];
}
```
Find more details on [Nix search](https://search.nixos.org/packages?show=versatiles).
### Docker
Pull the latest [Docker image](https://github.com/versatiles-org/versatiles-docker) for easy deployment:
```sh
docker pull versatiles-org/versatiles
```
### Building with Cargo
Ensure you have [Rust installed](https://doc.rust-lang.org/cargo/getting-started/installation.html), then run:
```sh
cargo install versatiles
```
### Building from Source
Clone the repository and build VersaTiles manually:
```sh
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]
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`:
```sh
versatiles convert --tile-format webp satellite_tiles.tar satellite_tiles.versatiles
```
### Serve Tiles
Serve tiles over HTTP:
```sh
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:
```text
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](https://github.com/versatiles-org/versatiles-rs/blob/main/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](https://crates.io/crates/versatiles) and [docs.rs](https://docs.rs/versatiles/latest/versatiles/) for more details.
---
## Additional Information
For advanced usage, guides, and detailed documentation, visit the [official documentation](https://docs.versatiles.org/).
---
## Contributing
VersaTiles is actively developed, and contributions are welcome! If you find bugs, need features, or want to contribute, please check the [GitHub repository](https://github.com/versatiles-org/versatiles-rs) and submit an issue or pull request.
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.