nabu 2023.2.1__py3-none-any.whl → 2024.1.0rc3__py3-none-any.whl

nabu/stitching/config.py

@@ -28,36 +28,27 @@ __license__ = "MIT"
 __date__ = "10/05/2022"
 
 
+from math import ceil
+from typing import Any, Iterable, Optional, Union, Sized
 from dataclasses import dataclass
 import numpy
+from pyunitsystem.metricsystem import MetricSystem
+from nxtomo.paths import nxtomo
+from tomoscan.factory import Factory
 from tomoscan.identifier import VolumeIdentifier, ScanIdentifier
-from tomoscan.esrf import HDF5TomoScan
-from tomoscan.nexus.paths import nxtomo
-from silx.utils.enum import Enum as _Enum
-from typing import Optional, Union, Sized
-from nabu.pipeline.config_validators import (
-    integer_validator,
-    list_of_shift_validator,
-    list_of_tomoscan_identifier,
-    optional_directory_location_validator,
+from tomoscan.esrf.scan.nxtomoscan import NXtomoScan
+from ..pipeline.config_validators import (
     boolean_validator,
     convert_to_bool,
-    optional_positive_integer_validator,
-    output_file_format_validator,
-    optional_tuple_of_floats_validator,
-    optional_file_name_validator,
 )
-from nabu.stitching.overlap import OverlapStitchingStrategy
-from nabu.utils import concatenate_dict, convert_str_to_tuple
-from nabu.io.utils import get_output_volume
-from tomoscan.factory import Factory
-from typing import Iterable
-from nabu.stitching.utils import ShiftAlgorithm
-from tomoscan.unitsystem.metricsystem import MetricSystem
-from math import ceil
-
+from ..utils import concatenate_dict, convert_str_to_tuple
+from ..io.utils import get_output_volume
+from .overlap import OverlapStitchingStrategy
+from .utils import ShiftAlgorithm
+from .definitions import StitchingType
+from .alignment import AlignmentAxis1, AlignmentAxis2
+from pyunitsystem.metricsystem import MetricSystem
 
-KEY_SCORE_METHOD = "score_method"
 
 KEY_IMG_REG_METHOD = "img_reg_method"
 
@@ -137,6 +128,12 @@ KEY_RESCALE_MIN_PERCENTILES = "rescale_min_percentile"
 
 KEY_RESCALE_MAX_PERCENTILES = "rescale_max_percentile"
 
+ALIGNMENT_AXIS_2_FIELD = "alignment_axis_2"
+
+ALIGNMENT_AXIS_1_FIELD = "alignment_axis_1"
+
+PAD_MODE_FIELD = "pad_mode"
+
 # SLURM
 
 SLURM_SECTION = "slurm"
@@ -155,8 +152,24 @@ SLURM_OTHER_OPTIONS = "other_options"
 
 SLURM_PREPROCESSING_COMMAND = "python_venv"
 
+SLURM_MODULES_TO_LOADS = "modules"
+
 SLURM_CLEAN_SCRIPTS = "clean_scripts"
 
+# normalization by sample
+
+NORMALIZATION_BY_SAMPLE_SECTION = "normalization_by_sample"
+
+NORMALIZATION_BY_SAMPLE_ACTIVE_FIELD = "active"
+
+NORMALIZATION_BY_SAMPLE_METHOD = "method"
+
+NORMALIZATION_BY_SAMPLE_SIDE = "side"
+
+NORMALIZATION_BY_SAMPLE_MARGIN = "margin"
+
+NORMALIZATION_BY_SAMPLE_WIDTH = "width"
+
 # kernel extra options
 
 STITCHING_KERNELS_EXTRA_PARAMS = "stitching_kernels_extra_params"
@@ -168,7 +181,6 @@ CROSS_CORRELATION_METHODS_AXIS_0 = {
     "": "",  # for display
     ShiftAlgorithm.NABU_FFT.value: "will call nabu `find_shift_correlate` function - shift search in fourier space",
     ShiftAlgorithm.SKIMAGE.value: "use scikit image `phase_cross_correlation` function in real space",
-    ShiftAlgorithm.SHIFT_GRID.value: "will compute a score for each possible shift and pick the shift with the highest score",
     ShiftAlgorithm.NONE.value: "no shift research is done. will only get shift from motor positions",
 }
 
@@ -189,6 +201,7 @@ SECTIONS_COMMENTS = {
     OUTPUT_SECTION: "section dedicated to output parameters\n",
     INPUTS_SECTION: "section dedicated to inputs\n",
     SLURM_SECTION: "section didicated to slurm. If you want to run locally avoid setting 'partition or remove this section'",
+    NORMALIZATION_BY_SAMPLE_SECTION: "section dedicated to normalization by a sample. If activate each frame can be normalized by a sample of the frame",
 }
 
 DEFAULT_SHIFT_ALG_AXIS_0 = "nabu-fft"
@@ -202,9 +215,7 @@ _shift_algs_axis_2 = "\n            + ".join(
 )
 
 HELP_SHIFT_PARAMS = f"""options for shifts algorithms as `key1=value1,key2=value2`. For now valid keys are:
-    - {KEY_WINDOW_SIZE}: size of the window for the 'shift-grid' algorithm'.
     - {KEY_OVERLAP_SIZE}: size to apply stitching. If not provided will take the largest size possible'.
-    - {KEY_SCORE_METHOD}: method to use in order to compute score for the 'shift-grid' algorithm. Values can be 'tv' (total variation), '1/tv', 'std' (standard deviation), '1/std'.
     - {KEY_IMG_REG_METHOD}: algorithm to use to find overlaps between the different sections. Possible values are \n        * for axis 0: {_shift_algs_axis_0}\n        * and for axis 2: {_shift_algs_axis_2}
     - {KEY_LOW_PASS_FILTER}: low pass filter value for filtering frames before shift research
     - {KEY_HIGH_PASS_FILTER}: high pass filter value for filtering frames before shift research"""
@@ -263,7 +274,6 @@ def _valid_shifts_params(my_dict: Union[dict, str]):
         my_dict = _str_to_dict(my_str=my_dict)
 
     valid_keys = (
-        KEY_SCORE_METHOD,
         KEY_WINDOW_SIZE,
         KEY_IMG_REG_METHOD,
         KEY_OVERLAP_SIZE,
@@ -326,6 +336,106 @@ def _scalar_or_tuple_to_bool_or_tuple_of_bool(my_str: Union[bool, tuple, str], d
         return values
 
 
+from nabu.stitching.sample_normalization import Method, SampleSide
+
+
+class NormalizationBySample:
+    def __init__(self) -> None:
+        self._active = False
+        self._method = Method.MEAN
+        self._margin = 0
+        self._side = SampleSide.LEFT
+        self._width = 30
+
+    def is_active(self):
+        return self._active
+
+    def set_is_active(self, active: bool):
+        assert isinstance(
+            active, bool
+        ), f"active is expected to be a bool. Get {type(active)} instead. Value == {active}"
+        self._active = active
+
+    @property
+    def method(self) -> Method:
+        return self._method
+
+    @method.setter
+    def method(self, method: Union[Method, str]) -> None:
+        self._method = Method.from_value(method)
+
+    @property
+    def margin(self) -> int:
+        return self._margin
+
+    @margin.setter
+    def margin(self, margin: int):
+        assert isinstance(margin, int), f"margin is expected to be an int. Get {type(margin)} instead"
+        self._margin = margin
+
+    @property
+    def side(self) -> SampleSide:
+        return self._side
+
+    @side.setter
+    def side(self, side: Union[SampleSide, str]):
+        self._side = SampleSide.from_value(side)
+
+    @property
+    def width(self) -> int:
+        return self._width
+
+    @width.setter
+    def width(self, width: int):
+        assert isinstance(width, int), f"width is expected to be an int. Get {type(width)} instead"
+
+    @staticmethod
+    def from_dict(my_dict: dict):
+        sample_normalization = NormalizationBySample()
+        # active
+        active = my_dict.get(NORMALIZATION_BY_SAMPLE_ACTIVE_FIELD, None)
+        if active is not None:
+            active = active in (True, "True", 1, "1")
+            sample_normalization.set_is_active(active)
+
+        # method
+        method = my_dict.get(NORMALIZATION_BY_SAMPLE_METHOD, None)
+        if method is not None:
+            sample_normalization.method = method
+
+        # margin
+        margin = my_dict.get(NORMALIZATION_BY_SAMPLE_MARGIN, None)
+        if margin is not None:
+            sample_normalization.margin = int(margin)
+
+        # side
+        side = my_dict.get(NORMALIZATION_BY_SAMPLE_SIDE, None)
+        if side is not None:
+            sample_normalization.side = side
+
+        # width
+        width = my_dict.get(NORMALIZATION_BY_SAMPLE_WIDTH, None)
+        if width is not None:
+            sample_normalization.width = int(width)
+
+        return sample_normalization
+
+    def to_dict(self) -> dict:
+        return {
+            NORMALIZATION_BY_SAMPLE_ACTIVE_FIELD: self.is_active(),
+            NORMALIZATION_BY_SAMPLE_METHOD: self.method.value,
+            NORMALIZATION_BY_SAMPLE_MARGIN: self.margin,
+            NORMALIZATION_BY_SAMPLE_SIDE: self.side.value,
+            NORMALIZATION_BY_SAMPLE_WIDTH: self.width,
+        }
+
+    def __eq__(self, __value: object) -> bool:
+        if not isinstance(__value, NormalizationBySample):
+            return False
+        else:
+            return self.to_dict() == __value.to_dict()
+
+
 @dataclass
 class SlurmConfig:
     "configuration for slurm jobs"
@@ -334,10 +444,18 @@ class SlurmConfig:
     n_jobs: int = 1
     other_options: str = ""
     preprocessing_command: str = ""
+    modules_to_load: tuple = tuple()
     clean_script: bool = ""
     n_tasks: int = 1
     n_cpu_per_task: int = 4
 
+    def __post_init__(self) -> None:
+        # make sure either 'modules' or 'preprocessing_command' is provided
+        if len(self.modules_to_load) > 0 and self.preprocessing_command not in (None, ""):
+            raise ValueError(
+                f"Either modules {SLURM_MODULES_TO_LOADS} or preprocessing_command {SLURM_PREPROCESSING_COMMAND} can be provided. Not both."
+            )
+
     def to_dict(self) -> dict:
         "dump configuration to dict"
         return {
@@ -346,6 +464,7 @@ class SlurmConfig:
             SLURM_N_JOBS: self.n_jobs,
             SLURM_OTHER_OPTIONS: self.other_options,
             SLURM_PREPROCESSING_COMMAND: self.preprocessing_command,
+            SLURM_MODULES_TO_LOADS: self.modules_to_load,
             SLURM_CLEAN_SCRIPTS: self.clean_script,
             SLURM_NUMBER_OF_TASKS: self.n_tasks,
             SLURM_COR_PER_TASKS: self.n_cpu_per_task,
@@ -363,15 +482,11 @@ class SlurmConfig:
             n_tasks=config.get(SLURM_NUMBER_OF_TASKS, 1),
             n_cpu_per_task=config.get(SLURM_COR_PER_TASKS, 4),
             preprocessing_command=config.get(SLURM_PREPROCESSING_COMMAND, ""),
+            modules_to_load=convert_str_to_tuple(config.get(SLURM_MODULES_TO_LOADS, "")),
             clean_script=convert_to_bool(config.get(SLURM_CLEAN_SCRIPTS, False))[0],
         )
 
 
-class StitchingType(_Enum):
-    Z_PREPROC = "z-preproc"
-    Z_POSTPROC = "z-postproc"
-
-
 def _cast_shift_to_str(shifts: Union[tuple, str, None]) -> str:
     if shifts is None:
         return ""
@@ -408,9 +523,9 @@ class StitchingConfiguration:
     axis_2_params: dict = None
     slurm_config: SlurmConfig = None
     flip_lr: Union[tuple, bool] = False
-    "flip frame left-right. For scan this will happen after possible flip of NXtomo metadata x_flipped field (also know as lr_flipped)"
+    "flip frame left-right. For scan this will be append to the NXtransformations of the detector"
     flip_ud: Union[tuple, bool] = False
-    "flip frame up-down. For scan this will happen after possible flip of NXtomo metadata y_flipped field (also know as ud_flipped)"
+    "flip frame up-down. For scan this will be append to the NXtransformations of the detector"
 
     overwrite_results: bool = False
     stitching_strategy: OverlapStitchingStrategy = OverlapStitchingStrategy.COSINUS_WEIGHTS
@@ -422,10 +537,16 @@ class StitchingConfiguration:
     rescale_frames: bool = False
     rescale_params: dict = None
 
+    normalization_by_sample: NormalizationBySample = None
+
     @property
     def stitching_type(self):
         raise NotImplementedError("Base class")
 
+    def __post_init__(self):
+        if self.normalization_by_sample is None:
+            self.normalization_by_sample = NormalizationBySample()
+
     @staticmethod
     def get_description_dict() -> dict:
         def get_pos_info(axis, unit, alternative):
@@ -526,6 +647,16 @@ class StitchingConfiguration:
                     "help": f"advanced parameters for some stitching kernels. must be provided as 'key1=value1;key_2=value2'. Valid keys for now are: {KEY_THRESHOLD_FREQUENCY}: threshold to be used by the {OverlapStitchingStrategy.IMAGE_MINIMUM_DIVERGENCE.value} to split images low and high frequencies in Fourier space.",
                     "type": "advanced",
                 },
+                ALIGNMENT_AXIS_2_FIELD: {
+                    "default": "center",
+                    "help": f"In case frame have different frame widths how to align them (so along volume axis 2). Valid keys are {AlignmentAxis2.values()}",
+                    "type": "advanced",
+                },
+                PAD_MODE_FIELD: {
+                    "default": "constant",
+                    "help": f"pad mode to use for frame alignment. Valid values are 'constant', 'edge', 'linear_ramp', maximum', 'mean', 'median', 'minimum', 'reflect', 'symmetric', 'wrap', and 'empty'. See nupy.pad documentation for details",
+                    "type": "advanced",
+                },
             },
             OUTPUT_SECTION: {
                 OVERWRITE_RESULTS_FIELD: {
@@ -583,6 +714,38 @@ class StitchingConfiguration:
                     "help": "python virtual environment to use",
                     "type": "optional",
                 },
+                SLURM_MODULES_TO_LOADS: {
+                    "default": "",
+                    "help": "module to load",
+                    "type": "optional",
+                },
+            },
+            NORMALIZATION_BY_SAMPLE_SECTION: {
+                NORMALIZATION_BY_SAMPLE_ACTIVE_FIELD: {
+                    "default": False,
+                    "help": "should we apply frame normalization by a sample or not",
+                    "type": "advanced",
+                },
+                NORMALIZATION_BY_SAMPLE_METHOD: {
+                    "default": "median",
+                    "help": "method to compute the normalization value",
+                    "type": "advanced",
+                },
+                NORMALIZATION_BY_SAMPLE_SIDE: {
+                    "default": "left",
+                    "help": "side to pick the sample",
+                    "type": "advanced",
+                },
+                NORMALIZATION_BY_SAMPLE_MARGIN: {
+                    "default": 0,
+                    "help": "margin (in px) between border and sample",
+                    "type": "advanced",
+                },
+                NORMALIZATION_BY_SAMPLE_WIDTH: {
+                    "default": 30,
+                    "help": "sample width (in px)",
+                    "type": "advanced",
+                },
             },
         }
 
