stouputils 1.2.40__tar.gz → 1.2.41__tar.gz

{stouputils-1.2.40 → stouputils-1.2.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.2.40
+Version: 1.2.41
 Summary: Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more.
 Project-URL: Homepage, https://github.com/Stoupy51/stouputils
 Project-URL: Issues, https://github.com/Stoupy51/stouputils/issues
@@ -62,7 +62,7 @@ It includes a range of tools for tasks such as execution of doctests, display ut
 <pre class="code-tree">stouputils/
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.html">applications/</a>
 │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.automatic_docs.html">automatic_docs.py</a>    <span class="comment"># 📚 Documentation generation utilities (used to create this documentation)</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.upscaler.html">upscaler/</a>    <span class="comment"># 🔎 Image & Video upscaler (configurable)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.upscaler.html">upscaler/</a>            <span class="comment"># 🔎 Image & Video upscaler (configurable)</span>
 │   └── ...
 │
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.html">continuous_delivery/</a>
@@ -72,6 +72,31 @@ It includes a range of tools for tasks such as execution of doctests, display ut
 │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.pyproject.html">pyproject.py</a>         <span class="comment"># 📝 Pyproject.toml utilities</span>
 │   └── ...
 │
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.html">data_science/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.config.html">config/</a>              <span class="comment"># ⚙️ Configuration utilities for data science</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.dataset.html">dataset/</a>             <span class="comment"># 📊 Dataset handling (dataset, dataset_loader, grouping_strategy)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.html">data_processing/</a>     <span class="comment"># 🔄 Data processing utilities (image augmentation, preprocessing)</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.image.html">image/</a>           <span class="comment"># 🖼️ Image processing techniques</span>
+│   │   └── ...
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.html">models/</a>              <span class="comment"># 🧠 ML/DL model interfaces and implementations</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras.html">keras/</a>           <span class="comment"># 🤖 Keras model implementations</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras_utils.html">keras_utils/</a>     <span class="comment"># 🛠️ Keras utilities (callbacks, losses, visualizations)</span>
+│   │   └── ...
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.scripts.html">scripts/</a>             <span class="comment"># 📜 Data science scripts (augment, preprocess, routine)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.metric_utils.html">metric_utils.py</a>      <span class="comment"># 📏 Metrics utilities for ML/DL models</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.mlflow_utils.html">mlflow_utils.py</a>      <span class="comment"># 📊 MLflow integration utilities</span>
+│   └── ...
+│
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.dont_look.html">dont_look/</a>               <span class="comment"># 🙈 Internal utilities (zip_file_override)</span>
+│
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.html">installer/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.common.html">common.py</a>            <span class="comment"># 🔧 Common installer utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.downloader.html">downloader.py</a>        <span class="comment"># ⬇️ File download utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.linux.html">linux.py</a>             <span class="comment"># 🐧 Linux-specific installer utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.main.html">main.py</a>              <span class="comment"># 🚀 Main installer functionality</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.windows.html">windows.py</a>           <span class="comment"># 💻 Windows-specific installer utilities</span>
+│   └── ...
+│
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.all_doctests.html">all_doctests.py</a>          <span class="comment"># ✅ Execution of all doctests for a given path</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.archive.html">archive.py</a>               <span class="comment"># 📦 Archive utilities (zip, repair_zip)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>                <span class="comment"># 📦 Backup utilities (delta backup, consolidate)</span>

{stouputils-1.2.40 → stouputils-1.2.41}/README.md

@@ -41,7 +41,7 @@ It includes a range of tools for tasks such as execution of doctests, display ut
 <pre class="code-tree">stouputils/
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.html">applications/</a>
 │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.automatic_docs.html">automatic_docs.py</a>    <span class="comment"># 📚 Documentation generation utilities (used to create this documentation)</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.upscaler.html">upscaler/</a>    <span class="comment"># 🔎 Image & Video upscaler (configurable)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.upscaler.html">upscaler/</a>            <span class="comment"># 🔎 Image & Video upscaler (configurable)</span>
 │   └── ...
 │
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.html">continuous_delivery/</a>
@@ -51,6 +51,31 @@ It includes a range of tools for tasks such as execution of doctests, display ut
 │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.pyproject.html">pyproject.py</a>         <span class="comment"># 📝 Pyproject.toml utilities</span>
 │   └── ...
 │
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.html">data_science/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.config.html">config/</a>              <span class="comment"># ⚙️ Configuration utilities for data science</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.dataset.html">dataset/</a>             <span class="comment"># 📊 Dataset handling (dataset, dataset_loader, grouping_strategy)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.html">data_processing/</a>     <span class="comment"># 🔄 Data processing utilities (image augmentation, preprocessing)</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.image.html">image/</a>           <span class="comment"># 🖼️ Image processing techniques</span>
+│   │   └── ...
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.html">models/</a>              <span class="comment"># 🧠 ML/DL model interfaces and implementations</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras.html">keras/</a>           <span class="comment"># 🤖 Keras model implementations</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras_utils.html">keras_utils/</a>     <span class="comment"># 🛠️ Keras utilities (callbacks, losses, visualizations)</span>
+│   │   └── ...
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.scripts.html">scripts/</a>             <span class="comment"># 📜 Data science scripts (augment, preprocess, routine)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.metric_utils.html">metric_utils.py</a>      <span class="comment"># 📏 Metrics utilities for ML/DL models</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.mlflow_utils.html">mlflow_utils.py</a>      <span class="comment"># 📊 MLflow integration utilities</span>
+│   └── ...
+│
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.dont_look.html">dont_look/</a>               <span class="comment"># 🙈 Internal utilities (zip_file_override)</span>
+│
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.html">installer/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.common.html">common.py</a>            <span class="comment"># 🔧 Common installer utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.downloader.html">downloader.py</a>        <span class="comment"># ⬇️ File download utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.linux.html">linux.py</a>             <span class="comment"># 🐧 Linux-specific installer utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.main.html">main.py</a>              <span class="comment"># 🚀 Main installer functionality</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.windows.html">windows.py</a>           <span class="comment"># 💻 Windows-specific installer utilities</span>
+│   └── ...
+│
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.all_doctests.html">all_doctests.py</a>          <span class="comment"># ✅ Execution of all doctests for a given path</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.archive.html">archive.py</a>               <span class="comment"># 📦 Archive utilities (zip, repair_zip)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>                <span class="comment"># 📦 Backup utilities (delta backup, consolidate)</span>

{stouputils-1.2.40 → stouputils-1.2.41}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.2.40"
+version = "1.2.41"
 description = "Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -64,6 +64,8 @@ ignore = [
 	"W191",
 	"N803",
 	"N806",
+	"F403",
+	"F405",
 ]
 
 [tool.hatch.build]

