ENH: Rewrite Orientation Class to make it easier to convert between representations (#34)

* ENH: Rewrite Orientation Class to make it easier to convert between representations
* Update Namespace to 'ebsdlib'

These updates represent a major API change and thus the version bump to 2.0.0.

Author: imikejackson

CMakeLists.txt

@@ -1,9 +1,44 @@
+cmake_minimum_required(VERSION 3.26)
+
 cmake_policy(SET CMP0002 NEW)
 cmake_policy(SET CMP0054 NEW)
 cmake_policy(SET CMP0079 NEW)
 cmake_policy(SET CMP0077 NEW)
+cmake_policy(SET CMP0080 NEW) # ``BundleUtilities`` cannot be included at configure time.
+
+# resolves symlinks before collapsing ../ components.
+if(CMAKE_VERSION VERSION_GREATER "3.28.0")
+  cmake_policy(SET CMP0152 NEW)
+endif()
+
+include(${CMAKE_CURRENT_LIST_DIR}/cmake/Utility.cmake)
+
+
+# ------------------------------------------------------------------------------
+# is building unit tests enabled
+# ------------------------------------------------------------------------------
+option(EbsdLib_BUILD_TESTS "Enable building tests" ON)
+enable_vcpkg_manifest_feature(TEST_VAR EbsdLib_BUILD_TESTS FEATURE "tests")
+
+# ------------------------------------------------------------------------------
+# are multithreading algorithms enabled
+# ------------------------------------------------------------------------------
+option(EbsdLib_ENABLE_MULTICORE "Enable multicore support" ON)
+enable_vcpkg_manifest_feature(TEST_VAR EbsdLib_ENABLE_MULTICORE FEATURE "parallel")
+
+
+option(EbsdLib_DISABLE_MSVC_WARNINGS ON)
+option(BUILD_SHARED_LIBS "Build Shared Libs" ON)
+
+# Extra Variables that need to be set before all the configured files are generated.
+option(EbsdLib_ENABLE_HDF5 "Enable HDF5 Support in the EbsdLibProj" ON)
+
+option(EbsdLib_BUILD_H5SUPPORT "Build H5Support Library" OFF)
+
+
+# set project's name
+project(EbsdLibProj VERSION 2.0.0)
 
-cmake_minimum_required(VERSION 3.14.0)
 
 # Request C++17 standard, using new CMake variables.
 set(CMAKE_CXX_STANDARD 17)
@@ -14,9 +49,6 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 # Always write out the compile_commands.json file to help out things like QtCreator and VS Code
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
-# set project's name
-project(EbsdLibProj VERSION 1.0.41)
-
 # ---------- Setup output Directories -------------------------
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY
 	${PROJECT_BINARY_DIR}/Bin
@@ -38,19 +70,13 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY
 	"Single Directory for all static libraries."
 )
 
-option(EbsdLib_DISABLE_MSVC_WARNINGS ON)
-option(BUILD_SHARED_LIBS "Build Shared Libs" ON)
-
 
 get_filename_component(EbsdLib_PARENT ${EbsdLibProj_SOURCE_DIR} DIRECTORY CACHE)
 
+
 #-------------------------------------------------------------------------------
 # Find the HDF5 Library as we need that.
 #-------------------------------------------------------------------------------
-# Extra Variables that need to be set before all the configured files are generated.
-option(EbsdLib_ENABLE_HDF5 "Enable HDF5 Support in the EbsdLibProj" ON)
-option(EbsdLib_BUILD_H5SUPPORT "Build H5Support Library" ON)
-
 if(EbsdLib_ENABLE_HDF5)
   if(EbsdLib_BUILD_H5SUPPORT)
     if(NOT TARGET H5Support::H5Support)
@@ -119,22 +145,25 @@ if(EbsdLib_USE_GHC_FILESYSTEM)
   find_package(ghcFilesystem REQUIRED NAMES ghc_filesystem ghcFilesystem)
 endif()
 
