Merge pull request #951 from CesiumGS/get-up-axis-transform

Add `Transforms::getUpAxisTransform`
CesiumGS · Oct 24, 2024 · 434e51f · 434e51f
2 parents 61baa8f + e35789b
commit 434e51f
Show file tree

Hide file tree

Showing 4 changed files with 127 additions and 18 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -9,6 +9,7 @@
 ##### Additions :tada:
 
 - Added `CesiumUtility::gzip`.
+- Added `CesiumGeometry::Transforms::getUpAxisTransform` to get the transform that converts from one up axis to another.
 
 ### v0.40.1 - 2024-10-01
 

diff --git a/CesiumGeometry/include/CesiumGeometry/Transforms.h b/CesiumGeometry/include/CesiumGeometry/Transforms.h
@@ -1,5 +1,6 @@
 #pragma once
 
+#include "Axis.h"
 #include "Library.h"
 
 #include <glm/fwd.hpp>
@@ -83,6 +84,17 @@ struct CESIUMGEOMETRY_API Transforms final {
       glm::dvec3* pTranslation,
       glm::dquat* pRotation,
       glm::dvec3* pScale);
+
+  /**
+   * @brief Gets a transform that converts from one up axis to another.
+   *
+   * @param from The up axis to convert from.
+   * @param to The up axis to convert to.
+   *
+   * @returns The up axis transform.
+   */
+  static const glm::dmat4&
+  getUpAxisTransform(CesiumGeometry::Axis from, CesiumGeometry::Axis to);
 };
 
 } // namespace CesiumGeometry
diff --git a/CesiumGeometry/src/Transforms.cpp b/CesiumGeometry/src/Transforms.cpp
@@ -115,4 +115,45 @@ void Transforms::computeTranslationRotationScaleFromMatrix(
     *pTranslation = glm::dvec3(matrix[3]);
 }
 
+namespace {
+const glm::dmat4 Identity(1.0);
+}
+
+const glm::dmat4& Transforms::getUpAxisTransform(Axis from, Axis to) {
+  switch (from) {
+  case Axis::X:
+    switch (to) {
+    case Axis::X:
+      return Identity;
+    case Axis::Y:
+      return X_UP_TO_Y_UP;
+    case Axis::Z:
+      return X_UP_TO_Z_UP;
+    }
+    break;
+  case Axis::Y:
+    switch (to) {
+    case Axis::X:
+      return Y_UP_TO_X_UP;
+    case Axis::Y:
+      return Identity;
+    case Axis::Z:
+      return Y_UP_TO_Z_UP;
+    }
+    break;
+  case Axis::Z:
+    switch (to) {
+    case Axis::X:
+      return Z_UP_TO_X_UP;
+    case Axis::Y:
+      return Z_UP_TO_Y_UP;
+    case Axis::Z:
+      return Identity;
+    }
+    break;
+  }
+
+  return Identity;
+}
+
 } // namespace CesiumGeometry
diff --git a/CesiumGeometry/test/TestTransforms.cpp b/CesiumGeometry/test/TestTransforms.cpp
@@ -1,46 +1,101 @@
+#include "CesiumGeometry/Axis.h"
 #include "CesiumGeometry/Transforms.h"
 
 #include <CesiumUtility/Math.h>
 
 #include <catch2/catch.hpp>
 #include <glm/mat4x4.hpp>
 
