stouputils 1.14.2__py3-none-any.whl → 1.15.0__py3-none-any.whl

stouputils/data_science/data_processing/image/bias_field_correction.py

@@ -1,74 +1,74 @@
-
-# pyright: reportUnknownMemberType=false
-# pyright: reportUnknownArgumentType=false
-# pyright: reportUnknownVariableType=false
-
-# Imports
-import SimpleITK as Sitk
-
-from .common import Any, NDArray, check_image, np
-
-
-# Functions
-def bias_field_correction_image(image: NDArray[Any], ignore_dtype: bool = False) -> NDArray[Any]:
-	""" Apply a bias field correction to an image. (N4 Filter)
-
-	Args:
-		image         (NDArray[Any]):  Image to apply the bias field correction (can't be 8-bit unsigned integer)
-		ignore_dtype  (bool):        Ignore the dtype check
-	Returns:
-		NDArray[Any]: Image with the curvature flow filter applied
-
-	>>> ## Basic tests
-	>>> image = np.random.randint(0, 255, size=(10,10), dtype=np.uint8) / 255
-	>>> corrected = bias_field_correction_image(image)
-	>>> corrected.shape == image.shape
-	True
-	>>> corrected.dtype == np.float64
-	True
-
-	>>> ## Test invalid inputs
-	>>> bias_field_correction_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)
-
-	# If the image is 3D, convert to grayscale first
-	if image.ndim == 3:
-		image = np.mean(image, axis=-1)
-
-	# Convert numpy array to SimpleITK image
-	image_sitk: Sitk.Image = Sitk.GetImageFromArray(image)
-
-	# Create binary mask of the head region
-	transformed: Sitk.Image = Sitk.RescaleIntensity(image_sitk)  # Normalize intensities
-	transformed = Sitk.LiThreshold(transformed, 0, 1)  # Apply Li thresholding
-	head_mask: Sitk.Image = transformed
-
-	# Downsample images to speed up bias field estimation
-	shrink_factor: int = 4  # Reduce image size by factor of 4
-	input_image: Sitk.Image = Sitk.Shrink(
-		image_sitk,
-		[shrink_factor] * image_sitk.GetDimension()  # Apply shrink factor to all dimensions
-	)
-	mask_image: Sitk.Image = Sitk.Shrink(
-		head_mask,
-		[shrink_factor] * image_sitk.GetDimension()
-	)
-
-	# Apply N4 bias field correction
-	corrector = Sitk.N4BiasFieldCorrectionImageFilter()
-	corrector.Execute(input_image, mask_image)
-
-	# Get estimated bias field and apply correction
-	log_bias_field: Sitk.Image = Sitk.Cast(
-		corrector.GetLogBiasFieldAsImage(image_sitk), Sitk.sitkFloat64
-	)
-	corrected_image_full_resolution: Sitk.Image = image_sitk / Sitk.Exp(log_bias_field)
-
-	# Convert back to numpy array and return
-	return Sitk.GetArrayFromImage(corrected_image_full_resolution)
-
+
+# pyright: reportUnknownMemberType=false
+# pyright: reportUnknownArgumentType=false
+# pyright: reportUnknownVariableType=false
+
+# Imports
+import SimpleITK as Sitk
+
+from .common import Any, NDArray, check_image, np
+
+
+# Functions
+def bias_field_correction_image(image: NDArray[Any], ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Apply a bias field correction to an image. (N4 Filter)
+
+	Args:
+		image         (NDArray[Any]):  Image to apply the bias field correction (can't be 8-bit unsigned integer)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with the curvature flow filter applied
+
+	>>> ## Basic tests
+	>>> image = np.random.randint(0, 255, size=(10,10), dtype=np.uint8) / 255
+	>>> corrected = bias_field_correction_image(image)
+	>>> corrected.shape == image.shape
+	True
+	>>> corrected.dtype == np.float64
+	True
+
+	>>> ## Test invalid inputs
+	>>> bias_field_correction_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)
+
+	# If the image is 3D, convert to grayscale first
+	if image.ndim == 3:
+		image = np.mean(image, axis=-1)
+
+	# Convert numpy array to SimpleITK image
+	image_sitk: Sitk.Image = Sitk.GetImageFromArray(image)
+
+	# Create binary mask of the head region
+	transformed: Sitk.Image = Sitk.RescaleIntensity(image_sitk)  # Normalize intensities
+	transformed = Sitk.LiThreshold(transformed, 0, 1)  # Apply Li thresholding
+	head_mask: Sitk.Image = transformed
+
+	# Downsample images to speed up bias field estimation
+	shrink_factor: int = 4  # Reduce image size by factor of 4
+	input_image: Sitk.Image = Sitk.Shrink(
+		image_sitk,
+		[shrink_factor] * image_sitk.GetDimension()  # Apply shrink factor to all dimensions
+	)
+	mask_image: Sitk.Image = Sitk.Shrink(
+		head_mask,
+		[shrink_factor] * image_sitk.GetDimension()
+	)
+
+	# Apply N4 bias field correction
+	corrector = Sitk.N4BiasFieldCorrectionImageFilter()
+	corrector.Execute(input_image, mask_image)
+
+	# Get estimated bias field and apply correction
+	log_bias_field: Sitk.Image = Sitk.Cast(
+		corrector.GetLogBiasFieldAsImage(image_sitk), Sitk.sitkFloat64
+	)
+	corrected_image_full_resolution: Sitk.Image = image_sitk / Sitk.Exp(log_bias_field)
+
+	# Convert back to numpy array and return
+	return Sitk.GetArrayFromImage(corrected_image_full_resolution)
+

stouputils/data_science/data_processing/image/binary_threshold.py

@@ -1,73 +1,73 @@
-
-# pyright: reportUnusedImport=false
-# ruff: noqa: F401
-
-# Imports
-from .common import Any, NDArray, check_image, cv2, np
-
-
-# Functions
-def binary_threshold_image(image: NDArray[Any], threshold: float, ignore_dtype: bool = False) -> NDArray[Any]:
-	""" Apply binary threshold to an image.
-
-	Args:
-		image         (NDArray[Any]):  Image to threshold
-		threshold     (float):       Threshold value (between 0 and 1)
-		ignore_dtype  (bool):        Ignore the dtype check
-	Returns:
-		NDArray[Any]: Thresholded binary image
-
-	>>> ## Basic tests
-	>>> image = np.array([[100, 150, 200], [50, 125, 175], [25, 75, 225]])
-	>>> binary_threshold_image(image.astype(np.uint8), 0.5).tolist()
-	[[0, 255, 255], [0, 0, 255], [0, 0, 255]]
-
-	>>> np.random.seed(42)
-	>>> img = np.random.randint(0, 256, (4,4), dtype=np.uint8)
-	>>> thresholded = binary_threshold_image(img, 0.7)
-	>>> set(np.unique(thresholded).tolist()) <= {0, 255}  # Should only contain 0 and 255
-	True
-
-	>>> rgb = np.random.randint(0, 256, (3,3,3), dtype=np.uint8)
-	>>> thresh_rgb = binary_threshold_image(rgb, 0.5)
-	>>> thresh_rgb.shape == rgb.shape
-	True
-	>>> set(np.unique(thresh_rgb).tolist()) <= {0, 255}
-	True
-
-	>>> ## Test invalid inputs
-	>>> binary_threshold_image("not an image", 0.5)
-	Traceback (most recent call last):
-		...
-	AssertionError: Image must be a numpy array
-
-	>>> binary_threshold_image(image.astype(np.uint8), "0.5")
-	Traceback (most recent call last):
-		...
-	AssertionError: threshold must be a number, got <class 'str'>
-
-	>>> binary_threshold_image(image.astype(np.uint8), 1.5)
-	Traceback (most recent call last):
-		...
-	AssertionError: threshold must be between 0 and 1, got 1.5
-	"""
-	# Check input data
-	check_image(image, ignore_dtype=ignore_dtype)
-	assert isinstance(threshold, float | int), f"threshold must be a number, got {type(threshold)}"
-	assert 0 <= threshold <= 1, f"threshold must be between 0 and 1, got {threshold}"
-
-	# Convert threshold from 0-1 range to 0-255 range
-	threshold_value: int = int(threshold * 255)
-
-	# Apply threshold
-	if len(image.shape) == 2:
-		# Grayscale image
-		binary: NDArray[Any] = cv2.threshold(image, threshold_value, 255, cv2.THRESH_BINARY)[1]
-	else:
-		# Color image - convert to grayscale first, then back to color
-		gray: NDArray[Any] = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
-		binary: NDArray[Any] = cv2.threshold(gray, threshold_value, 255, cv2.THRESH_BINARY)[1]
-		binary = cv2.cvtColor(binary, cv2.COLOR_GRAY2BGR)
-
-	return binary
-
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def binary_threshold_image(image: NDArray[Any], threshold: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Apply binary threshold to an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to threshold
+		threshold     (float):       Threshold value (between 0 and 1)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Thresholded binary image
+
+	>>> ## Basic tests
+	>>> image = np.array([[100, 150, 200], [50, 125, 175], [25, 75, 225]])
+	>>> binary_threshold_image(image.astype(np.uint8), 0.5).tolist()
+	[[0, 255, 255], [0, 0, 255], [0, 0, 255]]
+
+	>>> np.random.seed(42)
+	>>> img = np.random.randint(0, 256, (4,4), dtype=np.uint8)
+	>>> thresholded = binary_threshold_image(img, 0.7)
+	>>> set(np.unique(thresholded).tolist()) <= {0, 255}  # Should only contain 0 and 255
+	True
+
+	>>> rgb = np.random.randint(0, 256, (3,3,3), dtype=np.uint8)
+	>>> thresh_rgb = binary_threshold_image(rgb, 0.5)
+	>>> thresh_rgb.shape == rgb.shape
+	True
+	>>> set(np.unique(thresh_rgb).tolist()) <= {0, 255}
+	True
+
+	>>> ## Test invalid inputs
+	>>> binary_threshold_image("not an image", 0.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> binary_threshold_image(image.astype(np.uint8), "0.5")
+	Traceback (most recent call last):
+		...
+	AssertionError: threshold must be a number, got <class 'str'>
+
+	>>> binary_threshold_image(image.astype(np.uint8), 1.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: threshold must be between 0 and 1, got 1.5
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(threshold, float | int), f"threshold must be a number, got {type(threshold)}"
+	assert 0 <= threshold <= 1, f"threshold must be between 0 and 1, got {threshold}"
+
+	# Convert threshold from 0-1 range to 0-255 range
+	threshold_value: int = int(threshold * 255)
+
+	# Apply threshold
+	if len(image.shape) == 2:
+		# Grayscale image
+		binary: NDArray[Any] = cv2.threshold(image, threshold_value, 255, cv2.THRESH_BINARY)[1]
+	else:
+		# Color image - convert to grayscale first, then back to color
+		gray: NDArray[Any] = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+		binary: NDArray[Any] = cv2.threshold(gray, threshold_value, 255, cv2.THRESH_BINARY)[1]
+		binary = cv2.cvtColor(binary, cv2.COLOR_GRAY2BGR)
+
+	return binary
+

stouputils/data_science/data_processing/image/blur.py

@@ -1,59 +1,59 @@
-
-# pyright: reportUnusedImport=false
-# ruff: noqa: F401
-
-# Imports
-from .common import Any, NDArray, check_image, cv2, np
-
-
-# Functions
-def blur_image(image: NDArray[Any], blur_strength: float, ignore_dtype: bool = False) -> NDArray[Any]:
-	""" Apply Gaussian blur to an image.
-
-	Args:
-		image         (NDArray[Any]):  Image to blur
-		blur_strength (float):       Strength of the blur
-		ignore_dtype  (bool):        Ignore the dtype check
-	Returns:
-		NDArray[Any]: Blurred image
-
-	>>> ## Basic tests
-	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
-	>>> blurred = blur_image(image.astype(np.uint8), 1.5)
-	>>> blurred.shape == image.shape
-	True
-
-	>>> img = np.zeros((5,5), dtype=np.uint8)
-	>>> img[2,2] = 255  # Single bright pixel
-	>>> blurred = blur_image(img, 1.0)
-	>>> bool(blurred[2,2] < 255)  # Center should be blurred
-	True
-
-	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
-	>>> blurred_rgb = blur_image(rgb, 1.0)
-	>>> blurred_rgb.shape == (3,3,3)
-	True
-
-	>>> ## Test invalid inputs
-	>>> blur_image("not an image", 1.5)
-	Traceback (most recent call last):
-		...
-	AssertionError: Image must be a numpy array
-
-	>>> blur_image(image.astype(np.uint8), "1.5")
-	Traceback (most recent call last):
-		...
-	AssertionError: blur_strength must be a number, got <class 'str'>
-	"""
-	# Check input data
-	check_image(image, ignore_dtype=ignore_dtype)
-	assert isinstance(blur_strength, float | int), f"blur_strength must be a number, got {type(blur_strength)}"
-
-	# Apply Gaussian blur
-	kernel_size: int = max(3, int(blur_strength * 2) + 1)
-	if kernel_size % 2 == 0:
-		kernel_size += 1
-	blurred_image: NDArray[Any] = cv2.GaussianBlur(image, (kernel_size, kernel_size), 0)
-
-	return blurred_image
-
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def blur_image(image: NDArray[Any], blur_strength: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Apply Gaussian blur to an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to blur
+		blur_strength (float):       Strength of the blur
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Blurred image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> blurred = blur_image(image.astype(np.uint8), 1.5)
+	>>> blurred.shape == image.shape
+	True
+
+	>>> img = np.zeros((5,5), dtype=np.uint8)
+	>>> img[2,2] = 255  # Single bright pixel
+	>>> blurred = blur_image(img, 1.0)
+	>>> bool(blurred[2,2] < 255)  # Center should be blurred
+	True
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> blurred_rgb = blur_image(rgb, 1.0)
+	>>> blurred_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> blur_image("not an image", 1.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> blur_image(image.astype(np.uint8), "1.5")
+	Traceback (most recent call last):
+		...
+	AssertionError: blur_strength must be a number, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(blur_strength, float | int), f"blur_strength must be a number, got {type(blur_strength)}"
+
+	# Apply Gaussian blur
+	kernel_size: int = max(3, int(blur_strength * 2) + 1)
+	if kernel_size % 2 == 0:
+		kernel_size += 1
+	blurred_image: NDArray[Any] = cv2.GaussianBlur(image, (kernel_size, kernel_size), 0)
+
+	return blurred_image
+

stouputils/data_science/data_processing/image/brightness.py

@@ -1,54 +1,54 @@
-
-# pyright: reportUnusedImport=false
-# ruff: noqa: F401
-
-# Imports
-from .common import Any, NDArray, check_image, cv2, np
-
-
-# Functions
-def brightness_image(image: NDArray[Any], brightness_factor: float, ignore_dtype: bool = False) -> NDArray[Any]:
-	""" Adjust the brightness of an image.
-
-	Args:
-		image             (NDArray[Any]):  Image to adjust brightness
-		brightness_factor (float):       Brightness adjustment factor
-		ignore_dtype      (bool):        Ignore the dtype check
-	Returns:
-		NDArray[Any]: Image with adjusted brightness
-
-	>>> ## Basic tests
-	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
-	>>> brightened = brightness_image(image.astype(np.uint8), 1.5)
-	>>> brightened.shape == image.shape
-	True
-
-	>>> img = np.full((3,3), 100, dtype=np.uint8)
-	>>> bright = brightness_image(img, 2.0)
-	>>> dark = brightness_image(img, 0.5)
-	>>> bool(np.mean(bright) > np.mean(img) > np.mean(dark))
-	True
-
-	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
-	>>> bright_rgb = brightness_image(rgb, 1.5)
-	>>> bright_rgb.shape == (3,3,3)
-	True
-
-	>>> ## Test invalid inputs
-	>>> brightness_image("not an image", 1.5)
-	Traceback (most recent call last):
-		...
-	AssertionError: Image must be a numpy array
-
-	>>> brightness_image(image.astype(np.uint8), "1.5")
-	Traceback (most recent call last):
-		...
-	AssertionError: brightness_factor must be a number, got <class 'str'>
-	"""
-	# Check input data
-	check_image(image, ignore_dtype=ignore_dtype)
-	assert isinstance(brightness_factor, float | int), f"brightness_factor must be a number, got {type(brightness_factor)}"
-
-	# Apply brightness adjustment
-	return cv2.convertScaleAbs(image, alpha=brightness_factor, beta=0)
-
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def brightness_image(image: NDArray[Any], brightness_factor: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Adjust the brightness of an image.
+
+	Args:
+		image             (NDArray[Any]):  Image to adjust brightness
+		brightness_factor (float):       Brightness adjustment factor
+		ignore_dtype      (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with adjusted brightness
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> brightened = brightness_image(image.astype(np.uint8), 1.5)
+	>>> brightened.shape == image.shape
+	True
+
+	>>> img = np.full((3,3), 100, dtype=np.uint8)
+	>>> bright = brightness_image(img, 2.0)
+	>>> dark = brightness_image(img, 0.5)
+	>>> bool(np.mean(bright) > np.mean(img) > np.mean(dark))
+	True
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> bright_rgb = brightness_image(rgb, 1.5)
+	>>> bright_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> brightness_image("not an image", 1.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> brightness_image(image.astype(np.uint8), "1.5")
+	Traceback (most recent call last):
+		...
+	AssertionError: brightness_factor must be a number, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(brightness_factor, float | int), f"brightness_factor must be a number, got {type(brightness_factor)}"
+
+	# Apply brightness adjustment
+	return cv2.convertScaleAbs(image, alpha=brightness_factor, beta=0)
+