Crate copc_temporal 

Reader for the COPC Temporal Index Extension.

When a COPC file contains data from multiple survey passes over the same area, a spatial query alone returns points from every pass that touched that region. The temporal index extension adds per-node GPS time metadata so that clients can filter by time before decompressing any point data.

This crate reads the temporal index incrementally via ByteSource, matching the streaming design of copc_streaming.

Quick start

use copc_streaming::{Aabb, CopcStreamingReader, FileSource};
use copc_temporal::{GpsTime, TemporalCache};

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

let mut temporal = match TemporalCache::from_reader(&reader).await? {
    Some(t) => t,
    None => return Ok(()), // no temporal index in this file
};

let start = GpsTime(1_000_000.0);
let end   = GpsTime(1_000_010.0);

// One call: loads hierarchy + temporal pages, fetches chunks,
// filters by both bounds and time.
let points = temporal.query_points(
    &mut reader, &my_query_box, start, end,
).await?;

Low-level access

For full control over page loading and chunk processing, use the building blocks directly:

// Load only temporal pages that overlap the time range.
temporal.load_pages_for_time_range(reader.source(), start, end).await?;

// Find matching nodes, estimate point ranges, fetch chunks yourself.
for entry in temporal.nodes_in_range(start, end) {
    let range = entry.estimate_point_range(
        start, end, temporal.stride(), hier.point_count,
    );
    // ...
}

How it works

TemporalCache::from_reader loads the header and root page. TemporalCache::query_points then loads the relevant hierarchy and temporal pages, fetches matching chunks, and returns only the points that fall inside both the bounding box and time window.

For time-only queries (no spatial filter), use TemporalCache::query_points_by_time.

For advanced use cases you can call TemporalCache::load_pages_for_time_range and TemporalCache::nodes_in_range separately, or TemporalCache::load_all_pages to fetch the entire index at once.

Structs

Aabb

Axis-aligned bounding box.

GpsTime

Newtype over f64 GPS time. Implements Copy, PartialEq, PartialOrd.

NodeTemporalEntry

Per-node temporal data: a set of sampled GPS timestamps.

TemporalCache

Incrementally-loaded temporal index cache.

TemporalHeader

Header of the temporal index EVLR (32 bytes).

VoxelKey

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

Enums

TemporalError

Errors that can occur when reading the temporal index.

Traits

ByteSource

Async random-access byte source.

Functions

filter_points_by_time

Filter points to only those whose GPS time falls within [start, end].