Skip to content

PMTiles User Guide

Welcome to the Tileverse PMTiles User Guide. This guide will help you understand and use the PMTiles library effectively.

What You'll Learn

This guide covers:

Prerequisites

Before you begin, make sure you have:

  • Java 17 or newer installed
  • Basic familiarity with Maven or Gradle
  • Understanding of tile-based mapping concepts

Installation

Add the PMTiles dependency to your project:

<dependency>
    <groupId>io.tileverse.pmtiles</groupId>
    <artifactId>tileverse-pmtiles</artifactId>
    <version>1.1-SNAPSHOT</version>
</dependency>

<!-- Also add a Range Reader provider -->
<dependency>
    <groupId>io.tileverse.rangereader</groupId>
    <artifactId>tileverse-rangereader-all</artifactId>
    <version>1.1-SNAPSHOT</version>
</dependency>

dependencies {
    implementation 'io.tileverse.pmtiles:tileverse-pmtiles:1.1-SNAPSHOT'
    implementation 'io.tileverse.rangereader:tileverse-rangereader-all:1.1-SNAPSHOT'
}

Core Concepts

PMTiles Structure

A PMTiles archive contains:

  1. Header: Metadata about the tileset (bounds, zoom levels, tile format)
  2. Directory: Spatial index using Hilbert curves
  3. Tiles: Compressed tile data

Tile Addressing

Tiles are addressed using the standard XYZ scheme:

  • z: Zoom level (0 = world view, higher = more detailed)
  • x: Column number (west to east)
  • y: Row number (north to south in TMS, south to north in XYZ)

Data Sources

PMTiles can be read from any source supported by Range Reader:

  • Local files
  • HTTP/HTTPS servers
  • Amazon S3
  • Azure Blob Storage
  • Google Cloud Storage

Next Steps