stouputils 1.14.0__py3-none-any.whl

stouputils/data_science/data_processing/image/denoise.py

@@ -0,0 +1,378 @@
+
+# pyright: reportUnknownMemberType=false
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnknownArgumentType=false
+
+# Imports
+from typing import Literal
+
+from .common import Any, NDArray, check_image, cv2, np
+from ....ctx import Muffle
+
+
+# Functions
+def nlm_denoise_image(
+	image: NDArray[Any],
+	h: float = 10,
+	template_window_size: int = 7,
+	search_window_size: int = 21,
+	ignore_dtype: bool = False
+) -> NDArray[Any]:
+	""" Apply Non-Local Means denoising to an image.
+
+	This algorithm replaces each pixel with an average of similar pixels
+	found anywhere in the image. It is highly effective for removing Gaussian noise
+	while preserving edges and details.
+
+	Args:
+		image                  (NDArray[Any]):  Image to denoise
+		h                      (float):       Filter strength (higher values remove more noise but may blur details)
+		template_window_size   (int):         Size of the template window for patch comparison (should be odd)
+		search_window_size     (int):         Size of the search window (should be odd)
+		ignore_dtype           (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Denoised image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> denoised = nlm_denoise_image(image.astype(np.uint8), 10, 3, 5)
+	>>> denoised.shape == image.shape
+	True
+
+	>>> ## Test with colored image
+	>>> rgb = np.random.randint(0, 256, (10, 10, 3), dtype=np.uint8)
+	>>> denoised_rgb = nlm_denoise_image(rgb, 10, 5, 11)
+	>>> denoised_rgb.shape == rgb.shape
+	True
+
+	>>> ## Test invalid inputs
+	>>> nlm_denoise_image("not an image", 10)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> nlm_denoise_image(image.astype(np.uint8), "10")
+	Traceback (most recent call last):
+		...
+	AssertionError: h must be a number, got <class 'str'>
+
+	>>> nlm_denoise_image(image.astype(np.uint8), 10, 4)
+	Traceback (most recent call last):
+		...
+	AssertionError: template_window_size must be odd, got 4
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(h, float | int), f"h must be a number, got {type(h)}"
+	assert template_window_size % 2 == 1, f"template_window_size must be odd, got {template_window_size}"
+	assert search_window_size % 2 == 1, f"search_window_size must be odd, got {search_window_size}"
+
+	# Apply Non-Local Means denoising based on image type
+	if len(image.shape) == 2 or image.shape[2] == 1:  # Grayscale
+		return cv2.fastNlMeansDenoising(
+			image, None, float(h), template_window_size, search_window_size
+		)
+	else:  # Color
+		return cv2.fastNlMeansDenoisingColored(
+			image, None, float(h), float(h), template_window_size, search_window_size
+		)
+
+
+def bilateral_denoise_image(
+	image: NDArray[Any],
+	d: int = 9,
+	sigma_color: float = 75,
+	sigma_space: float = 75,
+	ignore_dtype: bool = False
+) -> NDArray[Any]:
+	""" Apply Bilateral Filter denoising to an image.
+
+	Bilateral filtering smooths images while preserving edges by considering
+	both spatial proximity and color similarity between pixels.
+
+	Args:
+		image         (NDArray[Any]):  Image to denoise
+		d             (int):         Diameter of each pixel neighborhood
+		sigma_color   (float):       Filter sigma in the color space
+		sigma_space   (float):       Filter sigma in the coordinate space
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Denoised image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> denoised = bilateral_denoise_image(image.astype(np.uint8))
+	>>> denoised.shape == image.shape
+	True
+
+	>>> ## Test with colored image
+	>>> rgb = np.random.randint(0, 256, (10, 10, 3), dtype=np.uint8)
+	>>> denoised_rgb = bilateral_denoise_image(rgb)
+	>>> denoised_rgb.shape == rgb.shape
+	True
+
+	>>> ## Test invalid inputs
+	>>> bilateral_denoise_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> bilateral_denoise_image(image.astype(np.uint8), "9")
+	Traceback (most recent call last):
+		...
+	AssertionError: d must be a number, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(d, int), f"d must be a number, got {type(d)}"
+	assert isinstance(sigma_color, float | int), f"sigma_color must be a number, got {type(sigma_color)}"
+	assert isinstance(sigma_space, float | int), f"sigma_space must be a number, got {type(sigma_space)}"
+
+	# Apply bilateral filter
+	return cv2.bilateralFilter(image, d, sigma_color, sigma_space)
+
+
+def tv_denoise_image(
+	image: NDArray[Any],
+	weight: float = 0.1,
+	iterations: int = 30,
+	method: Literal["chambolle", "bregman"] = "chambolle",
+	ignore_dtype: bool = False
+) -> NDArray[Any]:
+	""" Apply Total Variation denoising to an image.
+
+	Total Variation denoising removes noise while preserving sharp edges by
+	minimizing the total variation of the image.
+
+	Args:
+		image         (NDArray[Any]):  Image to denoise
+		weight        (float):       Denoising weight (higher values remove more noise)
+		iterations    (int):         Number of iterations
+		method        (str):         Method to use ("chambolle" or "bregman")
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Denoised image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> denoised = tv_denoise_image(image.astype(np.uint8), 0.1, 30)
+	>>> denoised.shape == image.shape
+	True
+
+	>>> ## Test invalid inputs
+	>>> tv_denoise_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> tv_denoise_image(image.astype(np.uint8), "0.1")
+	Traceback (most recent call last):
+		...
+	AssertionError: weight must be a number, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(weight, float | int), f"weight must be a number, got {type(weight)}"
+	assert isinstance(iterations, int), f"iterations must be an integer, got {type(iterations)}"
+	assert method in ["chambolle", "bregman"], f"method must be 'chambolle' or 'bregman', got {method}"
+
+	# Import skimage for TV denoising
+	try:
+		from skimage.restoration import denoise_tv_bregman, denoise_tv_chambolle
+	except ImportError as e:
+		raise ImportError("scikit-image is required for TV denoising. Install with 'pip install scikit-image'") from e
+
+	# Normalize image to [0, 1] for skimage functions
+	is_int_type = np.issubdtype(image.dtype, np.integer)
+	if is_int_type:
+		img_norm = image.astype(np.float32) / 255.0
+	else:
+		img_norm = image.astype(np.float32)
+
+	# Apply TV denoising based on method
+	if method == "chambolle":
+		denoised = denoise_tv_chambolle(
+			img_norm,
+			weight=weight,
+			max_num_iter=iterations,
+			channel_axis=-1 if len(image.shape) > 2 else None
+		)
+	else:
+		denoised = denoise_tv_bregman(
+			img_norm,
+			weight=weight,
+			max_num_iter=iterations,
+			channel_axis=-1 if len(image.shape) > 2 else None
+		)
+
+	# Convert back to original data type
+	if is_int_type:
+		denoised = np.clip(denoised * 255, 0, 255).astype(image.dtype)
+	else:
+		denoised = denoised.astype(image.dtype)
+
+	return denoised
+
+
+def wavelet_denoise_image(
+	image: NDArray[Any],
+	sigma: float | None = None,
+	wavelet: str = 'db1',
+	mode: str = 'soft',
+	wavelet_levels: int = 3,
+	ignore_dtype: bool = False
+) -> NDArray[Any]:
+	""" Apply Wavelet denoising to an image.
+
+	Wavelet denoising decomposes the image into wavelet coefficients,
+	applies thresholding, and reconstructs the image with reduced noise.
+
+	Args:
+		image          (NDArray[Any]):  Image to denoise
+		sigma          (float):       Noise standard deviation. If None, it's estimated from the image.
+		wavelet        (str):         Wavelet to use
+		mode           (str):         Thresholding mode ('soft' or 'hard')
+		wavelet_levels (int):         Number of wavelet decomposition levels
+		ignore_dtype   (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Denoised image
+
+	>>> ## Basic tests
+	>>> import importlib.util
+	>>> has_pywt = importlib.util.find_spec('pywt') is not None
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> if has_pywt:
+	...     denoised = wavelet_denoise_image(image.astype(np.uint8))
+	...     denoised.shape == image.shape
+	... else:
+	...     True
+	True
+
+	>>> ## Test invalid inputs
+	>>> wavelet_denoise_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> wavelet_denoise_image(image.astype(np.uint8), wavelet=123)
+	Traceback (most recent call last):
+		...
+	AssertionError: wavelet must be a string, got <class 'int'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	if sigma is not None:
+		assert isinstance(sigma, float | int), f"sigma must be a number or None, got {type(sigma)}"
+	assert isinstance(wavelet, str), f"wavelet must be a string, got {type(wavelet)}"
+	assert mode in ["soft", "hard"], f"mode must be 'soft' or 'hard', got {mode}"
+	assert isinstance(wavelet_levels, int), f"wavelet_levels must be an integer, got {type(wavelet_levels)}"
+
+	# Import skimage for wavelet denoising
+	try:
+		from skimage.restoration import denoise_wavelet
+
+		# Check for PyWavelets dependency specifically
+		try:
+			import pywt  # type: ignore
+		except ImportError as e:
+			raise ImportError(
+				"PyWavelets (pywt) is required for wavelet denoising. Install with 'pip install PyWavelets'", name="pywt"
+			) from e
+	except ImportError as e:
+		if e.name != "pywt":
+			raise ImportError("skimage is required for wavelet denoising. Install with 'pip install scikit-image'") from e
+		else:
+			raise e
+
+	# Normalize image to [0, 1] for skimage functions
+	is_int_type = np.issubdtype(image.dtype, np.integer)
+	if is_int_type:
+		img_norm = image.astype(np.float32) / 255.0
+	else:
+		img_norm = image.astype(np.float32)
+
+	# Apply wavelet denoising
+	with Muffle(mute_stderr=True):
+		denoised = denoise_wavelet(
+			img_norm, sigma=sigma, wavelet=wavelet, mode=mode,
+			wavelet_levels=wavelet_levels, channel_axis=-1 if len(image.shape) > 2 else None
+		)
+
+	# Convert back to original data type
+	if is_int_type:
+		denoised = np.clip(denoised * 255, 0, 255).astype(image.dtype)
+	else:
+		denoised = denoised.astype(image.dtype)
+
+	return denoised
+
+
+def adaptive_denoise_image(
+	image: NDArray[Any],
+	method: Literal["nlm", "bilateral", "tv", "wavelet"] | str = "nlm",
+	strength: float = 0.5,
+	ignore_dtype: bool = False
+) -> NDArray[Any]:
+	""" Apply adaptive denoising to an image using the specified method.
+
+	This is a convenience function that selects the appropriate denoising method
+	and parameters based on the image content and noise level.
+
+	Args:
+		image         (NDArray[Any]):  Image to denoise
+		method        (str):         Denoising method to use ("nlm", "bilateral", "tv", or "wavelet")
+		strength      (float):       Denoising strength (0.0 to 1.0)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Denoised image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> denoised = adaptive_denoise_image(image.astype(np.uint8), "nlm", 0.5)
+	>>> denoised.shape == image.shape
+	True
+
+	>>> ## Test invalid inputs
+	>>> adaptive_denoise_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> adaptive_denoise_image(image.astype(np.uint8), "invalid_method")
+	Traceback (most recent call last):
+		...
+	AssertionError: method must be one of: nlm, bilateral, tv, wavelet
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	valid_methods = ["nlm", "bilateral", "tv", "wavelet"]
+	assert method in valid_methods, f"method must be one of: {', '.join(valid_methods)}"
+	assert isinstance(strength, float | int), f"strength must be a number, got {type(strength)}"
+	assert 0 <= strength <= 1, f"strength must be between 0 and 1, got {strength}"
+
+	# Scale parameters based on strength
+	if method == "bilateral":
+		# sigma parameters scale from 30 (minimal) to 150 (strong)
+		sigma = 30 + strength * 120
+		return bilateral_denoise_image(
+			image, d=9, sigma_color=sigma, sigma_space=sigma, ignore_dtype=ignore_dtype
+		)
+
+	elif method == "tv":
+		# weight scales from 0.05 (minimal) to 0.5 (strong)
+		weight = 0.05 + strength * 0.45
+		return tv_denoise_image(
+			image, weight=weight, iterations=30, ignore_dtype=ignore_dtype
+		)
+
+	elif method == "wavelet":
+		# We'll estimate sigma from the image, but scale wavelet levels
+		wavelet_levels = max(2, min(5, int(2 + strength * 3)))
+		return wavelet_denoise_image(
+			image, wavelet_levels=wavelet_levels, ignore_dtype=ignore_dtype
+		)
+
+	else:
+		# h parameter scales from 5 (minimal) to 20 (strong)
+		h = 5 + strength * 15
+		return nlm_denoise_image(image, h=h, ignore_dtype=ignore_dtype)

stouputils/data_science/data_processing/image/histogram_equalization.py

@@ -0,0 +1,123 @@
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from typing import Literal
+
+from .common import Any, NDArray, check_image, cv2, np
+
+# Constants
+VALID_SPACES: list[str] = ["lab", "ycbcr", "hsv"]
+
+# Color space conversion constants
+COLOR_SPACE_CONSTANTS: dict[str, tuple[int, int, int]] = {
+    "lab":    (cv2.COLOR_BGR2LAB, cv2.COLOR_LAB2BGR, 0),      # L channel index is 0
+    "ycbcr":  (cv2.COLOR_BGR2YCrCb, cv2.COLOR_YCrCb2BGR, 0),  # Y channel index is 0
+    "hsv":    (cv2.COLOR_BGR2HSV, cv2.COLOR_HSV2BGR, 2),      # V channel index is 2
+}
+
+
+# Functions
+def histogram_equalization_image(
+	image: NDArray[Any],
+	color_space: Literal["lab", "ycbcr", "hsv"] = "lab",
+	ignore_dtype: bool = False,
+) -> NDArray[Any]:
+	""" Apply standard histogram equalization to an image.
+
+	Histogram equalization improves the contrast in images by stretching
+	the intensity range to utilize the full range of intensity values.
+
+	Args:
+		image           (NDArray[Any]):  Image to apply histogram equalization to
+		color_space     (str):           Color space to use for equalization ("lab", "ycbcr", or "hsv")
+			"lab":   CIELab color space (perceptually uniform, best visual fidelity)
+			"ycbcr": YCbCr color space (fast, good balance)
+			"hsv":   HSV color space (intuitive, may cause color shifts)
+		ignore_dtype    (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with histogram equalization applied
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> histogram_equalization_image(image.astype(np.uint8)).tolist()
+	[[0, 32, 64], [96, 128, 159], [191, 223, 255]]
+
+	>>> img = np.full((5,5), 128, dtype=np.uint8)
+	>>> img[1:3, 1:3] = 200  # Create a bright region
+	>>> histogram_equalization_image(img).tolist()
+	[[0, 0, 0, 0, 0], [0, 255, 255, 0, 0], [0, 255, 255, 0, 0], [0, 0, 0, 0, 0], [0, 0, 0, 0, 0]]
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> rgb[1, 1, :] = 50  # Create a dark region
+	>>> equalized_rgb = histogram_equalization_image(rgb)
+	>>> bool(np.std(equalized_rgb) > np.std(rgb))  # Should enhance contrast
+	True
+	>>> equalized_rgb.tolist()
+	[[[255, 255, 255], [255, 255, 255], [255, 255, 255]], [[255, 255, 255], [0, 0, 0], [255, 255, 255]], [[255, 255, 255], [255, 255, 255], [255, 255, 255]]]
+
+	>>> ## Test each color space
+	>>> test_img = np.zeros((20, 20, 3), dtype=np.uint8)
+	>>> test_img[5:15, 5:15] = 200  # Add contrast region
+
+	>>> # Test LAB color space
+	>>> lab_result = histogram_equalization_image(test_img, color_space="lab")
+	>>> isinstance(lab_result, np.ndarray) and lab_result.shape == test_img.shape
+	True
+	>>> bool(np.std(lab_result) > np.std(test_img))  # Verify contrast enhancement
+	True
+
+	>>> # Test YCbCr color space
+	>>> ycbcr_result = histogram_equalization_image(test_img, color_space="ycbcr")
+	>>> isinstance(ycbcr_result, np.ndarray) and ycbcr_result.shape == test_img.shape
+	True
+	>>> bool(np.std(ycbcr_result) > np.std(test_img))  # Verify contrast enhancement
+	True
+
+	>>> # Test HSV color space
+	>>> hsv_result = histogram_equalization_image(test_img, color_space="hsv")
+	>>> isinstance(hsv_result, np.ndarray) and hsv_result.shape == test_img.shape
+	True
+	>>> bool(np.std(hsv_result) > np.std(test_img))  # Verify contrast enhancement
+	True
+
+	>>> ## Test invalid inputs
+	>>> histogram_equalization_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> histogram_equalization_image(rgb, "invalid_space")
+	Traceback (most recent call last):
+		...
+	AssertionError: color_space must be one of: lab, ycbcr, hsv
+	"""  # noqa: E501
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	lowered_color_space = color_space.lower()
+	assert lowered_color_space in VALID_SPACES, f"color_space must be one of: {', '.join(VALID_SPACES)}"
+
+	# Handle different image types
+	if len(image.shape) == 2:
+		# Grayscale image - just apply histogram equalization directly
+		return cv2.equalizeHist(image)
+	else:
+		# Color image - apply equalization based on selected color space
+		convert_to, convert_from, channel_idx = COLOR_SPACE_CONSTANTS[lowered_color_space]
+
+		# Convert to target color space
+		converted: NDArray[Any] = cv2.cvtColor(image, convert_to)
+
+		# Split channels
+		channels: list[NDArray[Any]] = list(cv2.split(converted))
+
+		# Apply histogram equalization to the appropriate channel
+		channels[channel_idx] = cv2.equalizeHist(channels[channel_idx])
+
+		# Merge channels
+		result: NDArray[Any] = cv2.merge(channels)
+
+		# Convert back to BGR
+		return cv2.cvtColor(result, convert_from)
+

stouputils/data_science/data_processing/image/invert.py

@@ -0,0 +1,64 @@
+
+# Imports
+from .common import Any, NDArray, check_image, np
+
+
+# Function
+def invert_image(image: NDArray[Any], ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Invert the colors of an image.
+
+	This function inverts the colors of the input image by subtracting each pixel value
+	from the maximum possible value based on the image type.
+
+	Args:
+		image         (NDArray[Any]):       Input image as a NumPy array.
+		ignore_dtype  (bool):             Ignore the dtype check.
+	Returns:
+		NDArray[Any]: Image with inverted colors.
+
+	>>> ## Basic tests
+	>>> image = np.array([[10, 20, 30], [40, 50, 60], [70, 80, 90]], dtype=np.uint8)
+	>>> inverted = invert_image(image)
+	>>> inverted.tolist()
+	[[245, 235, 225], [215, 205, 195], [185, 175, 165]]
+
+	>>> # Test with floating point image
+	>>> float_img = np.array([[0.1, 0.2], [0.3, 0.4]], dtype=np.float32)
+	>>> [round(float(x), 1) for x in invert_image(float_img).flatten()]
+	[0.9, 0.8, 0.7, 0.6]
+
+	>>> # Test with RGB image
+	>>> rgb = np.zeros((2, 2, 3), dtype=np.uint8)
+	>>> rgb[0, 0] = [255, 0, 0]  # Red pixel
+	>>> inverted_rgb = invert_image(rgb)
+	>>> inverted_rgb[0, 0].tolist()
+	[0, 255, 255]
+
+	>>> ## Test invalid inputs
+	>>> invert_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+		"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+
+	# Get the maximum value based on the image's data type
+	if image.dtype == np.uint8:
+		max_value = 255
+	elif image.dtype == np.uint16:
+		max_value = 65535
+	elif image.dtype == np.float32 or image.dtype == np.float64:
+		# For float images, we assume range [0, 1]
+		max_value = 1.0
+	else:
+		# Default case, assuming 8-bit
+		max_value = 255
+		image = image.astype(np.uint8)
+
+	# Invert the image
+	inverted = max_value - image
+
+	# Ensure we return the same dtype as the input
+	return inverted.astype(image.dtype)
+

stouputils/data_science/data_processing/image/laplacian.py

@@ -0,0 +1,60 @@
+
+# pyright: reportUnknownMemberType=false
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnknownArgumentType=false
+# pyright: reportAttributeAccessIssue=false
+# pyright: reportArgumentType=false
+# pyright: reportCallIssue=false
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def laplacian_image(image: NDArray[Any], kernel_size: int = 3, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Apply Laplacian edge detection to an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to apply Laplacian edge detection
+		kernel_size   (int):         Size of the kernel (must be odd)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with Laplacian edge detection applied
+
+	>>> ## Basic tests
+	>>> image = np.array([[100, 150, 200], [50, 125, 175], [25, 75, 225]])
+	>>> edges = laplacian_image(image.astype(np.uint8))
+	>>> edges.shape == image.shape[:2]  # Laplacian returns single channel
+	True
+
+	>>> rgb = np.random.randint(0, 256, (3,3,3), dtype=np.uint8)
+	>>> edges_rgb = laplacian_image(rgb)
+	>>> edges_rgb.shape == rgb.shape[:2]  # Laplacian returns single channel
+	True
+
+	>>> ## Test invalid inputs
+	>>> laplacian_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> laplacian_image(image.astype(np.uint8), kernel_size=2)
+	Traceback (most recent call last):
+		...
+	AssertionError: kernel_size must be odd, got 2
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert kernel_size % 2 == 1, f"kernel_size must be odd, got {kernel_size}"
+
+	# Convert to grayscale if needed
+	if len(image.shape) > 2:
+		image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+	# Apply Laplacian edge detection
+	laplacian: NDArray[Any] = cv2.Laplacian(image, cv2.CV_64F, ksize=kernel_size)
+
+	# Convert back to uint8 and normalize to 0-255 range
+	normalized: NDArray[Any] = cv2.normalize(laplacian, None, alpha=0, beta=255, norm_type=cv2.NORM_MINMAX)
+	return normalized.astype(np.uint8)
+

stouputils/data_science/data_processing/image/median_blur.py

@@ -0,0 +1,52 @@
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def median_blur_image(image: NDArray[Any], kernel_size: int = 7, iterations: int = 1) -> NDArray[Any]:
+	""" Apply median blur to an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to apply median blur
+		kernel_size   (int):         Kernel size for the median blur
+		iterations    (int):         Number of iterations for the median blur
+	Returns:
+		NDArray[Any]: Image with median blur applied
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=np.uint8)
+	>>> adjusted = median_blur_image(image, kernel_size=7, iterations=1)
+	>>> adjusted.tolist()
+	[[3, 3, 3], [4, 5, 6], [7, 7, 7]]
+	>>> adjusted.shape == image.shape
+	True
+	>>> adjusted.dtype == image.dtype
+	True
+
+	>>> median_blur_image(image, kernel_size=3, iterations=1).tolist()
+	[[2, 3, 3], [4, 5, 6], [7, 7, 8]]
+	>>> median_blur_image(image, kernel_size=3, iterations=2).tolist()
+	[[3, 3, 3], [4, 5, 6], [7, 7, 7]]
+	>>> median_blur_image(image, kernel_size=3, iterations=5).tolist()
+	[[3, 3, 3], [4, 5, 6], [7, 7, 7]]
+
+	>>> ## Test invalid inputs
+	>>> median_blur_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=True)
+
+	# Apply median blur
+	for _ in range(iterations):
+		image = cv2.medianBlur(image, kernel_size)
+
+	# Return the image
+	return image
+