Skip to content

Commit 98e8dad

Browse files
imikejacksonimikejackson
committed
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.
1 parent 4333267 commit 98e8dad

File tree

184 files changed

+9278
-10099
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

184 files changed

+9278
-10099
lines changed

‎CMakeLists.txt‎

Lines changed: 47 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,44 @@
1+
cmake_minimum_required(VERSION 3.26)
2+
13
cmake_policy(SET CMP0002 NEW)
24
cmake_policy(SET CMP0054 NEW)
35
cmake_policy(SET CMP0079 NEW)
46
cmake_policy(SET CMP0077 NEW)
7+
cmake_policy(SET CMP0080 NEW) # ``BundleUtilities`` cannot be included at configure time.
8+
9+
# resolves symlinks before collapsing ../ components.
10+
if(CMAKE_VERSION VERSION_GREATER "3.28.0")
11+
cmake_policy(SET CMP0152 NEW)
12+
endif()
13+
14+
include(${CMAKE_CURRENT_LIST_DIR}/cmake/Utility.cmake)
15+
16+
17+
# ------------------------------------------------------------------------------
18+
# is building unit tests enabled
19+
# ------------------------------------------------------------------------------
20+
option(EbsdLib_BUILD_TESTS "Enable building tests" ON)
21+
enable_vcpkg_manifest_feature(TEST_VAR EbsdLib_BUILD_TESTS FEATURE "tests")
22+
23+
# ------------------------------------------------------------------------------
24+
# are multithreading algorithms enabled
25+
# ------------------------------------------------------------------------------
26+
option(EbsdLib_ENABLE_MULTICORE "Enable multicore support" ON)
27+
enable_vcpkg_manifest_feature(TEST_VAR EbsdLib_ENABLE_MULTICORE FEATURE "parallel")
28+
29+
30+
option(EbsdLib_DISABLE_MSVC_WARNINGS ON)
31+
option(BUILD_SHARED_LIBS "Build Shared Libs" ON)
32+
33+
# Extra Variables that need to be set before all the configured files are generated.
34+
option(EbsdLib_ENABLE_HDF5 "Enable HDF5 Support in the EbsdLibProj" ON)
35+
36+
option(EbsdLib_BUILD_H5SUPPORT "Build H5Support Library" OFF)
37+
38+
39+
# set project's name
40+
project(EbsdLibProj VERSION 2.0.0)
541

6-
cmake_minimum_required(VERSION 3.14.0)
742

843
# Request C++17 standard, using new CMake variables.
944
set(CMAKE_CXX_STANDARD 17)
@@ -14,9 +49,6 @@ set(CMAKE_CXX_EXTENSIONS OFF)
1449
# Always write out the compile_commands.json file to help out things like QtCreator and VS Code
1550
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
1651

17-
# set project's name
18-
project(EbsdLibProj VERSION 1.0.41)
19-
2052
# ---------- Setup output Directories -------------------------
2153
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY
2254
${PROJECT_BINARY_DIR}/Bin
@@ -38,19 +70,13 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY
3870
"Single Directory for all static libraries."
3971
)
4072

41-
option(EbsdLib_DISABLE_MSVC_WARNINGS ON)
42-
option(BUILD_SHARED_LIBS "Build Shared Libs" ON)
43-
4473

4574
get_filename_component(EbsdLib_PARENT ${EbsdLibProj_SOURCE_DIR} DIRECTORY CACHE)
4675

76+
4777
#-------------------------------------------------------------------------------
4878
# Find the HDF5 Library as we need that.
4979
#-------------------------------------------------------------------------------
50-
# Extra Variables that need to be set before all the configured files are generated.
51-
option(EbsdLib_ENABLE_HDF5 "Enable HDF5 Support in the EbsdLibProj" ON)
52-
option(EbsdLib_BUILD_H5SUPPORT "Build H5Support Library" ON)
53-
5480
if(EbsdLib_ENABLE_HDF5)
5581
if(EbsdLib_BUILD_H5SUPPORT)
5682
if(NOT TARGET H5Support::H5Support)
@@ -119,22 +145,25 @@ if(EbsdLib_USE_GHC_FILESYSTEM)
119145
find_package(ghcFilesystem REQUIRED NAMES ghc_filesystem ghcFilesystem)
120146
endif()
121147

