Add virtual backscatter electron image generator (#170)

* Add virtual backscatter electron image generator (thanks, pyxem!)

Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>

* Start to test VirtualBSEGenerator

Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>

* Complete tests of virtual BSE generator/image, add CommonImage cls

Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>

* Document the VirtualBSEGenerator/Image in user guide

Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>

doc/_static/image/concatenate_images.sh

@@ -7,6 +7,7 @@ PATPROC=pattern_processing
 CHANGES=change_scan_pattern_size
 VIS=visualizing_patterns
 FEATMAP=feature_maps
+VIRTUAL=virtual_backscatter_electron_imaging
 
 # Pattern processing
 convert ${PATPROC}/pattern_raw.png ${PATPROC}/pattern_static.png +append ${PATPROC}/static_correction.jpg
@@ -24,10 +25,19 @@ convert ${PATPROC}/fft_filter_laplacian_correlate.png ${PATPROC}/fft_filter_lapl
 # Change image size
 convert ${PATPROC}/pattern_dynamic.jpg ${CHANGES}/pattern_cropped.jpg +append ${CHANGES}/change_pattern_size.jpg
 
-# Virtual image
-#
+# Visualizing patterns
+# Rescale navigators
 convert ${VIS}/vbse_navigator.jpg -resize 860x581 ${VIS}/vbse_navigator_rescaled.jpg
-convert ${VIS}/vbse_navigator_rescaled.jpg ${VIS}/pattern_roi.jpg -gravity center +append ${VIS}/roi_vbse_navigator.jpg
+convert ${VIS}/orientation_similarity_map_navigator.jpg -resize 860x581 ${VIS}/osm_navigator_rescaled.jpg
+convert ${VIS}/orientation_map_navigator.jpg -resize 860x581 ${VIS}/om_navigator_rescaled.jpg
+# Concatenate images
+convert ${VIS}/vbse_signal.png ${VIS}/vbse_navigator_rescaled.jpg -gravity center +append ${VIS}/vbse_navigation.jpg
+convert ${VIS}/vbse_signal.png ${VIS}/osm_navigator_rescaled.jpg -gravity center +append ${VIS}/osm_navigation.jpg
+convert ${VIS}/vbse_signal.png ${VIS}/om_navigator_rescaled.jpg -gravity center +append ${VIS}/om_navigation.jpg
 
 # Feature maps
 convert ${FEATMAP}/image_quality_pattern.png ${FEATMAP}/fft_spectrum.png ${FEATMAP}/fft_frequency_vectors.png +append ${FEATMAP}/image_quality_pattern.jpg
+
+# Virtual imaging
+convert ${VIRTUAL}/images_nav.jpg -resize 477x433 ${VIRTUAL}/images_nav_rescaled.jpg
+convert ${VIRTUAL}/images_nav_rescaled.jpg ${VIRTUAL}/images_sig.jpg -gravity center +append ${VIRTUAL}/images.jpg

doc/_static/image/doc_feature_maps_images.py

@@ -1,3 +1,21 @@
+# -*- coding: utf-8 -*-
+# Copyright 2019-2020 The kikuchipy developers
+#
+# This file is part of kikuchipy.
+#
+# kikuchipy is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# kikuchipy is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with kikuchipy. If not, see <http://www.gnu.org/licenses/>.
+
 import os
 
 import matplotlib

doc/_static/image/doc_processing_images.py

@@ -1,3 +1,21 @@
+# -*- coding: utf-8 -*-
+# Copyright 2019-2020 The kikuchipy developers
+#
+# This file is part of kikuchipy.
+#
+# kikuchipy is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# kikuchipy is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with kikuchipy. If not, see <http://www.gnu.org/licenses/>.
+
 import os
 
 import matplotlib

doc/_static/image/doc_virtual_imaging.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+# Copyright 2019-2020 The kikuchipy developers
+#
+# This file is part of kikuchipy.
+#
+# kikuchipy is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# kikuchipy is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with kikuchipy. If not, see <http://www.gnu.org/licenses/>.
+
+import os
+
+import matplotlib
+
+matplotlib.rcParams["backend"] = "qt5agg"
+import matplotlib.pyplot as plt
+import numpy as np
+
+import kikuchipy as kp
+
+data = "/home/hakon/phd/data/ni/2020/1/nordif/Pattern.dat"
+outdir = "/home/hakon/kode/kikuchipy/doc/_static/image"
+vbsedir = os.path.join(outdir, "virtual_backscatter_electron_imaging")
+
+datadir, fname = os.path.split(data)
+fname, ext = os.path.splitext(fname)
+s = kp.load(data, lazy=False)
+
+vbse_gen = kp.generators.VirtualBSEGenerator(s)
+
+# Plot grid
+vbse_gen.grid_shape = (10, 10)
+red = [(7, 1), (8, 1), (8, 2), (9, 1), (9, 2)]
+green = [(8, 4), (8, 5), (9, 4), (9, 5)]
+blue = [(7, 8), (8, 7), (8, 8), (9, 7), (9, 8)]
+p = vbse_gen.plot_grid(
+    pattern_idx=(100, 87),
+    rgb_channels=[red, green, blue],
+    visible_indices=True,
+)
+p._plot.signal_plot.figure.savefig(os.path.join(vbsedir, "plot_grid.jpg"),)
+
+# Get an RGB image
+vbse_rgb = vbse_gen.get_rgb_image(r=red, g=green, b=blue)
+vbse_rgb.plot()
+vbse_rgb._plot.signal_plot.figure.savefig(
+    os.path.join(vbsedir, "rgb_image.jpg"), bbox_inches="tight",
+)
+
+# Get one image per grid tile
+vbse_gen.grid_shape = (5, 5)
+vbse_imgs = vbse_gen.get_images_from_grid()
+pattern_idx = (2, 4)
+vbse_imgs.axes_manager[0].index = pattern_idx[0]
+vbse_imgs.axes_manager[1].index = pattern_idx[1]
+vbse_imgs.plot()
+vbse_imgs._plot.navigator_plot.figure.savefig(
+    os.path.join(vbsedir, "images_nav.jpg"), bbox_inches="tight", pad_inches=0,
+)
+vbse_imgs._plot.signal_plot.figure.savefig(
+    os.path.join(vbsedir, "images_sig.jpg"),
+)
+
+plt.close("all")

doc/_static/image/doc_visualize_images.py

@@ -1,3 +1,21 @@
+# -*- coding: utf-8 -*-
+# Copyright 2019-2020 The kikuchipy developers
+#
+# This file is part of kikuchipy.
+#
+# kikuchipy is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# kikuchipy is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with kikuchipy. If not, see <http://www.gnu.org/licenses/>.
+
 import os
 import logging
 import hyperspy.api as hs
@@ -11,7 +29,7 @@
 
 data = "/home/hakon/phd/data/ni/190506_ebsd/1/nordif/Pattern.dat"
 data_mp = "/home/hakon/kode/emsoft/emdata/crystal_data/ni/ni_mc_mp_20kv.h5"
-imgdir = "/home/hakon/kode/kikuchipy/doc/source/_static/image"
+imgdir = "/home/hakon/kode/kikuchipy/doc/_static/image"
 visdir = os.path.join(imgdir, "visualizing_patterns")
 
 datadir, fname = os.path.split(data)
@@ -20,23 +38,33 @@
 
 # VBSE
 roi = hs.roi.RectangularROI(left=18, top=20, right=23, bottom=25)
-s.virtual_backscatter_electron_imaging(roi)
+s.plot_virtual_bse_intensity(roi)
 s._plot.navigator_plot.figure.savefig(
     os.path.join(visdir, "standard_navigator.jpg")
 )
 s._plot.signal_plot.figure.savefig(os.path.join(visdir, "pattern_roi.jpg"))
 
 # Virtual image
-vbse = s.get_virtual_image(roi)
-s.plot(navigator=vbse)
+vbse_gen = kp.generators.VirtualBSEGenerator(s)
+vbse_gen.grid_shape = (10, 10)
+red = [(7, 1), (8, 1), (8, 2), (9, 1), (9, 2)]
+green = [(8, 4), (8, 5), (9, 4), (9, 5)]
+blue = [(7, 8), (8, 7), (8, 8), (9, 7), (9, 8)]
+vbse_rgb = vbse_gen.get_rgb_image(r=red, g=green, b=blue)
+s.axes_manager.navigation_axes[0].index = 155
+s.axes_manager.navigation_axes[1].index = 77
+s.plot(navigator=vbse_rgb)
 s._plot.navigator_plot.figure.savefig(
-    os.path.join(visdir, "vbse_navigator.jpg")
+    os.path.join(visdir, "vbse_navigator.png"), bbox_inches="tight",
 )
+s._plot.signal_plot.figure.savefig(os.path.join(visdir, "vbse_signal.png"),)
 
 # Quality metric map
 osm = plt.imread(os.path.join(visdir, "orientation_similarity_map.png"))
 s_osm = hs.signals.Signal2D(osm)
 s_osm = s_osm.rebin(s.axes_manager.navigation_shape)
+s.axes_manager.navigation_axes[0].index = 155
+s.axes_manager.navigation_axes[1].index = 77
 s.plot(navigator=s_osm)
 s._plot.navigator_plot.figure.savefig(
     os.path.join(visdir, "orientation_similarity_map_navigator.jpg")
@@ -48,14 +76,16 @@
 s_om = hs.signals.Signal2D(om_scaled)
 s_om = s_om.transpose(signal_axes=1)
 s_om.change_dtype("rgb8")
+s.axes_manager.navigation_axes[0].index = 155
+s.axes_manager.navigation_axes[1].index = 77
 s.plot(navigator=s_om)
 s._plot.navigator_plot.figure.savefig(
     os.path.join(visdir, "orientation_map_navigator.jpg")
 )
 
 # Plot simulated and experimental side-by-side
-s.static_background_correction()
-s.dynamic_background_correction()
+s.remove_static_background()
+s.remove_dynamic_background()
 s_sim = kp.load(os.path.join(datadir, "../emsoft/orig/ni_emebsd2.h5"))
 s.plot()
 s._plot.signal_plot.figure.savefig(os.path.join(visdir, "pattern.jpg"))

doc/_static/image/remove_images_not_in_docs.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+# Images to remove after running concatenate_images.sh. These images are not
+# used in the documentation.
+
+# TODO: Use lists and loops
+
+# change_scan_pattern_size
+CHANGES=change_scan_pattern_size
+rm ${CHANGES}/pattern_cropped.jpg
+rm ${CHANGES}/pattern_cropped.png
+
+# pattern_processing
+PATPROC=pattern_processing
+rm ${PATPROC}/dynamic_background.png
+rm ${PATPROC}/pattern_raw.png
+rm ${PATPROC}/pattern_static.png
+rm ${PATPROC}/pattern_dynamic.png
+rm ${PATPROC}/pattern_scan_static.png
+rm ${PATPROC}/pattern_scan_averaged.png
+rm ${PATPROC}/rescale_intensities_before.png
+rm ${PATPROC}/rescale_intensities_after.png
+rm ${PATPROC}/contrast_stretching_before.png
+rm ${PATPROC}/contrast_stretching_after.png
+rm ${PATPROC}/normalize_intensity_before.png
+rm ${PATPROC}/normalize_intensity_after.png
+rm ${PATPROC}/fft_filter_highlowpass2d.png
+rm ${PATPROC}/fft_filter_highlowpass1d.png
+rm ${PATPROC}/fft_filter_highlowpass_after.png
+rm ${PATPROC}/fft_filter_laplacian_correlate.png
+rm ${PATPROC}/fft_filter_laplacian_spatial.png
+
+# feature_maps
+FEATMAP=feature_maps
+rm ${FEATMAP}/fft_frequency_vectors.png
+rm ${FEATMAP}/fft_spectrum.png
+rm ${FEATMAP}/image_quality_pattern.png
+
+# virtual_backscatter_electron_imaging
+VIRTUAL=virtual_backscatter_electron_imaging
+rm ${VIRTUAL}/images_nav.jpg
+rm ${VIRTUAL}/images_nav_rescaled.jpg
+rm ${VIRTUAL}/images_sig.jpg
+
+# visualizing_patterns
+VIS=visualizing_patterns
+rm ${VIS}/om_navigator_rescaled.jpg
+rm ${VIS}/orientation_map.jpg
+rm ${VIS}/orientation_map_navigator.jpg
+rm ${VIS}/orientation_similarity_map.png
+rm ${VIS}/orientation_similarity_map_navigator.jpg
+rm ${VIS}/osm_navigator_rescaled.jpg
+rm ${VIS}/pattern.jpg
+rm ${VIS}/pattern_roi.jpg
+rm ${VIS}/roi_vbse_navigator.jpg
+rm ${VIS}/simulated_pattern.jpg
+rm ${VIS}/standard_navigator.jpg
+rm ${VIS}/vbse_navigator.jpg
+rm ${VIS}/vbse_navigator.png
+rm ${VIS}/vbse_navigator_rescaled.jpg
+rm ${VIS}/vbse_signal.jpg
+rm ${VIS}/vbse_signal.png