@@ -614,6 +777,7 @@ class StitchingConfiguration:
                     self.overwrite_results,
                 ),
             },
+            NORMALIZATION_BY_SAMPLE_SECTION: self.normalization_by_sample.to_dict(),
         }
 
 
@@ -627,6 +791,10 @@ class ZStitchingConfiguration(StitchingConfiguration):
         slice, tuple, None
     ] = None  # slices to reconstruct. Over axis 0 for pre-processing, over axis 1 for post-processing. If None will reconstruct all
 
+    alignment_axis_2: AlignmentAxis2 = AlignmentAxis2.CENTER
+
+    pad_mode: str = "constant"  # pad mode to be used for alignment
+
     def settle_inputs(self) -> None:
         self.settle_slices()
 
@@ -648,7 +816,11 @@ class ZStitchingConfiguration(StitchingConfiguration):
             {
                 INPUTS_SECTION: {
                     STITCHING_SLICES: slices,
-                }
+                },
+                STITCHING_SECTION: {
+                    ALIGNMENT_AXIS_2_FIELD: self.alignment_axis_2.value,
+                    PAD_MODE_FIELD: self.pad_mode,
+                },
             },
         )
 
@@ -670,7 +842,7 @@ class PreProcessedZStitchingConfiguration(ZStitchingConfiguration):
         return StitchingType.Z_PREPROC
 
     def get_output_object(self):
