ultrasound_metrics.metrics.sharpness
====================================

.. py:module:: ultrasound_metrics.metrics.sharpness

.. autoapi-nested-parse::

   Image sharpness metrics, such as Tenengrad.



Functions
---------

.. autoapisummary::

   ultrasound_metrics.metrics.sharpness.tenengrad


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

.. py:function:: tenengrad(image: jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, height width], roi: Optional[jaxtyping.Bool[ultrasound_metrics._utils.array_api.ArrayAPIObj, height width]] = None, sobel_kernel: Optional[jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, kernel_height kernel_width]] = None, reduce_sum: bool = True, normalize: bool = False) -> ultrasound_metrics._utils.array_api.ArrayAPIObj

   Compute the Tenengrad sharpness metric of an image.

   Tenengrad sharpness [1][2] is a robust and accurate measure for focusing quality
   that performs well in digital photography. The metric applies a lateral
   Sobel filter to detect edges primarily in the horizontal direction, then
   sums the magnitude of the filtered response within a region of interest.

   This implementation is particularly suitable for ultrasound images where
   the lateral focusing quality is of primary interest.

   :param image: Input image for sharpness calculation. Should be a 2D array.
   :param roi: Binary mask defining the region of interest. If provided, only pixels
               where roi is True (or non-zero) will contribute to the sharpness metric.
               If None, the entire image is used. Can be boolean or numeric array.
   :param sobel_kernel: Custom convolution kernel to use for edge detection. If None, uses the
                        default lateral Sobel filter optimized for ultrasound applications [3]:
                        ```
                        [ 1  0 -1]
                        [ 2  0 -2]
                        [ 1  0 -1]
                        ```
                        Custom kernels should be 2D arrays with odd dimensions.
   :param reduce_sum: If True (default), returns the summed Tenengrad value as a scalar.
                      If False, returns the magnitude image after Sobel filtering for visualization.
   :param normalize: If True and reduce_sum=True, returns the mean instead of sum to normalize by ROI size.
                     This makes the metric independent of ROI area. Default is False.

   :returns: If reduce_sum=True: The Tenengrad sharpness value (scalar). Higher values indicate
             sharper images. If normalize=True, returns mean instead of sum.
             If reduce_sum=False: The magnitude image after Sobel filtering (same shape as input).
   :rtype: ndarray

   .. rubric:: Notes

   The Tenengrad metric is computed as:

   .. math::

       F = \sum |G(r)|

   where :math:`G(r)` is the result of convolving the image with the lateral Sobel
   filter, and the sum is taken over all pixels r in the region of interest.

   For ultrasound applications, it's recommended to exclude near-field
   artifacts by using an ROI that begins at approximately 10mm depth.

   The Tenengrad metric was originally developed for autofocus [1]_ and has been
   extensively studied for digital photography [2]_. The lateral Sobel kernel
   used here follows the ultrasound-specific implementation in [3]_.

   .. rubric:: References

   .. [1] Groen, F. C., Young, I. T., & Ligthart, G. (1985). A comparison of
          different focus functions for use in autofocus algorithms.
          Cytometry, 6(2), 81-91.
   .. [2] Mir, R. N., et al. (2014). An extensive study of focus measures for
          digital photography. In Proc. Int. Conf. Comput. Sci. Inf. Technol.
   .. [3] Vr˚alstad, A.E. et al. (2024). Coherence Based Sound Speed Aberration
          Correction — with clinical validation in fetal ultrasound. arXiv:2411.16551