stouputils 1.7.0__tar.gz → 1.7.2__tar.gz

{stouputils-1.7.0 → stouputils-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.7.0
+Version: 1.7.2
 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

{stouputils-1.7.0 → stouputils-1.7.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.7.0"
+version = "1.7.2"
 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"

{stouputils-1.7.0 → stouputils-1.7.2}/stouputils/all_doctests.py

@@ -13,14 +13,17 @@ import importlib
 import os
 import pkgutil
 import sys
-from doctest import TestResults, testmod
 from types import ModuleType
+from typing import TYPE_CHECKING
 
 from . import decorators
 from .decorators import measure_time
 from .io import clean_path, relative_path
 from .print import error, info, progress, warning
 
+if TYPE_CHECKING:
+	from doctest import TestResults
+
 
 # Main program
 def launch_tests(root_dir: str, strict: bool = True) -> int:
@@ -140,7 +143,7 @@ def launch_tests(root_dir: str, strict: bool = True) -> int:
 	return total_failed
 
 
-def test_module_with_progress(module: ModuleType, separator: str) -> TestResults:
+def test_module_with_progress(module: ModuleType, separator: str) -> "TestResults":
 	""" Test a module with testmod and measure the time taken with progress printing.
 
 	Args:
@@ -149,6 +152,7 @@ def test_module_with_progress(module: ModuleType, separator: str) -> TestResults
 	Returns:
 		TestResults: The results of the tests
 	"""
+	from doctest import TestResults, testmod
 	@measure_time(progress, message=f"Testing module '{module.__name__}' {separator}took")
 	def internal() -> TestResults:
 		return testmod(m=module)

{stouputils-1.7.0 → stouputils-1.7.2}/stouputils/archive.py

@@ -41,9 +41,6 @@ def repair_zip_file(file_path: str, destination: str) -> bool:
 
 		> repair_zip_file("/path/to/source.zip", "/path/to/destination.zip")
 	"""
-	import struct
-	import zlib
-
 	# Check
 	if not os.path.exists(file_path):
 		raise FileNotFoundError(f"File '{file_path}' not found")
@@ -51,6 +48,9 @@ def repair_zip_file(file_path: str, destination: str) -> bool:
 	if dirname and not os.path.exists(dirname):
 		raise FileNotFoundError(f"Directory '{dirname}' not found")
 
+	import struct
+	import zlib
+
 	# Read the entire ZIP file into memory
 	with open(file_path, 'rb') as f:
 		data = f.read()

{stouputils-1.7.0 → stouputils-1.7.2}/stouputils/collections.py

@@ -14,11 +14,14 @@ import atexit
 import os
 import shutil
 import tempfile
-from typing import Any, Literal, TypeVar
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
 
-import numpy as np
-import zarr  # pyright: ignore[reportMissingTypeStubs]
-from numpy.typing import NDArray
+# Lazy imports for typing
+if TYPE_CHECKING:
+	import numpy as np
+	import polars as pl
+	import zarr  # pyright: ignore[reportMissingTypeStubs]
+	from numpy.typing import NDArray
 
 # Typing
 T = TypeVar("T")
@@ -94,11 +97,62 @@ def sort_dict_keys(dictionary: dict[T, Any], order: list[T], reverse: bool = Fal
 	"""
 	return dict(sorted(dictionary.items(), key=lambda x: order.index(x[0]) if x[0] in order else len(order), reverse=reverse))
 
+def upsert_in_dataframe(
+	df: "pl.DataFrame",
+	new_entry: dict[str, Any],
+	primary_keys: dict[str, Any] | None = None
+) -> "pl.DataFrame":
+	""" Insert or update a row in the Polars DataFrame based on primary keys.
+
+	Args:
+		df				(pl.DataFrame):		The Polars DataFrame to update.
+		new_entry		(dict[str, Any]):	The new entry to insert or update.
+		primary_keys	(dict[str, Any]):	The primary keys to identify the row (default: empty).
+	Returns:
+		pl.DataFrame: The updated Polars DataFrame.
+	"""
+	# Imports
+	import polars as pl
+
+	# Create new DataFrame if file doesn't exist or is invalid
+	if df.is_empty():
+		return pl.DataFrame([new_entry])
+
+	# If no primary keys provided, return DataFrame with new entry appended
+	if not primary_keys:
+		new_row_df = pl.DataFrame([new_entry])
+		return pl.concat([df, new_row_df], how="diagonal_relaxed")
+
+	# Build mask based on primary keys
+	mask: pl.Expr = pl.lit(True)
+	for key, value in primary_keys.items():
+		if key in df.columns:
+			mask = mask & (df[key] == value)
+		else:
+			# Primary key column doesn't exist, so no match possible
+			mask = pl.lit(False)
+			break
+
+	# Insert or update row based on primary keys
+	if df.select(mask).to_series().any():
+		# Update existing row
+		for key, value in new_entry.items():
+			if key in df.columns:
+				df = df.with_columns(pl.when(mask).then(pl.lit(value)).otherwise(pl.col(key)).alias(key))
+			else:
+				# Add new column if it doesn't exist
+				df = df.with_columns(pl.when(mask).then(pl.lit(value)).otherwise(None).alias(key))
+		return df
+	else:
+		# Insert new row
+		new_row_df = pl.DataFrame([new_entry])
+		return pl.concat([df, new_row_df], how="diagonal_relaxed")
+
 def array_to_disk(
-	data: NDArray[Any] | zarr.Array,
+	data: "NDArray[Any] | zarr.Array",
 	delete_input: bool = True,
-	more_data: NDArray[Any] | zarr.Array | None = None
-) -> tuple[zarr.Array, str, int]:
+	more_data: "NDArray[Any] | zarr.Array | None" = None
+) -> tuple["zarr.Array", str, int]:
 	""" Easily handle large numpy arrays on disk using zarr for efficient storage and access.
 
 	Zarr provides a simpler and more efficient alternative to np.memmap with better compression
@@ -112,6 +166,7 @@ def array_to_disk(
 		tuple[zarr.Array, str, int]: The zarr array, the directory path, and the total size in bytes
 
 	Examples:
+		>>> import numpy as np
 		>>> data = np.random.rand(1000, 1000)
 		>>> zarr_array = array_to_disk(data)[0]
 		>>> zarr_array.shape
@@ -127,6 +182,9 @@ def array_to_disk(
 			for filename in filenames
 		)
 
+	# Imports
+	import zarr  # pyright: ignore[reportMissingTypeStubs]
+
 	# If data is already a zarr.Array and more_data is present, just append and return
 	if isinstance(data, zarr.Array) and more_data is not None:
 		original_size: int = data.shape[0]

{stouputils-1.7.0 → stouputils-1.7.2}/stouputils/collections.pyi

@@ -1,3 +1,4 @@
+import polars as pl
 import zarr
 from numpy.typing import NDArray as NDArray
 from typing import Any, Literal, TypeVar
@@ -49,7 +50,17 @@ def sort_dict_keys(dictionary: dict[T, Any], order: list[T], reverse: bool = Fal
 \t\t>>> sort_dict_keys({\'b\': 2, \'a\': 1, \'c\': 3, \'d\': 4}, order=["c", "b"])
 \t\t{\'c\': 3, \'b\': 2, \'a\': 1, \'d\': 4}
 \t'''
-def array_to_disk(data: NDArray[Any] | zarr.Array, delete_input: bool = True, more_data: NDArray[Any] | zarr.Array | None = None) -> tuple[zarr.Array, str, int]:
+def upsert_in_dataframe(df: pl.DataFrame, new_entry: dict[str, Any], primary_keys: dict[str, Any] | None = None) -> pl.DataFrame:
+    """ Insert or update a row in the Polars DataFrame based on primary keys.
+
+\tArgs:
+\t\tdf\t\t\t\t(pl.DataFrame):\t\tThe Polars DataFrame to update.
+\t\tnew_entry\t\t(dict[str, Any]):\tThe new entry to insert or update.
+\t\tprimary_keys\t(dict[str, Any]):\tThe primary keys to identify the row (default: empty).
+\tReturns:
+\t\tpl.DataFrame: The updated Polars DataFrame.
+\t"""
+def array_to_disk(data: NDArray[Any] | zarr.Array, delete_input: bool = True, more_data: NDArray[Any] | zarr.Array | None = None) -> tuple['zarr.Array', str, int]:
     """ Easily handle large numpy arrays on disk using zarr for efficient storage and access.
 
 \tZarr provides a simpler and more efficient alternative to np.memmap with better compression
@@ -63,6 +74,7 @@ def array_to_disk(data: NDArray[Any] | zarr.Array, delete_input: bool = True, mo
 \t\ttuple[zarr.Array, str, int]: The zarr array, the directory path, and the total size in bytes
 
 \tExamples:
+\t\t>>> import numpy as np
 \t\t>>> data = np.random.rand(1000, 1000)
 \t\t>>> zarr_array = array_to_disk(data)[0]
 \t\t>>> zarr_array.shape

{stouputils-1.7.0 → stouputils-1.7.2}/stouputils/continuous_delivery/cd_utils.py

@@ -4,15 +4,15 @@ It is mainly used by the `stouputils.continuous_delivery.github` module.
 
 # Imports
 import os
-from typing import Any
-
-import requests
-import yaml
+from typing import TYPE_CHECKING, Any
 
 from ..decorators import handle_error
 from ..io import clean_path, super_json_load
 from ..print import warning
 
+if TYPE_CHECKING:
+	import requests
+
 
 # Load credentials from file
 @handle_error()
@@ -63,6 +63,7 @@ def load_credentials(credentials_path: str) -> dict[str, Any]:
 
 	# Else, load the file if it's a YAML file
 	elif credentials_path.endswith((".yml", ".yaml")):
+		import yaml
 		with open(credentials_path) as f:
 			return yaml.safe_load(f)
 
@@ -71,7 +72,7 @@ def load_credentials(credentials_path: str) -> dict[str, Any]:
 		raise ValueError("Credentials file must be .json or .yml format")
 
 # Handle a response
-def handle_response(response: requests.Response, error_message: str) -> None:
+def handle_response(response: "requests.Response", error_message: str) -> None:
 	""" Handle a response from the API by raising an error if the response is not successful (status code not in 200-299).
 
 	Args:
@@ -79,6 +80,7 @@ def handle_response(response: requests.Response, error_message: str) -> None:
 		error_message	(str): The error message to raise if the response is not successful
 	"""
 	if response.status_code < 200 or response.status_code >= 300:
+		import requests
 		try:
 			raise ValueError(f"{error_message}, response code {response.status_code} with response {response.json()}")
 		except requests.exceptions.JSONDecodeError as e:

{stouputils-1.7.0 → stouputils-1.7.2}/stouputils/continuous_delivery/github.py

@@ -9,15 +9,16 @@
 
 # Imports
 import os
-from typing import Any
-
-import requests
+from typing import TYPE_CHECKING, Any
 
 from ..decorators import handle_error, measure_time
 from ..io import clean_path
 from ..print import info, progress, warning
 from .cd_utils import clean_version, handle_response, version_to_float
 
+if TYPE_CHECKING:
+	import requests
+
 # Constants
 GITHUB_API_URL: str = "https://api.github.com"
 PROJECT_ENDPOINT: str = f"{GITHUB_API_URL}/repos"
@@ -483,6 +484,8 @@ def upload_to_github(credentials: dict[str, Any], github_config: dict[str, Any])
 			}
 		)
 	"""
+	import requests  # type: ignore  # noqa: F401
+
 	# Validate credentials and configuration
 	owner, headers = validate_credentials(credentials)
 	project_name, version, build_folder, endswith = validate_config(github_config)

{stouputils-1.7.0 → stouputils-1.7.2}/stouputils/continuous_delivery/pyproject.py

@@ -17,8 +17,6 @@ writing, version management and TOML formatting capabilities.
 # Imports
 from typing import Any
 
-import toml
-
 from ..io import super_open
 
 
@@ -31,6 +29,7 @@ def read_pyproject(pyproject_path: str) -> dict[str, Any]:
 	Returns:
 		dict[str, Any]: The content of the pyproject.toml file.
 	"""
