cloud-optimized-geoparquet - GitLite

KO | EN

gitlite — search

#html #ai-agents #generative-ai #cli #terminal #ai #react-native #windows #monitoring #shell

cloud-optimized-geoparquet

(★ 20)

A specification for progressive, cloud-friendly GeoParquet

File Explorer

ZIP Download

- - deploy-demo.yml
  - release-cogp-rs.yml
  - test.yml
- FUNDING.yml
- - index.html
  - package.json
  - tsconfig.json
  - vite.config.ts
- - bbox.ts
  - coalescing-buffer.ts
  - index.ts
  - level.ts
  - meta.ts
  - reader.ts
- - coalescing-buffer.test.mjs
- package.json
- README.md
- tsconfig.json
- - convert.rs
  - lib.rs
  - main.rs
  - meta.rs
  - range_coalescing.rs
  - reader.rs
  - validate.rs
  - wkb_bbox.rs
- - end_to_end.rs
  - validate_failures.rs
- - bench_cogp.py
  - requirements-bench.txt
- Cargo.toml
- README.md
.gitignore
Cargo.lock
Cargo.toml
LICENSE
LICENSE-SPEC
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
SPEC.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`cargo test`

View Details ▼

Execute the unit and integration tests of a Rust package.

cargo {{[t|test]}} {{test_name}}

Only run tests containing a specific string in their names:

cargo {{[t|test]}} -- --test-threads {{count}}

Set the number of simultaneous running test cases:

cargo {{[t|test]}} {{[-r|--release]}}

Test artifacts in release mode, with optimizations:

🔍

`pnpm`

View Details ▼

Fast, disk space efficient package manager for Node.js.
Manage Node.js projects and their module dependencies.

pnpm init

Create a `package.json` file:

pnpm {{[i|install]}}

Download all the packages listed as dependencies in `package.json`:

pnpm add {{module_name}}@{{version}}

Download a specific version of a package and add it to the list of dependencies in `package.json`:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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

## TL;DR

A COGP file is a valid [GeoParquet 1.1](https://geoparquet.org/) file whose row groups are physically ordered from coarse to fine rendering detail, with file-level metadata describing where each level ends.

COGP is **feature-level**: it reorders features across row groups; it does not simplify, aggregate, or duplicate them. Each source feature appears in exactly one row group, with its geometry preserved verbatim.

A COGP-aware reader can stream just the leading row groups needed for its target rendering resolution and stop. A reader that does not understand the profile can ignore the `cogp` metadata and read the file as ordinary GeoParquet 1.1.

## 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 applies these ideas at the GeoParquet row group level. Unlike raster overviews or vector tile simplification pipelines, COGP keeps each feature geometry unchanged and places each source feature in exactly 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.

COGP is a small, conservative layout convention that enables this without changing GeoParquet's data model.

## Benefits

- **Faster overview rendering, even for non-COGP-aware software.** Because coarse-detail features are physically placed at the front of the file, any GeoParquet 1.1 reader that streams row groups in order will see a usable overview almost immediately, without needing to understand the `cogp` metadata.
- **Efficient AoI-based spatial queries, even for non-COGP-aware software.** The layout preserves GeoParquet 1.1 semantics and row group statistics, so existing engines can still prune by bounding box and answer area-of-interest queries efficiently.
- **Minimal, resolution-targeted streaming for COGP-aware software.** A COGP-aware reader can consult the level metadata and fetch only the leading row groups required for its target geographic resolution, enabling fast progressive streaming with the smallest possible byte footprint.

### Example: loading OvertureMaps buildings on QGIS 4.0

#### ordinary GeoParquet (spatially sorted)

https://github.com/user-attachments/assets/10d0390c-95ab-45e5-8503-6cbdbb015c93

#### COGP

https://github.com/user-attachments/assets/fd15605a-7d66-41a3-884d-c735e3467708

### Example: streaming from Cloudflare R2 to browser [demo page](https://kanahiro.github.io/cloud-optimized-geoparquet/)

https://github.com/user-attachments/assets/7daf178e-28b0-4440-845d-ee8f74fa5062

## Sample data

- [pois.cogp.parquet](https://cogp-demo.spatialty.io/pois.cogp.parquet) (OpenStreetMap)
- [segments.cogp.parquet](https://cogp-demo.spatialty.io/segments.cogp.parquet) (OvertureMaps)
- [buildings.cogp.parquet](https://cogp-demo.spatialty.io/buildings.cogp.parquet) (OvertureMaps)

## When COGP works well

COGP is particularly well suited to datasets of many small, well-distributed features — such as POIs or building footprints — where dropping later row groups still yields a meaningful overview.

Because COGP does not simplify geometries, datasets dominated by large, complex geometries (coastlines, rivers, road networks, administrative boundaries) have relatively larger per-feature payloads, so the Row Group size should be tuned to optimize progressive streaming. Other COGP benefits — GeoParquet 1.1 compatibility, fast overview rendering, and efficient AoI-based queries — still apply.

## Specification

See [`SPEC.md`](./SPEC.md) for the normative specification.

## Implementations

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

- [`cogp-rs`](./cogp-rs): Rust producer, validator, CLI, and reader library.
- [`cogp-js`](./cogp-js): TypeScript reader and browser 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.

## Development

Install JavaScript dependencies once from the repository root:

```sh
pnpm install --frozen-lockfile
```

Common checks also run from the root:

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

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

## Roadmap

- [x] Producer implementation: a tool/library that converts existing GeoParquet 1.1 files into the COGP layout. 
- [x] Reader implementation: a client that interprets the `cogp` metadata and fetches only the leading row groups required for the target resolution via HTTP range requests.

A proof-of-concept exploring this layout exists at [Kanahiro/yosegi](https://github.com/Kanahiro/yosegi).

## Status and feedback

COGP v0.1 is an early draft. Feedback, issues, and discussion are welcome via GitHub Issues.

## License

The contents of [`SPEC.md`](./SPEC.md) are licensed under [Creative Commons
Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
See [`LICENSE-SPEC`](./LICENSE-SPEC) for details.

The source code in this repository is licensed under the [MIT License](./LICENSE).