Welcome to cie-utils’s documentation!

Module Reference

cie_utils.accumulate_histograms(input_dir: str, labels_dir: str, n_clusters: int, component: str = 'L', bins: int = 40, use_sampling: bool = False, sampling_fraction: float = 0.25) → tuple[dict, tuple]

Accumulate histograms per cluster for the chosen component (‘L’, ‘a’, ‘b’).

Parameters:

• input_dir (str) – Folder with .npy images in LAB format.

• labels_dir (str) – Folder with K-means label files.

• n_clusters (int) – Number of detected clusters.

• component (str, optional) – Component to use: 'L', 'a', or 'b' (default is 'L').

• bins (int, optional) – Number of bins for the histogram (default is 40).

• use_sampling (bool, optional) – If True, use random sampling to speed up processing (default is False).

• sampling_fraction (float, optional) – Fraction of pixels to sample if use_sampling is True (default is 0.25).

Returns:

A tuple (accumulators, range) where accumulators is a dict with histograms per cluster and range is a tuple (range_min, range_max) of the range used.

Return type:

tuple of (dict, tuple)

cie_utils.analytical_noi_gaussians(mu1: float, sigma1: float, mu2: float, sigma2: float, range_min: float = 0.0, range_max: float = 100.0, n_points: int = 10000) → float

Analytically compute the NOI for two normal distributions.

Parameters:

• mu1 (float) – Mean of the first distribution.

• sigma1 (float) – Standard deviation of the first distribution.

• mu2 (float) – Mean of the second distribution.

• sigma2 (float) – Standard deviation of the second distribution.

• range_min (float, optional) – Minimum value of the range (default is 0.0).

• range_max (float, optional) – Maximum value of the range (default is 100.0).

• n_points (int, optional) – Number of points for numerical integration (default is 10000).

Returns:

Analytically computed NOI.

Return type:

float

cie_utils.analyze_lab_distributions(input_dir: str, labels_dir: str, use_sampling: bool = False, sampling_fraction: float = 0.25, show_plots: bool = True, bins: int = 40) → dict

Main function to analyze LAB distributions and compute intersections.

Parameters:

• input_dir (str) – Directory with .npy image files.

• labels_dir (str) – Directory with .npy label files.

• use_sampling (bool, optional) – If True, use random sampling (default is False).

• sampling_fraction (float, optional) – Fraction of pixels to sample (default is 0.25).

• show_plots (bool, optional) – If True, display plots (default is True).

• bins (int, optional) – Number of bins for histograms (default is 40).

Returns:

Dictionary with all analysis results including keys: 'data', 'n_clusters', 'names', 'colors', 'smoothed_curves', 'intersections_by_component', 'num_images_processed', 'use_sampling', 'sampling_fraction'.

Return type:

dict

cie_utils.apply_median_filter(image: ndarray, kernel_size: int = 3) → ndarray

Apply a median filter to an image.

Parameters:

• image (np.ndarray) – Numpy array with the image (2D or 3D for RGB).

• kernel_size (int, optional) – Kernel size (must be odd) (default is 3).

Returns:

Filtered image.

Return type:

np.ndarray

Raises:

ValueError – If kernel_size is not odd or is <= 0.

cie_utils.apply_median_filter_rgb(rgb_image: ndarray, kernel_size: int = 3) → ndarray

Apply a median filter to an RGB image (3 channels).

Parameters:

• rgb_image (np.ndarray) – Numpy array with the RGB image (H, W, 3).

• kernel_size (int, optional) – Kernel size (must be odd) (default is 3).

Returns:

Filtered RGB image.

Return type:

np.ndarray

Raises:

ValueError – If the image does not have 3 channels.

cie_utils.blur_img(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[float64]]

Applies a Gaussian filter to an image.

Uses skimage.filters.gaussian with a sigma of 1 and truncate of 1, resulting in a 3x3 Gaussian kernel.

Parameters:

image (npt.NDArray) – The input image. Pixel values are expected to be in the range [0.0, 1.0] (float) or [0, 255] (uint8). The skimage.filters.gaussian function automatically handles data types.

Returns:

The image with the Gaussian filter applied. The output will be of type float64. If the input was RGB, the output will also be RGB.

Return type:

npt.NDArray[np.float64]

cie_utils.clahe_img(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], illumination_axis: int, top_val: float) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Applies Contrast Limited Adaptive Histogram Equalization (CLAHE) to the image, specifically to the illumination channel.