-        return HDF5TomoScan(
+        return NXtomoScan(
             scan=self.output_file_path,
             entry=self.output_data_path,
         )
@@ -850,6 +1022,11 @@ class PreProcessedZStitchingConfiguration(ZStitchingConfiguration):
                     config[STITCHING_SECTION].get(STITCHING_KERNELS_EXTRA_PARAMS, {}),
                 )
             ),
+            alignment_axis_2=AlignmentAxis2.from_value(
+                config[STITCHING_SECTION].get(ALIGNMENT_AXIS_2_FIELD, AlignmentAxis2.CENTER)
+            ),
+            pad_mode=config[STITCHING_SECTION].get(PAD_MODE_FIELD, "constant"),
+            normalization_by_sample=NormalizationBySample.from_dict(config.get(NORMALIZATION_BY_SAMPLE_SECTION, {})),
         )
 
 
@@ -862,6 +1039,7 @@ class PostProcessedZStitchingConfiguration(ZStitchingConfiguration):
     input_volumes: tuple = ()  # tuple of VolumeBase
     output_volume: Optional[VolumeIdentifier] = None
     voxel_size: Optional[float] = None
+    alignment_axis_1: AlignmentAxis1 = AlignmentAxis1.CENTER
 
     @property
     def stitching_type(self) -> StitchingType:
@@ -909,16 +1087,22 @@ class PostProcessedZStitchingConfiguration(ZStitchingConfiguration):
         if len(self.input_volumes) == 0:
             raise ValueError("No input volume provided. Cannot settle slices")
         if slices is None:
-            slices = slice(0, self.input_volumes[0].get_volume_shape()[1], 1)
+            # before alignment was existing
+            # slices = slice(0, self.input_volumes[0].get_volume_shape()[1], 1)
+            slices = slice(
+                0,
+                max([volume.get_volume_shape()[1] for volume in self.input_volumes]),
+                1,
+            )
             n_slices = slices.stop
         if isinstance(slices, slice):
             # force slices indices to be positive
             start = slices.start
             if start < 0:
-                start += self.input_volumes[0].get_volume_shape()[1] + 1
+                start += max([volume.get_volume_shape()[1] for volume in self.input_volumes]) + 1
             stop = slices.stop
             if stop < 0:
-                stop += self.input_volumes[0].get_volume_shape()[1] + 1
+                stop += max([volume.get_volume_shape()[1] for volume in self.input_volumes]) + 1
             step = slices.step
             if step is None:
                 step = 1
@@ -987,6 +1171,14 @@ class PostProcessedZStitchingConfiguration(ZStitchingConfiguration):
                     config[STITCHING_SECTION].get(STITCHING_KERNELS_EXTRA_PARAMS, {}),
                 )
             ),
