copc_streaming/
reader.rs

1//! High-level streaming COPC reader.
2
3use crate::byte_source::ByteSource;
4use crate::chunk::{self, DecompressedChunk};
5use crate::error::CopcError;
6use crate::header::{self, CopcHeader, CopcInfo};
7use crate::hierarchy::{HierarchyCache, HierarchyEntry};
8use crate::types::VoxelKey;
9
10/// Async streaming COPC reader.
11///
12/// `open()` reads the LAS header, VLRs, and root hierarchy page.
13/// Deeper hierarchy pages and point chunks are loaded on demand.
14pub struct CopcStreamingReader<S: ByteSource> {
15    source: S,
16    header: CopcHeader,
17    hierarchy: HierarchyCache,
18}
19
20impl<S: ByteSource> CopcStreamingReader<S> {
21    /// Open a COPC file.
22    pub async fn open(source: S) -> Result<Self, CopcError> {
23        let size = source.size().await?.unwrap_or(65536);
24        let read_size = size.min(65536);
25        let data = source.read_range(0, read_size).await?;
26        let header = header::parse_header(&data)?;
27
28        let mut hierarchy = HierarchyCache::new();
29        hierarchy.load_root(&source, &header.copc_info).await?;
30
31        Ok(Self {
32            source,
33            header,
34            hierarchy,
35        })
36    }
37
38    // --- Header accessors ---
39
40    /// The parsed COPC file header.
41    pub fn header(&self) -> &CopcHeader {
42        &self.header
43    }
44
45    /// Shortcut for `header().copc_info()`.
46    pub fn copc_info(&self) -> &CopcInfo {
47        &self.header.copc_info
48    }
49
50    /// File offset where EVLRs start.
51    pub fn evlr_offset(&self) -> u64 {
52        self.header.evlr_offset
53    }
54
55    /// Number of EVLRs in the file.
56    pub fn evlr_count(&self) -> u32 {
57        self.header.evlr_count
58    }
59
60    /// The underlying byte source.
61    pub fn source(&self) -> &S {
62        &self.source
63    }
64
65    // --- Hierarchy queries ---
66
67    /// Look up a hierarchy entry by voxel key.
68    pub fn get(&self, key: &VoxelKey) -> Option<&HierarchyEntry> {
69        self.hierarchy.get(key)
70    }
71
72    /// Iterate all loaded hierarchy entries.
73    pub fn entries(&self) -> impl Iterator<Item = (&VoxelKey, &HierarchyEntry)> {
74        self.hierarchy.iter()
75    }
76
77    /// Return loaded child entries for a given node.
78    ///
79    /// Only returns children that are already in the hierarchy cache.
80    /// If deeper hierarchy pages haven't been loaded yet, this may
81    /// return fewer children than actually exist in the file.
82    pub fn children(&self, key: &VoxelKey) -> Vec<&HierarchyEntry> {
83        key.children()
84            .iter()
85            .filter_map(|child| self.hierarchy.get(child))
86            .collect()
87    }
88
89    /// Number of loaded hierarchy entries.
90    pub fn node_count(&self) -> usize {
91        self.hierarchy.len()
92    }
93
94    /// Whether there are hierarchy pages that haven't been loaded yet.
95    pub fn has_pending_pages(&self) -> bool {
96        self.hierarchy.has_pending_pages()
97    }
98
99    // --- Hierarchy loading ---
100
101    /// Load the next batch of pending hierarchy pages.
102    pub async fn load_pending_pages(&mut self) -> Result<(), CopcError> {
103        self.hierarchy.load_pending_pages(&self.source).await
104    }
105
106    /// Load only hierarchy pages whose subtree intersects `bounds`.
107    ///
108    /// Pages outside the region are left pending for future calls.
109    /// Much cheaper than `load_all_hierarchy` when querying a small area.
110    pub async fn load_hierarchy_for_bounds(
111        &mut self,
112        bounds: &crate::types::Aabb,
113    ) -> Result<(), CopcError> {
114        let root_bounds = self.header.copc_info.root_bounds();
115        self.hierarchy
116            .load_pages_for_bounds(&self.source, bounds, &root_bounds)
117            .await
118    }
119
120    /// Load all remaining hierarchy pages.
121    pub async fn load_all_hierarchy(&mut self) -> Result<(), CopcError> {
122        self.hierarchy
123            .load_all(&self.source, &self.header.copc_info)
124            .await
125    }
126
127    // --- Point data ---
128
129    /// Fetch and decompress a single point chunk.
130    pub async fn fetch_chunk(&self, key: &VoxelKey) -> Result<DecompressedChunk, CopcError> {
131        let entry = self
132            .hierarchy
133            .get(key)
134            .ok_or(CopcError::NodeNotFound(*key))?;
135        let point_record_length = self.header.las_header.point_format().len()
136            + self.header.las_header.point_format().extra_bytes;
137        chunk::fetch_and_decompress(
138            &self.source,
139            entry,
140            &self.header.laz_vlr,
141            point_record_length,
142        )
143        .await
144    }
145
146    /// Parse all points from a decompressed chunk.
147    pub fn read_points(&self, chunk: &DecompressedChunk) -> Result<Vec<las::Point>, CopcError> {
148        chunk::read_points(chunk, &self.header.las_header)
149    }
150
151    /// Parse a sub-range of points from a decompressed chunk.
152    ///
153    /// Only the points in `range` are parsed — bytes outside the range are skipped.
154    /// Pair with `NodeTemporalEntry::estimate_point_range` from the `copc-temporal`
155    /// crate to read only the points that fall within a time window.
156    pub fn read_points_range(
157        &self,
158        chunk: &DecompressedChunk,
159        range: std::ops::Range<u32>,
160    ) -> Result<Vec<las::Point>, CopcError> {
161        chunk::read_points_range(chunk, &self.header.las_header, range)
162    }
163}
copc_streaming/reader.rs

copc_streaming/
reader.rs