The illumination channel is scaled to [0, 255] before applying CLAHE, and then rescaled back to its original range [0, top_val].

Parameters:

• image (npt.NDArray) – The input image. Expected to be an image in a color space where one channel represents illumination (e.g., the L channel of LAB).

• illumination_axis (int) – The index of the channel representing illumination in the image (e.g., 0 for L in LAB).

• top_val (float) – The maximum value the illumination channel can take in its original range (e.g., 100 for L in LAB).

Returns:

The image with CLAHE applied to the illumination channel, maintaining float64 data type.

Return type:

npt.NDArray

cie_utils.classifier_model(clf_model: str, params: tuple, order: str = 'by_pixel', n_ref: int = 1) → tuple[Any, Any]

Applies a classification model (K-means, GaussianMixture, or AgglomerativeClustering) to images and sorts the results.

Parameters:

• clf_model ({"Kmeans", "GaussianMixture", "AgglomerativeClustering"}) – The type of classification model to use.

• params (tuple) –

  Specific parameters for the classification model.

  • For “Kmeans”: (img, k, stop_criteria, number_of_attempts, centroid_initialization_strategy)

  • For “GaussianMixture”: (img, k)

  • For “AgglomerativeClustering”: (img, k, linkage)

  img can be a single image or a list of images.

• order ({"by_pixel", "reference_values"}, optional) – Method to sort the resulting clusters. - “by_pixel”: sorts by the number of pixels in each cluster (descending). - “reference_values”: sorts by the closeness of centroids to reference LAB values. Defaults to “by_pixel”.

• n_ref (int, optional) – Reference number (0 or 1) to select the set of reference LAB values when order is “reference_values”. Defaults to 1.

Returns:

A tuple with:

• centerslist of ndarray

  The sorted cluster centroids (or means) for each image.

• ordered_imageslist of list of ndarray

  A list of lists, where each sublist contains the segmented images sorted by cluster for the corresponding image.

Return type:

tuple of list

Raises:

ValueError – If the clf_model classifier type is invalid.

cie_utils.combine_red_blood_cell_clusters(data: dict, n_clusters: int) → tuple[dict, int]

Combine clusters 3 and 4 into a single cluster for red blood cells.

Parameters:

• data (dict) – Dictionary with cluster data.

• n_clusters (int) – Original number of clusters.

Returns:

Modified data and new number of clusters.

Return type:

tuple of (dict, int)

cie_utils.compute_all_intersections(smoothed_curves: dict, names: dict, distance_threshold: float = 6.0) → dict

Compute all intersections between cluster pairs for each component.

Parameters:

• smoothed_curves (dict) – Dictionary with curves per component and cluster.

• names (dict) – Dictionary of cluster names.

• distance_threshold (float, optional) – Threshold for filtering nearby intersections (default is 6.0).

Returns:

Dictionary with intersections per component and cluster pair.

Return type:

dict

cie_utils.compute_histograms(data: dict, n_clusters: int, bins: int = 40) → dict

Compute smoothed histograms for all clusters and components.

Parameters:

• data (dict) – Dictionary with cluster data.

• n_clusters (int) – Number of clusters.

• bins (int, optional) – Number of bins for the histogram (default is 40).

Returns:

Dictionary with smoothed curves per component and cluster.

Return type:

dict

cie_utils.compute_manual_median(matrix: ndarray, i: int, j: int, kernel_size: int = 3) → float

Manually compute the median for a specific position. Useful for verifying filter results.

Parameters:

• matrix (np.ndarray) – Input matrix.

• i (int) – Row coordinate of the center point.

• j (int) – Column coordinate of the center point.

• kernel_size (int, optional) – Kernel size (default is 3).

Returns:

Manually computed median value.

Return type:

float

Raises:

ValueError – If kernel_size is not odd.

cie_utils.compute_noi(hist1: ndarray, hist2: ndarray, range_values: tuple, bins: int = 40) → float

Compute the NOI (overlap area) between two accumulated histograms.

Parameters:

• hist1 (np.ndarray) – Histogram of the first cluster.

• hist2 (np.ndarray) – Histogram of the second cluster.

• range_values (tuple of (float, float)) – Tuple (range_min, range_max) of the histogram range.

• bins (int, optional) – Number of histogram bins (default is 40).

Returns:

NOI value between 0 and 1.

Return type:

float

cie_utils.create_rgb_spectrum(num_steps: int) → list[int]