+            alignment_axis_1=AlignmentAxis1.from_value(
+                config[STITCHING_SECTION].get(ALIGNMENT_AXIS_1_FIELD, AlignmentAxis1.CENTER)
+            ),
+            alignment_axis_2=AlignmentAxis2.from_value(
+                config[STITCHING_SECTION].get(ALIGNMENT_AXIS_2_FIELD, AlignmentAxis2.CENTER)
+            ),
+            pad_mode=config[STITCHING_SECTION].get(PAD_MODE_FIELD, "constant"),
+            normalization_by_sample=NormalizationBySample.from_dict(config.get(NORMALIZATION_BY_SAMPLE_SECTION, {})),
         )
 
     def to_dict(self):
@@ -1007,6 +1199,9 @@ class PostProcessedZStitchingConfiguration(ZStitchingConfiguration):
                     if self.output_volume is not None
                     else "",
                 },
+                STITCHING_SECTION: {
+                    ALIGNMENT_AXIS_1_FIELD: self.alignment_axis_1.value,
+                },
             },
         )
 
@@ -1022,6 +1217,13 @@ class PostProcessedZStitchingConfiguration(ZStitchingConfiguration):
                         "type": "required",
                     },
                 },
+                STITCHING_SECTION: {
+                    ALIGNMENT_AXIS_1_FIELD: {
+                        "default": "center",
+                        "help": f"alignment to apply over axis 1 if needed. Valid values are {AlignmentAxis1.values()}",
+                        "type": "advanced",
+                    }
+                },
             },
         )
 

