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?;

let root_bounds = reader.copc_info().root_bounds();

// Load only the hierarchy pages that cover the region you care about.
reader.load_hierarchy_for_bounds(&my_query_box).await?;

// Walk loaded nodes — only those intersecting the query box.
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(&chunk)?;
    // each `point` has .x, .y, .z, .gps_time, .color, etc.
}

Load everything at once

If you don’t need spatial filtering, pull the full hierarchy in one call:

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

// Every node is now available via reader.entries() / reader.get().

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_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.

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.