-#-------------------------------------------------------------------------------
-# Are we using Parallel Algorithms.
-#-------------------------------------------------------------------------------
-option(EbsdLib_USE_PARALLEL_ALGORITHMS "Enable EBSDLib to use parallel algorithms" ON)
-if(EbsdLib_USE_PARALLEL_ALGORITHMS)  # If TBB already exists no need to look for it (e.g. EbsdLib is added as a subdirectory in DREAM3D)
+
+# ------------------------------------------------------------------------------
+# are multithreading algorithms enabled
+# ------------------------------------------------------------------------------
+if(EbsdLib_ENABLE_MULTICORE)  # If TBB already exists no need to look for it (e.g. EbsdLib is added as a subdirectory in DREAM3D)
   find_package(TBB CONFIG REQUIRED)
   get_target_property(tbb_dll_path TBB::tbb IMPORTED_LOCATION_RELEASE)
   get_filename_component(tbb_dll_path "${tbb_dll_path}" DIRECTORY)
   get_property(EbsdLib_EXTRA_LIBRARY_DIRS GLOBAL PROPERTY EbsdLib_EXTRA_LIBRARY_DIRS)
   set_property(GLOBAL PROPERTY EbsdLib_EXTRA_LIBRARY_DIRS ${EbsdLib_EXTRA_LIBRARY_DIRS} ${tbb_dll_path})
+  set(EbsdLib_USE_PARALLEL_ALGORITHMS ON)
 endif()
 
 include(${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/SourceList.cmake)
 
-option(EbsdLib_ENABLE_TESTING "Enable the unit test" ON)
-if(EbsdLib_ENABLE_TESTING)
+# ------------------------------------------------------------------------------
+# Build Unit Test
+# ------------------------------------------------------------------------------
+if(EbsdLib_BUILD_TESTS)
 	include(${EbsdLibProj_SOURCE_DIR}/Source/Test/CMakeLists.txt)
 endif()
 

CMakePresets.json

@@ -43,7 +43,7 @@
             },
             "VCPKG_MANIFEST_FEATURES": {
                 "type": "STRING",
-                "value": "parallel"
+                "value": "parallel;tests"
             },
             "EbsdLib_ENABLE_HDF5": {
                 "type": "BOOL",
@@ -53,6 +53,14 @@
                 "type": "BOOL",
                 "value": "OFF"
             },
