added a synthetic test/example and completed the doc.

nabu/preproc/alignment.py

@@ -562,12 +562,11 @@ class DetectorTranslationAlongBeam(AlignmentBase):
         return_shifts=False,
         use_adjacent_imgs=False,
     ):
-        """Find the deviation of the translation axis of the area detector
-        along the beam propagation direction.
-
-        TODO: Add more information here! Including interpretation of the result
-        This means giving also an example on how to convert the returned values
-        into meaningful quantities. See "Returns" for more details.
+        """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) 
 
         Parameters
         ----------
@@ -598,10 +597,10 @@ class DetectorTranslationAlongBeam(AlignmentBase):
             Low-pass filter properties, as described in `nabu.misc.fourier_filters`.
         high_pass: float or sequence of two floats
             High-pass filter properties, as described in `nabu.misc.fourier_filters`.
-        found_shifts_list: list, optional
-            if a list is given in input, it will be populated
-            with the found shifts. For each given image of the stack a tuple of shifts will be
-            appended to the list. This slot is intended for introspection.
+        return_shifts: boolean, optional
+            if a True a list, containing for each given image of the stack a tuple of shifts, will
+            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.
 
@@ -610,10 +609,41 @@ class DetectorTranslationAlongBeam(AlignmentBase):
         tuple(float, float)
             Estimated (vertical, horizontal) increment per unit-distance of the
             ratio between pixel-size and detector translation.
+            Optionally a tuple containing the shifts per each image are found if optional argument
+            return_shifts is true
 
         Examples
         --------
-        TODO: Add examples here!
+
+        >>> import numpy as np
+        ... import scipy.ndimage
+        ... from nabu.preproc.alignment import  DetectorTranslationAlongBeam
+        ...
+        ... T_calc = DetectorTranslationAlongBeam()
+        ...
+        ... stack = np.zeros([4, 512, 512], "d")
+        ...
+        ... # 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
+        ...
+        ... # Add the feature
+        ... x, y = np.meshgrid(np.arange(stack.shape[-1]), np.arange(stack.shape[-2]))
+        ... for i in range(4):
+        ...     xc = x - (250 + i * 1.234)
+        ...     yc = y - (250 + i * 1.234 * 2)
+        ...     stack[i] += np.exp(-(xc * xc + yc * yc) * 0.5)
+        ...
+        ... # 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
+        ... )
+        ... print(shifts_v, shifts_h)
+        >>> ( -2.47 , -1.236 )
+
+
+
         """
         self._check_img_sizes(img_stack, img_pos)
 

nabu/preproc/tests/test_alignment.py

@@ -228,3 +228,22 @@ class TestDetectorTranslation(object):
 
         message = "Computed shifts %s and expected %s do not coincide" % (found_shifts_list, self.reference_shifts_list)
         assert np.all(np.isclose(found_shifts_list, self.reference_shifts_list, atol=self.abs_tol)), message
+
+    def test_alignxc_synth(self):
+        T_calc = DetectorTranslationAlongBeam()
+
+        stack = np.zeros([4, 512, 512], "d")
+        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
+        x, y = np.meshgrid(np.arange(stack.shape[-1]), np.arange(stack.shape[-2]))
+        for i in range(4):
+            xc = x - (250 + i * 1.234)
+            yc = y - (250 + i * 1.234 * 2)
+            stack[i] += np.exp(-(xc * xc + yc * yc) * 0.5)
+        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
+        )
+
+        message = "Found shifts per units %s and reference %s do not coincide" % ((shifts_v, shifts_h), (-1.234 * 2, -1.234))
+        assert np.all(np.isclose((shifts_v, shifts_h), (-1.234 * 2, -1.234), atol=self.abs_tol)), message