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::{CopcStreamingReader, FileSource, VoxelKey};

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

// Coarse octree nodes are available immediately.
// Load deeper hierarchy pages as you need them.
let root_bounds = reader.copc_info().root_bounds();

while reader.has_pending_pages() {
    reader.load_pending_pages().await?;
}

// Walk the octree — check which nodes intersect your region.
for (key, entry) in reader.entries() {
    if entry.point_count == 0 { continue; }
    if !key.bounds(&root_bounds).intersects(&my_query_box) { continue; }

    // Drill into finer nodes when available.
    let finer = reader.children(key);
    if !finer.is_empty() { continue; } // render children instead

    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 progressive loading, 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

CopcStreamingReader::open reads the LAS header, COPC info and root hierarchy page. Coarse octree nodes are available right away. Deeper pages are loaded on demand:

• load_pending_pages — fetch the next level of pages. Call repeatedly, or only when you need finer detail.
• load_all_hierarchy — convenience to pull every remaining page in one go.
• children — list loaded children of a node.
• 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.