stouputils.data_science.data_processing.image.histogram_equalization module#

histogram_equalization_image(image: ndarray[Any, dtype[Any]], color_space: Literal['lab', 'ycbcr', 'hsv'] = 'lab', ignore_dtype: bool = False) → ndarray[Any, dtype[Any]][source]#

Apply standard histogram equalization to an image.

Histogram equalization improves the contrast in images by stretching the intensity range to utilize the full range of intensity values.

Parameters:

  • image (NDArray[Any]) – Image to apply histogram equalization to

  • color_space (str) – Color space to use for equalization (“lab”, “ycbcr”, or “hsv”) “lab”: CIELab color space (perceptually uniform, best visual fidelity) “ycbcr”: YCbCr color space (fast, good balance) “hsv”: HSV color space (intuitive, may cause color shifts)

  • ignore_dtype (bool) – Ignore the dtype check

Returns:

Image with histogram equalization applied

Return type:

NDArray[Any]

>>> ## Basic tests
>>> image = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> histogram_equalization_image(image.astype(np.uint8)).tolist()
[[0, 32, 64], [96, 128, 159], [191, 223, 255]]

>>> img = np.full((5,5), 128, dtype=np.uint8)
>>> img[1:3, 1:3] = 200  # Create a bright region
>>> histogram_equalization_image(img).tolist()
[[0, 0, 0, 0, 0], [0, 255, 255, 0, 0], [0, 255, 255, 0, 0], [0, 0, 0, 0, 0], [0, 0, 0, 0, 0]]

>>> rgb = np.full((3,3,3), 128, dtype=np.uint8)
>>> rgb[1, 1, :] = 50  # Create a dark region
>>> equalized_rgb = histogram_equalization_image(rgb)
>>> bool(np.std(equalized_rgb) > np.std(rgb))  # Should enhance contrast
True
>>> equalized_rgb.tolist()
[[[255, 255, 255], [255, 255, 255], [255, 255, 255]], [[255, 255, 255], [0, 0, 0], [255, 255, 255]], [[255, 255, 255], [255, 255, 255], [255, 255, 255]]]

>>> ## Test each color space
>>> test_img = np.zeros((20, 20, 3), dtype=np.uint8)
>>> test_img[5:15, 5:15] = 200  # Add contrast region

>>> # Test LAB color space
>>> lab_result = histogram_equalization_image(test_img, color_space="lab")
>>> isinstance(lab_result, np.ndarray) and lab_result.shape == test_img.shape
True
>>> bool(np.std(lab_result) > np.std(test_img))  # Verify contrast enhancement
True

>>> # Test YCbCr color space
>>> ycbcr_result = histogram_equalization_image(test_img, color_space="ycbcr")
>>> isinstance(ycbcr_result, np.ndarray) and ycbcr_result.shape == test_img.shape
True
>>> bool(np.std(ycbcr_result) > np.std(test_img))  # Verify contrast enhancement
True

>>> # Test HSV color space
>>> hsv_result = histogram_equalization_image(test_img, color_space="hsv")
>>> isinstance(hsv_result, np.ndarray) and hsv_result.shape == test_img.shape
True
>>> bool(np.std(hsv_result) > np.std(test_img))  # Verify contrast enhancement
True

>>> ## Test invalid inputs
>>> histogram_equalization_image("not an image")
Traceback (most recent call last):
        ...
AssertionError: Image must be a numpy array

>>> histogram_equalization_image(rgb, "invalid_space")
Traceback (most recent call last):
        ...
AssertionError: color_space must be one of: lab, ycbcr, hsv