nabu/stitching/definitions.py

@@ -0,0 +1,6 @@
+from silx.utils.enum import Enum as _Enum
+
+
+class StitchingType(_Enum):
+    Z_PREPROC = "z-preproc"
+    Z_POSTPROC = "z-postproc"

nabu/stitching/frame_composition.py

@@ -34,8 +34,10 @@ class ZFrameComposition(_FrameCompositionBase):
             )
 
     def compose(self, output_frame: numpy.ndarray, input_frames: tuple):
-        if not output_frame.ndim == 2:
-            raise TypeError(f"output_frame is expected to be 2D and not {output_frame.ndim}")
+        if not output_frame.ndim in (2, 3):
+            raise TypeError(
+                f"output_frame is expected to be 2D (gray scale) or 3D (RGB(A)) and not {output_frame.ndim}"
+            )
         for (
             global_start_y,
             global_end_y,

nabu/stitching/overlap.py

@@ -29,11 +29,15 @@ __date__ = "10/05/2022"
 
 
 import numpy
-from typing import Optional
+import logging
+from typing import Optional, Union
 from silx.utils.enum import Enum as _Enum
 from nabu.misc import fourier_filters
 from scipy.fft import rfftn as local_fftn
 from scipy.fft import irfftn as local_ifftn
+from tomoscan.utils.geometry import BoundingBox1D
+
+_logger = logging.getLogger(__name__)
 
 
 class OverlapStitchingStrategy(_Enum):
@@ -211,7 +215,7 @@ def compute_image_minimum_divergence(img_1: numpy.ndarray, img_2: numpy.ndarray,
     It split the two images into two parts: high frequency and low frequency.
 
     The two low frequency part will be stitched using a 'sinusoidal' / cosinus weights approach.
-    When the two high frequency part will be stitched by taking the lower divergent pixels
+    When the two high frequency parts will be stitched by taking the lower divergent pixels
     """
 
     # split low and high frequencies
@@ -268,10 +272,102 @@ def compute_image_minimum_divergence(img_1: numpy.ndarray, img_2: numpy.ndarray,
 
 def compute_image_higher_signal(img_1: numpy.ndarray, img_2: numpy.ndarray):
     """
-    the higher signal will pick pixel on the image have the higher signal.
+    the higher signal will pick pixel on the image having the higher signal.
     A use case is that if there is some artefacts on images which creates stripes (from scintillator artefacts for example)
     it could be removed from this method
     """
     # note: to be think about. But maybe it can be interesting to rescale img_1 and img_2
     # to ge something more coherent
     return numpy.where(img_1 >= img_2, img_1, img_2)
+
+
+def check_overlaps(frames: Union[tuple, numpy.ndarray], positions: tuple, axis: int, raise_error: bool):
+    """
+    check over frames if there is a single overlap other juxtaposed frames (at most and at least)
+
+    :param frames: liste of ordered / sorted frames along axis to test (from higher to lower)
+    :param positions: positions of frames in 3D space as (position axis 0, position axis 1, position axis 2)
+    :param axis: axis to check
+    :param raise_error: if True then raise an error if two frames don't have at least and at most one overlap. Else log an error
+    """
+    if not isinstance(frames, (tuple, numpy.ndarray)):
+        raise TypeError(f"frames is expected to be a tuple or a numpy array. Get {type(frames)} instead")
+    if not isinstance(positions, tuple):
+        raise TypeError(f"positions is expected to be a tuple. Get {type(positions)} instead")
+    assert isinstance(axis, int), "axis is expected to be an int"
+    assert isinstance(raise_error, bool), "raise_error is expected to be a bool"
+
+    def treat_error(error_msg: str):
+        if raise_error:
+            raise ValueError(error_msg)
+        else:
+            _logger.error(raise_error)
+
+    # convert each frame to appropriate bounding box according to the axis
+    def convert_to_bb(frame: numpy.ndarray, position: tuple, axis: int):
+        assert isinstance(axis, int)
+        assert isinstance(position, tuple), f"position expected a tuple. Get {type(position)} instead"
+        start_frame = position[axis] - frame.shape[axis] // 2
+        end_frame = start_frame + frame.shape[axis]
+        return BoundingBox1D(start_frame, end_frame)
+
+    bounding_boxes = {
+        convert_to_bb(frame=frame, position=position, axis=axis): position for frame, position in zip(frames, positions)
+    }
+
+    def get_frame_index(my_bb) -> str:
+        bb_index = tuple(bounding_boxes.keys()).index(my_bb) + 1
+        if bb_index in (1, 21, 31):
+            return f"{bb_index}st"
+        elif bb_index in (2, 22, 32):
+            return f"{bb_index}nd"
+        elif bb_index == (3, 23, 33):
+            return f"{bb_index}rd"
+        else:
+            return f"{bb_index}th"
+
+    # check that theres an overlap between two juxtaposed bb (or frame at the end)
+    all_bounding_boxes = tuple(bounding_boxes.keys())
+    bb_with_expected_overlap = [
+        (bb_frame, bb_next_frame) for bb_frame, bb_next_frame in zip(all_bounding_boxes[:-1], all_bounding_boxes[1:])
+    ]
+
+    for bb_pair in bb_with_expected_overlap:
+        bb_frame, bb_next_frame = bb_pair
+        if bb_frame.max < bb_next_frame.min:
+            treat_error(f"provided frames seems un sorted (from the higher to the lower)")
+        if bb_frame.min < bb_next_frame.min:
+            treat_error(
+                f"Seems like {get_frame_index(bb_frame)} frame is fully overlaping with frame {get_frame_index(bb_next_frame)}"
+            )
+        if bb_frame.get_overlap(bb_next_frame) is None:
+            treat_error(
+                f"no overlap found between two juxtaposed frames - {get_frame_index(bb_frame)} and {get_frame_index(bb_next_frame)}"
+            )
+
+    # check there is no overlap between none juxtaposed bb
+    def pick_all_none_juxtaposed_bb(index, my_bounding_boxes: tuple):
+        """return all the bounding boxes to check for the index 'index':
+
+        :return: (tested_bounding_box, bounding_boxes_to_test)
+        """
+        my_bounding_boxes = {bb_index: bb for bb_index, bb in enumerate(my_bounding_boxes)}
+        bounding_boxes = dict(
+            filter(
+                lambda pair: pair[0] not in (index - 1, index, index + 1),
+                my_bounding_boxes.items(),
+            )
+        )
+        return my_bounding_boxes[index], bounding_boxes.values()
+
+    bb_without_expected_overlap = [
+        pick_all_none_juxtaposed_bb(index, all_bounding_boxes) for index in range(len(all_bounding_boxes))
+    ]
+
+    for bb_pair in bb_without_expected_overlap:
+        bb_frame, bb_not_juxtaposed_frames = bb_pair
+        for bb_not_juxtaposed_frame in bb_not_juxtaposed_frames:
+            if bb_frame.get_overlap(bb_not_juxtaposed_frame) is not None:
+                treat_error(
+                    f"overlap found between two frames not juxtaposed - {bounding_boxes[bb_frame]} and {bounding_boxes[bb_not_juxtaposed_frame]}"
+                )

nabu/stitching/sample_normalization.py

@@ -0,0 +1,60 @@
+import numpy
+from silx.utils.enum import Enum as _Enum
+
+
+class SampleSide(_Enum):
+    LEFT = "left"
+    RIGHT = "right"
+
+
+class Method(_Enum):
+    MEAN = "mean"
+    MEDIAN = "median"
+
+
+def normalize_frame(
+    frame: numpy.ndarray, side: SampleSide, method: Method, sample_width: int = 50, margin_before_sample: int = 0
+):
+    """
+    normalize the frame from a sample section picked at the left of the right of the frame
+
+    :param frame: frame to normalize
+    :param SampleSide side: side to pick the sample
+    :param Method method: normalization method
+    :param int sample_width: sample width
+    :param int margin: margin before the sampling area
+    """
+    if not isinstance(frame, numpy.ndarray):
+        raise TypeError(f"Frame is expected to be a 2D numpy array.")
+    if frame.ndim != 2:
+        raise TypeError(f"Frame is expected to be a 2D numpy array. Get {frame.ndim}D")
+    side = SampleSide.from_value(side)
+    method = Method.from_value(method)
+
+    if frame.shape[1] < sample_width + margin_before_sample:
+        raise ValueError(
+            f"frame width ({frame.shape[1]}) < sample_width + margin ({sample_width + margin_before_sample})"
+        )
+
+    # create sample
+    if side is SampleSide.LEFT:
+        sample_start = margin_before_sample
+        sample_end = margin_before_sample + sample_width
+        sample = frame[:, sample_start:sample_end]
+    elif side is SampleSide.RIGHT:
+        sample_start = frame.shape[1] - (sample_width + margin_before_sample)
+        sample_end = frame.shape[1] - margin_before_sample
+        sample = frame[:, sample_start:sample_end]
+    else:
+        raise ValueError(f"side {side.value} not handled")
+
+    # do normalization
+    if method is Method.MEAN:
+        normalization_array = numpy.mean(sample, axis=1)
+    elif method is Method.MEDIAN:
+        normalization_array = numpy.median(sample, axis=1)
+    else:
+        raise ValueError(f"side {side.value} not handled")
+    for line in range(normalization_array.shape[0]):
+        frame[line, :] -= normalization_array[line]
+    return frame