@ready.net/co-geoparquet-layers

Read a cloud-optimized GeoParquet artifact straight from object storage and draw it with deck.gl — decoding the manifest, planning a viewport into HTTP range requests, and rendering each row group as it arrives.

Part of co-geoparquet. The companion Python package, co-geoparquet, builds the artifacts this one reads.

Developed with AI. Most of this project's code, tests and documentation were written by AI coding assistants (Anthropic's Claude, through Claude Code), directed and reviewed by a human maintainer. It has a test suite and its performance numbers are measured, not estimated, but AI-written code can be wrong in ways that look right. Check its output against your own data, review it before you depend on it in production, and report anything that looks off.

Install

npm install @ready.net/co-geoparquet-layers

Peer dependencies

Required:

| Package | Why | |---|---| | @deck.gl/core ^9.3 | The layer is a CompositeLayer | | @geoarrow/deck.gl-geoarrow ^0.4.2 | Draws the GeoArrow columns; brings its own deck.gl layer packages | | @loaders.gl/geoarrow ^4.4.5 | GeoArrow metadata and layout inspection — needed even for a barrel-only import | | apache-arrow >=15 | The record batches the layer hands to deck.gl |

Optional, each reached through a dynamic import() so you only install what you use:

| Package | Needed for | |---|---| | hyparquet, hyparquet-compressors | The built-in fetcher (the ./hyparquet export). Skip both if you bring your own reader | | parquet-wasm ^0.6 | Reading a plain .parquet with no manifest (the ./plain export). Carries a 5.5 MB wasm binary |

Usage

import { COGeoParquetLayer } from "@ready.net/co-geoparquet-layers/layers";

new COGeoParquetLayer({ id: "buildings", manifestUrl: "https://…/buildings.gpqm" });

The layer resolves the companion Parquet from the manifest's own parquet field, plans the current view into byte ranges, fetches the row groups it needs, and picks its deck.gl sublayer (Scatterplot / Path / Polygon) from the geometry it actually finds — you never pass a geometry type.

A bare Parquet URL works too:

new COGeoParquetLayer({ id: "someones-file", parquetUrl: "https://…/buildings.parquet" });

It probes for buildings.gpqm beside the file with a one-byte range GET. Found, the read is the ordinary LOD-planned one. Not found, the file is read as plain GeoParquet — whole, every row group, no viewport planning — which is what makes a .parquet link someone sent you render at all. Pass missingManifest: "error" if you would rather hear about a missing manifest than work around it.

Entry points

| Import | Contains | |---|---| | @ready.net/co-geoparquet-layers | Manifest decoding, view planning, the byte-range stack, error types. No Parquet reader, no deck.gl | | @ready.net/co-geoparquet-layers/layers | COGeoParquetLayer. Separate because it pulls in @geoarrow/deck.gl-geoarrow, whose published ESM build does not resolve under plain Node | | @ready.net/co-geoparquet-layers/hyparquet | createHyparquetFetcher, the default row-group reader | | @ready.net/co-geoparquet-layers/plain | openPlainParquet, the manifest-less read |

Documentation

• deck.gl layer and props
• Attribute columns and styling
• Simplify by zoom
• Plain GeoParquet without a manifest
• Bring your own reader
• Errors
• Format specification

Development

dist/ is gitignored and the docs site and demo viewer both import from it, so the build is not optional in a checkout:

npm install && npm run build && npm test

License

MIT — see LICENSE.