median_filter.py

Go to the documentation of this file.

import ctypes
from typing import Union
 
from ids_peak_icv import lib_loader
from ids_peak_icv.backend.utils import execute_and_map_return_codes
from ids_peak_icv.datatypes.image import Image, _check_and_get_icv_image
from ids_peak_common.datatypes.geometry.size import Size
from ids_peak_ipl import ids_peak_ipl
 
 
class MedianFilter:
    """!
    @brief
    Class for applying a median filter to an image.
 
    The median filter is a non-linear, spatial filter
    used to reduce impulsive noise in images.
    It replaces each pixel
    with the median value
    of the pixels in its local neighborhood,
    defined by the specified kernel size.
    The kernel size corresponds to a square neighborhood
    (size x size grid) around each pixel,
    where the median is calculated.
 
    This process preserves edges better than linear smoothing filters
    while effectively removing salt-and-pepper noise
    and small image artifacts.
    A larger kernel removes more noise
    but also reduces image detail.
 
    @since ids_peak_icv 1.1
 
    @ingroup ids_peak_icv_python_filters
    """
 
    def __init__(self) -> None:
        """!
        @brief
        Initializes a MedianFilter instance
        with a default kernel size of 3 (3 × 3 neighborhood).
 
        @since ids_peak_icv 1.1
        """
        self._kernel_size = 3
 
    @property
    def kernel_size(self) -> int:
        """!
        @brief
        The size of the kernel.
 
        @since ids_peak_icv 1.1
        """
        return self._kernel_size
 
    @kernel_size.setter
    def kernel_size(self, kernel_size: int) -> None:
        """!
        @brief
        Sets the size of the kernel used for the median filter.
 
        The size of the kernel
        must be an odd number
        greater than 1
        and smaller than the image dimensions.
        The kernel size defines the size of the neighborhood
        (in a size × size grid)
        used to calculate the median for each pixel.
 
        A larger kernel removes more noise
        but also reduces image detail.
 
        @param kernel_size:
            Size of the kernel used for the median filter.
 
        @since ids_peak_icv 1.1
        """
        self._kernel_size = kernel_size
 
    def process(self, image: Union[Image, ids_peak_ipl.Image]) -> Image:
        """!
        @brief
        Applies the median filter to the specified image.
 
        @supportedPixelformats{MedianFilter}
 
        @note
            Processes the entire image,
            ignoring any specified image region.
 
        @param image:
            The image to process.
 
        @return
            The filtered image.
 
        @exception NotSupportedException:
            The pixel format is unsupported.
        @exception NotPossibleException:
            The kernel size must be an odd number greater than 1.
        @exception OutOfRangeException:
            The kernel size exceeds the image dimensions.
 
        @since ids_peak_icv 1.1
        """
        _image = _check_and_get_icv_image(image)
 
        output_image = Image.create_from_pixel_format_and_size(_image._pixel_format,
                                                               Size(_image.width, _image.height))
 
        execute_and_map_return_codes(lib_loader.dll().peak_icv_Filter_Image_Median,
                                     _image._handle,
                                     ctypes.c_size_t(self._kernel_size),
                                     output_image._handle)
 
        return output_image