You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
DOC: Redesign top-level README with IPF/pole-figure visual showcase
Rework README.md into a polished landing page for the 3.0 release:
- Centered title, tagline, CI/license/standard badges
- Feature list highlighting IPF color maps, IPF legends, pole figures,
the three color keys (TSL/PUCM/Nolze-Hielscher) and MTEX validation
- Visual gallery: a Ni-superalloy IPF orientation map paired with its
composite pole figure (same scan), the cubic standard triangle in all
three color keys, and a hexagonal legend
- New "MTEX Compatibility" section citing the 396/396 pole-figure
position validation (worst deviation 6.29e-8) and the NH/ipfHSVKey
color-key equivalence
- Preserved the crystallographic-class and orientation-transformation
reference tables, examples, citation; added a vcpkg/dependency note
Showcase PNG/JPG assets added under Docs/readme_images/ (generated with
the bundled render_ebsd tool). Mark image formats binary in
.gitattributes so they are never LF-normalized.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
EBSDLib is a C++ Library that can read EBSD Files from OEMs and perform basic EBSD processing such as orientation conversion and IPF Color generation. Another important aspect of the
4
-
library is to be able to convert between the seven orientation representations that
5
-
are typically used through out materials science and engineering domains.
6
-
7
-
The [DREAM.3D](https://dream3d.bluequartz.net) project and [DREAM3D-NX](https://www.dream3d.io) uses this library for all the EBSD processing.
1
+
<h1align="center">EbsdLib</h1>
2
+
3
+
<palign="center">
4
+
<b>A modern C++20 library for reading, processing, and visualizing Electron Backscatter Diffraction (EBSD) data.</b>
EbsdLib reads EBSD files from all major OEM instruments and performs the core
20
+
crystallographic processing used throughout materials science:
21
+
conversion between the seven orientation representations, Laue-class–aware
22
+
fundamental-zone reduction, **Inverse Pole Figure (IPF) coloring**,
23
+
**IPF color-key legends**, and **pole figure** generation.
24
+
25
+
It is the crystallographic engine behind the
26
+
[DREAM.3D](https://dream3d.bluequartz.net) and
27
+
[DREAM3D-NX](https://www.dream3d.io) projects.
28
+
29
+
## Features
30
+
31
+
-**Read every major OEM format** — EDAX/AMETEK (`.ang`, HDF5), Oxford Instruments (`.ctf`, `.h5oina`), and Bruker (HDF5).
32
+
-**All 32 crystallographic point groups**, dispatched through the 11 Laue classes.
33
+
-**Seven orientation representations** with direct, mathematically exact conversions between them.
34
+
-**IPF color maps** rendered directly from a scan, with three selectable color keys — **TSL** (EDAX/AMETEK), **PUCM** (Perceptual unique-color mapping), and **Nolze–Hielscher** (MTEX-compatible HSV).
35
+
-**Publication-ready IPF legends** for every Laue class, in standard or gridded styles.
36
+
-**Composite pole figures** with color-intensity rendering, RD/TD framing, and a quantitative intensity scale.
37
+
-**MTEX-validated** pole figure positions — agreement to better than 1×10⁻⁷ across all Laue classes (see below).
38
+
-**Lean dependencies** — the core requires only Eigen; HDF5 and Qt are optional, enabled when you need the file readers or GUI integration.
39
+
- A suite of **command-line tools** (`render_ebsd`, `make_ipf`, `make_pole_figure`, `generate_ipf_legends`, …) that double as worked examples.
40
+
41
+
## 🎨 IPF Color Maps & Pole Figures
42
+
43
+
A single scan, processed end-to-end — the IPF orientation map and its pole
44
+
figures, both produced by EbsdLib from the same Ni-superalloy `.ctf` file
In addition to the Orientation class there are also classes that represent
73
-
the 11 Laue classes that allow a user to perform Laue class specific calculations
74
-
including the generation of an IPF Color which is a prevalent visualization scheme within
75
-
the EBSD community. Note that each vendor has slightly different algorithms and this
76
-
library has selected to align with the AMETEK/EDAX output.
174
+
## Conventions
77
175
78
-
The folder Data/IPF_Legend has premade IPF Legends for all the Laue classes.
176
+
-**Quaternions** are organized Vector–Scalar `(X, Y, Z, W)` by default. If your
177
+
quaternions are laid out Scalar–Vector `(W, X, Y, Z)`, reorder them before use.
178
+
-**Rotations** are **passive** by convention.
79
179
80
-
## Quaternion Convention
180
+
## Dependencies
81
181
82
-
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) you will need to reorder your data before
84
-
using this library.
182
+
**Required**
85
183
86
-
## Dependent Libraries
184
+
-[Eigen](https://eigen.tuxfamily.org) 3.4
87
185
88
-
EbsdLib is dependent on:
186
+
**Optional**
89
187
90
-
+ Eigen 3.4
188
+
- HDF5 1.10.4 (only required for the HDF5-based file readers/writers)
91
189
190
+
EbsdLib uses [vcpkg](https://vcpkg.io) for dependency management and a
191
+
CMake-based build system.
92
192
93
-
## Optional Libraries
193
+
## Examples
94
194
95
-
+ HDF5 1.10.4 (HDF5 is optional only if you want the HDF5 functionality)
96
-
+ Qt5 5.15.x (minimum: Optional)
195
+
Transform an Euler angle into any of the other six representations:
97
196
98
-
## Rotation Convention
197
+
```cpp
198
+
// Note: angles are in radians
199
+
ebsdlib::EulerDType euler(0.707, 1.23, 0.45);
99
200
100
-
By convention this library uses **Passive** rotations
201
+
OrientationMatrix om = euler.toOrientationMatrix();
202
+
AxisAngle ax = euler.toAxisAngle();
203
+
Rodrigues rod = euler.toRodrigues();
204
+
Quaternion quat = euler.toQuaternion();
205
+
Homochoric ho = euler.toHomochoric();
206
+
Cubochoric cu = euler.toCubochoric();
207
+
Stereographic stereo = euler.toStereographic();
101
208
102
-
## Citations
209
+
// Any representation streams to std::ostream
210
+
std::cout << euler << std::endl;
211
+
```
103
212
104
-
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
213
+
Render a full IPF map, pole figure, and legend from a scan with the bundled CLI:
0 commit comments