Creates an RGB color spectrum by varying the Hue in HSV space.

The spectrum goes from a hue close to red (0.75) to red (0), keeping saturation and value at maximum.

Parameters:

num_steps (int) – The number of steps (colors) to generate in the spectrum.

Returns:

A list of NumPy arrays, where each array represents an RGB color ([R, G, B]) with integer values in the range [0, 255].

Return type:

list[int]

cie_utils.create_test_matrix(size: int = 5, kind: str = 'ordered') → ndarray

Create test matrices to verify the median filter.

Parameters:

• size (int, optional) – Size of the square matrix (default is 5).

• kind (str, optional) – Type of matrix: 'ordered', 'random', 'stepped', or 'edges' (default is 'ordered').

Returns:

Test matrix.

Return type:

np.ndarray

Raises:

ValueError – If the matrix type is not valid.

cie_utils.detect_number_of_clusters(labels_dir: str) → int

Automatically detect the number of clusters used.

Parameters:

labels_dir (str) – Directory containing label files.

Returns:

Number of clusters detected.

Return type:

int

cie_utils.display_2d_scatter_plot(imgs: list[ndarray[tuple[int, ...], dtype[float64]]], cols: int, fsize: tuple[int, int] = (10, 2), titles: list[str] | None = None) → list[ndarray[tuple[int, ...], dtype[float64]]]

Displays 2D scatter plots of pixel frequency for a list of images.

Each scatter plot shows pixel values (x-axis) against their frequency of occurrence (number of pixels with that value, y-axis). Only non-zero pixel values are considered.

Parameters:

• imgs (list[npt.NDArray[np.float64]]) – A list of images (or image channels) for which to generate scatter plots.

• cols (int) – The number of columns in the plot display grid.

• fsize (tuple[int, int], optional) – The figure size (width, height) in inches. Defaults to (10, 2).

• titles (list[str] | None, optional) – A list of titles for each scatter plot. If None, no titles are displayed. Defaults to None.

Returns:

A list of NumPy arrays, where each array contains the frequency data of pixels ([pixel_value, frequency]) for each input image.

Return type:

list[npt.NDArray[np.float64]]

cie_utils.display_3d_scatter_plot(images: list[ndarray[tuple[int, ...], dtype[float64]]], colors: list[str] | None = None, title: str | None = None) → None

Creates a 3D scatter plot for classified data.

Each dataset in images is represented as a series of points in a 3D space, useful for visualizing cluster distribution.

Parameters:

• images (list[npt.NDArray[np.float64]]) – A list of NumPy arrays, where each array contains the coordinates (e.g., L, a, b from LAB) of the pixels in a cluster or group. Each array is expected to have 3 columns.

• colors (list[str] | None, optional) – A list of color strings for each set of points. If None, colors are automatically selected. Defaults to None.

• title (str | None, optional) – The title of the plot. Defaults to None.

cie_utils.display_hist(imgs: list[ndarray[tuple[int, ...], dtype[float64]]], cols: int, fsize: tuple[int, int] = (10, 2), titles: list[str] | None = None, xlabel: list[str] = None, ylabel: list[str] = None, save_imgs: bool = False, save_csv: bool = False, output_dir: Path = PosixPath('/home/runner/work/cie-utils/cie-utils')) → None

Displays histograms and Probability Density Functions (PDFs) for a list of images.

Parameters:

• imgs (list[npt.NDArray[np.float64]]) – A list of images (or image channels) for which to generate histograms.

• cols (int) – The number of columns in the histogram display grid.

• fsize (tuple[int, int], optional) – The figure size (width, height) in inches. Defaults to (10, 2).

• titles (list[str] | None, optional) – A list of titles for each histogram. If None, no titles are displayed. Defaults to None.

• xlabel (list[str], optional) – A list of labels for the x-axis of each histogram. Defaults to [“x”] for all.

• ylabel (list[str], optional) – A list of labels for the y-axis of each histogram. Defaults to [“y”] for all.

• save_imgs (bool, optional) – If True, saves the histograms to a file instead of displaying them. The filename is based on the first title if available, otherwise “test” is used. Defaults to False.

• save_csv (bool, optional) – If True, saves the density data (rng and density) of each histogram to a CSV file. Defaults to False.

• output_dir (Path, optional) – The directory where the images will be saved if save_imgs is True. Defaults to the current working directory.