122-
#-------------------------------------------------------------------------------
123-
# Are we using Parallel Algorithms.
124-
#-------------------------------------------------------------------------------
125-
option(EbsdLib_USE_PARALLEL_ALGORITHMS "Enable EBSDLib to use parallel algorithms" ON)
126-
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)
148+
149+
# ------------------------------------------------------------------------------
150+
# are multithreading algorithms enabled
151+
# ------------------------------------------------------------------------------
152+
if(EbsdLib_ENABLE_MULTICORE) # If TBB already exists no need to look for it (e.g. EbsdLib is added as a subdirectory in DREAM3D)
127153
find_package(TBB CONFIG REQUIRED)
128154
get_target_property(tbb_dll_path TBB::tbb IMPORTED_LOCATION_RELEASE)
129155
get_filename_component(tbb_dll_path "${tbb_dll_path}" DIRECTORY)
130156
get_property(EbsdLib_EXTRA_LIBRARY_DIRS GLOBAL PROPERTY EbsdLib_EXTRA_LIBRARY_DIRS)
131157
set_property(GLOBAL PROPERTY EbsdLib_EXTRA_LIBRARY_DIRS ${EbsdLib_EXTRA_LIBRARY_DIRS} ${tbb_dll_path})
158+
set(EbsdLib_USE_PARALLEL_ALGORITHMS ON)
132159
endif()
133160