{stouputils-1.2.40 → stouputils-1.2.41}/stouputils/all_doctests.py

@@ -16,6 +16,7 @@ from types import ModuleType
 from . import decorators
 from .decorators import LogLevels, handle_error, measure_time
 from .print import error, info, progress
+from .io import clean_path, relative_path
 
 
 def test_module_with_progress(module: ModuleType, separator: str) -> TestResults:
@@ -60,19 +61,39 @@ def launch_tests(root_dir: str, importing_errors: LogLevels = LogLevels.WARNING_
 		old_value: bool = strict
 		decorators.force_raise_exception = True
 		strict = old_value
-
+	
+	# Get the path of the directory to check modules from
+	working_dir: str = clean_path(os.getcwd())
+	root_dir = clean_path(os.path.abspath(root_dir))
+	dir_to_check: str = os.path.dirname(root_dir) if working_dir != root_dir else root_dir
 
 	# Get all modules from folder
-	sys.path.insert(0, root_dir)
+	sys.path.insert(0, dir_to_check)
 	modules_file_paths: list[str] = []
 	for directory_path, _, _ in os.walk(root_dir):
+		directory_path = clean_path(directory_path)
 		for module_info in pkgutil.walk_packages([directory_path]):
-			absolute_module_path: str = os.path.join(directory_path, module_info.name)
-			path: str = absolute_module_path.split(root_dir, 1)[1].replace(os.sep, ".")[1:]
-			if path not in modules_file_paths:
-				modules_file_paths.append(path)
+
+			# Extract root and module name
+			module_root: str = str(module_info.module_finder.path)	# type: ignore
+			module_name: str = module_info.name.split(".")[-1]
+
+			# Get the absolute path
+			absolute_module_path: str = clean_path(os.path.join(module_root, module_name))
+
+			# Check if the module is in the root directory that we want to check
+			if root_dir in absolute_module_path:
+
+				# Get the path of the module like 'stouputils.io'
+				path: str = absolute_module_path.split(dir_to_check, 1)[1].replace("/", ".")[1:]
+
+				# If the module is not already in the list, add it
+				if path not in modules_file_paths:
+					modules_file_paths.append(path)
+
+	# If no modules are found, raise an error
 	if not modules_file_paths:
-		raise ValueError(f"No modules found in '{root_dir}'")
+		raise ValueError(f"No modules found in '{relative_path(root_dir)}'")
 
 	# Find longest module path for alignment
 	max_length: int = max(len(path) for path in modules_file_paths)

{stouputils-1.2.40 → stouputils-1.2.41}/stouputils/ctx.py

@@ -222,8 +222,8 @@ class MeasureTime:
 		total_ms: float = total_ns / 1_000_000
 		total_s: float = total_ns / 1_000_000_000
 
-		# Print the execution time (nanoseconds if less than 0.3s, seconds otherwise)
-		if total_ms < 300:
+		# Print the execution time (nanoseconds if less than 0.1s, seconds otherwise)
+		if total_ms < 100:
 			self.print_func(f"{self.message}: {total_ms:.3f}ms ({total_ns}ns)")
 		elif total_s < 60:
 			self.print_func(f"{self.message}: {(total_s):.5f}s")

stouputils-1.2.41/stouputils/data_science/config/get.py

@@ -0,0 +1,51 @@
+""" Load configuration from the set.py file and handle some special cases.
+
+Proper way to get the configuration is by importing this module, not the set.py file directly.
+"""
+
+# pyright: reportUnknownMemberType=false
+# pyright: reportUnknownVariableType=false
+# pyright: reportMissingTypeStubs=false
+
+# Imports
+import os
+from typing import Any
+
+from .set import DataScienceConfig
+
+# Special cases
+# Hide GPU when using CPU
+if DataScienceConfig.TENSORFLOW_DEVICE.lower().startswith("/cpu"):
+	os.environ["CUDA_VISIBLE_DEVICES"] = "-1"
+
+# Precise which GPU we use
+elif DataScienceConfig.TENSORFLOW_DEVICE.lower().startswith("/gpu"):
+	os.environ["CUDA_VISIBLE_DEVICES"] = DataScienceConfig.TENSORFLOW_DEVICE.split(":")[-1]
+
+	# Configure TensorFlow (if available)
+	try:
+		from tensorflow import config as tf_config
+
+		# Get the physical devices
+		physical_devices: list[Any] = tf_config.list_physical_devices("GPU")
+
+		# Configure TensorFlow GPU memory management to allocate memory dynamically
+		# This prevents TensorFlow from allocating all GPU memory upfront
+		# Instead, memory will grow as needed, allowing better resource sharing
+		for device in physical_devices:
+			tf_config.experimental.set_memory_growth(device, True)
+
+		# Disable eager execution mode in TensorFlow
+		# This improves performance by allowing TensorFlow to create an optimized graph
+		# of operations instead of executing operations one by one (at the cost of debugging difficulty)
+		tf_config.run_functions_eagerly(False)
+	except ImportError:
+		pass
+
+	# Enable mixed precision training (if available)
+	try:
+		from keras import mixed_precision
+		mixed_precision.set_global_policy(DataScienceConfig.MIXED_PRECISION_POLICY)
+	except ImportError:
+		pass
+

stouputils-1.2.41/stouputils/data_science/config/set.py

@@ -0,0 +1,103 @@
+""" Configuration file for the project. """
+
+# Imports
+import os
+from typing import Literal
+
+from stouputils.decorators import LogLevels
+from stouputils.io import get_root_path
+
+# Environment variables
+os.environ["TF_CPP_MIN_LOG_LEVEL"] = "9"         # Suppress TensorFlow logging
+os.environ["GRPC_VERBOSITY"] = "ERROR"           # Suppress gRPC logging
+
+
+# Configuration class
+class DataScienceConfig:
+	""" Configuration class for the project. """
+
+	# Common
+	SEED: int = 42
+	""" Seed for the random number generator. """
+
+	ERROR_LOG: LogLevels = LogLevels.WARNING_TRACEBACK
+	""" Log level for errors for all functions. """
+
+	AUGMENTED_FILE_SUFFIX: str = "_aug_"
+	""" Suffix for augmented files, ex: 'image_008_aug_1.png'. """
+
+	AUGMENTED_DIRECTORY_PREFIX: str = "aug_"
+	""" Prefix for augmented directories, ex: 'data/hip_implant' -> 'data/aug_hip_implant'. """
+
+	PREPROCESSED_DIRECTORY_SUFFIX: str = "_preprocessed"
+	""" Suffix for preprocessed directories, ex: 'data/hip_implant' -> 'data/hip_implant_preprocessed'. """
+
+
+	# Directories
+	ROOT: str = get_root_path(__file__, go_up=3)
+	""" Root directory of the project. """
+
+	MLFLOW_FOLDER: str = f"{ROOT}/mlruns"
+	""" Folder containing the mlflow data. """
+	MLFLOW_URI: str = f"file://{MLFLOW_FOLDER}"
+	""" URI to the mlflow data. """
+
+	DATA_FOLDER: str = f"{ROOT}/data"
+	""" Folder containing all the data (e.g. subfolders containing images). """
+
+	TEMP_FOLDER: str = f"{ROOT}/temp"
+	""" Folder containing temporary files (e.g. models checkpoints, plots, etc.). """
+
+	LOGS_FOLDER: str = f"{ROOT}/logs"
+	""" Folder containing the logs. """
+
+	TENSORBOARD_FOLDER: str = f"{ROOT}/tensorboard"
+	""" Folder containing the tensorboard logs. """
+
+
+	# Behaviours
+	TEST_SIZE: float = 0.2
+	""" Size of the test set by default (0.2 means 80% training, 20% test). """
+
+	VALIDATION_SIZE: float = 0.2
+	""" Size of the validation set by default (0.2 means 80% training, 20% validation). """
+
+	# Machine learning
+	SAVE_MODEL: bool = False
+	""" If the model should be saved in the mlflow folder using mlflow.*.save_model. """
+
+	DO_SALIENCY_AND_GRADCAM: bool = True
+	""" If the saliency and gradcam should be done during the run. """
+
+	DO_LEARNING_RATE_FINDER: Literal[0, 1, 2] = 1
+	""" If the learning rate finder should be done during the run.
+	0: no, 1: only plot, 2: plot and use value for the remaining run
+	"""
+
+	DO_UNFREEZE_FINDER: Literal[0, 1, 2] = 0
+	""" If the unfreeze finder should be done during the run.
+	0: no, 1: only plot, 2: plot and use value for the remaining run
+	"""
+
+	DO_FIT_IN_SUBPROCESS: bool = True
+	""" If the model should be fitted in a subprocess.
+	Is memory efficient, and more stable. Turn it off only if you are having issues.
+
+	Note: This allow a program to make lots of runs without getting killed by the OS for using too much resources.
+	(e.g. LeaveOneOut Cross Validation, Grid Search, etc.)
+	"""
+
+	MIXED_PRECISION_POLICY: Literal["mixed_float16", "mixed_bfloat16", "float32"] = "mixed_float16"
+	""" Mixed precision policy to use. Turn back to "float32" if you are having issues with a specific model or metrics.
+	See: https://www.tensorflow.org/guide/mixed_precision
+	"""
+
+	TENSORFLOW_DEVICE: str = "/gpu:1"
+	""" TensorFlow device to use. """
+
+
+
+# Fix MLFLOW_URI for Windows by adding a missing slash
+if os.name == "nt":
+	DataScienceConfig.MLFLOW_URI = DataScienceConfig.MLFLOW_URI.replace("file:", "file:/")
+

stouputils-1.2.41/stouputils/data_science/data_processing/image/__init__.py

@@ -0,0 +1,66 @@
+
+# Imports
+from .auto_contrast import auto_contrast_image
+from .axis_flip import flip_image
+from .bias_field_correction import bias_field_correction_image
+from .binary_threshold import binary_threshold_image
+from .blur import blur_image
+from .brightness import brightness_image
+from .canny import canny_image
+from .clahe import clahe_image
+from .contrast import contrast_image
+from .curvature_flow_filter import curvature_flow_filter_image
+from .denoise import (
+    adaptive_denoise_image,
+    bilateral_denoise_image,
+    nlm_denoise_image,
+    tv_denoise_image,
+    wavelet_denoise_image,
+)
+from .invert import invert_image
+from .laplacian import laplacian_image
+from .median_blur import median_blur_image
+from .noise import noise_image
+from .normalize import normalize_image
+from .random_erase import random_erase_image
+from .resize import resize_image
+from .rotation import rotate_image
+from .salt_pepper import salt_pepper_image
+from .sharpening import sharpen_image
+from .shearing import shear_image
+from .threshold import threshold_image
+from .translation import translate_image
+from .zoom import zoom_image
+
+__all__ = [
+    "adaptive_denoise_image",
+    "auto_contrast_image",
+    "bias_field_correction_image",
+    "bilateral_denoise_image",
+    "binary_threshold_image",
+    "blur_image",
+    "brightness_image",
+    "canny_image",
+    "clahe_image",
+    "contrast_image",
+    "curvature_flow_filter_image",
+    "flip_image",
+    "invert_image",
+    "laplacian_image",
+    "median_blur_image",
+    "nlm_denoise_image",
+    "noise_image",
+    "normalize_image",
+    "random_erase_image",
+    "resize_image",
+    "rotate_image",
+    "salt_pepper_image",
+    "sharpen_image",
+    "shear_image",
+    "threshold_image",
+    "translate_image",
+    "tv_denoise_image",
+    "wavelet_denoise_image",
+    "zoom_image",
+]
+

stouputils-1.2.41/stouputils/data_science/data_processing/image/auto_contrast.py

@@ -0,0 +1,79 @@
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def auto_contrast_image(image: NDArray[Any], ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Adjust the contrast of an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to adjust contrast
+		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]], dtype=np.uint8)
+	>>> adjusted = auto_contrast_image(image)
+	>>> adjusted.tolist()
+	[[0, 36, 73], [109, 146, 182], [219, 255, 255]]
+	>>> adjusted.shape == image.shape
+	True
+	>>> adjusted.dtype == image.dtype
+	True
+
+	>>> ## Test invalid inputs
+	>>> auto_contrast_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)
+
+	# Perform histogram clipping
+	clip_hist_percent: float = 1.0
+
+	# Calculate the histogram of the image
+	hist: NDArray[Any] = cv2.calcHist([image], [0], None, [256], [0, 256])
+
+	# Create an accumulator list to store the cumulative histogram
+	accumulator: list[float] = []
+	accumulator.append(hist[0])
+	for i in range(1, 256):
+		accumulator.append(accumulator[i - 1] + hist[i])
+
+	# Find the maximum value in the accumulator
+	max_value: float = accumulator[-1]
+
+	# Calculate the clipping threshold
+	clip_hist_percent = clip_hist_percent * (max_value / 100.0)
+	clip_hist_percent = clip_hist_percent / 2.0
+
+	# Find the minimum and maximum gray levels after clipping
+	min_gray: int = 0
+	while accumulator[min_gray] < clip_hist_percent:
+		min_gray = min_gray + 1
+	max_gray: int = 256 - 1
+	while (max_gray >= 0 and accumulator[max_gray] >= (max_value - clip_hist_percent)):
+		max_gray = max_gray - 1
+
+	# Calculate the input range after clipping
+	input_range: int = max_gray - min_gray
+
+	# If the input range is 0, return the original image
+	if input_range == 0:
+		return image
+
+	# Calculate the scaling factors for contrast adjustment
+	alpha: float = (256 - 1) / input_range
+	beta: float = -min_gray * alpha
+
+	# Apply the contrast adjustment
+	adjusted: NDArray[Any] = cv2.convertScaleAbs(image, alpha=alpha, beta=beta)
+	return adjusted
+

