Skip to main content

tol_compress/
lib.rs

1//! Tolerance-bounded compression of spatial coordinate data.
2//!
3//! This crate stores spatial coordinates using a practical tolerance-compressed method, which
4//! takes advantage of two specific features of real world measurement data:
5//!
6//! 1. Real world measurement systems have known precisions below which differences in position
7//!    do not represent meaningful information, and users of measurement data have knowledge about
8//!    where increasingly small differences in values cease to be relevant to their use case.
9//! 2. Values produced by the measurement of physical objects rarely span more than a few orders
10//!    of magnitude more than the smallest meaningful precision for the measurement system and/or
11//!    the application.
12//!
13//! If a user can supply a tolerance that represents the largest acceptable round-trip accuracy of
14//! any value in their dataset, the storage algorithm can find a representation scheme that uses
15//! the smallest amount of bytes necessary to guarantee every position is recovered within that
16//! tolerance.
17//!
18//! # Where to start
19//!
20//! Most callers want one of the four container modules, which read and write whole files:
21//!
22//! | module | holds | extension |
23//! |---|---|---|
24//! | [`mesh`] | triangle meshes in 3D | `.tcmesh` |
25//! | [`polyline`] | ordered polylines in 2D or 3D, open or closed | `.tccurve2`, `.tccurve3` |
26//! | [`cloud`] | unordered point sets in 2D or 3D | `.tccloud2`, `.tccloud3` |
27//! | [`row_points`] | points in 3D grouped into the rows a rasterizing sensor produced | `.tcrpf3` |
28//!
29//! ```no_run
30//! use std::path::Path;
31//! use tol_compress::{Mesh3, mesh};
32//!
33//! let mesh = Mesh3::new(
34//!     vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
35//!     vec![[0, 1, 2]],
36//! );
37//!
38//! // Every vertex is guaranteed back within one micron of where it started.
39//! mesh::write_one_file(Path::new("part.tcmesh"), &mesh, 1e-6)?;
40//! let back = mesh::read_one_file(Path::new("part.tcmesh"))?;
41//! # Ok::<(), tol_compress::Error>(())
42//! ```
43//!
44//! Every container is an ordered **collection**, so a file may hold one item or many. The
45//! `write_one_*` and `read_one_*` functions are conveniences over that rather than a separate
46//! format, and reading one item from a file holding several is an error rather than a silent
47//! truncation. [`probe`] identifies a file without decoding its geometry.
48//!
49//! Items carry an optional name and an optional [`Metadata`] map, which is stored and never
50//! interpreted, so a caller can record whatever their domain needs without this crate learning
51//! anything about it.
52//!
53//! How hard the encoder works for a smaller file is one setting, [`Effort`], rather than a flag per
54//! technique. Each container's `write_to_with` and `write_file_with` take a `WriteOptions` carrying
55//! it, alongside that container's own semantic settings. See the [`effort`] module for what does
56//! and does not belong on that dial.
57//!
58//! # Underneath
59//!
60//! The containers are built from block encoders that are useful on their own if you are storing
61//! geometry inside some other format:
62//!
63//! - [`points`] encodes coordinates in any number of dimensions against a tolerance, and
64//!   [`quantize`] and [`bounds`] are where the tolerance guarantee is actually decided.
65//! - [`indices`] encodes simplex connectivity, exactly, at whichever of its two codings is smaller.
66//! - [`rows`] encodes the integer grouping that assigns a sequence of points to sensor rows.
67//! - [`reorder`] renumbers a mesh so its indices compress. [`mesh`] applies this by default; see
68//!   its documentation if you hold per-vertex data outside the file.
69//! - [`segment`] plans where a point sequence wants to be cut into partitions, and [`transform`]
70//!   carries the frame a partition can be written in, which nothing currently chooses.
71//! - [`blocks`] and [`bits`] are the packing layer everything else sits on.
72//!
73//! # Errors and forward compatibility
74//!
75//! Everything fallible returns [`Error`], which implements [`std::error::Error`], so a caller using
76//! a boxed-error alias absorbs it through `?` with no glue.
77//!
78//! Two fields in the format are reserved for features not yet implemented: compression and
79//! per-item attributes. A reader from this version meeting a file that uses one of them **fails
80//! with a specific error rather than misreading it**, and files written today stay readable as
81//! those features arrive. The multiple-partition field was reserved the same way and is now in use;
82//! because the decoder always read it generically, a reader built before partitioning shipped reads
83//! a partitioned file correctly.
84//!
85//! The point block's per-partition transform is further along than either: both ends of it are
86//! implemented and tested, but nothing chooses a frame, so no file this version writes uses it. See
87//! [`transform`] for what it is worth and why it is idle.
88
89#![deny(missing_docs)]
90#![deny(rustdoc::broken_intra_doc_links)]
91
92pub mod bits;
93pub mod blocks;
94pub mod bounds;
95pub mod cloud;
96pub mod container;
97pub mod effort;
98pub mod error;
99pub mod indices;
100pub mod mesh;
101pub mod metadata;
102pub mod points;
103pub mod polyline;
104pub mod quantize;
105mod raw;
106pub mod reorder;
107pub mod row_points;
108pub mod rows;
109pub mod segment;
110pub mod transform;
111
112/// Compiles and runs the README's examples as doctests, so the first thing a reader copies cannot
113/// silently rot. Not part of the public API and not rendered anywhere.
114#[cfg(doctest)]
115#[doc = include_str!("../README.md")]
116struct ReadmeExamples;
117
118/// Deliberately awkward test geometry, behind the non-default `corpus` feature.
119#[cfg(any(test, feature = "corpus"))]
120pub mod corpus;
121
122#[cfg(any(test, feature = "corpus"))]
123pub mod testgen;
124
125pub use blocks::BLOCK;
126pub use bounds::Bounds;
127pub use cloud::{Cloud, Cloud2, Cloud3};
128pub use container::{Header, Kind, Named, find_by_name, probe};
129pub use effort::Effort;
130pub use error::{Error, Result};
131pub use indices::{bits_for_count, read_indices, write_indices};
132pub use mesh::{Mesh3, VertexOrder};
133pub use metadata::{Metadata, Value};
134pub use points::{read_points, write_points, write_points_with};
135pub use polyline::{Polyline, Polyline2, Polyline3};
136pub use quantize::{Quantizer, bits_for_tol};
137pub use reorder::{Reordering, permute};
138pub use row_points::{PointRow3, RowPoints3};
139pub use rows::{RowLayout, read_rows, write_rows};