ENH/BUG: Alignment Filters Modernization (#1237)

* Change All Alignment Filters (inheriting from AlignSections) to work from Arrays

* Added the option to work from relative or cumulative shifts in AlignSectionsList

* Patched a bug in AlignSectionsFeatureCentroids that caused it to write 0s for relative paths

* Extensive reworks and cleanup

* Documentation updates and tutorial

* Test cases

* Add 3 example pipelines and example data

- Implemented `getSelectedDataPaths()` in the AlignSections class since all subclasses were doing the same thing
- Align Sections Feature Centroid: Removed the Cell Data Array path parameter since we get that from the Image geometry
- Fixed a pipeline file that was throwing warnings about non-existent parameters
- Parameter terminology is consistently used among the Align Section filters.

Signed-off-by: Michael Jackson <[email protected]>

---------

Signed-off-by: Michael Jackson <[email protected]>
Co-authored-by: Michael Jackson <[email protected]>

Author: nyoungbq

src/Plugins/OrientationAnalysis/docs/AlignSectionsMisorientationFilter.md

@@ -17,24 +17,32 @@ This **Filter** attempts to align consecutive 'sections' perpendicular to the Z-
 
 **Note that this is similar to a downhill simplex and can get caught in a local minimum!**
 
-If the user elects to use a mask array, the **Cells** flagged as *false* in the mask array will not be considered during the alignment process.  
-
-The user can choose to write the determined shift to an output file by enabling *Write Alignment Shifts File* and providing a file path.  
+If the user elects to use a mask array, the **Cells** flagged as *false* in the mask array will not be considered during the alignment process.
 
 The user can also decide to remove a *background shift* present in the sample. The process for this is to fit a line to the X and Y shifts along the Z-direction of the sample.  The individual shifts are then modified to make the slope of the fit line be 0.  Effectively, this process is trying to keep the top and bottom section of the sample fixed.  Some combinations of sample geometry and internal features can result in this algorithm introducing a 'shear' in the sample and the *Linear Background Subtraction* will attempt to correct for this.
 
-## Optional Output File Format
+## Optional Output Data
+
+The user can optionally have the shifts that are generated by the filter stored in various DataArrays in a new Attribute Matrix.
 
-The user can optionally have the shifts that are generated by the filter written to a file. The format of the file follows:
+The structure for which looks like this
 
 ```console
-    slice_m slice_m+1 newxshift newyshift xshifts yshifts
-    slice_n slice_n+1 newxshift newyshift xshifts yshifts
-    etc...
+|-- Image Geometry
+  |-- Alignment Shifts Data
+    |-- Slices
+    |-- Relative Shifts
+    |-- Cumulative Shifts
 ```
 
-where the `newxshift` and `newyshift` are the shifts from the previous slice and 
-`xshifts` and `yshifts` are the accumulated shift for the slice.
+In this new structure, what follows is what the created structures represent:
+
+- Alignment Shifts Data (Attribute Matrix) - The tuple size here is defined by the number of slices [ie the Z Dimension of the Image Geometry]
+- Slices (DataArray | 2 component) - The slice indices (stored as uint32s)
+- Relative Shifts (DataArray | 2 component) - The slices shift relative to previous shift (stored as int64s) [*previously known as `newxshift` and `newyshift`*]
+- Cumulative Shifts (DataArray | 2 component) - The slice's accumulated shift (stored as int64s)
+
+In previous versions a file would have been produced instead. If you wish to recreate this, you can write the Attribute Matrix as a CSV/Text file.
 
 
 % Auto generated parameter table will be inserted here

src/Plugins/OrientationAnalysis/docs/AlignSectionsMutualInformationFilter.md

@@ -24,23 +24,30 @@ The user choses the level of *misorientation tolerance* by which to align **Cell
 
 The approach used in this **Filter** is to group neighboring **Cells** on a slice that have a *misorientation* below the tolerance the user entered. *Misorientation* here means the minimum rotation angle of one **Cell's** crystal axis needed to coincide with another **Cell's** crystal axis. When the **Features** in the slices are defined, they are moved until *disks* in neighboring slices align with each other.
 
-If the user elects to use a mask array, the **Cells** flagged as *false* in the mask array will not be considered during the alignment process.  
+If the user elects to use a mask array, the **Cells** flagged as *false* in the mask array will not be considered during the alignment process.
 
-The user can choose to write the determined shift to an output file by enabling *Write Alignment Shifts File* and providing a file path.  
+## Optional Output Data
 
-## Optional Output File Format
+The user can optionally have the shifts that are generated by the filter stored in various DataArrays in a new Attribute Matrix.
 
-The user can optionally have the shifts that are generated by the filter written to a file. The format of the file follows:
+The structure for which looks like this
 
 ```console
-    slice_m slice_m+1 newxshift newyshift xshifts yshifts
-    slice_n slice_n+1 newxshift newyshift xshifts yshifts
-    etc...
+|-- Image Geometry
+  |-- Alignment Shifts Data
+    |-- Slices
+    |-- Relative Shifts
+    |-- Cumulative Shifts
 ```
 
-where the `newxshift` and `newyshift` are the shifts from the previous slice and 
-`xshifts` and `yshifts` are the accumulated shift for the slice.
+In this new structure, what follows is what the created structures represent:
 
+- Alignment Shifts Data (Attribute Matrix) - The tuple size here is defined by the number of slices [ie the Z Dimension of the Image Geometry]
+- Slices (DataArray | 2 component) - The slice indices (stored as uint32s)
+- Relative Shifts (DataArray | 2 component) - The slices shift relative to previous shift (stored as int64s) [*previously known as `newxshift` and `newyshift`*]
+- Cumulative Shifts (DataArray | 2 component) - The slice's accumulated shift (stored as int64s)
+
+In previous versions a file would have been produced instead. If you wish to recreate this, you can write the Attribute Matrix as a CSV/Text file.
 
 % Auto generated parameter table will be inserted here
 

src/Plugins/OrientationAnalysis/pipelines/AlignSectionsMutualInformation.d3dpipeline

@@ -135,10 +135,6 @@
     },
     {
       "args": {
-        "alignment_shift_file_name": {
-          "value": "Data/Output/OrientationAnalysis/Alignment_By_Mutual_Information_Shifts.txt",
-          "version": 1
-        },
         "cell_phases_array_path": {
           "value": "DataContainer/Cell Data/Phases",
           "version": 1
@@ -159,18 +155,13 @@
           "value": 5.0,
           "version": 1
         },
-        "parameters_version": 1,
         "quats_array_path": {
           "value": "DataContainer/Cell Data/Quats",
           "version": 1
         },
         "use_mask": {
           "value": true,
           "version": 1
-        },
-        "write_alignment_shifts": {
-          "value": true,
-          "version": 1
         }
       },
       "comments": "",