+	import toml
 	return toml.load(pyproject_path)
 
 
@@ -81,6 +80,7 @@ def format_toml_lists(content: str) -> str:
 
 def write_pyproject(pyproject_path: str, pyproject_content: dict[str, Any]) -> None:
 	""" Write to the pyproject.toml file with properly indented lists. """
+	import toml
 	content: str = "\n" + toml.dumps(pyproject_content) + "\n"
 	content = format_toml_lists(content)  # Apply formatting
 

stouputils-1.7.2/stouputils/image.py

@@ -0,0 +1,225 @@
+"""
+This module provides little utilities for image processing.
+
+- image_resize: Resize an image while preserving its aspect ratio by default.
+- auto_crop: Automatically crop an image to remove zero/uniform regions.
+
+See stouputils.data_science.data_processing for lots more image processing utilities.
+"""
+
+# Imports
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+	import numpy as np
+	from numpy.typing import NDArray
+	from PIL import Image
+
+
+# Functions
+def image_resize(
+	image: "Image.Image | NDArray[np.number]",
+	max_result_size: int,
+	resampling: "Image.Resampling | None" = None,
+	min_or_max: Callable[[int, int], int] = max,
+	return_type: type["Image.Image | NDArray[np.number]"] | str = "same",
+	keep_aspect_ratio: bool = True,
+) -> Any:
+	""" Resize an image while preserving its aspect ratio by default.
+	Scales the image so that its largest dimension equals max_result_size.
+
+	Args:
+		image             (Image.Image | np.ndarray): The image to resize.
+		max_result_size   (int):                      Maximum size for the largest dimension.
+		resampling        (Image.Resampling | None):  PIL resampling filter to use (default: Image.Resampling.LANCZOS).
+		min_or_max        (Callable):                 Function to use to get the minimum or maximum of the two ratios.
+		return_type       (type | str):               Type of the return value (Image.Image, np.ndarray, or "same" to match input type).
+		keep_aspect_ratio (bool):                     Whether to keep the aspect ratio.
+	Returns:
+		Image.Image | NDArray[np.number]: The resized image with preserved aspect ratio.
+	Examples:
+		>>> # Test with (height x width x channels) numpy array
+		>>> import numpy as np
+		>>> array = np.random.randint(0, 255, (100, 50, 3), dtype=np.uint8)
+		>>> image_resize(array, 100).shape
+		(100, 50, 3)
+		>>> image_resize(array, 100, min_or_max=max).shape
+		(100, 50, 3)
+		>>> image_resize(array, 100, min_or_max=min).shape
+		(200, 100, 3)
+
+		>>> # Test with PIL Image
+		>>> from PIL import Image
+		>>> pil_image: Image.Image = Image.new('RGB', (200, 100))
+		>>> image_resize(pil_image, 50).size
+		(50, 25)
+		>>> # Test with different return types
+		>>> resized_array = image_resize(array, 50, return_type=np.ndarray)
+		>>> isinstance(resized_array, np.ndarray)
+		True
+		>>> resized_array.shape
+		(50, 25, 3)
+		>>> # Test with different resampling methods
+		>>> image_resize(pil_image, 50, resampling=Image.Resampling.NEAREST).size
+		(50, 25)
+	"""
+	# Imports
+	import numpy as np
+	from PIL import Image
+
+	# Set default resampling method if not provided
+	if resampling is None:
+		resampling = Image.Resampling.LANCZOS
+
+	# Store original type for later conversion
+	original_was_pil: bool = isinstance(image, Image.Image)
+
+	# Convert numpy array to PIL Image if needed
+	if isinstance(image, np.ndarray):
+		image = Image.fromarray(image)
+
+	if keep_aspect_ratio:
+
+		# Get original image dimensions
+		width: int = image.size[0]
+		height: int = image.size[1]
+
+		# Determine which dimension to use for scaling based on min_or_max function
+		max_dimension: int = min_or_max(width, height)
+
+		# Calculate scaling factor
+		scale: float = max_result_size / max_dimension
+
+		# Calculate new dimensions while preserving aspect ratio
+		new_width: int = int(width * scale)
+		new_height: int = int(height * scale)
+
+		# Resize the image with the calculated dimensions
+		new_image: Image.Image = image.resize((new_width, new_height), resampling)
+	else:
+		# If not keeping aspect ratio, resize to square with max_result_size
+		new_image: Image.Image = image.resize((max_result_size, max_result_size), resampling)
+
+	# Return the image in the requested format
+	if return_type == "same":
+		# Return same type as input
+		if original_was_pil:
+			return new_image
+		else:
+			return np.array(new_image)
+	elif return_type == np.ndarray:
+		return np.array(new_image)
+	else:
+		return new_image
+
+
+def auto_crop(
+	image: "Image.Image | NDArray[np.number]",
+	mask: "NDArray[np.bool_] | None" = None,
+	threshold: int | float | Callable[["NDArray[np.number]"], int | float] | None = None,
+	return_type: type["Image.Image | NDArray[np.number]"] | str = "same",
+	contiguous: bool = True,
+) -> Any:
+	""" Automatically crop an image to remove zero or uniform regions.
+
+	This function crops the image to keep only the region where pixels are non-zero
+	(or above a threshold). It can work with a mask or directly analyze the image.
+
+	Args:
+		image       (Image.Image | NDArray):	  The image to crop.
+		mask        (NDArray[np.bool_] | None):   Optional binary mask indicating regions to keep.
+		threshold   (int | float | Callable):     Threshold value or function (default: np.min).
+		return_type (type | str):                 Type of the return value (Image.Image, NDArray[np.number], or "same" to match input type).
+		contiguous  (bool):                       If True (default), crop to bounding box. If False, remove entire rows/columns with no content.
+	Returns:
+		Image.Image | NDArray[np.number]: The cropped image.
+
+	Examples:
+		>>> # Test with numpy array with zeros on edges
+		>>> import numpy as np
+		>>> array = np.zeros((100, 100, 3), dtype=np.uint8)
+		>>> array[20:80, 30:70] = 255  # White rectangle in center
+		>>> cropped = auto_crop(array, return_type=np.ndarray)
+		>>> cropped.shape
+		(60, 40, 3)
+
+		>>> # Test with custom mask
+		>>> mask = np.zeros((100, 100), dtype=bool)
+		>>> mask[10:90, 10:90] = True
+		>>> cropped_with_mask = auto_crop(array, mask=mask, return_type=np.ndarray)
+		>>> cropped_with_mask.shape
+		(80, 80, 3)
+
+		>>> # Test with PIL Image
+		>>> from PIL import Image
+		>>> pil_image = Image.new('RGB', (100, 100), (0, 0, 0))
+		>>> from PIL import ImageDraw
+		>>> draw = ImageDraw.Draw(pil_image)
+		>>> draw.rectangle([25, 25, 75, 75], fill=(255, 255, 255))
+		>>> cropped_pil = auto_crop(pil_image)
+		>>> cropped_pil.size
+		(51, 51)
+
+		>>> # Test with threshold
+		>>> array_gray = np.ones((100, 100), dtype=np.uint8) * 10
+		>>> array_gray[20:80, 30:70] = 255
+		>>> cropped_threshold = auto_crop(array_gray, threshold=50, return_type=np.ndarray)
+		>>> cropped_threshold.shape
+		(60, 40)
+
+		>>> # Test with callable threshold (using lambda to avoid min value)
+		>>> array_gray2 = np.ones((100, 100), dtype=np.uint8) * 10
+		>>> array_gray2[20:80, 30:70] = 255
+		>>> cropped_max = auto_crop(array_gray2, threshold=lambda x: 50, return_type=np.ndarray)
+		>>> cropped_max.shape
+		(60, 40)
+
+		>>> # Test with non-contiguous crop
+		>>> array_sparse = np.zeros((100, 100, 3), dtype=np.uint8)
+		>>> array_sparse[10, 10] = 255
+		>>> array_sparse[50, 50] = 255
+		>>> array_sparse[90, 90] = 255
+		>>> cropped_contiguous = auto_crop(array_sparse, contiguous=True, return_type=np.ndarray)
+		>>> cropped_contiguous.shape  # Bounding box from (10,10) to (90,90)
+		(81, 81, 3)
+		>>> cropped_non_contiguous = auto_crop(array_sparse, contiguous=False, return_type=np.ndarray)
+		>>> cropped_non_contiguous.shape  # Only rows/cols 10, 50, 90
+		(3, 3, 3)
+	"""
+	# Imports
+	import numpy as np
+	from PIL import Image
+
+	# Convert to numpy array and store original type
+	original_was_pil: bool = isinstance(image, Image.Image)
+	image_array: NDArray[np.number] = np.array(image) if original_was_pil else image
+
+	# Create mask if not provided
+	if mask is None:
+		if threshold is None:
+			threshold = cast(Callable[["NDArray[np.number]"], int | float], np.min)
+		threshold_value: int | float = threshold(image_array) if callable(threshold) else threshold
+		mask = (image_array > threshold_value) if image_array.ndim == 2 else np.any(image_array > threshold_value, axis=2)
+
+	# Find rows and columns with content
+	rows_with_content: NDArray[np.bool_] = np.any(mask, axis=1)
+	cols_with_content: NDArray[np.bool_] = np.any(mask, axis=0)
+
+	# Return original if no content found
+	if not (np.any(rows_with_content) and np.any(cols_with_content)):
+		return image_array if return_type == np.ndarray else (image if original_was_pil else Image.fromarray(image_array))
+
+	# Crop based on contiguous parameter
+	if contiguous:
+		row_idx, col_idx = np.where(rows_with_content)[0], np.where(cols_with_content)[0]
+		cropped_array: NDArray[np.number] = image_array[row_idx[0]:row_idx[-1]+1, col_idx[0]:col_idx[-1]+1]
+	else:
+		ix = np.ix_(rows_with_content, cols_with_content, np.ones(image_array.shape[2], dtype=bool)) if image_array.ndim == 3 else np.ix_(rows_with_content, cols_with_content)
+		cropped_array = image_array[ix]
+
+	# Return in requested format
+	if return_type == "same":
+		return Image.fromarray(cropped_array) if original_was_pil else cropped_array
+	return cropped_array if return_type == np.ndarray else Image.fromarray(cropped_array)
+

