microcorrelate.utils
====================

.. py:module:: microcorrelate.utils

.. autoapi-nested-parse::

   This module is a placeholder for the utils module of the microcorrelate package.



Functions
---------

.. autoapisummary::

   microcorrelate.utils.deep_items
   microcorrelate.utils.extract_integers
   microcorrelate.utils.find_common_vals
   microcorrelate.utils.flatten_dict
   microcorrelate.utils.get_crop_idx
   microcorrelate.utils.resample_to_spacing
   microcorrelate.utils.round_up_multiple
   microcorrelate.utils.vprint


Module Contents
---------------

.. py:function:: deep_items(d: dict[str, Any], prefix: tuple[str, Ellipsis] = ()) -> Iterator[tuple[str, Any]]

   Recursively yield (key.path, value) for all non-dict values
   in a nested dictionary.


.. py:function:: extract_integers(base_path: pathlib.Path, regex_pattern: str, glob_pattern: str) -> list[int]

   Extract integers matching the group in a regex pattern from filenames matching
   the glob pattern


.. py:function:: find_common_vals(d1: dict[str, Any], d2: dict[str, Any]) -> dict[str, Any]

   Returns a dictionary with the keys share the same value between the two input
   dictionaries


.. py:function:: flatten_dict(d: dict[str, Any]) -> dict[str, Any]

   Flatten a nested dictionary. Key hierarchy is preserved by assigning new
   keys as 'a.b.c'.


.. py:function:: get_crop_idx(mask: numpy.ndarray, margin: int = 0) -> tuple[slice, Ellipsis]

   Compute array slices to crop a numpy array to the bounding box of non-zero mask regions.

   Useful for removing empty borders (e.g. black frames from image stitching).

   :param mask: 2D binary mask where non-zero pixels define the region of interest.
   :type mask: np.ndarray
   :param margin: Number of pixels to expand the bounding box on each side, by default 0.
                  Clamped to array boundaries.
   :type margin: int, optional

   :returns: A tuple of slices ``(row_slice, col_slice)`` that can be used to index
             a numpy array directly, e.g. ``image[get_crop_idx(mask)]``.
   :rtype: tuple[slice, ...]

   .. rubric:: Examples

   .. code-block:: python

       cropped = image[get_crop_idx(mask, margin=10)]


.. py:function:: resample_to_spacing(array: numpy.ndarray, input_spacing: float | tuple[float, float], output_spacing: float | tuple[float, float], channel_axis: int | None = None) -> numpy.ndarray

   Resample an array to a target pixel spacing.

   :param array: Input image array.
   :type array: np.ndarray
   :param input_spacing: Current pixel spacing. A scalar is treated as isotropic.
   :type input_spacing: float or tuple of float
   :param output_spacing: Target pixel spacing. A scalar is treated as isotropic.
   :type output_spacing: float or tuple of float
   :param channel_axis: Axis containing channels, excluded from resampling. Default is None.
   :type channel_axis: int or None, optional

   :returns: Resampled array with the same dtype as the input.
   :rtype: np.ndarray


.. py:function:: round_up_multiple(num: int, base: int) -> int

   Round up a number to a multiple of base


.. py:function:: vprint(text: str, verbose: bool) -> None

   Helper function for cleanly handling print statements with a verbose option