a5 0.7.3

High-performance Rust implementation of the A5 hierarchical spatial indexing system
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

// A5
// SPDX-License-Identifier: Apache-2.0
// Copyright (c) A5 contributors

use crate::core::utils::Quat;

// The quaternions for a regular dodecahedron are computed from exact trigonometric values.
//
// Dodecahedron face centers (origins) can be defined exactly using trigonometry:
// - The north and south poles are at z=1 and z=-1
// - Two rings at z = ±sqrt(0.2), with radius 2 * sqrt(0.2)
//
// The computation involves:
// - cos36° = (√5 + 1) / 4, cos72° = (√5 - 1) / 4
// - sin36° = √(10 - 2√5) / 4, sin72° = √(10 + 2√5) / 4
// - Half-angle rotations: sinAlpha = √((1 - √0.2) / 2), cosAlpha = √((1 + √0.2) / 2)

/// Array of 12 quaternions representing rotations for each face of a regular dodecahedron
///
/// The quaternions are arranged as follows:
/// - Index 0: North pole (identity quaternion)
/// - Indices 1-5: First ring around the north pole
/// - Indices 6-10: Second ring around the south pole  
/// - Index 11: South pole
///
/// Each quaternion represents the rotation needed to transform the north pole (0,0,1)
/// to the center of the corresponding dodecahedron face.
pub const QUATERNIONS: [Quat; 12] = [
    [0.0, 0.0, 0.0, 1.0], // 0: North pole (identity)
    // First ring (indices 1-5): z component = 0, w component = cosAlpha
    [0.0, 0.5257311121191336, 0.0, 0.8506508083520399], // 1
    [-0.5, 0.16245984811645314, 0.0, 0.8506508083520399], // 2
    [
        -0.30901699437494745,
        -0.42532540417602,
        0.0,
        0.8506508083520399,
    ], // 3
    [
        0.30901699437494745,
        -0.42532540417602,
        0.0,
        0.8506508083520399,
    ], // 4
    [0.5, 0.16245984811645314, 0.0, 0.8506508083520399], // 5
    // Second ring (indices 6-10): z component = 0, w component = sinAlpha
    [0.0, -0.8506508083520399, 0.0, 0.5257311121191336], // 6
    [
        0.8090169943749475,
        -0.2628655560595668,
        0.0,
        0.5257311121191336,
    ], // 7
    [0.5, 0.6881909602355868, 0.0, 0.5257311121191336],  // 8
    [-0.5, 0.6881909602355868, 0.0, 0.5257311121191336], // 9
    [
        -0.8090169943749475,
        -0.2628655560595668,
        0.0,
        0.5257311121191336,
    ], // 10
    [0.0, -1.0, 0.0, 0.0],                               // 11: South pole
];

#[cfg(test)]
mod tests {
    use super::*;

    const COS_ALPHA: f64 = 0.8506508083520399;
    const SIN_ALPHA: f64 = 0.5257311121191336;

    #[test]
    fn test_quaternions_length() {
        assert_eq!(QUATERNIONS.len(), 12);
    }

    #[test]
    fn test_quaternions_normalized() {
        for (i, q) in QUATERNIONS.iter().enumerate() {
            let magnitude = (q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]).sqrt();
            assert!(
                (magnitude - 1.0).abs() < 1e-10,
                "Quaternion {} is not normalized: magnitude = {}",
                i,
                magnitude
            );
        }
    }

    #[test]
    fn test_north_pole_identity() {
        assert_eq!(QUATERNIONS[0], [0.0, 0.0, 0.0, 1.0]);
    }

    #[test]
    fn test_south_pole() {
        assert_eq!(QUATERNIONS[11], [0.0, -1.0, 0.0, 0.0]);
    }

    #[test]
    fn test_first_ring_structure() {
        for q in QUATERNIONS.iter().take(6).skip(1) {
            // Third component should be 0 for first ring
            assert!((q[2] - 0.0).abs() < 1e-15);
            // Fourth component should be cosAlpha for first ring
            assert!((q[3] - COS_ALPHA).abs() < 1e-10);
        }
    }

    #[test]
    fn test_second_ring_structure() {
        for q in QUATERNIONS.iter().take(11).skip(6) {
            // Third component should be 0 for second ring
            assert!((q[2] - 0.0).abs() < 1e-15);
            // Fourth component should be sinAlpha for second ring
            assert!((q[3] - SIN_ALPHA).abs() < 1e-10);
        }
    }
}