Orientation refinement of two-phased crystal map from Hough indexing

[Erlendos12]

As I have understood, when doing dictionary indexing on a multi-phased specimen, it is ideal to refine the orientations of each crystal map (one for each phase) before merging the results together. However, the EBSD.hough_indexing() method takes a list of phases (2 max) and returns a single crystal map. When doing orientation refinement on this crystal map, I understand one should use a navigation mask to make it possible to refine one phase of the crystal map at the time #620 (comment). This makes it so refinement is only performed on the already determined phases instead of the whole area of interest like in dictionary indexing. This makes it so refinement has little impact when merging the partially refined crystal maps, as an indexed pattern cannot switch phase.

You have maybe thought about this already, but I was wondering if there is a way to make it refine orientations for the whole specimen for each phase. I have thought about using Hough indexing on one phase at the time, to create two crystal maps (one for each phase) before refining orientations and merging the results myself (like DI).

[hakonanes]

Very good question. I did not think of this workflow, which is why it is not covered in any tutorial. However, it is fully possible with the current tools! We just need to move some extra data around.

PyEBSDIndex' EBSDIndexer.index_pats() returns data per point for the combined phase map and per phase, meaning that it returns three "values" per point if we have two phases in our dataset. EBSD.hough_indexing() only returns the combined crystal map by default, but you can ask for the full data array returned by PyEBSDIndex with the additional "values" by passing return_index_data=True (docs). You can then pass this index_data array to xmap_from_hough_indexing() (docs) with the corresponding phase list, and specify which index into the array you want a crystal map from. Remember to pass in navigation shape, step sizes and scan unit as well, to obtain a complete crystal map. You should then be able to refine these separately, just like you would dictionary indexed crystal maps.

You shouldn't need to worry about how the index_data array is structured with this workflow. If you want to know, though, it's structure is described in PyEBSDIndex' documentation and hough indexing demo.

This workflow should be covered in the docs. I've been thinking about adding some small multi phase datasets to the data module for testing and doc purposes, but haven't found the time...

[hakonanes]

If you don't mind, I could put together a first draft for a notebook describing the workflow, which you can put in the docs.

Sounds great. You should know that there are some restrictions for our tutorial notebooks, which aren't mentioned in the contributing guide (we should add these at some point):

• Datasets must be small (ideally < 100 MB) and available under an open license online (say, on Zenodo). An exception is made for the si_wafer() dataset (doc).
• Datasets should be downloadable to the notebook, so that users can run the notebook as is without having to download outside of the notebook and then point to the dataset on their computer. An exception is made for the well known and analyzed EDAX Ni dataset, used in the tutorial Orientation dependence of the projection center.

Finally, I'd like for any new tutorial notebooks to be runnable when building the docs, i.e. they shouldn't have cell outputs stored. Thus it should not take too long to run. Read The Docs offers 3 GB of memory and two cores, which we must keep in mind when writing tutorials.

I realize that these restrictions are quite severe... Just let me know how I can help.

[Erlendos12]

Yes, I will keep that in mind. Keeping you updated as I investigate.

[Erlendos12]

@hakonanes I was able to use the index data to create two separate crystal maps, where I could refine the orientations, thanks!

For creating the documentation:
I tried following the steps in contributing guide, but when I do make html I get the error:

Traceback (most recent call last):
  File "C:\kikuchipy\env\lib\site-packages\sphinx\config.py", line 350, in eval_config_file
    exec(code, namespace)
  File "C:\kikuchipy\doc\conf.py", line 258, in <module>
    pyvista.start_xvfb()
  File "C:\kikuchipy\env\lib\site-packages\pyvista\utilities\xvfb.py", line 44, in start_xvfb
    raise OSError('`start_xvfb` is only supported on Linux')
OSError: `start_xvfb` is only supported on Linux

I am using Windows, does this mean I can only build on Linux? If so, is it sufficient to only create the notebook and you will handle the rest needed?

[hakonanes]

Great to hear!

That error is raised by a call to start_xvfb() with PyVista in our Sphinx configuration file. I use Linux myself, and Read The Docs (RTD) server uses Linux, so I haven't encountered this error before. Thank you for bringing it to my attention. The call starts a virtual frame buffer (xvfb) so that the nice 3D interactive visualizations like the one here run in a user's browser instead of on RTD's server with streaming to the browser. I want Windows users to be able to build our documentation locally, so this should be fixed somehow. We can continue this discussion in another issue (#631).

For now, you can just set up the PR, and we can take it from there.

[Erlendos12]

Will do, once I have something to commit. 👍