cie_utils.display_images(imgs: list[ndarray[tuple[int, ...], dtype[float64]]], cols: int = 1, fsize: tuple[int, int] = (10, 5), cmaps: list[str] | None = None, titles: list[str] | None = None, save_imgs: bool = False, output_dir: Path = PosixPath('/home/runner/work/cie-utils/cie-utils')) → None

Displays a list of images in a grid.

Parameters:

• imgs (list[npt.NDArray[np.float64]]) – A list of images to display.

• cols (int, optional) – The number of columns in the display grid. Defaults to 1.

• fsize (tuple[int, int], optional) – The figure size (width, height) in inches. Defaults to (10, 5).

• cmaps (list[str] | None, optional) – A list of colormaps to apply to each image. If None, no colormap is applied. Defaults to None.

• titles (list[str] | None, optional) – A list of titles for each image. If None, no titles are displayed. Defaults to None.

• save_imgs (bool, optional) – If True, saves the images to a file instead of displaying them. The filename is based on the first title if available, otherwise “test” is used. Defaults to False.

• output_dir (Path, optional) – The directory where the images will be saved if save_imgs is True. Defaults to the current working directory.

cie_utils.display_plot(imgs: list[ndarray[tuple[int, ...], dtype[float64]]], fsize: tuple[int, int] = (10, 2), cmaps: list[str] | None = None, titles: list[str] | None = None) → None

Displays a combination of image, histogram, and pixel frequency scatter plot for each image in the list.

For each image: 1. The original image is displayed. 2. A histogram and its Probability Density Function (PDF) are generated. 3. A scatter plot of pixel value frequency is created.

Parameters:

• imgs (list[npt.NDArray[np.float64]]) – A list of images (or image channels) to visualize.

• fsize (tuple[int, int], optional) – The figure size (width, height) in inches. Defaults to (10, 2).

• cmaps (list[str] | None, optional) – A list of colormaps to apply to each image. If None, no colormap is applied. Defaults to None.

• titles (list[str] | None, optional) – A list of titles for each set of plots. If None, no titles are displayed. Defaults to None.

cie_utils.enter_str_input(text: str) → str

Prompts the user for a text input and ensures it is not empty.

Parameters:

text (str) – The message to display to the user.

Returns:

The text string entered by the user.

Return type:

str

Raises:

ValueError – If the user’s input is None or an empty string.

cie_utils.extract_segmentation(img_path: str, rimg_path: str, lbl_path: str, dest: str, dsfile: str) → None

Extracts image segments based on label information and a dataset file.

This function reads an image, segmentation coordinates from a label file, and category names from a YAML dataset file. It then creates masks, crops the regions of interest (ROI), and saves the segmented images and their references (if provided) into folders organized by category.

Parameters:

• img_path (str) – Absolute path to the image to be segmented.

• rimg_path (str) – Absolute path to the reference image. Can be an empty string if no reference image.

• lbl_path (str) – Absolute path to the text file with segmentation label information.

• dest (str) – Absolute path to the destination folder where segmented images will be saved.

• dsfile (str) – Absolute path to the dataset.yaml file containing category names.

cie_utils.extract_segmentation_main() → None

Main function for image segmentation extraction.

Prompts the user for the necessary paths for the image, reference image, label file, and destination folder, then calls extract_segmentation.

cie_utils.false_color_scale(channel: Any, color_list: Any, ranges_list: Any) → Any

Applies a false color scale to a single-channel image.

Assigns colors from a color_list to the pixels of channel based on the ranges specified in ranges_list.

Parameters:

• channel (Any) – The single-channel image to which the color scale will be applied. Expected to be a 2D NumPy array.

• color_list (Any) – A list of RGB colors ([R, G, B]) to assign to the ranges.

• ranges_list (Any) – A list of tuples or lists, where each tuple represents a range (min_val, max_val]. Pixel values within this range will be mapped to the corresponding color.

Returns:

A new image with the false color scale applied, of integer type and 3 channels.

Return type:

Any

cie_utils.filter_intersections_for_console(intersections: list[tuple[float, float]], distance_threshold: float = 1.0) → list[tuple[float, float]]

Filter intersections for console output, removing nearby points.

Parameters:

• intersections (list of tuple of (float, float)) – List of (x, y) intersections.

• distance_threshold (float, optional) – Minimum distance between points to keep them separate (default is 1.0).

Returns:

Filtered list of intersections.

Return type:

list of tuple of (float, float)

cie_utils.find_intersections(x1: ndarray, y1: ndarray, x2: ndarray, y2: ndarray, distance_threshold: float = 5.0) → list[tuple[float, float]]

