Skip to content

About

A GeoParquet extension for progressive map rendering and partial access over HTTP range requests.

Resources

Stars

108 stars

Watchers

1 watching

Forks

Repository files navigation

Cloud Optimized GeoParquet (COGP)

Tests npm: @cogp/reader npm: @cogp/maplibre crates.io: cogp

A GeoParquet extension for progressive map rendering and partial access over HTTP range requests or object storage.

Created by Kanahiro Iguchi.

TL;DR

A COGP file is a valid GeoParquet file whose row groups are arranged in coarse-to-fine detail levels. File-level geo.lod metadata records the cumulative row-group prefix available at each level. That metadata is optional in the LoD extension, but required for a file to be treated as COGP.

The producer assigns each input row to one level. Level selection works on whole row-group prefixes, not individual features; within the selected prefix, area-of-interest reads can still skip row groups and pages using bbox statistics and Page Indexes. Every input row appears once, and its primary geometry and source attributes are preserved. Optional rendering overviews can contain simplified geometries in a separate column.

A COGP-aware reader can select the row-group prefix and, when available, the geometry overview for its target rendering resolution, then prune that prefix spatially to the viewport. A reader that does not understand the profile can ignore geo.lod and read the complete file as ordinary GeoParquet, but cannot use the metadata to select a coarse level.

Design influences

COGP is informed by several existing cloud-optimized and progressive rendering patterns:

  • Cloud Optimized GeoTIFF: remaining a valid GeoTIFF while adding cloud-friendly layout and overview structure;
  • Cloud Optimized Point Cloud: remaining a valid LAZ file while adding thinning and multi-resolution level concepts;
  • tippecanoe: design choice to avoid rendering every feature literally at low zoom levels.

COGP expresses these levels as GeoParquet row-group boundaries, so they combine with ordinary row-group and page-level spatial pruning. Its primary geometries remain unchanged; optional rendering overviews can provide simplified geometries without replacing them. Each input row belongs to one level.

Why

GeoParquet is well suited for analytics and cloud storage, but ordinary GeoParquet files are not laid out for progressive visual access. For map rendering, tile serving, and viewport-driven applications, readers often want to fetch a coarse overview first and only descend into finer detail when the display scale requires it.

Benefits

  • Progressive rendering for COGP-aware software. A reader can use geo.lod to select a cumulative row-group prefix for its target resolution, then add later groups as finer detail is needed. Optional geometry overviews can reduce the cost of rendering large lines and polygons.
  • Ordinary GeoParquet compatibility. Readers that ignore geo.lod can read every row and its unchanged primary geometry. A reader that happens to process row groups in order and render incrementally may display coarse features first, but that behavior depends on the reader and does not provide level selection.
  • Spatial pruning within a level. The file retains GeoParquet bounding-box statistics and Page Indexes, so area-of-interest queries can skip row groups and individual pages, including in readers unaware of COGP. A COGP-aware reader applies this inside the selected prefix: a viewport read at a coarse level touches only the intersecting pages of the leading row groups. Query efficiency depends on the data, packing, and reader; ordering by detail can be less effective than a global spatial sort for some full-resolution queries.

Example: loading OvertureMaps buildings on QGIS 4.0

ordinary GeoParquet (spatially sorted)

Screen.Recording.2026-05-24.at.11.09.24.mov

COGP

Screen.Recording.2026-05-24.at.11.10.23.mov

Example: streaming from Cloudflare R2 to browser demo page

Screen.Recording.2026-05-24.at.11.26.13.mov

Example: render administrative polygon with overviews

Screen.Recording.2026-09-26.at.13.17.48.mov

Sample data

Getting started

This walks through converting your own vector data into COGP and reading it from JavaScript.

1. Convert your data to COGP

cogp convert takes GeoParquet 1.x with WKB geometries. Convert any GDAL-readable source (Shapefile, GeoJSON, GeoPackage, ...) to GeoParquet with the gdal command (GDAL 3.11 or later), which writes a bbox covering by default. toMvt in the JavaScript reader assumes longitude/latitude, so use gdal vector reproject --dst-crs EPSG:4326 instead of gdal vector convert for data in another CRS.

Then convert it with a prebuilt cogp binary for your platform from the GitHub releases:

gdal vector convert my-data.shp my-data.parquet
cogp convert my-data.parquet my-data.cogp.parquet
cogp validate my-data.cogp.parquet

The defaults target a Web Mercator z0–z17 pyramid of 512-pixel tiles, as in MapLibre GL JS and deck.gl. See the CLI reference for tuning levels, point thinning, and row group size.

2. Read it from JavaScript

Install the reader from npm:

npm install @cogp/reader

