com-croftsoft-core 0.14.0

A core library of highly reusable code
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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

// =============================================================================
//! - Axis-angle (used in 3D graphics)
//!
//! # Metadata
//! - Copyright: © 2008 - 2022 [`CroftSoft Inc`]
//! - Author: [`David Wallace Croft`]
//! - Rust version: 2022-10-14
//! - Rust since: 2022-10-10
//! - Java version: 2008-05-09
//! - Java since: 2008-05-09
//!
//! # History
//! - Adapted from the Java package com.croftsoft.core.math.axis
//!   - In the Java-based [`CroftSoft Core Library`]
//!
//! [`CroftSoft Core Library`]: https://www.croftsoft.com/library/code/
//! [`CroftSoft Inc`]: https://www.croftsoft.com/
//! [`David Wallace Croft`]: https://www.croftsoft.com/people/david/
// =============================================================================

use super::{matrix::structures::Matrix, quat::Quat};

#[cfg(test)]
mod test;

#[derive(Clone, Copy, Debug, PartialEq)]
pub struct AxisAngle {
  pub radians: f64,
  pub x: f64,
  pub y: f64,
  pub z: f64,
}

impl AxisAngle {
  // ---------------------------------------------------------------------------
  /// Distance from the origin
  // ---------------------------------------------------------------------------
  pub fn magnitude(&self) -> f64 {
    let x = self.x;
    let y = self.y;
    let z = self.z;
    (x * x + y * y + z * z).sqrt()
  }

  // ---------------------------------------------------------------------------
  /// Returns false if any difference magnitude is greater than the tolerance.
  ///
  /// The tolerance should be a positive number.
  // ---------------------------------------------------------------------------
  pub fn matches_closely(
    &self,
    other: &Self,
    tolerance: f64,
  ) -> bool {
    (self.radians - other.radians).abs() <= tolerance
      && (self.x - other.x).abs() <= tolerance
      && (self.y - other.y).abs() <= tolerance
      && (self.z - other.z).abs() <= tolerance
  }

  // ---------------------------------------------------------------------------
  /// Returns false if any field value of other differs from the value of self
  // ---------------------------------------------------------------------------
  pub fn matches_exactly(
    &self,
    other: &Self,
  ) -> bool {
    self.radians == other.radians
      && self.x == other.x
      && self.y == other.y
      && self.z == other.z
  }

  // ---------------------------------------------------------------------------
  /// Divides each entry by the magnitude and then returns a reference to self
  // ---------------------------------------------------------------------------
  pub fn normalize(&mut self) -> &mut Self {
    let magnitude = self.magnitude();
    self.x /= magnitude;
    self.y /= magnitude;
    self.z /= magnitude;
    self
  }
}

// Default ---------------------------------------------------------------------

impl Default for AxisAngle {
  fn default() -> Self {
    Self {
      radians: 0.0,
      x: 1.0,
      y: 0.0,
      z: 0.0,
    }
  }
}

// From ------------------------------------------------------------------------

impl From<AxisAngle> for Matrix<3, 3> {
  fn from(axis_angle: AxisAngle) -> Self {
    let AxisAngle {
      radians,
      x,
      y,
      z,
    } = axis_angle;
    let c = radians.cos();
    let s = radians.sin();
    // Lengyel, "Mathematics for 3D Game Programming & Computer Graphics",
    // Second Edition, p80, equation 3.22.
    Matrix {
      rows: [
        [
          c + (1.0 - c) * x * x,
          (1.0 - c) * x * y - s * z,
          (1.0 - c) * x * z + s * y,
        ],
        [
          (1.0 - c) * x * y + s * z,
          c + (1.0 - c) * y * y,
          (1.0 - c) * y * z - s * x,
        ],
        [
          (1.0 - c) * x * z - s * y,
          (1.0 - c) * y * z + s * x,
          c + (1.0 - c) * z * z,
        ],
      ],
    }
  }
}

impl From<AxisAngle> for Quat {
  fn from(axis_angle: AxisAngle) -> Self {
    let half_radians = axis_angle.radians / 2.0;
    let sin_half_radians = half_radians.sin();
    Quat {
      w: half_radians.cos(),
      x: sin_half_radians * axis_angle.x,
      y: sin_half_radians * axis_angle.y,
      z: sin_half_radians * axis_angle.z,
    }
  }
}