A GeoParquet extension for progressive map rendering and partial access over HTTP range requests or object storage.
Created by Kanahiro Iguchi.
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.
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.
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.
- Progressive rendering for COGP-aware software. A reader can use
geo.lodto 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.lodcan 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.
Screen.Recording.2026-05-24.at.11.09.24.mov
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
Screen.Recording.2026-09-26.at.13.17.48.mov
- pois.cogp.parquet (OpenStreetMap)
- segments.cogp.parquet (OvertureMaps)
- buildings.cogp.parquet (OvertureMaps)
- admin.cogp.parquet (administrative boundaries, https://nlftp.mlit.go.jp/ksj/gml/datalist/KsjTmplt-N03-2025.html)
This walks through converting your own vector data into COGP and reading it from JavaScript.
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.parquetThe 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.
Install the reader from npm:
npm install @cogp/readerRead 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 streamread() 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.
See SPEC.md for the LoD extension, including optional quantized geometry overviews.
This repository is the source of truth for the specification and its reference implementations:
cogp-rs: Rust producer, validator, CLI, and reader library.js: TypeScript packages (@cogp/reader,@cogp/maplibre) and the browser demo (js/demo).
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.
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.
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.
- 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.
- 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. - 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.
Install JavaScript dependencies once from the repository root:
pnpm install --frozen-lockfileCommon checks also run from the root:
cargo test --workspace --all-features
pnpm typecheck
pnpm buildSee each implementation's README for its public API and focused workflows.
- Producer implementation: a tool/library that converts existing GeoParquet 1.1 files into the COGP layout.
- Reader implementation: a client that interprets the
geo.lodmetadata 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.
- 2026-10-07 CNG Forum 2026 / GeoParquet is not Cloud Optimized... yet!
- 2026-09-03 MapLibre Meetup in Hiroshima / What vector tiles don’t solve.
- 2026-09-02 FOSS4G 2026 Hiroshima / A Proposal for Hierarchically Organized GeoParquet
- 2026-08-24 CNG Japan / Spatial sort for well-packed GeoParquet
- 2026-06-10 MIERUNE JCT #03 / GeoParquetはほんとうにCloud Optimizedなのか?
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.