Read the features in a bbox at a given resolution, then convert the batch to GeoJSON, encode it as a Mapbox Vector Tile, or encode it as a GeoArrow IPC stream:

import { CogpReader, toGeoArrow, toGeoJSON, toMvt } from '@cogp/reader';

const reader = await CogpReader.open('https://my-host.com/my-data.cogp.parquet');
const batch = await reader.read({
  maxLevel: reader.selectLevel(0.001), // CRS units per pixel (degrees here)
  bbox: [139.4, 35.4, 139.6, 35.6],
  useOverview: true, // simplified overviews when the file has them
});

const geojson = toGeoJSON(batch); // FeatureCollection; feature IDs are source row indexes
const tile = toMvt(batch, { z: 12, x: 3635, y: 1615 }); // ArrayBuffer
const arrow = toGeoArrow(batch, { crs: 'OGC:CRS84' }); // ArrayBuffer, Arrow IPC stream

read() returns every attribute plus the primary geometry by default; pass columns to fetch fewer. toMvt assumes longitude/latitude and is meant for a tile-sized bbox. toGeoArrow writes one record batch that tableFromIPC from apache-arrow (or pyarrow) can read, with the geometry as a GeoArrow multi type (geoarrow.multipolygon, geoarrow.multilinestring or geoarrow.multipoint). See the JavaScript reader README for usage and options, and the demo for rendering with MapLibre or deck.gl.

Specification

See SPEC.md for the LoD extension, including optional quantized geometry overviews.

Implementations

This repository is the source of truth for the specification and its reference implementations:

The implementations remain independently publishable. The repository root owns shared dependency locks, CI, releases, and development commands so changes to the profile can be tested against both implementations together.

Releases

The specification and each implementation are versioned and released separately, each with its own tag prefix:

Component Tag Published to
Specification spec-v<version> GitHub Releases
cogp-rs cogp-rs-v<version> GitHub Releases (binaries), crates.io (cogp)
@cogp/reader (js/packages/reader) cogp-js-v<version> npm (@cogp/reader)
@cogp/maplibre (js/packages/maplibre) cogp-js-v<version> npm (@cogp/maplibre)

Each implementation README states the specification version it implements. To release an implementation, bump the version in its Cargo.toml or package.json, merge, then publish a GitHub Release whose tag matches that version. Tags v0.1.0–v2.0.1 predate this split and covered the whole repository. The JavaScript packages share one version and are published together by the cogp-js-v<version> release workflow. It publishes @cogp/reader before @cogp/maplibre, which depends on that reader version.

The demo is not released: it deploys to GitHub Pages from main whenever js/** changes.

Writer implementation

SPEC.md defines the format contract. The cogp-rs writer orders features as follows; these are implementation choices, not format requirements. See the CLI reference for options and defaults.

The writer outputs GeoParquet 1.1, the most widely supported version. Its spatial pruning relies on the statistics of the 1.1 bbox covering columns, including their Page Indexes.

  1. Assign each feature to the coarsest level where it is visible. Each level has a rendering resolution. Lines and polygons enter once their bbox is large enough to see at that resolution. Points are thinned on a grid so each cell keeps one point per level. Everything else, including null and empty geometries, goes to the finest level; no rows are dropped.
  2. Write levels coarse to fine. A Row Group never mixes levels, so each level ends on a Row Group boundary recorded in geo.lod.levels.
  3. Pack each level spatially. Within a level, Sort-Tile-Recursive packing groups nearby features into the same Row Group and page, so bbox statistics and Page Indexes prune reads by area.

When the input is all lines or all polygons, the writer also adds simplified, quantized overviews for each level. A feature is deferred until its simplified geometry survives. Null and empty geometries get empty overview values, so they do not prevent overviews. Primary geometries and attributes are never changed.

Development

Install JavaScript dependencies once from the repository root:

pnpm install --frozen-lockfile

Common checks also run from the root:

cargo test --workspace --all-features
pnpm typecheck
pnpm build

See each implementation's README for its public API and focused workflows.

Roadmap

  • Producer implementation: a tool/library that converts existing GeoParquet 1.1 files into the COGP layout.
  • Reader implementation: a client that interprets the geo.lod metadata and fetches only the leading row groups required for the target resolution, and within them only the pages intersecting the viewport, via HTTP range requests.
  • Propose the level-of-detail layout as a GeoParquet extension.
  • Add geometry overviews for scale-dependent rendering while preserving the lossless primary geometry.

A proof-of-concept exploring this layout exists at Kanahiro/yosegi.

Presentation

License

The contents of SPEC.md are licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). See LICENSE-SPEC for details.

The source code in this repository is licensed under the MIT License.

About

A GeoParquet extension for progressive map rendering and partial access over HTTP range requests.

Resources

Stars

108 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Contributors

Languages