Top-Level Utilities

The utils module provides additional utilities not specific to configuration, metrics, or callbacks.

ucs.utils.apply_color_map(mask, id2color)

Map class indices to RGB values for visualization.

Parameters:

• mask (ndarray) – 2D array with class indices.

• id2color (dict) – Dictionary mapping class IDs to RGB color tuples.

Returns:

3D array of RGB values.

Return type:

ndarray

ucs.utils.find_checkpoint(checkpoints_dir, version)

Locate the single checkpoint file in the specified versioned directory.

Parameters:

• chekpoints_dir (str) – A path to parent checkpoints directory.

• version (int) – The version folder name (e.g., “version_0”).

Returns:

Absolute path to the checkpoint file.

Return type:

Path

Raises:

• CheckpointDirectoryError – If the checkpoint directory is missing or invalid.

• CheckpointNotFoundError – If no checkpoint file is found.

• MultipleCheckpointsError – If multiple checkpoint files are found.

ucs.utils.format_metrics(metrics)

Format metrics for display below the confusion matrix.

Parameters:

metrics (dict) – Dictionary containing metric names and values.

Returns:

Formatted string representation of the metrics for plot box.

Return type:

str

ucs.utils.get_last_version(logs_dir)

Get the last version number for the logs directory containing only ‘version_[n]’ folders.

Parameters:

logs_dir (Path) – The base directory where ‘lightning_logs’ are stored.

Returns:

The last version number. Returns -1 if no ‘version_[n]’ folders exist.

Return type:

int

ucs.utils.get_next_version(logs_dir)

Get the next version number for the logs directory containing only ‘version_[n]’ folders.

Parameters:

logs_dir (Path) – The base directory where ‘lightning_logs’ are stored.

Returns:

The next version number in the format ‘version_[n]’.

Return type:

str

ucs.utils.load_class_weights(class_weights_dir)

Load precomputed class weights from a file and return as a torch tensor.

Parameters:

class_weights_dir (str) – path to the dir contain weights file.

Returns:

Loaded class weights as a tensor.

Return type:

Tensor

ucs.utils.plot_image_and_mask(image, mask, id2color)

Display an image and its corresponding mask side by side.

Parameters:

• image (Image or str) – Image to display, or the path to the image file.

• mask (ndarray) – 2D array representing the mask.

• id2color (dict) – Dictionary mapping class IDs to RGB color tuples.

ucs.utils.save_class_weights(class_weights_dir, class_weights)

Save computed class weights to a file.

Parameters:

• class_weights_dir (str) – path to the dir contain weights file.

• class_weights (list) – Class weights to save.

ucs.utils.save_confusion_matrix_plot(conf_matrix, labels, save_path, metrics=None, title='Confusion Matrix')

Save a confusion matrix plot to a file using sklearn’s ConfusionMatrixDisplay.

Parameters:

• conf_matrix (ndarray) – Confusion matrix containing y_true (actual labels) and y_pred (predicted labels).

• labels (list) – List of class labels.

• save_path (Path) – path to save the confusion matrix plot.

• metrics (dict, optional) – Dictionary of metrics to annotate below the confusion matrix. Defaults to None.

• title (str, optional) – Title for the confusion matrix plot. Defaults to “Confusion Matrix”.