ultrasound_metrics.metrics.sll
==============================

.. py:module:: ultrasound_metrics.metrics.sll

.. autoapi-nested-parse::

   Side Lobe Level (SLL) measurement for point targets in ultrasound images.



Attributes
----------

.. autoapisummary::

   ultrasound_metrics.metrics.sll.IMG_DIM


Functions
---------

.. autoapisummary::

   ultrasound_metrics.metrics.sll.compute_sll
   ultrasound_metrics.metrics.sll.find_one_side_side_lobe_amplitude
   ultrasound_metrics.metrics.sll.measure_half_width_half_max
   ultrasound_metrics.metrics.sll.measure_sll
   ultrasound_metrics.metrics.sll.measure_sll_of_target


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

.. py:function:: compute_sll(img: numpy.typing.NDArray[numpy.floating], roi_indices: Optional[numpy.typing.NDArray[numpy.integer]] = None, dims_to_measure: Optional[numpy.typing.NDArray[numpy.integer]] = None, target_radius: Optional[int] = None, show_plot: bool = False) -> tuple[Optional[float], Ellipsis]

   Compute the side lobe level (SLL) of a point target.

   :param img: The input image.
   :param roi_indices: Region of interest in the form of array indices.
   :param dims_to_measure: List of dimensions across which to measure the SLL.
                           If `None`, then the default space dimensions of the bmode
                           image are used (dimensions [1,2,3]). If any of these
                           dimensions are singleton, then they are excluded from
                           consideration.
   :param target_radius: Expected radius of the target used to find max point around
                         the max detected within the ROI. This is used in case the
                         target is registered but the position of the max value is
                         not located within the ROI. If `None`, then then no search
                         for the max value outside the roi is performed.
   :param show_plot: Whether to display plots for visualization.

   :returns: The side lobe level of the point target over all input and
             non-singleton dimensions. The side lobe level is calculated as
             sll = 10*log10((side lobe peak amplitude)/(main lobe peak amplitude)).
   :rtype: tuple


.. py:function:: find_one_side_side_lobe_amplitude(pixel_array: numpy.typing.NDArray[numpy.floating]) -> float

   Find the side lobe amplitude on one side of the main lobe.

   :param pixel_array: 1D pixel array.

   :returns: Amplitude of the first detected side lobe peak.
   :rtype: float


.. py:function:: measure_half_width_half_max(pixel_array: numpy.typing.NDArray[numpy.floating], max_val: float, use_interp: bool) -> float

   Measure half-width at half-maximum of a 1D array.

   :param pixel_array: 1D pixel array.
   :param max_val: Maximum value in the array.
   :param use_interp: Whether to use linear interpolation for sub-pixel precision.

   :returns: Half-width at half-maximum.
   :rtype: float


.. py:function:: measure_sll(im_line: numpy.typing.NDArray[numpy.floating], max_idx: int, max_val: float, use_interp: bool = True) -> float

   Measure the side lobe level (SLL) of the input pixel array.

   The half-max point is detected and used as a starting index
   for detecting the next occurring peak in the line.  This way,
   sub-peaks within the main lobe will not be accidentally
   counted as the side lobe. The side lobe peak is measured
   on each side of the PSF and then the maximum one is used for
   computing the SLL.

   :param im_line: The 1-D orthogonal line across the target.
   :param max_idx: The index of the maximum position in the ROI.
   :param max_val: The value of the maximum position in the ROI.
   :param use_interp: Whether to use linear interpolation to obtain sub-pixel
                      precision for detection of the half-max point.

   :returns: The side lobe level is calculated as
             sll = 10*log10((side lobe peak amplitude)/(main lobe peak amplitude)).
   :rtype: float


.. py:function:: measure_sll_of_target(img: numpy.typing.NDArray[numpy.floating], img_max_idx: tuple[int, Ellipsis], show_plot: bool) -> numpy.typing.NDArray[numpy.floating]

   Measure side lobe level across all dimensions of the target.

   :param img: Input image array.
   :param img_max_idx: Index of the maximum value in the image.
   :param show_plot: Whether to display plots for visualization.

   :returns: Side lobe level for each dimension.
   :rtype: ndarray


.. py:data:: IMG_DIM
   :value: 4