Alignment: extended doctstring of DetectorTranslationAlongBeam.find_shift

Simplified initial description, and extended examples
Signed-off-by: Nicola VIGANÒ <nicola.vigano@esrf.fr>

nabu/preproc/alignment.py

@@ -578,11 +578,19 @@ class DetectorTranslationAlongBeam(AlignmentBase):
         return_shifts=False,
         use_adjacent_imgs=False,
     ):
-        """Find  vertical and  horizontal position increments per a unit-distance detector translation along the
-        traslation axis. The units are pixel_unit/input_unit where input_unit are the  unit that the user has  used
-        to pass the argument img_pos. The output expresses shifts of the detector so that if the image is moving
-        in the positive direction (expressed in pixels coordinates) the output will be negative because it means
-        that the detector as a whole is shifting in the opposite direction (taking the shaped  beam as a reference)
+        """Find the vertical and horizontal shifts for translations of the
+        detector along the beam direction.
+
+        These shifts are in pixels-per-unit-translation, and they are due to
+        the misalignment of the translation stage, with respect to the beam
+        propagation direction.
+
+        To compute the vertical and horizontal tilt angles from the obtained `shift_pix`:
+
+        >>> tilt_deg = np.rad2deg(np.arctan(shift_pix * pixel_size))
+
+        where `pixel_size` and and the input parameter `img_pos` have to be
+        expressed in the same units.
 
         Parameters
         ----------
@@ -618,7 +626,10 @@ class DetectorTranslationAlongBeam(AlignmentBase):
             be return together with  the increment per unit-distance.
             This slot is intended for introspection.
         use_adjacent_imgs: boolean, optional
-            Compute correlation between adjacent images. It is better when dealing with large shifts.
+            Compute correlation between adjacent images.
+            It can be used when dealing with large shifts, to avoid overflowing the shift.
+            This option allows to replicate the behavior of the reference function `alignxc.m`
+            However, it is detrimental to shift fitting accuracy. Defaults to False.
 
         Returns
         -------
@@ -630,19 +641,22 @@ class DetectorTranslationAlongBeam(AlignmentBase):
 
         Examples
         --------
+        The following example creates a stack of shifted images, and retrieves the computed shift.
+        Here we use a high-pass filter, due to the presence of some low-frequency noise component.
 
         >>> import numpy as np
+        ... import scipy as sp
         ... import scipy.ndimage
         ... from nabu.preproc.alignment import  DetectorTranslationAlongBeam
         ...
-        ... T_calc = DetectorTranslationAlongBeam()
+        ... tr_calc = DetectorTranslationAlongBeam()
         ...
-        ... stack = np.zeros([4, 512, 512], "d")
+        ... stack = np.zeros([4, 512, 512])
         ...
         ... # Add low frequency spurious component
         ... for i in range(4):
         ...     stack[i, 200 - i * 10, 200 - i * 10] = 1
-        ... stack = scipy.ndimage.filters.gaussian_filter(stack, [0, 10, 10.0]) * 100
+        ... stack = sp.ndimage.filters.gaussian_filter(stack, [0, 10, 10.0]) * 100
         ...
         ... # Add the feature
         ... x, y = np.meshgrid(np.arange(stack.shape[-1]), np.arange(stack.shape[-2]))
@@ -651,12 +665,27 @@ class DetectorTranslationAlongBeam(AlignmentBase):
         ...     yc = y - (250 + i * 1.234 * 2)
         ...     stack[i] += np.exp(-(xc * xc + yc * yc) * 0.5)
         ...
+        ... # Image translation along the beam
+        ... img_pos = np.arange(4)
+        ...
         ... # Find the shifts from the features
-        ... shifts_v, shifts_h, found_shifts_list = T_calc.find_shift(
-        ...     stack, np.array([0.0, 1, 2, 3]), high_pass=1.0, return_shifts=True
-        ... )
+        ... shifts_v, shifts_h = tr_calc.find_shift(stack, img_pos, high_pass=1.0)
         ... print(shifts_v, shifts_h)
         >>> ( -2.47 , -1.236 )
+
+        and the following commands convert the shifts in angular tilts:
+
+        >>> tilt_v_deg = np.rad2deg(np.arctan(shifts_v * pixel_size))
+        >>> tilt_h_deg = np.rad2deg(np.arctan(shifts_h * pixel_size))
+
+        To enable the legacy behavior of `alignxc.m` (correlation between adjacent images):
+
+        >>> shifts_v, shifts_h = tr_calc.find_shift(stack, img_pos, use_adjacent_imgs=True)
+
+        To plot the correlation shifts and the fitted straight lines for both directions:
+
+        >>> tr_calc = DetectorTranslationAlongBeam(verbose=True)
+        ... shifts_v, shifts_h = tr_calc.find_shift(stack, img_pos)
         """
         self._check_img_sizes(img_stack, img_pos)