stouputils 1.14.0__py3-none-any.whl

stouputils/data_science/data_processing/image/noise.py

@@ -0,0 +1,59 @@
+
+# Imports
+from .common import Any, NDArray, check_image, np
+
+
+# Functions
+def noise_image(image: NDArray[Any], amount: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Add Gaussian noise to an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to add noise to
+		amount        (float):       Amount of noise to add (between 0 and 1)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Noisy image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> noisy = noise_image(image.astype(np.uint8), 0.5)
+	>>> noisy.shape == image.shape
+	True
+	>>> bool(np.all(noisy >= 0) and np.all(noisy <= 255))
+	True
+
+	>>> np.random.seed(0)
+	>>> image = np.array([[128] * 3] * 3)
+	>>> noise_image(image.astype(np.uint8), 0.1).tolist()
+	[[172, 138, 152], [185, 175, 104], [152, 125, 126]]
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> noisy_rgb = noise_image(rgb, 0.1)
+	>>> noisy_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> noise_image("not an image", 0.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> noise_image(image.astype(np.uint8), "0.5")
+	Traceback (most recent call last):
+		...
+	AssertionError: amount must be a number, got <class 'str'>
+
+	>>> noise_image(image.astype(np.uint8), 1.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: amount must be between 0 and 1, got 1.5
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(amount, float | int), f"amount must be a number, got {type(amount)}"
+	assert 0 <= amount <= 1, f"amount must be between 0 and 1, got {amount}"
+
+	# Generate noise
+	noise: NDArray[Any] = np.random.normal(0, amount * 255, image.shape).astype(np.int16)
+	return np.clip(image.astype(np.int16) + noise, 0, 255).astype(image.dtype) # pyright: ignore [reportUnknownMemberType]
+

stouputils/data_science/data_processing/image/normalize.py

@@ -0,0 +1,65 @@
+
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnusedImport=false
+# pyright: reportArgumentType=false
+# pyright: reportCallIssue=false
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np  # noqa: F401
+
+
+# Functions
+def normalize_image(
+	image: NDArray[Any],
+	a: float | int = 0,
+	b: float | int = 255,
+	method: int = cv2.NORM_MINMAX,
+	ignore_dtype: bool = False,
+) -> NDArray[Any]:
+	""" Normalize an image to the range 0-255.
+
+	Args:
+		image         (NDArray[Any]):  Image to normalize
+		a             (float | int): Minimum value (default: 0)
+		b             (float | int): Maximum value (default: 255)
+		method        (int):         Normalization method (default: cv2.NORM_MINMAX)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Normalized image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=np.uint8)
+	>>> normalized = normalize_image(image)
+	>>> normalized.tolist()
+	[[0, 32, 64], [96, 128, 159], [191, 223, 255]]
+	>>> normalized.shape == image.shape
+	True
+	>>> normalized.dtype == image.dtype
+	True
+
+	>>> ## Test invalid inputs
+	>>> normalize_image("not an image")
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> normalize_image(image, a="not an integer")
+	Traceback (most recent call last):
+		...
+	AssertionError: a must be a float or an integer
+
+	>>> normalize_image(image, b="not an integer")
+	Traceback (most recent call last):
+		...
+	AssertionError: b must be a float or an integer
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(a, float | int), "a must be a float or an integer"
+	assert isinstance(b, float | int), "b must be a float or an integer"
+	assert isinstance(method, int), "method must be an integer"
+	assert a < b, "a must be less than b"
+
+	# Normalize image
+	return cv2.normalize(image, None, a, b, method)
+

stouputils/data_science/data_processing/image/random_erase.py

@@ -0,0 +1,66 @@
+
+# pyright: reportUnknownMemberType=false
+
+# Imports
+from .common import Any, NDArray, check_image, np
+
+
+# Functions
+def random_erase_image(image: NDArray[Any], erase_factor: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Randomly erase a rectangle in the image.
+
+	Args:
+		image         (NDArray[Any]):  Image to apply random erase
+		erase_factor  (float):       Factor determining the size of the rectangle to erase
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with random erasing applied
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> erased = random_erase_image(image.astype(np.uint8), 0.5)
+	>>> erased.shape == image.shape
+	True
+
+	>>> np.random.seed(42)
+	>>> img = np.ones((5,5), dtype=np.uint8) * 255
+	>>> erased = random_erase_image(img, 0.4)
+	>>> bool(np.any(erased == 0))  # Should have some erased pixels
+	True
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> erased_rgb = random_erase_image(rgb, 0.3)
+	>>> erased_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> random_erase_image("not an image", 0.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> random_erase_image(image.astype(np.uint8), "0.5")
+	Traceback (most recent call last):
+		...
+	AssertionError: erase_factor must be a number, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(erase_factor, float | int), f"erase_factor must be a number, got {type(erase_factor)}"
+
+	# Get image dimensions
+	height, width = image.shape[:2]
+
+	# Determine size of the rectangle to erase
+	erase_height: int = int(height * erase_factor)
+	erase_width: int = int(width * erase_factor)
+
+	# Randomly choose the top-left corner of the rectangle
+	top_left_x: int = np.random.randint(0, width - erase_width)
+	top_left_y: int = np.random.randint(0, height - erase_height)
+
+	# Apply random erasing
+	erased_image: NDArray[Any] = image.copy()
+	erased_image[top_left_y:top_left_y + erase_height, top_left_x:top_left_x + erase_width] = 0
+	return erased_image
+

stouputils/data_science/data_processing/image/resize.py

@@ -0,0 +1,69 @@
+
+# Imports
+from PIL import Image
+
+from .common import Any, NDArray, check_image, np
+
+
+# Functions
+def resize_image(
+	image: NDArray[Any],
+	width: int,
+	height: int,
+	resample: Image.Resampling | int = Image.Resampling.LANCZOS,
+	ignore_dtype: bool = False
+) -> NDArray[Any]:
+	""" Resize an image to a new width and height.
+
+	Args:
+		image         (NDArray[Any]):              Image to resize
+		width         (int):                     New width
+		height        (int):                     New height
+		resample      (Image.Resampling | int):  Resampling method
+		ignore_dtype  (bool):                    Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with resized dimensions
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> resized = resize_image(image.astype(np.uint8), 6, 6)
+	>>> resized.shape
+	(6, 6)
+
+	>>> img = np.ones((5, 5), dtype=np.uint8) * 255
+	>>> resized = resize_image(img, 10, 10)
+	>>> resized.shape
+	(10, 10)
+
+	>>> rgb = np.full((3, 3, 3), 128, dtype=np.uint8)
+	>>> resized_rgb = resize_image(rgb, 6, 6)
+	>>> resized_rgb.shape
+	(6, 6, 3)
+
+	>>> ## Test invalid inputs
+	>>> resize_image("not an image", 10, 10)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> resize_image(image.astype(np.uint8), "10", 10)
+	Traceback (most recent call last):
+		...
+	AssertionError: width must be integer, got <class 'str'>
+
+	>>> resize_image(image.astype(np.uint8), 10, "10")
+	Traceback (most recent call last):
+		...
+	AssertionError: height must be integer, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(width, int), f"width must be integer, got {type(width)}"
+	assert isinstance(height, int), f"height must be integer, got {type(height)}"
+	assert isinstance(resample, Image.Resampling | int), f"resample must be Image.Resampling, got {type(resample)}"
+
+	# Resize image
+	new_image: Image.Image = Image.fromarray(image)
+	new_image = new_image.resize((width, height), resample=resample)
+	return np.array(new_image)
+

stouputils/data_science/data_processing/image/rotation.py

@@ -0,0 +1,80 @@
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def rotate_image(image: NDArray[Any], angle: float | int, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Rotate an image by a given angle.
+
+	Args:
+		image         (NDArray[Any]):  Image to rotate
+		angle         (float|int):   Angle in degrees to rotate the image (between -360 and 360)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Rotated image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> rotate_image(image.astype(np.int16), 90).tolist()
+	[[3, 6, 9], [2, 5, 8], [1, 4, 7]]
+
+	>>> rotate_image(image.astype(np.float32), 90).tolist()
+	[[3.0, 6.0, 9.0], [2.0, 5.0, 8.0], [1.0, 4.0, 7.0]]
+
+	>>> rotate_image(image.astype(np.uint8), 45).tolist()
+	[[1, 4, 4], [2, 5, 8], [2, 6, 5]]
+
+	>>> rotate_image(image.astype(np.float32), 45).tolist()
+	[[1.1875, 3.5625, 3.5625], [2.125, 5.0, 7.875], [2.375, 6.4375, 4.75]]
+
+	>>> ## Test invalid inputs
+	>>> rotate_image([1,2,3], 90)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> rotate_image(np.array([1,2,3]), 90)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must have at least 2 dimensions
+
+	>>> rotate_image(image.astype(np.uint8), "90")
+	Traceback (most recent call last):
+		...
+	AssertionError: Angle must be a number, got <class 'str'>
+
+	>>> rotate_image(image.astype(np.uint8), 400)
+	Traceback (most recent call last):
+		...
+	AssertionError: Angle must be between -360 and 360 degrees, got 400
+
+	>>> rotate_image(image.astype(np.int32), 90)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be of type [<class 'numpy.uint8'>, <class 'numpy.int16'>, <class 'numpy.float32'>, <class 'numpy.float64'>]
+	"""  # noqa: E501
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(angle, float | int), f"Angle must be a number, got {type(angle)}"
+	assert -360 <= angle <= 360, f"Angle must be between -360 and 360 degrees, got {angle}"
+
+	# Get image dimensions
+	height: int
+	width: int
+	height, width = image.shape[:2]
+	image_center: tuple[int, int] = (width // 2, height // 2)
+
+	# Get rotation matrix and rotate image
+	rotation_matrix: NDArray[Any] = cv2.getRotationMatrix2D(image_center, angle, 1.0)
+	rotated_image: NDArray[Any] = cv2.warpAffine(
+		image,
+		rotation_matrix,
+		(width, height)
+	)
+
+	return rotated_image
+

stouputils/data_science/data_processing/image/salt_pepper.py

@@ -0,0 +1,68 @@
+
+# Imports
+from .common import Any, NDArray, check_image, np
+
+
+# Functions
+def salt_pepper_image(image: NDArray[Any], density: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Add salt and pepper noise to an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to add noise to
+		density       (float):       Density of the noise (between 0 and 1)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Image with salt and pepper noise
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> noisy = salt_pepper_image(image.astype(np.uint8), 0.1)
+	>>> noisy.shape == image.shape
+	True
+
+	>>> np.random.seed(42)
+	>>> img = np.full((4,4), 128, dtype=np.uint8)
+	>>> noisy = salt_pepper_image(img, 1.0)
+	>>> sorted(np.unique(noisy).tolist())  # Should only contain 0 and 255
+	[0, 255]
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> noisy_rgb = salt_pepper_image(rgb, 0.1)
+	>>> noisy_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> salt_pepper_image("not an image", 0.1)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> salt_pepper_image(image.astype(np.uint8), "0.1")
+	Traceback (most recent call last):
+		...
+	AssertionError: density must be a number, got <class 'str'>
+
+	>>> salt_pepper_image(image.astype(np.uint8), 1.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: density must be between 0 and 1, got 1.5
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(density, float | int), f"density must be a number, got {type(density)}"
+	assert 0 <= density <= 1, f"density must be between 0 and 1, got {density}"
+
+	# Create a mask of the same shape as the input image
+	mask: NDArray[Any] = np.random.choice( # pyright: ignore [reportUnknownMemberType]
+		[0, 1, 2],
+		size=image.shape,
+		p=[1-density, density/2, density/2],
+	)
+
+	# Apply the mask to the input image
+	noisy_image: NDArray[Any] = image.copy()
+	noisy_image[mask == 1] = 0		# Pepper noise
+	noisy_image[mask == 2] = 255	# Salt noise
+
+	return noisy_image
+

stouputils/data_science/data_processing/image/sharpening.py

@@ -0,0 +1,55 @@
+
+# pyright: reportUnusedImport=false
+# ruff: noqa: F401
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def sharpen_image(image: NDArray[Any], alpha: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Sharpen an image.
+
+	Args:
+		image         (NDArray[Any]):  Image to sharpen
+		alpha         (float):       Sharpening factor
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Sharpened image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> sharpened = sharpen_image(image.astype(np.uint8), 1.5)
+	>>> sharpened.shape == image.shape
+	True
+
+	>>> img = np.full((5,5), 128, dtype=np.uint8)
+	>>> img[2,2] = 255  # Center bright pixel
+	>>> sharp = sharpen_image(img, 1.0)
+	>>> bool(sharp[2,2] > img[2,2] * 0.9)  # Center should stay bright
+	True
+
+	>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
+	>>> sharp_rgb = sharpen_image(rgb, 1.0)
+	>>> sharp_rgb.shape == (3,3,3)
+	True
+
+	>>> ## Test invalid inputs
+	>>> sharpen_image("not an image", 1.5)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> sharpen_image(image.astype(np.uint8), "1.5")
+	Traceback (most recent call last):
+		...
+	AssertionError: alpha must be a number, got <class 'str'>
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(alpha, float | int), f"alpha must be a number, got {type(alpha)}"
+
+	# Apply sharpening
+	blurred: NDArray[Any] = cv2.GaussianBlur(image, (0, 0), 3)
+	return cv2.addWeighted(image, 1 + alpha, blurred, -alpha, 0)
+

stouputils/data_science/data_processing/image/shearing.py

@@ -0,0 +1,64 @@
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def shear_image(image: NDArray[Any], x: float, y: float, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Shear an image
+
+	Args:
+		image         (NDArray[Any]):  Image to shear
+		x             (float):       Shearing along the x axis (between -180 and 180)
+		y             (float):       Shearing along the y axis (between -180 and 180)
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Sheared image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+	>>> shear_image(image.astype(np.uint8), 15, 0).tolist()
+	[[1, 2, 3], [3, 5, 6], [3, 7, 8]]
+
+	>>> shear_image(image.astype(np.float32), 0, 15).tolist()
+	[[1.0, 1.4375, 1.40625], [4.0, 4.15625, 4.40625], [7.0, 7.15625, 7.40625]]
+
+	>>> ## Test invalid inputs
+	>>> shear_image(image.astype(np.uint8), 200, 0)
+	Traceback (most recent call last):
+		...
+	AssertionError: x must be between -180 and 180, got 200
+
+	>>> shear_image(image.astype(np.uint8), 0, -200)
+	Traceback (most recent call last):
+		...
+	AssertionError: y must be between -180 and 180, got -200
+
+	>>> shear_image("not an image", 0, 0)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(x, float | int), f"x must be a number, got {type(x)}"
+	assert isinstance(y, float | int), f"y must be a number, got {type(y)}"
+	assert -180 <= x <= 180, f"x must be between -180 and 180, got {x}"
+	assert -180 <= y <= 180, f"y must be between -180 and 180, got {y}"
+
+	# Get image dimensions
+	height, width = image.shape[:2]
+
+	# Convert relative shear angles to absolute values
+	x_shear: float = np.tan(np.radians(x))
+	y_shear: float = np.tan(np.radians(y))
+
+	# Create shear matrix
+	shear_matrix: NDArray[Any] = np.array([
+		[1, x_shear, 0],
+		[y_shear, 1, 0]
+	], dtype=np.float32)
+
+	# Apply affine transformation
+	return cv2.warpAffine(image, shear_matrix, (width, height))
+

stouputils/data_science/data_processing/image/threshold.py

@@ -0,0 +1,64 @@
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def threshold_image(image: NDArray[Any], thresholds: list[float], ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Apply multi-level threshold to an image.
+
+	Args:
+		image         (NDArray[Any]):      Image to threshold
+		threshold     (list[float]):     List of threshold values (between 0 and 1)
+		ignore_dtype  (bool):            Ignore the dtype check
+	Returns:
+		NDArray[Any]: Multi-level thresholded image
+
+	>>> ## Basic tests
+	>>> image = np.array([[100, 150, 200], [50, 125, 175], [25, 75, 225]])
+	>>> threshold_image(image.astype(np.uint8), [0.3, 0.6]).tolist()
+	[[85, 85, 170], [0, 85, 170], [0, 0, 170]]
+
+	>>> rgb = np.random.randint(0, 256, (3,3,3), dtype=np.uint8)
+	>>> thresh_rgb = threshold_image(rgb, [0.3, 0.6])
+	>>> thresh_rgb.shape == rgb.shape
+	True
+
+	>>> ## Test invalid inputs
+	>>> threshold_image("not an image", [0.5])
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> threshold_image(image.astype(np.uint8), [1.5])
+	Traceback (most recent call last):
+		...
+	AssertionError: threshold values must be between 0 and 1, got [1.5]
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert all(0 <= t <= 1 for t in thresholds), f"threshold values must be between 0 and 1, got {thresholds}"
+
+	# Convert thresholds from 0-1 range to 0-255 range
+	threshold_values: list[int] = [int(t * 255) for t in sorted(thresholds)]
+
+	# Apply threshold
+	if len(image.shape) == 2:
+		# Grayscale image
+		result: NDArray[Any] = np.zeros_like(image)
+		for i, thresh in enumerate(threshold_values):
+			value: int = int(255 * (i + 1) / (len(threshold_values) + 1))
+			mask: NDArray[Any] = cv2.threshold(image, thresh, value, cv2.THRESH_BINARY)[1]
+			result = cv2.max(result, mask)
+	else:
+		# Color image - convert to grayscale first, then back to color
+		gray: NDArray[Any] = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+		result: NDArray[Any] = np.zeros_like(gray)
+		for i, thresh in enumerate(threshold_values):
+			value: int = int(255 * (i + 1) / (len(threshold_values) + 1))
+			mask: NDArray[Any] = cv2.threshold(gray, thresh, value, cv2.THRESH_BINARY)[1]
+			result = cv2.max(result, mask)
+		result = cv2.cvtColor(result, cv2.COLOR_GRAY2BGR)
+
+	return result
+

stouputils/data_science/data_processing/image/translation.py

@@ -0,0 +1,71 @@
+
+# Imports
+from .common import Any, NDArray, check_image, cv2, np
+
+
+# Functions
+def translate_image(image: NDArray[Any], x: float, y: float, padding: int = 0, ignore_dtype: bool = False) -> NDArray[Any]:
+	""" Translate an image
+
+	Args:
+		image         (NDArray[Any]):  Image to translate
+		x             (float):       Translation along the x axis (between -1 and 1)
+		y             (float):       Translation along the y axis (between -1 and 1)
+		padding       (int):         Padding that has been added to the image before calling this function
+		ignore_dtype  (bool):        Ignore the dtype check
+	Returns:
+		NDArray[Any]: Translated image
+
+	>>> ## Basic tests
+	>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]).astype(np.uint8)
+	>>> translate_image(image, 0.5, 0.5).tolist()
+	[[0, 0, 0], [0, 1, 2], [0, 4, 5]]
+
+	>>> translate_image(image, 0, -2/3).tolist()
+	[[7, 8, 9], [0, 0, 0], [0, 0, 0]]
+
+	>>> ## Test invalid inputs
+	>>> translate_image(image, 2, 0)
+	Traceback (most recent call last):
+		...
+	AssertionError: x must be between -1 and 1, got 2
+
+	>>> translate_image(image, 0, 2)
+	Traceback (most recent call last):
+		...
+	AssertionError: y must be between -1 and 1, got 2
+
+	>>> translate_image("not an image", 0, 0)
+	Traceback (most recent call last):
+		...
+	AssertionError: Image must be a numpy array
+
+	>>> translate_image(image, 0, 0, padding=-1)
+	Traceback (most recent call last):
+		...
+	AssertionError: padding must be positive, got -1
+	"""
+	# Check input data
+	check_image(image, ignore_dtype=ignore_dtype)
+	assert isinstance(x, float | int), f"x must be a number, got {type(x)}"
+	assert isinstance(y, float | int), f"y must be a number, got {type(y)}"
+	assert -1 <= x <= 1, f"x must be between -1 and 1, got {x}"
+	assert -1 <= y <= 1, f"y must be between -1 and 1, got {y}"
+	assert isinstance(padding, int), f"padding must be an integer, got {type(padding)}"
+	assert padding >= 0, f"padding must be positive, got {padding}"
+
+	# Get image dimensions
+	height, width = image.shape[:2]
+	original_width: int = width - 2 * padding
+	original_height: int = height - 2 * padding
+
+	# Convert relative translations to absolute pixels
+	x_pixels: int = int(x * original_width)
+	y_pixels: int = int(y * original_height)
+
+	# Create translation matrix
+	translation_matrix: NDArray[Any] = np.array([[1, 0, x_pixels], [0, 1, y_pixels]], dtype=np.float32)
+
+	# Apply affine transformation
+	return cv2.warpAffine(image, translation_matrix, (width, height))
+