stouputils-1.2.41/stouputils/data_science/data_processing/image/axis_flip.py

@@ -0,0 +1,58 @@
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from typing import Literal
+
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def flip_image(
+	image: NDArray[Any], axis: Literal["horizontal", "vertical", "both"], ignore_dtype: bool = True
+) -> NDArray[Any]:
+	""" Flip an image along specified axis
+
+	Args:
+		image         (NDArray[Any]):     Image to flip
+		axis          (str):            Axis along which to flip ("horizontal" or "vertical" or "both")
+		ignore_dtype  (bool):           Ignore the dtype check
+	Returns:
+		NDArray[Any]: Flipped image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> flip_image(image, "horizontal").tolist()
+	[[3, 2, 1], [6, 5, 4], [9, 8, 7]]
+
+	>>> flip_image(image, "vertical").tolist()
+	[[7, 8, 9], [4, 5, 6], [1, 2, 3]]
+
+	>>> flip_image(image, "both").tolist()
+	[[9, 8, 7], [6, 5, 4], [3, 2, 1]]
+
+	>>> ## Test invalid inputs
+	>>> flip_image(image, "diagonal")
+	Traceback (most recent call last):
+	AssertionError: axis must be either 'horizontal' or 'vertical' or 'both', got 'diagonal'
+
+	>>> flip_image("not an image", "horizontal")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert axis in ("horizontal", "vertical", "both"), (
+		f"axis must be either 'horizontal' or 'vertical' or 'both', got '{axis}'"
+	)
+
+	# Apply the flip
+	if axis == "horizontal":
+		return cv2.flip(image, 1)	# 1 for horizontal flip
+	elif axis == "vertical":
+		return cv2.flip(image, 0)	# 0 for vertical flip
+	else:
+		return cv2.flip(image, -1)	# -1 for both flips
+

stouputils-1.2.41/stouputils/data_science/data_processing/image/bias_field_correction.py

@@ -0,0 +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)
+