{"id":15202964,"url":"https://github.com/versatiles-org/versatiles-rs","last_synced_at":"2026-02-26T04:27:04.686Z","repository":{"id":65490151,"uuid":"593291642","full_name":"versatiles-org/versatiles-rs","owner":"versatiles-org","description":"VersaTiles - A toolbox for converting, checking and serving map tiles in various formats.","archived":false,"fork":false,"pushed_at":"2025-04-11T10:45:21.000Z","size":28290,"stargazers_count":225,"open_issues_count":18,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-11T12:02:29.292Z","etag":null,"topics":["map","openstreetmap","rust","tiles","vector-tiles"],"latest_commit_sha":null,"homepage":"https://versatiles.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/versatiles-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-25T17:15:02.000Z","updated_at":"2025-04-11T10:45:23.000Z","dependencies_parsed_at":"2024-01-05T10:36:58.184Z","dependency_job_id":"204604bc-df2a-4171-a773-9b07e7b1b9b2","html_url":"https://github.com/versatiles-org/versatiles-rs","commit_stats":null,"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versatiles-org%2Fversatiles-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versatiles-org%2Fversatiles-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versatiles-org%2Fversatiles-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versatiles-org%2Fversatiles-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/versatiles-org","download_url":"https://codeload.github.com/versatiles-org/versatiles-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754743,"owners_count":21958903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["map","openstreetmap","rust","tiles","vector-tiles"],"created_at":"2024-09-28T04:07:48.694Z","updated_at":"2026-02-26T04:27:04.676Z","avatar_url":"https://github.com/versatiles-org.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Crates.io version](https://img.shields.io/crates/v/versatiles?label=crates.io)](https://crates.io/crates/versatiles)\n[![Crates.io downloads](https://img.shields.io/crates/d/versatiles?label=downloads)](https://crates.io/crates/versatiles)\n[![Code coverage](https://codecov.io/gh/versatiles-org/versatiles-rs/branch/main/graph/badge.svg?token=IDHAI13M0K)](https://codecov.io/gh/versatiles-org/versatiles-rs)\n[![CI status](https://img.shields.io/github/actions/workflow/status/versatiles-org/versatiles-rs/ci.yml)](https://github.com/versatiles-org/versatiles-rs/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n# VersaTiles\n\nVersaTiles is a Rust-based tool for processing and serving tile data efficiently. It supports multiple tile formats and offers functionalities for seamless tile handling.\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [Linux](#linux)\n  - [MacOS](#macos)\n  - [NixOS](#nixos)\n  - [Docker](#docker)\n  - [npm (Node.js)](#npm-nodejs)\n  - [Building with Cargo](#building-with-cargo)\n  - [Building from Source](#building-from-source)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n  - [Core Concepts](#core-concepts)\n  - [Commands](#commands)\n  - [VersaTiles Pipeline Language](#versatiles-pipeline-language)\n- [Configuration](#configuration)\n- [GDAL Support](#gdal-support)\n- [Development](#development)\n  - [Prerequisites](#prerequisites)\n  - [Setup](#setup)\n  - [Development Workflow](#development-workflow)\n  - [Pre-commit Hooks (Recommended)](#pre-commit-hooks-recommended)\n  - [Node.js Bindings Development](#nodejs-bindings-development)\n  - [Contributing](#contributing)\n- [Repository Structure](#repository-structure)\n- [Using as a Library](#using-as-a-library)\n- [Additional Information](#additional-information)\n- [For Maintainers](#for-maintainers)\n- [License](#license)\n\n---\n\n## Installation\n\n### Linux\n\nInstall VersaTiles using the provided [installation script](https://github.com/versatiles-org/versatiles-rs/blob/main/scripts/install-unix.sh) (that downloads the correct [precompiled binary](https://github.com/versatiles-org/versatiles-rs/releases/latest/)):\n\n```sh\ncurl -Ls \"https://github.com/versatiles-org/versatiles-rs/releases/latest/download/install-unix.sh\" | sudo sh\n```\n\n### MacOS\n\nInstall VersaTiles via [Homebrew](https://docs.versatiles.org/guides/install_versatiles#homebrew-for-macos):\n\n```sh\nbrew tap versatiles-org/versatiles\nbrew install versatiles\n```\n\n### NixOS\n\nVersaTiles is available via `nixpkgs` (starting from version 24.05):\n\n[![nixpkgs unstable](https://repology.org/badge/version-for-repo/nix_unstable/versatiles.svg?header=nixpkgs%20unstable)](https://repology.org/project/versatiles/versions)\n[![nixpkgs stable 25.11](https://repology.org/badge/version-for-repo/nix_stable_25_11/versatiles.svg?header=nixpkgs%20stable%2025.11)](https://repology.org/project/versatiles/versions)\n[![nixpkgs stable 25.05](https://repology.org/badge/version-for-repo/nix_stable_25_05/versatiles.svg?header=nixpkgs%20stable%2025.05)](https://repology.org/project/versatiles/versions)\n[![nixpkgs stable 24.11](https://repology.org/badge/version-for-repo/nix_stable_24_11/versatiles.svg?header=nixpkgs%20stable%2024.11)](https://repology.org/project/versatiles/versions)\n[![nixpkgs stable 24.05](https://repology.org/badge/version-for-repo/nix_stable_24_05/versatiles.svg?header=nixpkgs%20stable%2024.05)](https://repology.org/project/versatiles/versions)\n\nAdd this snippet to `configuration.nix`:\n\n```nix\nenvironment.systemPackages = with pkgs; [ versatiles ];\n```\n\nAlternatively, use it in a shell environment:\n\n```nix\n{ pkgs ? import \u003cnixpkgs\u003e {} }:\n\npkgs.mkShell {\n  buildInputs = with pkgs; [ versatiles ];\n}\n```\n\nFind more details on [Nix search](https://search.nixos.org/packages?show=versatiles).\n\n### Docker\n\nPull the latest [Docker image](https://github.com/versatiles-org/versatiles-docker) for easy deployment:\n\n```sh\ndocker pull versatiles-org/versatiles\n```\n\n### npm (Node.js)\n\nInstall the Node.js bindings for use in JavaScript/TypeScript projects:\n\n```sh\nnpm install @versatiles/versatiles-rs\n```\n\n#### Prerelease Versions\n\nTest upcoming features with prerelease tags:\n\n```sh\n# Alpha (bleeding edge)\nnpm install @versatiles/versatiles-rs@alpha\n\n# Beta (feature complete, testing)\nnpm install @versatiles/versatiles-rs@beta\n\n# Release Candidate (final testing)\nnpm install @versatiles/versatiles-rs@rc\n```\n\nSee all available versions:\n\n```sh\nnpm view @versatiles/versatiles-rs versions\n```\n\n### Building with Cargo\n\nEnsure you have [Rust installed](https://doc.rust-lang.org/cargo/getting-started/installation.html), then run:\n\n```sh\ncargo install versatiles\n```\n\n### Building from Source\n\nClone the repository and build VersaTiles manually:\n\n```sh\ngit clone https://github.com/versatiles-org/versatiles-rs.git\ncd versatiles-rs\ncargo build --bin versatiles --release\ncp ./target/release/versatiles /usr/local/bin/\n```\n\n---\n\n## Quick Start\n\nGet started with VersaTiles in 3 steps:\n\n### 1. Verify Installation\n\n```sh\nversatiles --version\n```\n\n### 2. Download Sample Data\n\n```sh\n# Download a small region (Berlin, ~60MB)\nversatiles convert --bbox=13.0,52.3,13.8,52.7 --bbox-border=3 https://download.versatiles.org/osm.versatiles berlin.versatiles\n```\n\n### 3. Explore Your Data\n\n```sh\n# View tile information\nversatiles probe berlin.versatiles\n\n# Serve tiles locally\nversatiles serve berlin.versatiles\n\n# Access at http://localhost:8080\n```\n\n### Common Workflows\n\n**Convert tile formats:**\n\n```sh\nversatiles convert input.mbtiles output.versatiles\n```\n\n**Filter by zoom level:**\n\n```sh\nversatiles convert --min-zoom=5 --max-zoom=12 input.versatiles output.versatiles\n```\n\n**Extract a region:**\n\n```sh\nversatiles convert --bbox=13.0,52.3,13.8,52.7 world.versatiles berlin.versatiles\n```\n\n---\n\n## Usage\n\n### Core Concepts\n\nVersaTiles works with **tile containers** - files or directories containing map tiles organized by zoom level (z), column (x), and row (y).\n\n**Supported formats:**\n\n- `.versatiles` - Native format (best compression, fastest access)\n- `.mbtiles` - SQLite-based (widely compatible)\n- `.pmtiles` - Cloud-optimized single-file format\n- `.tar` - Simple archive format\n- Directories - Folder structure: `z/x/y.ext`\n\n**Remote access:** VersaTiles can read remote `.versatiles` and `.pmtiles` files via HTTPS:\n\n```sh\nversatiles serve https://download.versatiles.org/osm.versatiles\n```\n\n### Commands\n\nRun `versatiles` to see available commands:\n\n```text\nUsage: versatiles [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  convert  Convert between different tile containers\n  probe    Show information about a tile container\n  serve    Serve tiles via HTTP\n  dev      Developer tools (unstable)\n  help     Show detailed help\n```\n\n#### convert - Convert Between Tile Formats\n\nConvert tiles between formats, filter by region or zoom, and transform coordinates.\n\n**Basic conversion:**\n\n```sh\nversatiles convert input.mbtiles output.versatiles\n```\n\n**Advanced options:**\n\n| Option                     | Description                                      | Example                      |\n|----------------------------|--------------------------------------------------|------------------------------|\n| `--min-zoom`, `--max-zoom` | Filter zoom levels                               | `--min-zoom=5 --max-zoom=12` |\n| `--bbox`                   | Extract region (lon_min,lat_min,lon_max,lat_max) | `--bbox=13.0,52.3,13.8,52.7` |\n| `--bbox-border`            | Add border tiles around bbox                     | `--bbox-border=3`            |\n| `--compress`               | Set compression (gzip, brotli, zstd)             | `--compress=brotli`          |\n| `--tile-format`            | Convert tile format (png, jpg, webp, avif, pbf)  | `--tile-format=webp`         |\n| `--swap-xy`                | Swap X/Y coordinates (z/x/y → z/y/x)             | `--swap-xy`                  |\n| `--flip-y`                 | Flip tiles vertically                            | `--flip-y`                   |\n\n**Real-world examples:**\n\n```sh\n# Extract city region from world tiles\nversatiles convert --bbox=13.0,52.3,13.8,52.7 \\\n  world.versatiles berlin.versatiles\n\n# Compress tiles with maximum compression\nversatiles convert --compress=brotli \\\n  uncompressed.tar compressed.versatiles\n\n# Convert image format for smaller file size\nversatiles convert --tile-format=webp \\\n  tiles.mbtiles tiles-webp.versatiles\n\n# Fix coordinate system (TMS to XYZ)\nversatiles convert --flip-y \\\n  tms-tiles.mbtiles xyz-tiles.versatiles\n\n# Remote conversion with zoom filtering\nversatiles convert --min-zoom=1 --max-zoom=10 \\\n  https://download.versatiles.org/osm.versatiles \\\n  local-osm-filtered.versatiles\n```\n\n#### probe - Inspect Tile Containers\n\nAnalyze tile containers to understand their contents and structure.\n\n**Basic usage:**\n\n```sh\nversatiles probe tiles.versatiles\n```\n\n**Depth levels:**\n\n| Level | Flag   | Scans                | Use Case                             |\n|-------|--------|----------------------|--------------------------------------|\n| 1     | `-d`   | Container metadata   | Quick info (zoom range, tile format) |\n| 2     | `-dd`  | All tile coordinates | Find actual tile coverage            |\n| 3     | `-ddd` | Tile contents        | Analyze tile sizes, validate data    |\n\n**Examples:**\n\n```sh\n# Quick metadata check\nversatiles probe tiles.versatiles -d\n\n# Find actual zoom range with tiles\nversatiles probe tiles.versatiles -dd\n\n# Deep inspection with tile statistics\nversatiles probe tiles.versatiles -ddd\n\n# Probe remote container\nversatiles probe https://download.versatiles.org/osm.versatiles -d\n```\n\n#### serve - HTTP Tile Server\n\nRun a local or production tile server with advanced configuration.\n\n**Basic usage:**\n\n```sh\nversatiles serve tiles.versatiles\n# Access at http://localhost:8080\n```\n\n**Server options:**\n\n| Option                    | Description                     | Default |\n|---------------------------|---------------------------------|---------|\n| `-i, --ip`                | Bind IP address                 | 0.0.0.0 |\n| `-p, --port`              | Port number                     | 8080    |\n| `-c, --config`            | YAML configuration file         | -       |\n| `--minimal-recompression` | Fast serving (less compression) | false   |\n| `--disable-api`           | Disable `/api` endpoints        | false   |\n\n**Custom tile IDs:**\n\nAssign custom IDs to tile sources using bracket or hash syntax:\n\n```sh\n# Bracket prefix: [id]source\nversatiles serve [osm]tiles.versatiles\n\n# Bracket suffix: source[id]\nversatiles serve tiles.versatiles[osm]\n\n# Hash syntax: source#id\nversatiles serve tiles.versatiles#osm\n```\n\nAccess tiles at: `http://localhost:8080/{id}/{z}/{x}/{y}.{ext}`\n\n**Static content serving:**\n\n```sh\n# Serve tar archive at root\nversatiles serve -s \"static.tar.br\" tiles.versatiles\n\n# Serve with custom prefix\nversatiles serve -s \"[/assets]static.tar.gz\" tiles.versatiles\n# Access: http://localhost:8080/assets/...\n\n# Multiple static sources (first match wins)\nversatiles serve \\\n  -s \"[/styles]styles.tar.br\" \\\n  -s \"[/fonts]fonts.tar.gz\" \\\n  tiles.versatiles\n```\n\n**Supported static formats:** `.tar`, `.tar.gz`, `.tar.br`, directories\n\n**Remote serving:**\n\n```sh\n# Serve remote tiles directly\nversatiles serve https://download.versatiles.org/osm.versatiles\n\n# Mix local and remote sources\nversatiles serve \\\n  [local]local.versatiles \\\n  [osm]https://download.versatiles.org/osm.versatiles\n```\n\n**Configuration file:**\n\nFor production deployments, use YAML configuration (see [Configuration](#configuration) section):\n\n```sh\nversatiles serve -c production.yaml\n```\n\nFor a full description of all configuration options:\n\n```sh\nversatiles help config\n```\n\n#### dev - Developer Tools (Unstable)\n\nExperimental tools for tile analysis and debugging.\n\n**measure-tile-sizes** - Generate a visual heatmap of tile sizes:\n\n```sh\nversatiles dev measure-tile-sizes tiles.versatiles output.png\n\n# With options\nversatiles dev measure-tile-sizes \\\n  --level=14 \\\n  --scale=4 \\\n  tiles.versatiles output.png\n```\n\nOutput: PNG image where brightness = 10*log2(tile_size). Use to identify large tiles or data quality issues.\n\n**export-outline** - Export tile coverage as GeoJSON:\n\n```sh\nversatiles dev export-outline tiles.versatiles coverage.geojson\n\n# Specify zoom level (default: max zoom)\nversatiles dev export-outline --level=10 tiles.versatiles coverage.geojson\n```\n\nOutput: GeoJSON polygon showing which areas have tiles. Useful for visualizing coverage in QGIS/Mapbox.\n\n**print-tilejson** - Print TileJSON metadata:\n\n```sh\n# Compact JSON\nversatiles dev print-tilejson tiles.versatiles\n\n# Pretty-printed JSON\nversatiles dev print-tilejson -p tiles.versatiles\n```\n\nOutput: Standard TileJSON 3.0.0 format with attribution, bounds, zoom levels, etc.\n\n#### help - Detailed Help Topics\n\nGet detailed help for specific topics:\n\n```sh\n# Pipeline language reference\nversatiles help pipeline\n\n# Configuration file reference\nversatiles help config\n\n# Raw markdown output (for documentation)\nversatiles help pipeline --raw\n```\n\n### VersaTiles Pipeline Language\n\nThe VersaTiles Pipeline Language (VPL) allows you to define tile-processing pipelines. Operations include merging multiple tile sources, filtering, and modifying tile content.\n\n**Example of combining multiple vector tile sources:**\n\n```text\nfrom_merged_vector [\n   from_container filename=\"world.versatiles\",\n   from_container filename=\"europe.versatiles\" | filter level_min=5,\n   from_container filename=\"germany.versatiles\"\n]\n```\n\nMore details can be found in [versatiles_pipeline/README.md](https://github.com/versatiles-org/versatiles-rs/blob/main/versatiles_pipeline/README.md).\n\n---\n\n## Configuration\n\nFor production deployments, use YAML configuration files for fine-grained control over the tile server.\n\n### Basic Configuration\n\n```yaml\nserver:\n  ip: 0.0.0.0\n  port: 8080\n  minimal_recompression: false  # true = faster, larger responses\n  disable_api: false             # true = disable /api endpoints\n\ntiles:\n  - name: osm\n    src: \"./tiles/osm.versatiles\"\n  - name: satellite\n    src: \"https://tiles.example.com/sat.versatiles\"\n\nstatic:\n  - src: \"./static\"\n    prefix: \"/\"\n```\n\n**Start with config:**\n\n```sh\nversatiles serve -c config.yaml\n```\n\n### Key Features\n\n**CORS Configuration** - Control cross-origin access:\n\n```yaml\ncors:\n  allowed_origins:\n    - \"https://example.org\"          # Exact domain\n    - \"*.dev.example.org\"            # Subdomain wildcard\n    - \"https://example.*\"            # TLD wildcard\n    - \"/^https://.*\\\\.example\\\\.org$/\" # Regex pattern\n  max_age_seconds: 86400\n```\n\n**Custom Response Headers** - Add caching and CDN headers:\n\n```yaml\nextra_response_headers:\n  Cache-Control: \"public, max-age=86400, immutable\"\n  Surrogate-Control: \"max-age=604800\"      # For Varnish\n  CDN-Cache-Control: \"max-age=604800\"      # For CDNs\n```\n\n**Multiple Tile Sources** - Serve multiple tile sets:\n\n```yaml\ntiles:\n  # Local file\n  - name: city\n    src: \"./city.versatiles\"\n\n  # Remote HTTPS\n  - name: osm\n    src: \"https://download.versatiles.org/osm.versatiles\"\n\n  # MBTiles format\n  - name: elevation\n    src: \"./terrain.mbtiles\"\n\n  # VPL pipeline (processed on-the-fly)\n  - name: processed\n    src: \"./pipeline.vpl\"\n```\n\nAccess tiles at: `http://localhost:8080/{name}/{z}/{x}/{y}.{ext}`\n\n**Static Content** - Serve styles, fonts, and sprites:\n\n```yaml\nstatic:\n  # Tar archive at root\n  - src: \"./static.tar.br\"\n    prefix: \"/\"\n\n  # Directory at custom path\n  - src: \"./public\"\n    prefix: \"/assets\"\n```\n\nSupported formats: directories, `.tar`, `.tar.gz`, `.tar.br`\n\n### Complete Example\n\n```yaml\nserver:\n  ip: 0.0.0.0\n  port: 8080\n  minimal_recompression: false\n\ncors:\n  allowed_origins:\n    - \"https://myapp.com\"\n    - \"*.myapp.dev\"\n  max_age_seconds: 86400\n\nextra_response_headers:\n  Cache-Control: \"public, max-age=86400\"\n\ntiles:\n  - name: basemap\n    src: \"https://download.versatiles.org/osm.versatiles\"\n  - name: satellite\n    src: \"./satellite.mbtiles\"\n\nstatic:\n  - src: \"./styles.tar.br\"\n    prefix: \"/styles\"\n  - src: \"./fonts.tar.gz\"\n    prefix: \"/fonts\"\n```\n\n### Full Reference\n\nFor complete configuration documentation, see:\n\n- [versatiles/CONFIG.md](https://github.com/versatiles-org/versatiles-rs/blob/main/versatiles/CONFIG.md) - Full reference (auto-generated)\n\nOr run:\n\n```sh\nversatiles help config\n```\n\n### Environment Variables\n\nVersaTiles supports the following environment variables:\n\n- `VERSATILES_CACHE_DIR` - Enable disk-based tile caching. This is useful if you want to convert large tile sets with the `from_gdal_raster` VPL operation but have limited memory. Example: `VERSATILES_CACHE_DIR=/tmp/versatiles_cache`\n\n**Example usage:**\n\n```sh\n# In one line\nVERSATILES_CACHE_DIR=/var/cache/versatiles versatiles serve tiles.versatiles\n\n# or\nexport VERSATILES_CACHE_DIR=/tmp/versatiles_cache\nversatiles serve https://download.versatiles.org/osm.versatiles\n```\n\n---\n\n## GDAL support\n\n`versatiles` supports GDAL since v1.0.0. However, this is still experimental.\n\n### Building with GDAL support\n\nDue 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:\n\n1. Build GDAL locally by running `./scripts/install-gdal.sh`. This will build and install GDAL in the subfolder `./.toolchain/gdal`\n2. Build `versatiles` with the features `gdal`. We recommend using the scripts `./scripts/build_debug.sh` and `./scripts/build_release.sh`.\n\n---\n\n## Development\n\nVersaTiles is built with Rust and includes Node.js bindings (NAPI-RS).\n\n### Prerequisites\n\n**Required:**\n\n- Rust 1.92+ ([installation](https://www.rust-lang.org/tools/install))\n- Node.js 20+ (for Node.js bindings)\n\n**Optional:**\n\n- [Lefthook](https://github.com/evilmartians/lefthook) - Pre-commit hooks\n- GDAL 3.x - For GDAL support ([build instructions](#building-with-gdal-support))\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/versatiles-org/versatiles-rs.git\ncd versatiles-rs\n\n# Build debug version\ncargo build --bin versatiles\n\n# Run tests\ncargo test\n\n# Run binary\n./target/debug/versatiles --version\n```\n\n### Development Workflow\n\n#### Running All Checks\n\nVerify code quality before committing:\n\n```bash\n./scripts/check.sh\n```\n\nThis runs:\n\n- **Rust:** formatting (rustfmt), linting (clippy), type-checking, tests, doc tests\n- **Node.js:** formatting (Prettier), linting (ESLint), type-checking (TypeScript), tests (Vitest)\n\n#### Quick Fixes\n\n**Rust:**\n\n```bash\n# Auto-format\ncargo fmt\n\n# Auto-fix clippy warnings\ncargo clippy --fix\n\n# Run specific tests\ncargo test raster_overscale\ncargo test --package versatiles_pipeline\n```\n\n**Node.js:**\n\n```bash\ncd versatiles_node\n\n# Auto-fix all issues\nnpm run fix\n\n# Individual tasks\nnpm run format        # Prettier\nnpm run lint:fix      # ESLint auto-fix\nnpm run typecheck     # TypeScript check\nnpm test              # Vitest\n```\n\n#### Building\n\n**Debug build (fast compilation, slow execution):**\n\n```bash\ncargo build --bin versatiles\n# Output: ./target/debug/versatiles\n```\n\n**Release build (slow compilation, fast execution):**\n\n```bash\ncargo build --bin versatiles --release\n# Output: ./target/release/versatiles\n```\n\n**With GDAL support:**\n\n```bash\n# Build GDAL first\n./scripts/install-gdal.sh\n\n# Build with GDAL features\n./scripts/build_release.sh\n```\n\n#### Testing\n\n```bash\n# All tests\ncargo test\n\n# Specific package\ncargo test --package versatiles_core\ncargo test --package versatiles_pipeline\n\n# Specific test\ncargo test raster_overscale\n\n# With output\ncargo test -- --nocapture\n\n# Ignored tests (long-running)\ncargo test -- --ignored\n```\n\n#### Documentation\n\n```bash\n# Generate docs\ncargo doc --no-deps --open\n\n# Test docs\ncargo test --doc\n```\n\n### Pre-commit Hooks (Recommended)\n\nInstall [Lefthook](https://github.com/evilmartians/lefthook) for automatic quality checks:\n\n```bash\n# macOS\nbrew install lefthook\n\n# Linux\ncurl -fsSL https://raw.githubusercontent.com/evilmartians/lefthook/main/install.sh | sh\n\n# Windows\nscoop install lefthook\n\n# Enable hooks\nlefthook install\n```\n\n**Hook behavior:**\n\n- **pre-commit:** Fast checks (formatting, basic linting)\n- **pre-push:** Full checks (all tests, clippy, type-checking)\n\n**Skip hooks when needed:**\n\n```bash\n# Skip pre-commit\nLEFTHOOK=0 git commit -m \"message\"\n\n# Skip pre-push\ngit push --no-verify\n```\n\n### Node.js Bindings Development\n\nSee [versatiles_node/CONTRIBUTING.md](versatiles_node/CONTRIBUTING.md) for detailed workflow.\n\n**Quick reference:**\n\n```bash\ncd versatiles_node\n\n# Install dependencies\nnpm install\n\n# Build Rust bindings\nnpm run build\n\n# Build debug (faster compilation)\nnpm run build:debug\n\n# Run tests\nnpm test\n\n# Full check before commit\nnpm run check\n```\n\n### Contributing\n\nWe welcome contributions! Please:\n\n1. **Fork and create a feature branch:**\n\n   ```bash\n   git checkout -b feature/my-feature\n   ```\n\n2. **Make changes and test:**\n\n   ```bash\n   ./scripts/check.sh\n   ```\n\n3. **Commit with clear messages:**\n\n   ```bash\n   git commit -m \"feat: add new feature\"\n   ```\n\n4. **Push and create pull request:**\n\n   ```bash\n   git push origin feature/my-feature\n   ```\n\n**Commit message format:**\n\n- `feat:` New feature\n- `fix:` Bug fix\n- `docs:` Documentation only\n- `style:` Formatting, no code change\n- `refactor:` Code restructuring\n- `test:` Adding tests\n- `chore:` Maintenance tasks\n\n---\n\n## Repository Structure\n\n### Code\n\n- **/versatiles/** - Main library and binary\n- **/versatiles_container/** - Handles tile containers (`*.versatiles`, `*.mbtiles`, `*.pmtiles`, etc.)\n- **/versatiles_core/** - Core data types and utilities\n- **/versatiles_derive/** - Derive macros for the library\n- **/versatiles_geometry/** - Handles geometric data (OSM, GeoJSON, vector tiles, etc.)\n- **/versatiles_image/** - Manages image data (PNG, JPEG, WEBP)\n- **/versatiles_pipeline/** - VersaTiles Pipeline for efficient tile processing\n\nDependencies of the versatiles packages:\n\n```mermaid\n---\nconfig:\n  layout: elk\n---\nflowchart TB\n    versatiles --\u003e versatiles_container\n    versatiles --\u003e versatiles_core\n    versatiles --\u003e versatiles_derive\n    versatiles --\u003e versatiles_geometry\n    versatiles --\u003e versatiles_image\n    versatiles --\u003e versatiles_pipeline\n    versatiles_container --\u003e versatiles_core\n    versatiles_container --\u003e versatiles_derive\n    versatiles_container --\u003e versatiles_geometry\n    versatiles_container --\u003e versatiles_image\n    versatiles_core --\u003e versatiles_derive\n    versatiles_geometry --\u003e versatiles_core\n    versatiles_geometry --\u003e versatiles_derive\n    versatiles_image --\u003e versatiles_core\n    versatiles_image --\u003e versatiles_derive\n    versatiles_node --\u003e versatiles\n    versatiles_node --\u003e versatiles_container\n    versatiles_node --\u003e versatiles_core\n    versatiles_pipeline --\u003e versatiles_container\n    versatiles_pipeline --\u003e versatiles_core\n    versatiles_pipeline --\u003e versatiles_derive\n    versatiles_pipeline --\u003e versatiles_geometry\n    versatiles_pipeline --\u003e versatiles_image\n```\n\n### Helpers\n\n- **/docker/** - Dockerfile for Linux builds\n- **/testdata/** - Test files for validation\n- **/scripts/** - Development and CI/CD automation scripts:\n\n| Script                 | Purpose                                                        |\n|------------------------|----------------------------------------------------------------|\n| **`build-debug.sh`**   | **Build debug binary with GDAL**                               |\n| **`build-release.sh`** | **Build release binary with GDAL support**                     |\n| **`check.sh`**         | **Run all checks (formatting, linting, tests Rust + Node.js)** |\n| **`install-gdal.sh`**  | **Install GDAL from source into `.toolchain/gdal`**            |\n| `audit-unused-deps.sh` | Find unused dependencies                                       |\n| `build-docker-*.sh`    | Build Docker images (GDAL, multi-platform)                     |\n| `build-docs*.sh`       | Generate documentation                                         |\n| `install-unix.sh`      | Install VersaTiles binary on Unix platforms                    |\n| `install-windows.ps1`  | Install VersaTiles binary on Windows                           |\n| `perf-benchmarks.sh`   | Run performance benchmarks                                     |\n| `release-package.sh`   | Create versioned releases                                      |\n| `sync-version.sh`      | Synchronize versions across workspace                          |\n| `test-coverage.sh`     | Generate code coverage reports                                 |\n| `test-unix.sh`         | Run tests on Unix platforms                                    |\n| `test-windows.ps1`     | Run tests on Windows                                           |\n| `upgrade-deps.sh`      | Update Rust dependencies to latest versions                    |\n| `workflow-*.sh/ps1`    | CI/CD workflow automation                                      |\n\n**Most commonly used:** `check.sh`, `build-release.sh`, `release-package.sh`\n\n---\n\n## Using as a Library\n\nVersaTiles 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.\n\n---\n\n## Additional Information\n\nFor advanced usage, guides, and detailed documentation, visit the [official documentation](https://docs.versatiles.org/).\n\n---\n\n## For Maintainers\n\n### Creating a Release\n\nSee [RELEASING.md](./RELEASING.md) for the complete release process.\n\nQuick version:\n\n```bash\n# Interactive mode - select release type from menu\n./scripts/release-package.sh\n\n# Or use command-line argument\n./scripts/release-package.sh patch  # or minor/major/alpha/beta/rc/dev\n\n# Push to trigger automated release\ngit push origin main --follow-tags\n```\n\nThe GitHub Actions workflow will automatically:\n\n- Build CLI binaries for 8 platforms (Linux gnu/musl x64/arm64, macOS x64/arm64, Windows x64/arm64)\n- Build NAPI-RS bindings for Node.js (8 platform-specific packages)\n- Publish to npmjs.com (@versatiles/versatiles-rs + 8 platform-specific packages)\n- Create GitHub release with CLI binaries\n- Trigger Docker and Homebrew updates\n\n---\n\n## Contributing\n\nVersaTiles 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.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversatiles-org%2Fversatiles-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fversatiles-org%2Fversatiles-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversatiles-org%2Fversatiles-rs/lists"}