Skip to main content

QBTiles

QBTiles (Quadkey Bitmask Tiles) — a spatial data format that encodes existence as a tree structure, reducing ID storage cost to zero.

Documentation | Live Demos | 한국어 문서

Install

# Python — build & write QBT files
pip install qbtiles

# TypeScript/JavaScript — read & query QBT files in the browser
npm install qbtiles

What It Does

Map tiles and spatial grids are inherently quadtrees. QBTiles encodes cell existence as 4-bit bitmasks in BFS order. The position of each entry is implied by the tree structure — no IDs, no coordinates stored.

Level 1:  [0100]          → only child 1 exists
Level 2:  [0001]          → only child 3 exists
Level 3:  [0010]          → only child 2 exists

quadkey bitmask structure

Three Modes

Mode Flags Use Case Access Comparable to
Variable-entry 0x0 Tile archives (MVT, PNG) Per tile PMTiles
Fixed row 0x1 Raster grids Per cell (Range Request) COG (GeoTIFF)
Fixed columnar 0x3 Compressed grids Whole file (gzip) Parquet

Benchmarks

Variable-entry — Tile Index (vs PMTiles)

Dataset Entries PMTiles QBTiles Reduction
adm-korea 36K 80.9 KB 61.3 KB -24.3%
Full OSM 160M 300.7 MB 235.2 MB -21.8%

Fixed row — Raster Grid (WorldPop 51M cells, float32)

Format Size Ratio Per-cell access
FlatGeobuf 6,001 MB 29.4x per feature
GeoParquet 700 MB 3.4x full download only
GeoTIFF (COG) 276 MB 1.4x 512×512 block
QBTiles 204 MB 1.0x single cell

Fixed columnar — Compressed Grid (Korea 100m, 931K cells × 3 values)

Format Size Per cell
Parquet (gzip) 2.9 MB coordinate scan
QBTiles columnar 1.7 MB O(log N) quadkey search

Quick Start

Python — Build QBT Files

import qbtiles as qbt

# Mode 1: Tile archive — from a folder of z/x/y tiles (e.g., tiles/5/27/12.mvt)
qbt.build("korea_tiles.qbt", folder="tiles/")

# Mode 2: Columnar — coordinates + multiple value columns
# coords: list of (x, y) in the target CRS
# columns: dict of column_name → value list (same length as coords)
# cell_size: grid cell size in CRS units (meters for EPSG:5179)
# → zoom, origin, extent are auto-calculated from coords and cell_size
qbt.build("population.qbt.gz",
    coords=list(zip(df["x"], df["y"])),         # [(950000, 1950000), ...]
    columns={"total": totals, "male": males, "female": females},
    cell_size=100, crs=5179)                     # 100m grid, Korean CRS

# Mode 3: Fixed row — coordinates + single value array (for Range Request)
# values: flat list of numbers (one per cell)
# entry_size: bytes per cell (4 for float32)
qbt.build("global_pop.qbt",
    coords=list(zip(lons, lats)),                # [(-73.99, 40.75), ...]
    values=population,                           # [52.3, 41.2, ...]
    cell_size=1000, entry_size=4,                # 1km grid, 4 bytes/cell
    fields=[{"type": qbt.TYPE_FLOAT32, "name": "pop"}])

# GeoTIFF → QBTiles conversion (cell_size, CRS, extent auto-detected)
qbt.build("worldpop.qbt", geotiff="worldpop_2025.tif")

# Bitmask-only — store only cell existence (no values), e.g. land/water mask
qbt.build("landmask.qbt", geotiff="landmask.tif", nodata=0, bitmask_only=True)

TypeScript — Read & Query

import { openQBT } from 'qbtiles';

// openQBT reads the header, detects the mode, and loads data automatically.

// Mode 1: Tile archive — serve MVT/PNG tiles from a single .qbt file
const tiles = await openQBT('korea_tiles.qbt');
const tile = await tiles.getTile(7, 109, 49);  // ArrayBuffer (gzip MVT) | null
tiles.addProtocol(maplibregl, 'qbt');           // one-line MapLibre integration

// Mode 3: Fixed row — per-cell Range Request on a remote file
const grid = await openQBT('https://cdn.example.com/global_pop.qbt');
const cells = await grid.query([126, 35, 128, 37]);  // [west, south, east, north]
// → Array<{ position: [lng, lat], value: number }>