stouputils-1.7.2/stouputils/image.pyi

@@ -0,0 +1,112 @@
+import numpy as np
+from PIL import Image
+from collections.abc import Callable
+from numpy.typing import NDArray as NDArray
+from typing import Any
+
+def image_resize(image: Image.Image | NDArray[np.number], max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[Image.Image | NDArray[np.number]] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
+    ''' Resize an image while preserving its aspect ratio by default.
+\tScales the image so that its largest dimension equals max_result_size.
+
+\tArgs:
+\t\timage             (Image.Image | np.ndarray): The image to resize.
+\t\tmax_result_size   (int):                      Maximum size for the largest dimension.
+\t\tresampling        (Image.Resampling | None):  PIL resampling filter to use (default: Image.Resampling.LANCZOS).
+\t\tmin_or_max        (Callable):                 Function to use to get the minimum or maximum of the two ratios.
+\t\treturn_type       (type | str):               Type of the return value (Image.Image, np.ndarray, or "same" to match input type).
+\t\tkeep_aspect_ratio (bool):                     Whether to keep the aspect ratio.
+\tReturns:
+\t\tImage.Image | NDArray[np.number]: The resized image with preserved aspect ratio.
+\tExamples:
+\t\t>>> # Test with (height x width x channels) numpy array
+\t\t>>> import numpy as np
+\t\t>>> array = np.random.randint(0, 255, (100, 50, 3), dtype=np.uint8)
+\t\t>>> image_resize(array, 100).shape
+\t\t(100, 50, 3)
+\t\t>>> image_resize(array, 100, min_or_max=max).shape
+\t\t(100, 50, 3)
+\t\t>>> image_resize(array, 100, min_or_max=min).shape
+\t\t(200, 100, 3)
+
+\t\t>>> # Test with PIL Image
+\t\t>>> from PIL import Image
+\t\t>>> pil_image: Image.Image = Image.new(\'RGB\', (200, 100))
+\t\t>>> image_resize(pil_image, 50).size
+\t\t(50, 25)
+\t\t>>> # Test with different return types
+\t\t>>> resized_array = image_resize(array, 50, return_type=np.ndarray)
+\t\t>>> isinstance(resized_array, np.ndarray)
+\t\tTrue
+\t\t>>> resized_array.shape
+\t\t(50, 25, 3)
+\t\t>>> # Test with different resampling methods
+\t\t>>> image_resize(pil_image, 50, resampling=Image.Resampling.NEAREST).size
+\t\t(50, 25)
+\t'''
+def auto_crop(image: Image.Image | NDArray[np.number], mask: NDArray[np.bool_] | None = None, threshold: int | float | Callable[[NDArray[np.number]], int | float] | None = None, return_type: type[Image.Image | NDArray[np.number]] | str = 'same', contiguous: bool = True) -> Any:
+    ''' Automatically crop an image to remove zero or uniform regions.
+
+\tThis function crops the image to keep only the region where pixels are non-zero
+\t(or above a threshold). It can work with a mask or directly analyze the image.
+
+\tArgs:
+\t\timage       (Image.Image | NDArray):\t  The image to crop.
+\t\tmask        (NDArray[np.bool_] | None):   Optional binary mask indicating regions to keep.
+\t\tthreshold   (int | float | Callable):     Threshold value or function (default: np.min).
+\t\treturn_type (type | str):                 Type of the return value (Image.Image, NDArray[np.number], or "same" to match input type).
+\t\tcontiguous  (bool):                       If True (default), crop to bounding box. If False, remove entire rows/columns with no content.
+\tReturns:
+\t\tImage.Image | NDArray[np.number]: The cropped image.
+
+\tExamples:
+\t\t>>> # Test with numpy array with zeros on edges
+\t\t>>> import numpy as np
+\t\t>>> array = np.zeros((100, 100, 3), dtype=np.uint8)
+\t\t>>> array[20:80, 30:70] = 255  # White rectangle in center
+\t\t>>> cropped = auto_crop(array, return_type=np.ndarray)
+\t\t>>> cropped.shape
+\t\t(60, 40, 3)
+
+\t\t>>> # Test with custom mask
+\t\t>>> mask = np.zeros((100, 100), dtype=bool)
+\t\t>>> mask[10:90, 10:90] = True
+\t\t>>> cropped_with_mask = auto_crop(array, mask=mask, return_type=np.ndarray)
+\t\t>>> cropped_with_mask.shape
+\t\t(80, 80, 3)
+
+\t\t>>> # Test with PIL Image
+\t\t>>> from PIL import Image
+\t\t>>> pil_image = Image.new(\'RGB\', (100, 100), (0, 0, 0))
+\t\t>>> from PIL import ImageDraw
+\t\t>>> draw = ImageDraw.Draw(pil_image)
+\t\t>>> draw.rectangle([25, 25, 75, 75], fill=(255, 255, 255))
+\t\t>>> cropped_pil = auto_crop(pil_image)
+\t\t>>> cropped_pil.size
+\t\t(51, 51)
+
+\t\t>>> # Test with threshold
+\t\t>>> array_gray = np.ones((100, 100), dtype=np.uint8) * 10
+\t\t>>> array_gray[20:80, 30:70] = 255
+\t\t>>> cropped_threshold = auto_crop(array_gray, threshold=50, return_type=np.ndarray)
+\t\t>>> cropped_threshold.shape
+\t\t(60, 40)
+
+\t\t>>> # Test with callable threshold (using lambda to avoid min value)
+\t\t>>> array_gray2 = np.ones((100, 100), dtype=np.uint8) * 10
+\t\t>>> array_gray2[20:80, 30:70] = 255
+\t\t>>> cropped_max = auto_crop(array_gray2, threshold=lambda x: 50, return_type=np.ndarray)
+\t\t>>> cropped_max.shape
+\t\t(60, 40)
+
+\t\t>>> # Test with non-contiguous crop
+\t\t>>> array_sparse = np.zeros((100, 100, 3), dtype=np.uint8)
+\t\t>>> array_sparse[10, 10] = 255
+\t\t>>> array_sparse[50, 50] = 255
+\t\t>>> array_sparse[90, 90] = 255
+\t\t>>> cropped_contiguous = auto_crop(array_sparse, contiguous=True, return_type=np.ndarray)
+\t\t>>> cropped_contiguous.shape  # Bounding box from (10,10) to (90,90)
+\t\t(81, 81, 3)
+\t\t>>> cropped_non_contiguous = auto_crop(array_sparse, contiguous=False, return_type=np.ndarray)
+\t\t>>> cropped_non_contiguous.shape  # Only rows/cols 10, 50, 90
+\t\t(3, 3, 3)
+\t'''