+            "EbsdLib_BUILD_TESTS": {
+              "type": "BOOL",
+              "value": "ON"
+            },
+            "EbsdLib_ENABLE_MULTICORE": {
+              "type": "BOOL",
+              "value": "ON"
+            },
             "BUILDNAME": {
               "type": "STRING",
               "value": "$env{PRESET_NAME}-$env{BUILD_BUILDNUMBER}-PR$env{SYSTEM_PULLREQUEST_PULLREQUESTNUMBER}"

README.md

@@ -6,7 +6,7 @@ are typically used through out materials science and engineering domains.
 
 The [DREAM.3D](https://dream3d.bluequartz.net) project and [DREAM3D-NX](https://www.dream3d.io) uses this library for all the EBSD processing.
 
-## Supported EBSD OEM Data FilesDirectionalStatsTest
+## Supported EBSD OEM Data Files
 
 + EDAX/AMETEK: .ang and HDF5 based file formats
 + Oxford Instruments: .ctf and .h5oina file formats
@@ -16,8 +16,8 @@ Please have a look at the unit tests for examples on using the various readers.
 
 ## Crystallographic Classes
 
-|  # | Point Group (H–M) | Rotation Point Group | Space Group No(s). | Schoenflies   | Crystal system | Laue class  | Laue Ops         |
-|---:|-------------------|----------------------|--------------------|---------------|----------------|-------------|------------------|
+|  Point Group | (H–M) | Rotation Point Group | Space Group No(s). | Schoenflies   | Crystal system | Laue class  | Laue Ops |
+|----------------------|----------------------|--------------------|---------------|----------------|-------------|------------------|
 |  1 | 1                 | 1                    | 1                  | C₁            | Triclinic      | (\bar{1})   | TriclinicOps     |
 |  2 | (\bar{1})         | 1                    | 2                  | C(_i)         | Triclinic      | (\bar{1})   |                  |
 |  3 | 2                 | 2                    | 3–5                | C₂            | Monoclinic     | 2/m         |                  |
@@ -52,7 +52,7 @@ Please have a look at the unit tests for examples on using the various readers.
 | 32 | m(\bar{3})m       | 432                  | 221–230            | O(_h)         | Cubic          | m(\bar{3})m | CubicOps         |
 
 
-## Orientation TransformationsDirectionalStatsTest
+## Orientation Transformations
 
 | From/To            | Euler | Orientation Matrix | Axis Angle | Rodrigues | Quaternion | Homochoric | Cubochoric | Stereographic |
 |--------------------|-------|--------------------|------------|-----------|------------|------------|------------|---------------|
@@ -69,58 +69,58 @@ Please have a look at the unit tests for examples on using the various readers.
 lower case letters denote the conversion uses other more basic conversions. For
 example to go from Euler->Homochoric the conversion process calls the Euler->AxisAngle->OrientationMatrix->Homochoric functions.
 
-In addition to the OrientationTransformation class there are also classes that represent
+In addition to the Orientation class there are also classes that represent
 the 11 Laue classes that allow a user to perform Laue class specific calculations
 including the generation of an IPF Color which is a prevalent visualization scheme within
 the EBSD community. Note that each vendor has slightly different algorithms and this
 library has selected to align with the AMETEK/EDAX output.
 
 The folder Data/IPF_Legend has premade IPF Legends for all the Laue classes.
 
-## Quaternion ConventionDirectionalStatsTest
+## Quaternion Convention
 
 Please also note that by default EbsdLib organizes Quaternions as Vector-Scalar (X,Y,Z,W). If your quaternions
-are laid out as Scalar-Vector (w,x,y,z) there is an extra argument to some functions that you
-can set to allow the orientation transformations to accept this layout.
+are laid out as Scalar-Vector (w,x,y,z) you will need to reorder your data before
+using this library.
 
-## Dependent LibrariesDirectionalStatsTest
+## Dependent Libraries
 
 EbsdLib is dependent on:
 
 + Eigen 3.4
 
+
 ## Optional Libraries
 
 + HDF5 1.10.4 (HDF5 is optional only if you want the HDF5 functionality)
 + Qt5 5.15.x (minimum: Optional)
 
-## Rotation ConventionDirectionalStatsTest
+## Rotation Convention
 
 By convention this library uses **Passive** rotations
 
-## CitationsDirectionalStatsTest
+## Citations
 
 D Rowenhorst, A D Rollett, G S Rohrer, M Groeber, M Jackson, P J Konijnenberg and M De Graef  _et al_ 2015 _Modelling Simul. Mater. Sci. Eng._ **23** 083501
 
 [DOI: https://doi.org/10.1088/0965-0393/23/8/083501](https://doi.org/10.1088/0965-0393/23/8/083501)
 
-## ExamplesDirectionalStatsTest
-
-If you want to transform an Euler angle into a Quaternion the following works:
-
-        Quaternion<float> quat = OrientationTransformation::eu2qu(Orientation<float>(33.0f, 10.0f, 0.0f));
+## Examples
 
-If you have a *lot* of angles to transform the **Orienation** class can wrap a pointer instead at which point
-you can loop over the array of angles. There is also the **OrientationConverter** class that can 
-mass transform from one representation into another.
+If you want to transform an Euler angle into any other representation the following works:
 
-Reading from an AMETEK .ang file is straightforward:
+```
+// Note use of Radians for angles
+ebsdlib::EulerDType euler(0.707, 1.23, 0.45);
+OrientationMatrix om = euler.toOrientationMatrix();
+AxisAngle ax = euler.toAxisAngle();
+Rodrigues rod = euler.toRodrigues();
+Quaternion quat = euler.toQuaternion();
+Homochoric ho = euler.toHomochoric();
+Cubochoric cu = euler.toCubochoric();
+Stereographic stereo = euler.toStereographic();
 
-    AngReader reader;
-    reader.setFileName(std::string("/path/to/ebsd_scan.ang"));
-    int32_t err = reader.readFile();
-    // All of the data from the .ang file is now in memory. You can access it through the pointers
-    size_t numElements = reader.getNumberOfElements();
-    float* ptr = reader.getPhi1Pointer();
-    // The reader will clean up the memory so either tell the reader to Not clean up the pointer or keep the reader in scope.
+// To print out any representation, just use the C++ std::out or std::ostream
+std::cout << euler << std::endl;
 
+```

Source/Apps/ConvertOrientations.cpp

@@ -9,9 +9,11 @@
 #include "EbsdLib/OrientationMath/OrientationConverter.hpp"
 #include "EbsdLib/Utilities/EbsdStringUtils.hpp"
 
+using namespace ebsdlib;
+
 using EbsdDoubleArrayType = EbsdDataArray<double>;
 using EbsdDoubleArrayPointerType = EbsdDoubleArrayType::Pointer;
-using OCType = OrientationConverter<EbsdLib::DoubleArrayType, float>;
+using OCType = OrientationConverter<ebsdlib::DoubleArrayType, float>;
 
 // -----------------------------------------------------------------------------
 template <typename T>
@@ -30,7 +32,7 @@ std::shared_ptr<EbsdDataArray<T>> generateRepresentation(int32_t inputType, int3
   converters[5] = HomochoricConverter<EbsdDataArray<T>, T>::New();
   converters[6] = CubochoricConverter<EbsdDataArray<T>, T>::New();
 
-  std::vector<OrientationRepresentation::Type> ocTypes = OCType::GetOrientationTypes();
+  std::vector<ebsdlib::orientations::Type> ocTypes = OCType::GetOrientationTypes();
 
   converters[inputType]->setInputData(inputOrientations);
   converters[inputType]->convertRepresentationTo(ocTypes[outputType]);

Source/Apps/ParseAztecProject.cpp

@@ -4,6 +4,8 @@
 
 #include <iostream>
 
+using namespace ebsdlib;
+
 namespace detail
 {
 // const std::string k_CprPath = "/Volumes/OWC_Express_1M2/DREAM3D_Troubleshoot_Data/Benjamin_Layer1/Layer1.cpr";

Source/Apps/eq_orientations.cpp

@@ -6,14 +6,13 @@
 #include <string>
 #include <vector>
 
-#include "EbsdLib/Core/OrientationTransformation.hpp"
-#include "EbsdLib/Core/Quaternion.hpp"
 #include "EbsdLib/EbsdLib.h"
 #include "EbsdLib/LaueOps/LaueOps.h"
+#include "EbsdLib/Orientation/Quaternion.hpp"
 #include "EbsdLib/OrientationMath/OrientationConverter.hpp"
 #include "EbsdLib/Utilities/EbsdStringUtils.hpp"
 
-#include "Test/TestPrintFunctions.h"
+using namespace ebsdlib;
 
 bool quaternionsAreClose(const QuatD& q1, const QuatD& q2, double tolerance = 1e-6)
 {

Source/Apps/gen_sym_code.cpp

@@ -1,11 +1,11 @@
 
 #include "EbsdLib/Core/EbsdLibConstants.h"
 
-#include "EbsdLib/Core/OrientationTransformation.hpp"
 #include "EbsdLib/LaueOps/LaueOps.h"
 #include "EbsdLib/Math/EbsdLibMath.h"
 #include "EbsdLib/Math/Matrix3X1.hpp"
 #include "EbsdLib/Math/Matrix3X3.hpp"
+#include "EbsdLib/Orientation/Quaternion.hpp"
 
 #include <cmath>
 #include <fstream>
@@ -16,6 +16,8 @@
 #include <string>
 #include <vector>
 
+using namespace ebsdlib;
+
 const double sq22 = 0.7071067811865475244; // sqrt(2)/2
 static double sq32 = std::sqrt(3.0) / 2.0;
 
@@ -151,7 +153,7 @@ std::vector<QuatD> InitRotationPointGroup(int rotPointGroup)
   return sym_ops;
 }
 
-void Print3x3(const OrientationD& m)
+void Print3x3(const OrientationMatrixDType& m)
 {
   std::cout << std::fixed;
   std::cout << std::setprecision(16);
@@ -175,7 +177,7 @@ void PrintQuat(const QuatD& q, bool sv)
   }
 }
 
-void PrintRod(const OrientationD& q)
+void PrintRod(const RodriguesDType& q)
 {
   std::cout << std::fixed;
   std::cout << std::setprecision(16);
@@ -214,10 +216,10 @@ int main(int argc, char* argv[])
     }
     std::cout << "};\n\n";
 
-    std::cout << "static const std::vector<OrientationD> RodSym = {\n";
+    std::cout << "static const std::vector<RodriguesDType> RodSym = {\n";
     for(const auto& symOp : symOPs)
     {
-      auto ro = OrientationTransformation::qu2ro<QuatD, OrientationD>(symOp);
+      auto ro = QuaternionDType(symOp).toRodrigues();
       PrintRod(ro);
       std::cout << ",\n";
     }
@@ -226,7 +228,7 @@ int main(int argc, char* argv[])
     std::cout << "static const double MatSym[k_SymOpsCount][3][3] = {\n";
     for(const auto& symOp : symOPs)
     {
-      auto om = OrientationTransformation::qu2om<QuatD, OrientationD>(symOp);
+      auto om = QuaternionDType(symOp).toOrientationMatrix();
       Print3x3(om);
       std::cout << "    \n";
     }
@@ -235,6 +237,4 @@ int main(int argc, char* argv[])
   }
 
   return -1;
-
-  return 0;
 }