// Mode 2: Columnar — downloads entire file, queries in memory
const pop = await openQBT('population.qbt.gz');
pop.columns!.get('total')!;                     // number[931495] — direct access
const result = await pop.query([126, 35, 128, 37]);
// → Array<{ position: [lng, lat], values: {total: 523, male: 261, female: 262} }>

File Format (v1)

[Header 128B+]  magic, version, flags, zoom, CRS, origin, extent,
                bitmask_length, values_offset, index_hash (SHA-256), field schema
[Bitmask]       gzip-compressed 4-bit nibbles in BFS order
[Values]        row: raw entry_size × leaf_count (Range-requestable)
                columnar: column-by-column (varint + fixed types)

Full spec: format-spec.md

API Reference

Python (pip install qbtiles) — Writer

Function Description
build(output, ...) Unified builder — auto-detects mode from folder / columns / values / geotiff. Options: nodata=, bitmask_only=True
read_qbt_header(path_or_bytes) Parse QBT header to dict
tile_to_quadkey_int64(z, x, y) Tile coords → 64-bit quadkey

Low-level: build_quadtree(), serialize_bitmask(), write_qbt_variable(), write_qbt_fixed(), write_qbt_columnar()

TypeScript/JavaScript (npm install qbtiles) — Reader

Function / Class Description
openQBT(url) → QBT Unified loader — auto-detects mode from header flags
QBT.getTile(z, x, y) Fetch tile data via Range Request (variable mode)
QBT.query(bbox) Spatial query — all modes (Range Request or in-memory)
QBT.columns Column values as Map<string, number[]> (columnar mode)
QBT.addProtocol(maplibregl) One-line MapLibre custom protocol (variable mode)
QBT.toWGS84(x, y) CRS conversion via proj4 (built-in for common EPSG codes)
registerCRS(epsg, proj4Def) Register custom CRS definitions

Low-level: parseQBTHeader(), queryBbox(), mergeRanges(), fetchRanges(), readColumnarValues()

Live Demos

Tile Viewer — Variable-entry (0x0)

MVT vector tiles served via QBTiles index + Range Request. Administrative boundaries of South Korea.

Tile Viewer

Population Grid — Fixed columnar (0x3)

931K cells in 1.75 MB. Korea 100m population grid with 3 values per cell at 1.97 Byte/cell.

Population Grid

Range Request Comparison — Fixed row (0x1)

Split-screen comparison: QBTiles cell-level vs COG block-level Range Request on WorldPop 1km global population.

Range Request Comparison

File Viewer — All modes

Drag & drop any .qbt or .qbt.gz file to inspect its contents. Supports all three modes with auto-detection.

File Viewer

  • Sparse Voxel Octree (SVO) — Same bitmask principle in 3D (8-bit masks for octree)
  • LOUDS — Succinct tree encoding via BFS bit sequences
  • PMTiles — Hilbert curve tile indexing with varint delta encoding

License

MIT

Metadata

Release files for qbtiles 0.7.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qbtiles 0.7.2
File Size Uploaded Provenance Actions
qbtiles-0.7.2.tar.gz 31.8 kB Without provenance Details for qbtiles-0.7.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qbtiles 0.7.2
File Interpreter ABI Platform Actions
qbtiles-0.7.2-py3-none-any.whl Python 3 none any Details for qbtiles-0.7.2-py3-none-any.whl

Total release size: 56.2 kB

Release files / qbtiles-0.7.2.tar.gz

Download URL qbtiles-0.7.2.tar.gz
Size 31.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c9a4c9f7958ea53c78e1be8a1e2e7de72095650f1f5c6e981e9414c99553540c
BLAKE2b-256 checksum
How to use checksums
b70445f5c030eb57346161bfd8db90eb39890f52cc42d4c66f4924c1790b0c8e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / qbtiles-0.7.2-py3-none-any.whl

Download URL qbtiles-0.7.2-py3-none-any.whl
Size 24.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4d6e0ce02fb13ebd3b23972841d8ca4489618932a8315ccebee31b257ce07253
BLAKE2b-256 checksum
How to use checksums
6825017afeed9aebbbaaf17a2fcb8a07729bd6efe55174be74113f9f7b91aaa6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for qbtiles 0.7.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page