134161
include(${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/SourceList.cmake)
135162

136-
option(EbsdLib_ENABLE_TESTING "Enable the unit test" ON)
137-
if(EbsdLib_ENABLE_TESTING)
163+
# ------------------------------------------------------------------------------
164+
# Build Unit Test
165+
# ------------------------------------------------------------------------------
166+
if(EbsdLib_BUILD_TESTS)
138167
include(${EbsdLibProj_SOURCE_DIR}/Source/Test/CMakeLists.txt)
139168
endif()
140169

‎CMakePresets.json‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@
4343
},
4444
"VCPKG_MANIFEST_FEATURES": {
4545
"type": "STRING",
46-
"value": "parallel"
46+
"value": "parallel;tests"
4747
},
4848
"EbsdLib_ENABLE_HDF5": {
4949
"type": "BOOL",
@@ -53,6 +53,14 @@
5353
"type": "BOOL",
5454
"value": "OFF"
5555
},
56+
"EbsdLib_BUILD_TESTS": {
57+
"type": "BOOL",
58+
"value": "ON"
59+
},
60+
"EbsdLib_ENABLE_MULTICORE": {
61+
"type": "BOOL",
62+
"value": "ON"
63+
},
5664
"BUILDNAME": {
5765
"type": "STRING",
5866
"value": "$env{PRESET_NAME}-$env{BUILD_BUILDNUMBER}-PR$env{SYSTEM_PULLREQUEST_PULLREQUESTNUMBER}"

‎README.md‎

Lines changed: 61 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ are typically used through out materials science and engineering domains.
66

77
The [DREAM.3D](https://dream3d.bluequartz.net) project and [DREAM3D-NX](https://www.dream3d.io) uses this library for all the EBSD processing.
88

9-
## Supported EBSD OEM Data FilesDirectionalStatsTest
9+
## Supported EBSD OEM Data Files
1010

1111
+ EDAX/AMETEK: .ang and HDF5 based file formats
1212
+ Oxford Instruments: .ctf and .h5oina file formats
@@ -16,43 +16,43 @@ Please have a look at the unit tests for examples on using the various readers.
1616

1717
## Crystallographic Classes
1818

19-
| # | Point Group (H–M) | Rotation Point Group | Space Group No(s). | Schoenflies | Crystal system | Laue class | Laue Ops |
20-
|---:|-------------------|----------------------|--------------------|---------------|----------------|-------------|------------------|
21-
| 1 | 1 | 1 | 1 | C₁ | Triclinic | (\bar{1}) | TriclinicOps |
22-
| 2 | (\bar{1}) | 1 | 2 | C(_i) | Triclinic | (\bar{1}) | |
23-
| 3 | 2 | 2 | 3–5 | C₂ | Monoclinic | 2/m | |
24-
| 4 | m | 1 | 6–9 | C(_s) | Monoclinic | 2/m | |
25-
| 5 | 2/m | 2 | 10–15 | C(_{2h}) | Monoclinic | 2/m | MonoclinicOps |
26-
| 6 | 222 | 222 | 16–24 | D₂ | Orthorhombic | mmm | |
27-
| 7 | mm2 | 2 | 25–46 | C(_{2v}) | Orthorhombic | mmm | |
28-
| 8 | mmm | 222 | 47–74 | D(_{2h}) | Orthorhombic | mmm | OrthorhombicOps |
29-
| 9 | 4 | 4 | 75–80 | C₄ | Tetragonal | 4/m | |
30-
| 10 | (\bar{4}) | 2 | 81–82 | S₄ | Tetragonal | 4/m | |
31-
| 11 | 4/m | 4 | 83–88 | C(_{4h}) | Tetragonal | 4/m | TetragonalLowOps |
32-
| 12 | 422 | 422 | 89–98 | D₄ | Tetragonal | 4/mmm | |
33-
| 13 | 4mm | 4 | 99–110 | C(_{4v}) | Tetragonal | 4/mmm | |
34-
| 14 | (\bar{4}2m) | 222 | 111–122 | D(_{2d}) | Tetragonal | 4/mmm | |
35-
| 15 | 4/mmm | 422 | 123–142 | D(_{4h}) | Tetragonal | 4/mmm | TetragonalOps |
36-
| 16 | 3 | 3 | 143–146 | C₃ | Trigonal | (\bar{3}) | |
37-
| 17 | (\bar{3}) | 3 | 147–148 | C(_{3i}) (S₆) | Trigonal | (\bar{3}) | TrigonalLowOps |
38-
| 18 | 32 | 32 | 149–155 | D₃ | Trigonal | (\bar{3}m) | |
39-
| 19 | 3m | 3 | 156–161 | C(_{3v}) | Trigonal | (\bar{3}m) | |
40-
| 20 | (\bar{3}m) | 32 | 162–167 | D(_{3d}) | Trigonal | (\bar{3}m) | TrigonalOps |
41-
| 21 | 6 | 6 | 168–173 | C₆ | Hexagonal | 6/m | |
42-
| 22 | (\bar{6}) | 3 | 174 | C(_{3h}) | Hexagonal | 6/m | |
43-
| 23 | 6/m | 6 | 175–176 | C(_{6h}) | Hexagonal | 6/m | HexagonalLowOps |
44-
| 24 | 622 | 622 | 177–182 | D₆ | Hexagonal | 6/mmm | |
45-
| 25 | 6mm | 6 | 183–186 | C(_{6v}) | Hexagonal | 6/mmm | |
46-
| 26 | (\bar{6}m2) | 32 | 187–190 | D(_{3h}) | Hexagonal | 6/mmm | |
47-
| 27 | 6/mmm | 622 | 191–194 | D(_{6h}) | Hexagonal | 6/mmm | HexagonalOps |
48-
| 28 | 23 | 23 | 195–199 | T | Cubic | m(\bar{3}) | |
49-
| 29 | m(\bar{3}) | 23 | 200–206 | T(_h) | Cubic | m(\bar{3}) | CubicLowOps |
50-
| 30 | 432 | 432 | 207–214 | O | Cubic | m(\bar{3})m | |
51-
| 31 | (\bar{4}3m) | 23 | 215–220 | T(_d) | Cubic | m(\bar{3})m | |
52-
| 32 | m(\bar{3})m | 432 | 221–230 | O(_h) | Cubic | m(\bar{3})m | CubicOps |
53-
54-
55-
## Orientation TransformationsDirectionalStatsTest
19+
| Point Group | (H–M) | Rotation Point Group | Space Group No(s). | Schoenflies | Crystal system | Laue class | Laue Ops |
20+
|-------------|-------------|----------------------|--------------------|---------------|----------------|-------------|------------------|
21+
| 1 | 1 | 1 | 1 | C₁ | Triclinic | (\bar{1}) | TriclinicOps |
22+
| 2 | (\bar{1}) | 1 | 2 | C(_i) | Triclinic | (\bar{1}) | |
23+
| 3 | 2 | 2 | 3–5 | C₂ | Monoclinic | 2/m | |
24+
| 4 | m | 1 | 6–9 | C(_s) | Monoclinic | 2/m | |
25+
| 5 | 2/m | 2 | 10–15 | C(_{2h}) | Monoclinic | 2/m | MonoclinicOps |
26+
| 6 | 222 | 222 | 16–24 | D₂ | Orthorhombic | mmm | |
27+
| 7 | mm2 | 2 | 25–46 | C(_{2v}) | Orthorhombic | mmm | |
28+
| 8 | mmm | 222 | 47–74 | D(_{2h}) | Orthorhombic | mmm | OrthorhombicOps |
29+
| 9 | 4 | 4 | 75–80 | C₄ | Tetragonal | 4/m | |
30+
| 10 | (\bar{4}) | 2 | 81–82 | S₄ | Tetragonal | 4/m | |
31+
| 11 | 4/m | 4 | 83–88 | C(_{4h}) | Tetragonal | 4/m | TetragonalLowOps |
32+
| 12 | 422 | 422 | 89–98 | D₄ | Tetragonal | 4/mmm | |
33+
| 13 | 4mm | 4 | 99–110 | C(_{4v}) | Tetragonal | 4/mmm | |
34+
| 14 | (\bar{4}2m) | 222 | 111–122 | D(_{2d}) | Tetragonal | 4/mmm | |
35+
| 15 | 4/mmm | 422 | 123–142 | D(_{4h}) | Tetragonal | 4/mmm | TetragonalOps |
36+
| 16 | 3 | 3 | 143–146 | C₃ | Trigonal | (\bar{3}) | |
37+
| 17 | (\bar{3}) | 3 | 147–148 | C(_{3i}) (S₆) | Trigonal | (\bar{3}) | TrigonalLowOps |
38+
| 18 | 32 | 32 | 149–155 | D₃ | Trigonal | (\bar{3}m) | |
39+
| 19 | 3m | 3 | 156–161 | C(_{3v}) | Trigonal | (\bar{3}m) | |
40+
| 20 | (\bar{3}m) | 32 | 162–167 | D(_{3d}) | Trigonal | (\bar{3}m) | TrigonalOps |
41+
| 21 | 6 | 6 | 168–173 | C₆ | Hexagonal | 6/m | |
42+
| 22 | (\bar{6}) | 3 | 174 | C(_{3h}) | Hexagonal | 6/m | |
43+
| 23 | 6/m | 6 | 175–176 | C(_{6h}) | Hexagonal | 6/m | HexagonalLowOps |
44+
| 24 | 622 | 622 | 177–182 | D₆ | Hexagonal | 6/mmm | |
45+
| 25 | 6mm | 6 | 183–186 | C(_{6v}) | Hexagonal | 6/mmm | |
46+
| 26 | (\bar{6}m2) | 32 | 187–190 | D(_{3h}) | Hexagonal | 6/mmm | |
47+
| 27 | 6/mmm | 622 | 191–194 | D(_{6h}) | Hexagonal | 6/mmm | HexagonalOps |
48+
| 28 | 23 | 23 | 195–199 | T | Cubic | m(\bar{3}) | |
49+
| 29 | m(\bar{3}) | 23 | 200–206 | T(_h) | Cubic | m(\bar{3}) | CubicLowOps |
50+
| 30 | 432 | 432 | 207–214 | O | Cubic | m(\bar{3})m | |
51+
| 31 | (\bar{4}3m) | 23 | 215–220 | T(_d) | Cubic | m(\bar{3})m | |
52+
| 32 | m(\bar{3})m | 432 | 221–230 | O(_h) | Cubic | m(\bar{3})m | CubicOps |
53+
54+
55+
## Orientation Transformations
5656

5757
| From/To | Euler | Orientation Matrix | Axis Angle | Rodrigues | Quaternion | Homochoric | Cubochoric | Stereographic |
5858
|--------------------|-------|--------------------|------------|-----------|------------|------------|------------|---------------|
@@ -69,58 +69,58 @@ Please have a look at the unit tests for examples on using the various readers.
6969
lower case letters denote the conversion uses other more basic conversions. For
7070
example to go from Euler->Homochoric the conversion process calls the Euler->AxisAngle->OrientationMatrix->Homochoric functions.
7171

72-
In addition to the OrientationTransformation class there are also classes that represent
72+
In addition to the Orientation class there are also classes that represent
7373
the 11 Laue classes that allow a user to perform Laue class specific calculations
7474
including the generation of an IPF Color which is a prevalent visualization scheme within
7575
the EBSD community. Note that each vendor has slightly different algorithms and this
7676
library has selected to align with the AMETEK/EDAX output.
7777

7878
The folder Data/IPF_Legend has premade IPF Legends for all the Laue classes.
7979

80-
## Quaternion ConventionDirectionalStatsTest
80+
## Quaternion Convention
8181

8282
Please also note that by default EbsdLib organizes Quaternions as Vector-Scalar (X,Y,Z,W). If your quaternions
83-
are laid out as Scalar-Vector (w,x,y,z) there is an extra argument to some functions that you
84-
can set to allow the orientation transformations to accept this layout.
83+
are laid out as Scalar-Vector (w,x,y,z) you will need to reorder your data before
84+
using this library.
8585

86-
## Dependent LibrariesDirectionalStatsTest
86+
## Dependent Libraries
8787

8888
EbsdLib is dependent on:
8989

9090
+ Eigen 3.4
9191

92+
9293
## Optional Libraries
9394

9495
+ HDF5 1.10.4 (HDF5 is optional only if you want the HDF5 functionality)
9596
+ Qt5 5.15.x (minimum: Optional)
9697

97-
## Rotation ConventionDirectionalStatsTest
98+
## Rotation Convention
9899

99100
By convention this library uses **Passive** rotations
100101

101-
## CitationsDirectionalStatsTest
102+
## Citations
102103

103104
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
104105

105106
[DOI: https://doi.org/10.1088/0965-0393/23/8/083501](https://doi.org/10.1088/0965-0393/23/8/083501)
106107

107-
## ExamplesDirectionalStatsTest
108-
109-
If you want to transform an Euler angle into a Quaternion the following works:
110-
111-
Quaternion<float> quat = OrientationTransformation::eu2qu(Orientation<float>(33.0f, 10.0f, 0.0f));
108+
## Examples
112109

113-
If you have a *lot* of angles to transform the **Orienation** class can wrap a pointer instead at which point
114-
you can loop over the array of angles. There is also the **OrientationConverter** class that can
115-
mass transform from one representation into another.
110+
If you want to transform an Euler angle into any other representation the following works:
116111

117-
Reading from an AMETEK .ang file is straightforward:
112+
```
113+
// Note use of Radians for angles
114+
ebsdlib::EulerDType euler(0.707, 1.23, 0.45);
115+
OrientationMatrix om = euler.toOrientationMatrix();
116+
AxisAngle ax = euler.toAxisAngle();
117+
Rodrigues rod = euler.toRodrigues();
118+
Quaternion quat = euler.toQuaternion();
119+
Homochoric ho = euler.toHomochoric();
120+
Cubochoric cu = euler.toCubochoric();
121+
Stereographic stereo = euler.toStereographic();
118122
119-
AngReader reader;
120-
reader.setFileName(std::string("/path/to/ebsd_scan.ang"));
121-
int32_t err = reader.readFile();
122-
// All of the data from the .ang file is now in memory. You can access it through the pointers
123-
size_t numElements = reader.getNumberOfElements();
124-
float* ptr = reader.getPhi1Pointer();
125-
// The reader will clean up the memory so either tell the reader to Not clean up the pointer or keep the reader in scope.
123+
// To print out any representation, just use the C++ std::out or std::ostream
124+
std::cout << euler << std::endl;
126125
126+
```

0 commit comments

Comments
 (0)