chore(lambda-rs): Update math API to return errors instead of panicking

Author: vmarcella

crates/lambda-rs/examples/reflective_room.rs

@@ -317,7 +317,8 @@ impl Component<ComponentResult, String> for ReflectiveRoomExample {
       lambda::math::matrix::identity_matrix(4, 4),
       [1.0, 0.0, 0.0],
       -self.camera_pitch_turns,
-    );
+    )
+    .expect("rotation axis must be a unit axis vector");
     let view = rot_x.multiply(&compute_view_matrix(camera.position));
     let projection = compute_perspective_projection(
       camera.field_of_view_in_turns,
@@ -360,7 +361,8 @@ impl Component<ComponentResult, String> for ReflectiveRoomExample {
       model_floor,
       [1.0, 0.0, 0.0],
       self.floor_tilt_turns,
-    );
+    )
+    .expect("rotation axis must be a unit axis vector");
     let mvp_floor = projection.multiply(&view).multiply(&model_floor);
 
     let viewport = ViewportBuilder::new().build(self.width, self.height);

crates/lambda-rs/examples/textured_cube.rs

@@ -411,12 +411,14 @@ impl Component<ComponentResult, String> for TexturedCubeExample {
       model,
       [0.0, 1.0, 0.0],
       angle_y_turns,
-    );
+    )
+    .expect("rotation axis must be a unit axis vector");
     model = lambda::math::matrix::rotate_matrix(
       model,
       [1.0, 0.0, 0.0],
       angle_x_turns,
-    );
+    )
+    .expect("rotation axis must be a unit axis vector");
 
     let view = compute_view_matrix(camera.position);
     let projection = compute_perspective_projection(

crates/lambda-rs/src/math/error.rs

@@ -0,0 +1,65 @@
+//! Math error types returned from fallible operations.
+
+use std::fmt;
+
+/// Errors returned by fallible math operations in `lambda-rs`.
+#[derive(Debug, Clone, PartialEq)]
+pub enum MathError {
+  /// Cross product requires exactly 3 dimensions.
+  CrossProductDimension { actual: usize },
+  /// Cross product requires both vectors to have the same dimension.
+  MismatchedVectorDimensions { left: usize, right: usize },
+  /// Rotation axis must be a unit axis vector (one of `[1,0,0]`, `[0,1,0]`,
+  /// `[0,0,1]`). A zero axis (`[0,0,0]`) is treated as "no rotation".
+  InvalidRotationAxis { axis: [f32; 3] },
+  /// Rotation requires a 4x4 matrix.
+  InvalidRotationMatrixSize { rows: usize, cols: usize },
+  /// Determinant requires a square matrix.
+  NonSquareMatrix { rows: usize, cols: usize },
+  /// Determinant cannot be computed for an empty matrix.
+  EmptyMatrix,
+  /// Cannot normalize a zero-length vector.
+  ZeroLengthVector,
+}
+
+impl fmt::Display for MathError {
+  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    match self {
+      MathError::CrossProductDimension { actual } => {
+        return write!(f, "Cross product requires 3D vectors, got {}D", actual);
+      }
+      MathError::MismatchedVectorDimensions { left, right } => {
+        return write!(
+          f,
+          "Vectors must have matching dimensions (left {}D, right {}D)",
+          left, right
+        );
+      }
+      MathError::InvalidRotationAxis { axis } => {
+        return write!(f, "Rotation axis {:?} is not a unit axis vector", axis);
+      }
+      MathError::InvalidRotationMatrixSize { rows, cols } => {
+        return write!(
+          f,
+          "Rotation requires a 4x4 matrix, got {}x{}",
+          rows, cols
+        );
+      }
+      MathError::NonSquareMatrix { rows, cols } => {
+        return write!(
+          f,
+          "Determinant requires square matrix, got {}x{}",
+          rows, cols
+        );
+      }
+      MathError::EmptyMatrix => {
+        return write!(f, "Determinant requires a non-empty matrix");
+      }
+      MathError::ZeroLengthVector => {
+        return write!(f, "Cannot normalize a zero-length vector");
+      }
+    }
+  }
+}
+
+impl std::error::Error for MathError {}