Find intersection points between two curves, ignoring nearby points.

Parameters:

• x1 (np.ndarray) – X-coordinates of the first curve.

• y1 (np.ndarray) – Y-coordinates of the first curve.

• x2 (np.ndarray) – X-coordinates of the second curve.

• y2 (np.ndarray) – Y-coordinates of the second curve.

• distance_threshold (float, optional) – Minimum distance between intersections to consider them distinct (default is 5.0).

Returns:

List of (x, y) tuples with the intersections found.

Return type:

list of tuple of (float, float)

cie_utils.get_automatic_names_and_colors(n_clusters: int) → tuple[dict, dict]

Automatically generate names and colors based on the number of clusters.

Parameters:

n_clusters (int) – Number of clusters.

Returns:

A tuple containing a names dictionary and a colors dictionary.

Return type:

tuple of (dict, dict)

cie_utils.get_csv_data(now: str, data: ndarray[tuple[int, ...], dtype[float64]], filename: str, folder: Path, col_names: list[str] | None = None) → None

Saves data to a CSV file within a specific folder structure.

The save path is folder/csv/now/filename.csv.

Parameters:

• now (str) – A timestamp string to be used as a subfolder name within ‘csv’.

• data (npt.NDArray[np.float64]) – The data to save, must be a 2D NumPy array.

• filename (str) – The name of the CSV file (without the .csv extension).

• folder (Path) – The Path object of the base folder where the ‘csv/now/’ structure will be created.

• col_names (list[str] | None, optional) – A list of names for the CSV columns. If None, no column names will be used. Defaults to None.

cie_utils.get_csv_data_from_images(imgs: list[~typing.Any], folder: ~pathlib.Path, col_names: list[str] | None = None, timezone=<DstTzInfo 'America/Bogota' LMT-1 day, 19:04:00 STD>) → None

Extracts pixel frequency data from a list of images and saves them to CSV files.

For each image in imgs, pixel frequencies are calculated (pixel values vs. number of occurrences) and saved to a CSV file. Files are organized by date and time within the specified folder.

Parameters:

• imgs (list[Any]) – A list of tuples where each tuple contains (image_name: str, image: npt.NDArray[np.float64]). The image must be a NumPy array. Pixels with zero value are ignored.

• folder (Path) – The Path object of the base folder where the CSV file structure will be created.

• col_names (list[str] | None, optional) – A list of names for the CSV columns (e.g., [“pixel_value”, “frequency”]). If None, no column names will be used. Defaults to None.

cie_utils.get_pdf(img: ndarray[tuple[int, ...], dtype[float64]]) → tuple[Any, Any, Any, int]

Calculates the Probability Density Function (PDF) for image data.

This function filters non-zero pixels, calculates the number of bins using the Freedman-Diaconis rule, and estimates the PDF using Gaussian Kernel Density Estimation (KDE).

Parameters:

img (npt.NDArray[np.float64]) – The input image as a NumPy array.

Returns:

• datanpt.NDArray[np.float64]

  The pixel data (non-zero values) of the image, rounded to one decimal place.

• rngnpt.NDArray[np.float64]

  The range of values over which the density is calculated.

• densityAny

  The density values of the estimated probability density function.

• binsint

  The number of bins calculated using the Freedman-Diaconis rule.

Return type:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], Any, int]

cie_utils.hsv_to_rgb(h: float, s: float, v: float) → Any

Converts a color from HSV to RGB.

HSV values are in the range [0, 1]. The RGB output is in the range [0, 255] and are integers.

Parameters:

• h (float) – Hue component, in the range [0, 1].

• s (float) – Saturation component, in the range [0, 1].

• v (float) – Value/Brightness component, in the range [0, 1].

Returns:

A NumPy array of integers representing the color in RGB format [R, G, B], with values in the range [0, 255].

Return type:

Any

cie_utils.img_preparation(img: ndarray[tuple[int, ...], dtype[float64]], rimg: ndarray[tuple[int, ...], dtype[float64]], sd_val: float) → list[ndarray[tuple[int, ...], dtype[float64]]]

Prepares an image by applying normalization, background removal, and color space transformations.

The input image is normalized with a reference image, its background is removed using a standard deviation threshold, and then it is converted to CIELAB and CIELCh color spaces to extract their channels.

Parameters:

• img (npt.NDArray[np.float64]) – The input image in RGB format (float64 values).

