This presentation introduces Squaba, a type-safe spatial mathematics library for Rust designed to mitigate the complexity and common errors associated with 3D coordinate system transformations. The speaker, John, begins by detailing the inherent difficulties of spatial math, using the example of locating an object from an airplane. He explains the various frames of reference involved, such as local body-fixed systems (Front-Right-Down), local tangent plane systems (North-East-Down), and global systems (WGS84 GPS). The talk highlights the error-prone nature of this domain due to inconsistent conventions, including right-handed vs. left-handed coordinate systems, axis ordering, and the non-standard definitions of bearings.
The core of the presentation demonstrates how Squaba leverages Rust's type system to enforce correctness at compile time. Each coordinate system is represented by a unique type, preventing the accidental mixing of data from different frames. The library features a type-state builder pattern, integrates with the uom crate for dimensional analysis (e.g., meters vs. feet), and ensures that transformations are chained logically. A key concept discussed is the library's novel use of the unsafe keyword to demarcate "type unsafety"—points where the programmer must assert a runtime fact (like an object's current location) to bridge the physical world with the type system, thus isolating potential logical errors.
An Introduction to Squaba: A Type-Safe Spatial Math Library in Rust
(0:00:28) What is Squaba?: Squaba is a type-safe Rust library created to simplify and prevent common errors when working with different 3D coordinate systems (or "frames of reference").
(0:01:31) The Core Problem of Spatial Math: The primary challenge is correctly defining and converting between different frames of reference, such as a pilot's viewpoint, compass directions, and global GPS coordinates. Simple mistakes, like a single incorrect sign, can lead to completely wrong results.
(0:03:12) Key Coordinate Systems Explained: The talk introduces the main types of coordinate systems that often need to be managed simultaneously:
Local Body-Fixed: Attached to an object, like Front-Right-Down (FRD) for aerospace.
Local Tangent Plane: Based on compass directions at a point on Earth, like North-East-Down (NED).
Global Geodetic: Describes points on the Earth, with WGS84 (used by GPS) being the most common.
(0:10:14) Inconsistent Conventions Cause Critical Errors: The speaker emphasizes that many subtle complexities lead to bugs. These include right-handed vs. left-handed systems (the Unity game engine famously uses a left-handed system), inconsistent axis ordering (NED vs. East-North-Up), and non-standard definitions for bearings (azimuth and elevation).
(17:17) Squaba's Type-Safe Solution: The library's main feature is representing every distinct frame of reference as a unique Rust type. This allows the compiler to catch logically incorrect operations, such as adding a coordinate in one plane's system to a coordinate in another's without an explicit transformation.
(19:28) Type-Safe Construction and Units: Squaba uses a type-state builder pattern for creating coordinates and integrates with the uom crate to enforce correct physical units (e.g., degrees vs. radians, meters vs. kilometers), preventing another common class of errors.
(23:23) Compiler-Enforced Transformations: Transformations between coordinate systems are also typed. The compiler ensures transformations are chained correctly (the output system of one must match the input of the next), preventing invalid conversion paths and combining them into a single, efficient operation.
(27:14) A Novel Use of unsafe for Logical Correctness: Squaba uses unsafe blocks not for memory safety, but to flag "type unsafety." These blocks isolate the exact points where the programmer must assert a runtime fact that the compiler cannot verify (e.g., a plane's current GPS location). This makes the most critical assumptions in the code explicit and auditable.
(31:51) Motivation and Real-World Application: The library was created for safety-critical applications in the defense sector, where correctness is paramount. It was developed to replace existing code that was difficult to verify and maintain, and in the process, it uncovered several existing bugs.
(29:08) Availability and Documentation: Squaba is open-source and available on crates.io, with extensive documentation explaining both the API and the underlying mathematical concepts.