Skip to content

Add point-cloud data-out methods (metadata / numpy / dataframe) - #208

Merged
amarcozzi merged 1 commit into
mainfrom
199-point-cloud-data-out
Aug 26, 2026
Merged

Add point-cloud data-out methods (metadata / numpy / dataframe)#208
amarcozzi merged 1 commit into
mainfrom
199-point-cloud-data-out

Conversation

@amarcozzi

Copy link
Copy Markdown
Contributor

Summary

Adds data-out to the PointCloud class, which previously had no way to read its points into memory (unlike Grid.to_numpy / to_xarray). Mirrors the Grid chunk-reader pattern, paging over the tiled point-cloud data endpoints added in the recent client regen.

New public surface on PointCloud:

  • metadata() — the tile index (occupied tiles, columns/dtypes, coordinate encoding, per-LOD point counts) without downloading any points; drives tile iteration.
  • to_numpy(lod=None, classes=None, columns=("X","Y","Z"), decode_coordinates=True) — pages over occupied tiles and stacks the requested columns into an (N, k) float64 array. Defaults to decoded XYZ coordinates.
  • to_dataframe(lod=None, classes=None, columns=None, decode_coordinates=True) — one row per point, one column per stored attribute (all columns by default).

The binary transport is the fast path: a module-level _decode_point_cloud_tile() splits the contiguous little-endian column blocks described by the X-Data-* headers (bypassing the generated parser, which casts the binary body to str, exactly as Grid does for its binary chunks). lod / classes / columns selections are forwarded to the endpoint. X/Y/Z are decoded from stored scaled integers to CRS coordinates via the metadata scales/offsets.

Tests

  • Offline unit tests: binary tile decoding with synthetic bytes, the CSV query helper, and completion guards (no network).
  • Live tests against a completed 3DEP point cloud: metadata shape, point counts vs. the metadata LOD totals, decoded coordinates within reported bounds, LOD/class filtering, and column projection.
  • The binary reconstruction is validated value for value against an independent reassembly over the JSON tile endpoint (typed generated parser, no shared code with the binary decode), at an LOD that keeps the JSON transport under its 1M-value cap.

All 33 tests in tests/v2/test_point_clouds.py pass against the live API. black and flake8 are clean.

Depends on #195 (client regen, already merged to main).

Closes #199

Add PointCloud.metadata(), to_numpy(), and to_dataframe() that page over the
tiled point-cloud data endpoints and assemble points in memory, mirroring the
Grid chunk-reader pattern. The binary transport is the fast path; a module-level
_decode_point_cloud_tile() splits the contiguous little-endian column blocks
described by the X-Data-* headers. metadata() drives tile iteration, and
lod / classes / columns selections are forwarded to the endpoints.

Tests cover offline binary decoding with synthetic bytes, the CSV query helper,
completion guards, and live 3DEP reads validated value-for-value against an
independent reassembly over the JSON tile endpoint.
@amarcozzi
amarcozzi merged commit 7816af1 into main Aug 26, 2026
2 of 3 checks passed
@amarcozzi
amarcozzi deleted the 199-point-cloud-data-out branch August 26, 2026 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SDK: point-cloud data-out methods (metadata / tiled JSON / binary)

1 participant