• rimg (npt.NDArray[np.float64]) – The reference image for normalization in RGB format (float64 values).

• sd_val (float) – The standard deviation threshold value for background removal.

Returns:

A list containing the L, a, b channels of the LAB image, and the C (chroma) and H (hue) channels of the LCh image. If the dimensions of img and rimg do not match, returns a list containing only the original input image.

Return type:

list[npt.NDArray[np.float64]]

cie_utils.min_max(img: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Normalizes an image using min-max scaling.

This method independently normalizes each color channel of the image to a range of [0, 1] based on the minimum and maximum values of each channel. It is sensitive to outliers.

Parameters:

img (npt.NDArray[np.float64]) – The input image as a NumPy array of type float64, with 3 channels.

Returns:

The normalized image in the range [0, 1].

Return type:

npt.NDArray[np.float64]

cie_utils.mix_images(img1: Any, img2: Any) → Any

Blends two images: an original image and a false-color image.

Pixels in the overlay image that are not completely black (i.e., do not have an RGB component sum equal to zero) replace the corresponding pixels in the original image. If a pixel in img2 is black, the original image’s pixel is retained.

Parameters:

• img1 (Any) – The original image (e.g., RGB). A NumPy array with 3 channels is expected.

• img2 (Any) – The image to overlay. A NumPy array with 3 channels is expected.

Returns:

The blended image, where non-black pixels from img2 have replaced pixels from img1.

Return type:

Any

cie_utils.normalize_img(img: ndarray[tuple[int, ...], dtype[float64]], rimg: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Normalizes an image based on a reference image.

Pixel values of the input image are divided by the corresponding values of the reference image. NaN values resulting from division by zero are replaced by zero, and values are clipped to the range [0, 1].

Parameters:

• img (npt.NDArray[np.float64]) – The image to normalize. Must be a NumPy array of type float64.

• rimg (npt.NDArray[np.float64]) – The reference image for normalization. Must be a NumPy array of type float64.

Returns:

The normalized image, with pixel values in the range [0, 1].

Return type:

npt.NDArray[np.float64]

cie_utils.pca_img(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], comp_num: int) → ndarray[tuple[int, ...], dtype[float64]]

Performs Principal Component Analysis (PCA) on the pixels of an image.

Transforms each pixel (interpreted as a point in a 3D space, e.g., RGB or LAB) to its 3 principal components.

Parameters:

• image (npt.NDArray) – The input image. A NumPy array with pixels expected in the last dimension (e.g., (height, width, channels)).

• comp_num (int) – The number of principal components to retain.

Returns:

A NumPy array representing the transformed image in PCA space, where each pixel now has 3 values corresponding to its principal components. The shape will be (N, 3) where N is the total number of pixels.

Return type:

npt.NDArray[np.float64]

cie_utils.plot_distributions_with_intersections(smoothed_curves: dict, names: dict, colors: dict, intersections_by_component: dict, show_plots: bool = True) → Figure | None

Plot distributions with marked intersections.

Parameters:

• smoothed_curves (dict) – Dictionary with smoothed curves.

• names (dict) – Dictionary of cluster names.

• colors (dict) – Dictionary of colors per cluster.

• intersections_by_component (dict) – Computed intersections.

• show_plots (bool, optional) – If True, display the plots (default is True).

Returns:

Matplotlib figure if show_plots is False, otherwise None.

Return type:

matplotlib.figure.Figure or None

cie_utils.plot_rgb_3d(images: Any, colors: Any, title: Any) → None

Generates a 3D scatter plot of RGB pixels.

Allows visualizing the distribution of colors in 3D space (R, G, B).

Parameters:

• images (Any | list[Any]) – An image or a list of images. Images should be NumPy arrays representing pixel data (e.g., RGB). If it’s a 3D image (height, width, 3), it will be flattened to (N, 3).

• colors (Any | list[Any]) – The color or a list of colors for the points in the scatter plot. Must match the number of images if it’s a list. # Example: colors = [np.array([255, 0, 0]), np.array([0, 255, 0]), np.array([0, 0, 255])]

• title (Any | list[Any]) – The title or a list of titles for the plot(s). Must match the number of images if it’s a list.

cie_utils.print_intersection_summary(intersections_by_component: dict, names: dict, n_clusters: int) → None

Print a summary of intersections to the console.

Parameters:

• intersections_by_component (dict) – Dictionary with intersections.

• names (dict) – Dictionary of cluster names.

• n_clusters (int) – Number of clusters.

cie_utils.process_image_with_sampling(image_path: str, label_path: str, data: dict, n_clusters: int, use_sampling: bool = False, sampling_fraction: float = 0.25) → None

Process an image with optional random pixel sampling.

Parameters:

• image_path (str) – Path to the .npy image file.

• label_path (str) – Path to the .npy label file.

• data (dict) – Dictionary for storing data.

• n_clusters (int) – Number of clusters.

• use_sampling (bool, optional) – If True, use random sampling (default is False).

• sampling_fraction (float, optional) – Fraction of pixels to sample (default is 0.25).

cie_utils.process_npy_images(input_folder: str, output_folder: str, kernel_size: int = 3, process_rgb: bool = True) → None

Process all .npy images in a folder by applying a median filter.

Parameters:

• input_folder (str) – Path to the folder with .npy files.

• output_folder (str) – Path where processed images will be saved.

• kernel_size (int, optional) – Kernel size (must be odd) (default is 3).

• process_rgb (bool, optional) – If True, process as RGB (3 channels); if False, as grayscale (default is True).

Raises:

ValueError – If folders do not exist or kernel_size is invalid.

cie_utils.rm_bg(img: ndarray[tuple[int, ...], dtype[float64]], sd_val: float, sdimg: Any | None = None) → ndarray[tuple[int, ...], dtype[float64]]

Removes the background from a normalized image based on a standard deviation value.

Pixels whose value (or the value in sdimg if provided) is less than or equal to sd_val are considered part of the background and are set to zero.

Parameters:

• img (npt.NDArray[np.float64]) – The normalized input image, of type float64.

• sd_val (float) – The standard deviation threshold value. Pixels with a standard deviation below this value are considered background.

• sdimg (Any | None, optional) – An optional standard deviation image to use as a mask. If None, the input image img is used. Defaults to None.

Returns:

The image without background, where background pixels have been set to zero and values have been clipped to the range [0, 255].

Return type:

npt.NDArray[np.float64]

cie_utils.rm_bg2channel(chn: ndarray[tuple[int, ...], dtype[float64]], sd_val: float, sdimg: ndarray[tuple[int, ...], dtype[float64]] | None = None) → ndarray[tuple[int, ...], dtype[float64]]

Removes the background from an image channel based on a standard deviation value.

Pixels whose value in the channel (or the value in sdimg if provided) is less than or equal to sd_val are considered part of the background and are set to zero.

Parameters:

• chn (npt.NDArray[np.float64]) – The input image channel, of type float64.

• sd_val (float) – The standard deviation threshold value. Pixels with a standard deviation below this value are considered background.

• sdimg (npt.NDArray[np.float64] | None, optional) – An optional standard deviation image to use as a mask. If None, the input channel chn is used. Defaults to None.

Returns:

The image channel without background, where background pixels have been set to zero and values have been clipped to the range [0, 1].

Return type:

npt.NDArray[np.float64]

cie_utils.sd_by_elem(img: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Calculates the standard deviation per color component (R, G, B) for each pixel.

For each color channel (red, green, blue), this function calculates the standard deviation of pixels that are greater than zero. If a pixel is zero, its individual standard deviation is considered zero.

Parameters:

img (npt.NDArray[np.float64]) – The input image as a NumPy array of type float64, with 3 channels.

Returns:

An array with the same shape as the input image, where each element represents the standard deviation of the corresponding color component.

Return type:

npt.NDArray[np.float64]

cie_utils.sd_by_px(img: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Calculates the standard deviation per RGB pixel.

For each pixel in the image, calculates the standard deviation of its three color components (R, G, B).

Parameters:

img (npt.NDArray[np.float64]) – The input image as a NumPy array of type float64, with 3 channels.

Returns:

A 2D array containing the standard deviation of the RGB values for each pixel.

Return type:

npt.NDArray[np.float64]

cie_utils.simulate_distributions(mu1: float, sigma1: float, mu2: float, sigma2: float, bins: int = 40, n_samples: int = 10000) → tuple

Simulate two normal distributions and compute the NOI. Useful for unit tests.

Parameters:

• mu1 (float) – Mean of the first distribution.

• sigma1 (float) – Standard deviation of the first distribution.

• mu2 (float) – Mean of the second distribution.

• sigma2 (float) – Standard deviation of the second distribution.

• bins (int, optional) – Number of bins (default is 40).

• n_samples (int, optional) – Number of samples to generate (default is 10000).

Returns:

A tuple (hist1, hist2, range, computed_noi).

Return type:

tuple of (np.ndarray, np.ndarray, tuple, float)

cie_utils.sort_classifier_results(image, labels, centers, ordered, n_ref, verbose=False)

Sorts clustering results (e.g., K-means) based on the number of pixels or closeness to LAB reference values.

Parameters:

• image (npt.NDArray) – The original image (flattened if used for clustering) in LAB color space.

• labels (npt.NDArray) – The cluster identifiers assigned to each pixel.

• centers (npt.NDArray) – The coordinates (centroids) of the clusters in LAB color space.

• ordered (str) – The sorting method to use. Must be “by_pixel” (by number of pixels in each cluster, descending) or “reference_values” (by closeness to predefined LAB reference values).

• n_ref (int) – Index of the reference points to use if ordered is “reference_values”. Must be 0 or 1, selecting between two sets of LAB references.

• verbose (bool, optional) – If True, prints detailed information about the sorting process and the average colors of the clusters. Defaults to False.

Returns:

• centersnpt.NDArray

  The sorted cluster centroids.

• ordered_imageslist[npt.NDArray]

  A list of images, where each element is the segmented image corresponding to a cluster, sorted according to the specified method.

Return type:

tuple[npt.NDArray, list[npt.NDArray]]

Raises:

ValueError – If the ordered sorting method is invalid.

cie_utils.std4elem(x: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

Compute the element-wise standard deviation relative to the mean of non-zero elements in the input array.

This function calculates the deviation of each element from the mean of all non-zero elements in x, returning an array where elements originally equal to zero remain zero.

Parameters:

x (numpy.ndarray) – A 1D NumPy array of type float64. Elements with value zero are ignored in the mean and standard deviation calculation.

Returns:

An array of the same shape as x containing the standard deviation for each element with respect to the mean of non-zero elements. Zero entries remain zero.

Return type:

numpy.ndarray

Examples

>>> import numpy as np
>>> from cie_utils import std4elem
>>> x = np.array([1.0, 2.0, 0.0, 4.0], dtype=np.float64)
>>> std4elem(x)
array([1.52752523, 0.15275252, 0., 1.37477271])

cie_utils.transform_img(image: ndarray[tuple[int, ...], dtype[float64]], bg_pixel: ndarray[tuple[int, ...], dtype[float64]] | None = None, blur: bool = True, lab: bool = True, clahe: bool = True) → list[ndarray[tuple[int, ...], dtype[float64]]]

Applies a series of transformations to an image: Gaussian blur, conversion to L*a*b* color space, and adaptive histogram equalization (CLAHE).

Pixels that are black (considered background) can be replaced by a specified bg_pixel before transformations.

Parameters:

• image (npt.NDArray[np.float64]) – The normalized input image, in the range [0.0, 1.0]. RGB format is expected.

• bg_pixel (npt.NDArray[np.float64] | None, optional) – An RGB pixel (float64) to insert as background where the original image was black. If None, black pixels are retained. Defaults to None.

• blur (bool, optional) – If True, applies a Gaussian blur to the image. Defaults to True.

• lab (bool, optional) – If True, converts the image to CIELAB color space. Defaults to True.

• clahe (bool, optional) – If True, applies CLAHE to the illumination channel of the image (only if lab is True). Defaults to True.

Returns:

A list containing:

• blur_imagenpt.NDArray[np.float64]

  The blurred image (or the original image if blur is False).

• rgb_image_eqnpt.NDArray[np.float64]

  The resulting image after all transformations, converted back to RGB.

• lab_image_eqnpt.NDArray[np.float64]

  The resulting image in CIELAB color space, flattened to (N, 3) where N is the total number of pixels.

Return type:

list[npt.NDArray[np.float64]]

cie_utils.verify_median_filter(matrix: ndarray, kernel_size: int = 3, positions: list | None = None) → tuple[bool, dict]

Verify that the median filter works correctly by comparing with manual computation.

Parameters:

• matrix (np.ndarray) – Input matrix.

• kernel_size (int, optional) – Kernel size (default is 3).

• positions (list of tuple of (int, int) or None, optional) – List of positions [(i1, j1), …] to verify. If None, verifies all positions (default is None).

Returns:

A tuple (all_correct, detailed_results) where all_correct is True if all positions match, and detailed_results is a dictionary with per-position comparison data.

Return type:

tuple of (bool, dict)