Crate copc_streaming 

Async streaming reader for COPC (Cloud-Optimized Point Cloud) files.

COPC organises LAS/LAZ point cloud data in a spatial octree so that clients can fetch only the regions they need. This crate reads COPC files incrementally through the ByteSource trait — any random-access backend (local files, HTTP range requests, in-memory buffers) works out of the box.

Quick start

use copc_streaming::{Aabb, CopcStreamingReader, FileSource};

let mut reader = CopcStreamingReader::open(
    FileSource::open("points.copc.laz")?,
).await?;

// One call: loads hierarchy, fetches chunks, filters points by bounds.
let points = reader.query_points(&my_query_box).await?;
// each `point` has .x, .y, .z, .gps_time, .color, etc.

With LOD control

// Load points with at most 0.5 m between samples.
let level = reader.copc_info().level_for_resolution(0.5);
let points = reader.query_points_to_level(&my_query_box, level).await?;

Low-level access

For full control over hierarchy loading and chunk processing:

let mut reader = CopcStreamingReader::open(
    FileSource::open("points.copc.laz")?,
).await?;

let root_bounds = reader.copc_info().root_bounds();
reader.load_hierarchy_for_bounds(&my_query_box).await?;

for (key, entry) in reader.entries() {
    if entry.point_count == 0 { continue; }
    if !key.bounds(&root_bounds).intersects(&my_query_box) { continue; }

    let chunk = reader.fetch_chunk(key).await?;
    let points = reader.read_points_in_bounds(&chunk, &my_query_box)?;
}

Hierarchy loading

The COPC hierarchy is stored as a tree of pages. Each page contains metadata for a group of octree nodes (typically several levels deep) plus pointers to child pages covering deeper subtrees.

CopcStreamingReader::open reads the LAS header, COPC info, and the root hierarchy page. This gives you the coarse octree nodes immediately (often levels 0–3, depending on the file). Any subtrees stored in separate pages are tracked as pending pages — they haven’t been fetched yet.

You then control when and which deeper pages are loaded:

• load_hierarchy_for_bounds — load only pages whose subtree intersects a bounding box. Call this when the camera moves or a spatial query arrives.
• load_hierarchy_for_bounds_to_level — same, but stops at a maximum octree level. Use with CopcInfo::level_for_resolution for LOD control.
• load_pending_pages — fetch the next batch of pending pages (all of them). Useful when you don’t need spatial filtering and just want to go one level deeper.
• load_all_hierarchy — convenience to pull every remaining page in one go.
• children — list loaded children of a node. Returns only children already in the cache; if deeper pages haven’t been loaded yet this may return fewer than exist in the file.
• has_pending_pages — check if there are still unloaded pages.

Custom byte sources

Implement ByteSource to read from any backend. The trait requires only read_range(offset, length) and size(). A default read_ranges implementation issues sequential reads — override it for backends that support parallel fetches (e.g. HTTP/2 multiplexing).

Built-in implementations: FileSource (local files), Vec<u8> and &[u8] (in-memory).

Futures returned by ByteSource are not required to be Send, so the crate works in single-threaded runtimes and WASM environments.

Structs

Aabb

Axis-aligned bounding box.

CopcHeader

Parsed COPC file header.

CopcInfo

COPC info VLR payload (160 bytes). This is COPC-specific — not part of the LAS standard.

CopcStreamingReader

Async streaming COPC reader.

DecompressedChunk

A decompressed point data chunk.

FileSource

A ByteSource backed by a local file.

HierarchyCache

Incrementally-loaded hierarchy cache.

HierarchyEntry

A single hierarchy entry: metadata for one octree node.

Point

Re-export las::Point — the point type returned by all read methods. A three dimensional point.

VoxelKey

Octree node key: (level, x, y, z).

Enums

CopcError

Errors that can occur when reading a COPC file.

Traits

ByteSource

Async random-access byte source.

Functions

fetch_and_decompress

Fetch and decompress a single chunk.

filter_points_by_bounds

Filter points to only those inside an axis-aligned bounding box.