IPF Visualization and Orientation Reference Frames in DAMASK

[LeoDanninger]

Dear colleagues,

I would like to ask for your help in clarifying some aspects of IPF visualization and orientation reference frames in DAMASK. I’ve been focusing on how DAMASK handles crystallographic orientations and texture evolution, particularly in terms of visualization.

I came across two different ways to generate the information about inverse pole figures (IPFs):

The example on initial IPFs:
https://damask-multiphysics.org/documentation/examples/initial_IPF.html

The add_IPF_color method in the post-processing tools:
https://damask-multiphysics.org/documentation/processing_tools/post-processing.html#damask.Result.add_IPF_color

If I understand correctly, both approaches produce similar visualizations (color-coded according to orientation), with the main difference being that the first is applied during preprocessing and the second during postprocessing. Is this interpretation correct?

Additionally, I’m a bit confused about how crystallographic directions like [100] relate to what is shown in ParaView. In a cubic system, can we assume that the [100] direction aligns with the x-axis of the ParaView coordinate system? Or does DAMASK apply some transformation before exporting the data? In essence, my question is: what is the relationship between the "Lab frame" orientation and a specific crystallographic direction?

While exploring the DAMASK documentation further, I came across the article “Consistent representations of and conversions between 3D rotations” (https://iopscience.iop.org/article/10.1088/0965-0393/23/8/083501). Although it does not directly address DAMASK, based on its content and the information available under the "Rotation" section of the DAMASK documentation, it seems that there is some internal relationship between Euler angles and quaternions in DAMASK. However, I’m still unsure how these internal representations relate to the graphical output in ParaView.

Finally, regarding hexagonal metals like Ti: how should Miller-Bravais indices be interpreted within the DAMASK–ParaView visualization workflow? I understand that there are equations to convert from the three-index notation [u′ v′ w′] to the four-index notation [uvtw], but I’m still a bit unclear on how to connect this with the orientation data provided in the Lab frame.

Any help, clarification, or references you could provide would be greatly appreciated!

Thanks in advance.

Leo R D

[eisenlohr]

Dear @LeoDanninger,

The essential object that is performing all orientation-related tasks within DAMASK is damask.Orientation. An orientation is a combination of a damask.Rotation and a symmetry (or lattice for even more functionality). The rotation part is defined as the coordinate transformation from the lab frame to the crystal frame. Rotations have multiple equivalent representations, such as quaternion, Euler angles, rotation matrix, axis–angle pair, Rodrigues vector, etc., but that does not change the underlying quantity.

The Orientation.IPF_color method assigns a specific RGB triplet to each orientation based on which crystal direction is aligned with a fixed lab frame direction (the vector argument).

What orientation information is used to generate these visualizations (e.g., initial orientations known during preprocessing or evolved orientations known after simulating deformation) does not make a conceptual difference. Hence, your interpretation is correct.

Repeating the important fact from above: a damask.Orientation represents the coordinate transformation (rotation) from the lab frame to the crystal frame. The coordinate frame shown in ParaView is the lab frame.

Miller and Miller–Bravais indices designate either directions (or plane normals) in the real (or reciprocal) lattice basis. The Orientation.to_frame method can be used to calculate the lab direction aligned with either of these.

[LeoDanninger]

Dear Prof. @eisenlohr

First of all, thank you very much for your reply. I truly appreciate you taking the time to respond, and I apologize for the delay in getting back to you.

I have been trying to understand how to process the information you provided and how it fits into the workflow to visualize the relationship between crystal orientation and the lab frame orientation. However, I still have some questions and difficulties:

1 – You mentioned that the Orientation.IPF_color method assigns a specific RGB triplet to each orientation based on which crystal direction is aligned with a fixed lab frame direction (the vector argument). If I understood correctly how this method works, it assigns a specific color to a specific direction of the lab frame. For example, if the z direction of my lab frame is blue, then, when I visualize the orientation information in ParaView, the grains shown in blue will be preferentially aligned with z. Is that correct?

2 – My second question concerns the Orientation.to_frame method. I did not fully understand how to use it. I tried to create a small Python script to test this method, but I think I may either be using it incorrectly or misinterpreting the results.

In a simple example, I tried taking the quaternion orientation of a single grain at a single increment and seeing the output. The script and result are shown below:

Script:

import numpy as np
import damask

#quaternion from simulation file#
quat_example = [0.14298372093377196,
-0.039498236995856674,
-0.6390153454339087,
-0.7547548828077464]

O = damask.Orientation.from_quaternion(q=quat_example, family='hexagonal', lattice='hP')
print ('\n')
print (O)
print('\n')

v_lab2 = O.to_frame(uvtw=[0, 0, 0, 1], with_symmetry=False, normalize=True)
print(v_lab2)

Results:

Crystal family: hexagonal
Bravais lattice: hP
a=1 m, b=1 m, c=1.633 m
α=90°, β=90°, γ=120°
Quaternion [ 0.14298372 -0.03949824 -0.63901535 -0.75475488]

[-0.12311461 0.97589511 0.18019856]

Once again, thank you very much for having taken the time to address my previous questions

Thanks in advance.

Leo R D

[eisenlohr]

@LeoDanninger,

Your understanding of the first point is incorrect. There is no "specific color [assigned] to a specific direction of the lab frame". The color is based on what crystal direction is parallel to a fixed lab direction of interest.

I provide a small script that hopefully illustrates this with the example of a cubic lattice. The cube is rotated to match the lattice frame of the orientation, whereas the axes shown in ParaView correspond to the lab frame. The chosen IPF coloring selects the $z$-axis (i.e. the vector (0,0,1) in the lab frame) as the reference, marked by the gray arrow.

import numpy as np
import pyvista as pv
import damask

def IPF_colored_cube(O, labdirection):
    # Step 1: Define the cube corners (unit cube centered at origin)
    cube = pv.Cube(center=(0, 0, 0), x_length=1, y_length=1, z_length=1)

    # Step 2: Apply active rotation
    cube.points = ~O@cube.points

    # Step 3: Extract edges (convert to wireframe)
    edges = cube.extract_all_edges()

    # Step 4: Add RGB color array to edges
    edges["RGB"] = np.tile(O.IPF_color(np.asarray(labdirection)),
                           (edges.n_lines, 1))

    return edges

lab = [0,0,1]

for angle in np.arange(0,90,15):
    for axis in [[0,0,1],[1,0,0]]:
        IPF_colored_cube(
            O=damask.Orientation.from_axis_angle(
                axis+[angle],
                degrees=True,
                family='cubic'),
            labdirection=lab).save(f'rot{"".join(str(x) for x in axis)}@{angle:02}_{"".join(str(x) for x in lab)}.vtp')

The first image shows that for a rotation of the crystal frame that only goes about the $z$-axis, the crystal $c$-axis is always parallel to that, hence, all unit cells are colored red (please check the standard color scheme for IPFs, e.g. at EDAX, to confirm the $c$-axis is found in the bottom-left corner of the triangle).

If the crystal frame orientation differs by a rotation about the $x$-axis, as in the second image, then the lattice direction aligned with the $z$-axis (gray arrow) depends on the specific orientation, resulting in color variation from red to green, since, at 45° rotation, the $[011]$ direction aligns with $z$.

Taking the green case as our example to illustrate the meaning of to_frame, we would expect the [011] lattice direction (blue arrow) to be parallel to the $z$-axis, i.e., parallel to (0,0,1) in the lab frame:

damask.Orientation.from_axis_angle(
    [1,0,0,45],
    degrees=True,
    lattice='cF').to_frame(uvw=[0,1,1])

array([8.65956056e-17, 0.00000000e+00, 1.00000000e+00])

Similarly, the [0,1,0] direction ($b$-axis of the lattice, violet arrow), should point up and right, i.e., along (0,1,1):

damask.Orientation.from_axis_angle(
    [1,0,0,45],
    degrees=True,
    lattice='cF').to_frame(uvw=[0,1,0])

array([6.12323400e-17, 7.07106781e-01, 7.07106781e-01])

[LeoDanninger]

Dear Prof. @eisenlohr ,

First of all, please accept my apologies for the delay in replying.
Thanks to your explanation, I believe I now have a much clearer understanding of the crystallographic orientation issues and how they are represented in DAMASK.

I am truly grateful for your kind assistance.

Best regards,

Leo R D