stouputils 1.14.0__py3-none-any.whl

stouputils/data_science/data_processing/image/canny.py

@@ -0,0 +1,110 @@
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def canny_image(
+	image: NDArray[Any],
+	threshold1: float,
+	threshold2: float,
+	aperture_size: int = 3,
+	sigma: float = 3,
+	stop_at_nms: bool = False,
+	ignore_dtype: bool = False,
+) -> NDArray[Any]:
+	""" Apply Canny edge detection to an image.
+
+	Args:
+		image           (NDArray[Any]):  Image to apply Canny edge detection
+		threshold1      (float):       First threshold for hysteresis (between 0 and 1)
+		threshold2      (float):       Second threshold for hysteresis (between 0 and 1)
+		aperture_size   (int):         Aperture size for Sobel operator (3, 5, or 7)
+		sigma           (float):       Standard deviation for Gaussian blur
+		stop_at_nms     (bool):        Stop at non-maximum suppression step (don't apply thresholding)
+		ignore_dtype    (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with Canny edge detection applied
+
+	>>> ## Basic tests
+	>>> image = np.array([[100, 150, 200], [50, 125, 175], [25, 75, 225]])
+	>>> edges = canny_image(image.astype(np.uint8), 0.1, 0.2)
+	>>> edges.shape == image.shape[:2]  # Canny returns single channel
+	True
+	>>> set(np.unique(edges).tolist()) <= {0, 255}  # Only contains 0 and 255
+	True
+
+	>>> rgb = np.random.randint(0, 256, (3,3,3), dtype=np.uint8)
+	>>> edges_rgb = canny_image(rgb, 0.1, 0.2)
+	>>> edges_rgb.shape == rgb.shape[:2]  # Canny returns single channel
+	True
+
+	>>> ## Test invalid inputs
+	>>> canny_image("not an image", 0.1, 0.2)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> canny_image(image.astype(np.uint8), 1.5, 0.2)
+	Traceback (most recent call last):
+		...
+	AssertionError: threshold1 must be between 0 and 1, got 1.5
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert 0 <= threshold1 <= 1, f"threshold1 must be between 0 and 1, got {threshold1}"
+	assert 0 <= threshold2 <= 1, f"threshold2 must be between 0 and 1, got {threshold2}"
+	assert aperture_size in (3, 5, 7), f"aperture_size must be 3, 5 or 7, got {aperture_size}"
+
+	# Convert to grayscale if needed
+	if len(image.shape) > 2:
+		image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+	# Convert thresholds to 0-255 range
+	t1: int = int(threshold1 * 255)
+	t2: int = int(threshold2 * 255)
+
+	if not stop_at_nms:
+		# Apply full Canny edge detection
+		return cv2.Canny(image, t1, t2, apertureSize=aperture_size)
+	else:
+		# Manual implementation up to non-maximum suppression
+		# 1. Apply Gaussian blur to reduce noise
+		blurred: NDArray[Any] = cv2.GaussianBlur(image, (5, 5), sigma)
+
+		# 2. Calculate gradients using Sobel
+		# Use constant value 6 for 64-bit float depth (CV_64F)
+		gx: NDArray[Any] = cv2.Sobel(blurred, 6, 1, 0, ksize=aperture_size)
+		gy: NDArray[Any] = cv2.Sobel(blurred, 6, 0, 1, ksize=aperture_size)
+
+		# Calculate gradient magnitude and direction
+		magnitude: NDArray[Any] = np.sqrt(gx**2 + gy**2)
+		direction: NDArray[Any] = np.arctan2(gy, gx) * 180 / np.pi
+
+		# 3. Non-maximum suppression
+		nms: NDArray[Any] = np.zeros_like(magnitude, dtype=np.uint8)
+		height, width = magnitude.shape
+
+		for i in range(1, height - 1):
+			for j in range(1, width - 1):
+				# Get gradient direction
+				angle: float = direction[i, j]
+				if angle < 0:
+					angle += 180
+
+				# Round to 0, 45, 90, or 135 degrees
+				if (0 <= angle < 22.5) or (157.5 <= angle <= 180):
+					neighbors = [magnitude[i, j-1], magnitude[i, j+1]]
+				elif 22.5 <= angle < 67.5:
+					neighbors = [magnitude[i-1, j-1], magnitude[i+1, j+1]]
+				elif 67.5 <= angle < 112.5:
+					neighbors = [magnitude[i-1, j], magnitude[i+1, j]]
+				else:  # 112.5 <= angle < 157.5
+					neighbors = [magnitude[i-1, j+1], magnitude[i+1, j-1]]
+
+				# Check if current pixel is local maximum
+				if magnitude[i, j] >= max(neighbors):
+					nms[i, j] = np.uint8(min(magnitude[i, j], 255))
+
+		return nms
+

stouputils/data_science/data_processing/image/clahe.py

@@ -0,0 +1,92 @@
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def clahe_image(
+	image: NDArray[Any],
+	clip_limit: float = 2.0,
+	tile_grid_size: int = 8,
+	ignore_dtype: bool = False,
+) -> NDArray[Any]:
+	""" Apply Contrast Limited Adaptive Histogram Equalization (CLAHE) to an image.
+
+	Args:
+		image           (NDArray[Any]):  Image to apply CLAHE to
+		clip_limit      (float):       Threshold for contrast limiting (1.0-4.0 recommended)
+		tile_grid_size  (int):         Size of grid for histogram equalization (2-16 recommended)
+		ignore_dtype    (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with CLAHE applied
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> clahed = clahe_image(image.astype(np.uint8), 2.0, 1)
+	>>> clahed.tolist()
+	[[28, 57, 85], [113, 142, 170], [198, 227, 255]]
+	>>> clahed.shape == image.shape
+	True
+
+	>>> img = np.full((10,10), 128, dtype=np.uint8)
+	>>> img[2:8, 2:8] = 200  # Create a bright region
+	>>> clahed = clahe_image(img, 2.0, 4)
+	>>> bool(np.mean(clahed) > np.mean(img))  # Should enhance contrast
+	True
+	>>> bool(np.std(clahed) > np.std(img))  # Should enhance contrast
+	True
+
+	>>> rgb = np.full((10,10,3), 128, dtype=np.uint8)
+	>>> rgb[2:8, 2:8, :] = 50  # Create a dark region
+	>>> clahed_rgb = clahe_image(rgb, 2.0, 4)
+	>>> bool(np.mean(clahed_rgb) > np.mean(rgb))  # Should enhance contrast
+	True
+	>>> bool(np.std(clahed_rgb) > np.std(rgb))  # Should enhance contrast
+	True
+	>>> clahed_rgb.shape == rgb.shape
+	True
+
+	>>> ## Test invalid inputs
+	>>> clahe_image("not an image", 2.0, 8)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> clahe_image(image.astype(np.uint8), "2.0", 8)
+	Traceback (most recent call last):
+		...
+	AssertionError: clip_limit must be a number, got <class 'str'>
+
+	>>> clahe_image(image.astype(np.uint8), 2.0, -1)
+	Traceback (most recent call last):
+		...
+	AssertionError: tile_grid_size must be positive, got -1
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(clip_limit, float | int), f"clip_limit must be a number, got {type(clip_limit)}"
+	assert isinstance(tile_grid_size, int), f"tile_grid_size must be an integer, got {type(tile_grid_size)}"
+	assert tile_grid_size > 0, f"tile_grid_size must be positive, got {tile_grid_size}"
+
+	# Create CLAHE object
+	clahe: cv2.CLAHE = cv2.createCLAHE(clipLimit=clip_limit, tileGridSize=(tile_grid_size, tile_grid_size))
+
+	# Handle different image types
+	if len(image.shape) == 2:
+		# Grayscale image
+		return clahe.apply(image)
+	else:
+		# Color image - convert to LAB color space
+		lab: NDArray[Any] = cv2.cvtColor(image, cv2.COLOR_BGR2LAB)
+		channel_l, channel_a, channel_b = cv2.split(lab)
+
+		# Apply CLAHE to L channel
+		cl: NDArray[Any] = clahe.apply(channel_l)
+
+		# Merge channels and convert back to BGR
+		limg: NDArray[Any] = cv2.merge((cl, channel_a, channel_b))
+		return cv2.cvtColor(limg, cv2.COLOR_LAB2BGR)
+

stouputils/data_science/data_processing/image/common.py

@@ -0,0 +1,30 @@
+
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from typing import Any
+
+import cv2
+import numpy as np
+from numpy.typing import NDArray
+
+
+# Functions
+def check_image(image: NDArray[Any], ignore_dtype: bool = False) -> None:
+	""" Check if the image is valid
+
+	Args:
+		image         (NDArray[Any]):  Image to check
+		ignore_dtype  (bool):        Ignore the dtype check
+	"""
+	# Check input data
+	assert isinstance(image, np.ndarray), "Image must be a numpy array"
+	assert len(image.shape) >= 2, "Image must have at least 2 dimensions"
+
+	# Check dtype
+	if not ignore_dtype:
+		dtypes: list[type] = [np.uint8, np.int16, np.float32, np.float64]
+		assert image.dtype in dtypes, f"Image must be of type {dtypes}"
+

stouputils/data_science/data_processing/image/contrast.py

@@ -0,0 +1,53 @@
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def contrast_image(image: NDArray[Any], factor: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Adjust the contrast of an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to adjust contrast
+		factor        (float):       Contrast adjustment factor
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with adjusted contrast
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> contrasted = contrast_image(image.astype(np.uint8), 1.5)
+	>>> contrasted.shape == image.shape
+	True
+
+	>>> img = np.array([[50, 100, 150]], dtype=np.uint8)
+	>>> high = contrast_image(img, 2.0)
+	>>> low = contrast_image(img, 0.5)
+	>>> bool(high.std() > img.std() > low.std())  # Higher contrast = higher std
+	True
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> rgb[1,1] = [50, 100, 150]
+	>>> cont_rgb = contrast_image(rgb, 1.5)
+	>>> cont_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> contrast_image("not an image", 1.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> contrast_image(image.astype(np.uint8), "1.5")
+	Traceback (most recent call last):
+		...
+	AssertionError: factor must be a number, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(factor, float | int), f"factor must be a number, got {type(factor)}"
+
+	# Apply contrast adjustment
+	mean: float = float(np.mean(image))
+	return cv2.addWeighted(image, factor, image, 0, mean * (1 - factor))
+

stouputils/data_science/data_processing/image/curvature_flow_filter.py

@@ -0,0 +1,74 @@
+
+# pyright: reportUnknownMemberType=false
+# pyright: reportUnknownArgumentType=false
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+import SimpleITK as Sitk
+
+from .common import Any, NDArray, check_image, np
+
+
+# Functions
+def curvature_flow_filter_image(
+	image: NDArray[Any],
+	time_step: float = 0.05,
+	number_of_iterations: int = 5,
+	ignore_dtype: bool = False,
+) -> NDArray[Any]:
+	""" Apply a curvature flow filter to an image.
+
+	Args:
+		image                (NDArray[Any]):  Image to apply the curvature flow filter
+		time_step            (float):       Time step for the curvature flow filter
+		number_of_iterations (int):         Number of iterations for the curvature flow filter
+		ignore_dtype         (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with the curvature flow filter applied
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=np.uint8)
+	>>> filtered = curvature_flow_filter_image(image, 0.05, 5)
+	>>> filtered.tolist()[0][0]
+	1.2910538407309702
+	>>> filtered.shape == image.shape
+	True
+	>>> filtered.dtype == image.dtype
+	False
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> rgb[1,1] = [50, 100, 150]
+	>>> filtered_rgb = curvature_flow_filter_image(rgb, 0.05, 5)
+	>>> filtered_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> curvature_flow_filter_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> curvature_flow_filter_image(image, time_step="not a float")
+	Traceback (most recent call last):
+		...
+	AssertionError: time_step must be a float
+
+	>>> curvature_flow_filter_image(image, number_of_iterations="not an integer")
+	Traceback (most recent call last):
+		...
+	AssertionError: number_of_iterations must be an integer
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(time_step, float), "time_step must be a float"
+	assert isinstance(number_of_iterations, int), "number_of_iterations must be an integer"
+	assert time_step > 0, "time_step must be greater than 0"
+	assert number_of_iterations > 0, "number_of_iterations must be greater than 0"
+
+	# Apply the curvature flow filter
+	image_Sitk: Sitk.Image = Sitk.GetImageFromArray(image)
+	image_Sitk = Sitk.CurvatureFlow(image_Sitk, timeStep=time_step, numberOfIterations=number_of_iterations)
+	return Sitk.GetArrayFromImage(image_Sitk)
+