+using namespace CesiumGeometry;
+
 TEST_CASE("Transforms convert the axes correctly") {
 
   glm::dvec4 X_AXIS{1.0, 0.0, 0.0, 0.0};
   glm::dvec4 Y_AXIS{0.0, 1.0, 0.0, 0.0};
   glm::dvec4 Z_AXIS{0.0, 0.0, 1.0, 0.0};
 
   SECTION("Y_UP_TO_Z_UP transforms  X to  X,  Y to -Z, and  Z to Y") {
-    REQUIRE(X_AXIS * CesiumGeometry::Transforms::Y_UP_TO_Z_UP == X_AXIS);
-    REQUIRE(Y_AXIS * CesiumGeometry::Transforms::Y_UP_TO_Z_UP == -Z_AXIS);
-    REQUIRE(Z_AXIS * CesiumGeometry::Transforms::Y_UP_TO_Z_UP == Y_AXIS);
+    REQUIRE(X_AXIS * Transforms::Y_UP_TO_Z_UP == X_AXIS);
+    REQUIRE(Y_AXIS * Transforms::Y_UP_TO_Z_UP == -Z_AXIS);
+    REQUIRE(Z_AXIS * Transforms::Y_UP_TO_Z_UP == Y_AXIS);
   }
   SECTION("Z_UP_TO_Y_UP transforms  X to  X,  Y to  Z, and  Z to -Y") {
-    REQUIRE(X_AXIS * CesiumGeometry::Transforms::Z_UP_TO_Y_UP == X_AXIS);
-    REQUIRE(Y_AXIS * CesiumGeometry::Transforms::Z_UP_TO_Y_UP == Z_AXIS);
-    REQUIRE(Z_AXIS * CesiumGeometry::Transforms::Z_UP_TO_Y_UP == -Y_AXIS);
+    REQUIRE(X_AXIS * Transforms::Z_UP_TO_Y_UP == X_AXIS);
+    REQUIRE(Y_AXIS * Transforms::Z_UP_TO_Y_UP == Z_AXIS);
+    REQUIRE(Z_AXIS * Transforms::Z_UP_TO_Y_UP == -Y_AXIS);
   }
 
   SECTION("X_UP_TO_Z_UP transforms  X to -Z,  Y to  Y, and  Z to  X") {
-    REQUIRE(X_AXIS * CesiumGeometry::Transforms::X_UP_TO_Z_UP == -Z_AXIS);
-    REQUIRE(Y_AXIS * CesiumGeometry::Transforms::X_UP_TO_Z_UP == Y_AXIS);
-    REQUIRE(Z_AXIS * CesiumGeometry::Transforms::X_UP_TO_Z_UP == X_AXIS);
+    REQUIRE(X_AXIS * Transforms::X_UP_TO_Z_UP == -Z_AXIS);
+    REQUIRE(Y_AXIS * Transforms::X_UP_TO_Z_UP == Y_AXIS);
+    REQUIRE(Z_AXIS * Transforms::X_UP_TO_Z_UP == X_AXIS);
   }
   SECTION("Z_UP_TO_X_UP transforms  X to  Z,  Y to  Y, and  Z to -X") {
-    REQUIRE(X_AXIS * CesiumGeometry::Transforms::Z_UP_TO_X_UP == Z_AXIS);
-    REQUIRE(Y_AXIS * CesiumGeometry::Transforms::Z_UP_TO_X_UP == Y_AXIS);
-    REQUIRE(Z_AXIS * CesiumGeometry::Transforms::Z_UP_TO_X_UP == -X_AXIS);
+    REQUIRE(X_AXIS * Transforms::Z_UP_TO_X_UP == Z_AXIS);
+    REQUIRE(Y_AXIS * Transforms::Z_UP_TO_X_UP == Y_AXIS);
+    REQUIRE(Z_AXIS * Transforms::Z_UP_TO_X_UP == -X_AXIS);
   }
 
   SECTION("X_UP_TO_Y_UP transforms  X to -Y,  Y to  X, and  Z to  Z") {
-    REQUIRE(X_AXIS * CesiumGeometry::Transforms::X_UP_TO_Y_UP == -Y_AXIS);
-    REQUIRE(Y_AXIS * CesiumGeometry::Transforms::X_UP_TO_Y_UP == X_AXIS);
-    REQUIRE(Z_AXIS * CesiumGeometry::Transforms::X_UP_TO_Y_UP == Z_AXIS);
+    REQUIRE(X_AXIS * Transforms::X_UP_TO_Y_UP == -Y_AXIS);
+    REQUIRE(Y_AXIS * Transforms::X_UP_TO_Y_UP == X_AXIS);
+    REQUIRE(Z_AXIS * Transforms::X_UP_TO_Y_UP == Z_AXIS);
   }
   SECTION("Y_UP_TO_X_UP transforms  X to  Y,  Y to -X, and  Z to  Z") {
-    REQUIRE(X_AXIS * CesiumGeometry::Transforms::Y_UP_TO_X_UP == Y_AXIS);
-    REQUIRE(Y_AXIS * CesiumGeometry::Transforms::Y_UP_TO_X_UP == -X_AXIS);
-    REQUIRE(Z_AXIS * CesiumGeometry::Transforms::Y_UP_TO_X_UP == Z_AXIS);
+    REQUIRE(X_AXIS * Transforms::Y_UP_TO_X_UP == Y_AXIS);
+    REQUIRE(Y_AXIS * Transforms::Y_UP_TO_X_UP == -X_AXIS);
+    REQUIRE(Z_AXIS * Transforms::Y_UP_TO_X_UP == Z_AXIS);
+  }
+}
+
+TEST_CASE("Gets up axis transform") {
+  const glm::dmat4 Identity(1.0);
+
+  SECTION("Gets X-up to X-up transform") {
+    CHECK(Transforms::getUpAxisTransform(Axis::X, Axis::X) == Identity);
+  }
+
+  SECTION("Gets X-up to Y-up transform") {
+    CHECK(
+        Transforms::getUpAxisTransform(Axis::X, Axis::Y) ==
+        Transforms::X_UP_TO_Y_UP);
+  }
+
+  SECTION("Gets X-up to Z-up transform") {
+    CHECK(
+        Transforms::getUpAxisTransform(Axis::X, Axis::Z) ==
+        Transforms::X_UP_TO_Z_UP);
+  }
+
+  SECTION("Gets Y-up to X-up transform") {
+    CHECK(
+        Transforms::getUpAxisTransform(Axis::Y, Axis::X) ==
+        Transforms::Y_UP_TO_X_UP);
+  }
+
+  SECTION("Gets Y-up to Y-up transform") {
+    CHECK(Transforms::getUpAxisTransform(Axis::Y, Axis::Y) == Identity);
+  }
+
+  SECTION("Gets Y-up to Z-up transform") {
+    CHECK(
+        Transforms::getUpAxisTransform(Axis::Y, Axis::Z) ==
+        Transforms::Y_UP_TO_Z_UP);
+  }
+
+  SECTION("Gets Z-up to X-up transform") {
+    CHECK(
+        Transforms::getUpAxisTransform(Axis::Z, Axis::X) ==
+        Transforms::Z_UP_TO_X_UP);
+  }
+
+  SECTION("Gets Z-up to Y-up transform") {
+    CHECK(
+        Transforms::getUpAxisTransform(Axis::Z, Axis::Y) ==
+        Transforms::Z_UP_TO_Y_UP);
+  }
+
+  SECTION("Gets Z-up to Z-up transform") {
+    CHECK(Transforms::getUpAxisTransform(Axis::Z, Axis::Z) == Identity);
   }
 }