stripack_sys/lib.rs
1//! Raw Rust FFI bindings to STRIPACK.
2//!
3//! This crate provides low-level unsafe bindings to STRIPACK, a Fortran library for
4//! constructing Delaunay triangulations and Voronoi diagrams on the surface of the unit sphere.
5//!
6//! # Overview
7//!
8//! STRIPACK (Algorithm 772) computes Delaunay triangulations and Voronoi diagrams of a set of
9//! nodes on the surface of the unit sphere. The algorithms are generalizations of Robert Renka's
10//! TRIPACK software for the plane.
11//!
12//! This `-sys` crate provides direct FFI bindings to the underlying Fortran routines.
13//!
14//! # Building
15//!
16//! This crate requires a Fortran compiler to build the bundled STRIPACK library:
17//!
18//! - **Arch Linux**: `pacman -S gcc-fortran`
19//! - **Ubuntu/Debian**: `apt install gfortran`
20//! - **macOS**: `brew install gcc`
21//!
22//! # Safety
23//!
24//! All functions in this crate are `unsafe` because they:
25//! - Work with raw pointers
26//! - Call into Fortran code with different calling conventions
27//! - Require the caller to ensure proper memory allocation and alignment
28//! - May have undefined behavior if preconditions are not met
29//!
30//! Users must ensure:
31//! - Arrays are properly sized (e.g., `list[6*(n-2)]`, `lptr[6*(n-2)]`, `lend[n]`)
32//! - Pointers are valid and properly aligned
33//! - Nodes are unit vectors (x² + y² + z² = 1)
34//! - Indices are 1-based (as per Fortran convention)
35//!
36//! # Data Structure
37//!
38//! The triangulation is represented using a linked list data structure:
39//! - `list`: Adjacency lists
40//! - `lptr`: Pointers within `list`
41//! - `lend`: Pointers to ends of adjacency lists
42//! - `lnew`: Pointer to first empty location
43//!
44//! Refer to the individual function documentation for details on array sizes and conventions.
45//!
46//! # Example
47//!
48//! ```rust
49//! use stripack_sys::ffi::*;
50//!
51//! // Create a simple tetrahedral triangulation with 4 nodes
52//! let n = 4;
53//! let x = vec![1.0, 0.0, 0.0, 0.0];
54//! let y = vec![0.0, 1.0, 0.0, 0.0];
55//! let z = vec![0.0, 0.0, 1.0, 1.0];
56//!
57//! let mut list = vec![0; 6 * (n - 2) as usize];
58//! let mut lptr = vec![0; 6 * (n - 2) as usize];
59//! let mut lend = vec![0; n as usize];
60//! let mut lnew = 0;
61//! let mut near = vec![0; n as usize];
62//! let mut next = vec![0; n as usize];
63//! let mut dist = vec![0.0; n as usize];
64//! let mut ier = 0;
65//!
66//! unsafe {
67//! trmesh(
68//! &raw const n,
69//! x.as_ptr(),
70//! y.as_ptr(),
71//! z.as_ptr(),
72//! list.as_mut_ptr(),
73//! lptr.as_mut_ptr(),
74//! lend.as_mut_ptr(),
75//! &raw mut lnew,
76//! near.as_mut_ptr(),
77//! next.as_mut_ptr(),
78//! dist.as_mut_ptr(),
79//! &raw mut ier,
80//! );
81//! }
82//!
83//! assert_eq!(ier, 0);
84//! ```
85//! # License
86//!
87//! The Rust bindings are licensed under MIT OR Apache-2.0 at your option.
88//!
89//! The bundled Fortran code is distributed under the GNU LGPL.
90//!
91//! # Attribution
92//!
93//! STRIPACK — Delaunay Triangulation and Voronoi Diagram on the Surface of a Sphere
94//!
95//! - Original author: Robert J. Renka, University of North Texas
96//! - Reference: R. J. Renka, "Algorithm 772: STRIPACK: Delaunay Triangulation and Voronoi Diagram on the Surface of a Sphere",
97//! ACM Transactions on Mathematical Software, Vol. 23, No. 3, September 1997, pp. 416-434.
98//! - DOI: <https://doi.org/10.1145/275323.275329>
99//!
100//! The Fortran 90 version used in this crate was prepared by John Burkardt and is distributed under the GNU LGPL.
101
102pub mod ffi;