Utilities

Device management, precision control, export, and helper functions.

Device Management

medical_image.utils.device.resolve_device(*images, explicit=None)[source]

Determine the target device for a processing operation.

Priority:

  1. Explicit device parameter (if provided)

  2. Device of the first loaded image

  3. Fallback to CPU

Parameters:

explicit (str | device | None)

Return type:

device

class medical_image.utils.device.Precision[source]

Bases: Enum

FULL = torch.float32
HALF = torch.float16
BFLOAT16 = torch.bfloat16
medical_image.utils.device.set_default_precision(precision)[source]
Parameters:

precision (Precision)

Return type:

None

medical_image.utils.device.get_default_precision()[source]
Return type:

Precision

medical_image.utils.device.get_dtype()[source]
Return type:

dtype

medical_image.utils.device.estimate_image_bytes(image, dtype=torch.float32)[source]

Estimate GPU memory needed for an image tensor.

Parameters:

  • image – An Image object or any object with pixel_data/width/height.

  • dtype (dtype) – Assumed dtype if pixel_data is not loaded.

Returns:

Estimated bytes required.

Return type:

int

medical_image.utils.device.check_gpu_budget(required_bytes, device=None)[source]

Return True if enough GPU memory is available for the operation.

Parameters:

  • required_bytes (int) – Estimated memory needed in bytes.

  • device (device) – Target CUDA device. Returns True for non-CUDA devices.

Return type:

bool

class medical_image.utils.device.DeviceContext[source]

Bases: object

Context manager for GPU-aware processing with automatic memory management.

Features:

  • Clears GPU cache on entry and exit

  • Provides memory usage tracking

  • Automatic CPU fallback when CUDA is unavailable

__init__(device='cuda', fallback='cpu', verbose=False)[source]
Parameters:
property device: device
memory_stats()[source]

Return current GPU memory usage.

Return type:

dict

medical_image.utils.device.gpu_safe(func)[source]

Decorator: catches CUDA errors (OOM, device-side asserts) and retries on CPU.

class medical_image.utils.device.AsyncGPUPipeline[source]

Bases: object

Overlap disk I/O, CPU→GPU transfer, and GPU compute using CUDA streams.

Only usable when CUDA is available.

__init__(device='cuda')[source]
Parameters:

device (str)

process_images(images, algorithm)[source]

Process pre-loaded Image objects with overlapped transfer and compute.

Parameters:

  • images (list) – List of Image objects (already loaded).

  • algorithm – An Algorithm instance.

Returns:

List of output Image objects.

Return type:

list

class medical_image.utils.device.MultiGPUAlgorithm[source]

Bases: object

Distribute algorithm execution across available GPUs (data-parallel).

__init__(algorithm_cls, gpu_ids=None, **kwargs)[source]
Parameters:
apply_batch(images, outputs)[source]

Distribute images across GPUs round-robin.

Parameters:
Return type:

list

Image Utilities

class medical_image.utils.image_utils.TensorConverter[source]

Bases: object

static to_numpy(image)[source]

Convert Image.pixel_data (torch tensor) to NumPy array on CPU.

Parameters:

image (Image) – Image instance containing pixel_data.

Returns:

np.ndarray

Return type:

ndarray

static ensure_tensor(image, device=None, dtype=None)[source]

Move Image.pixel_data to target device and dtype.

Parameters:

  • image (Image) – Image instance.

  • device – Target device.

  • dtype – Target dtype.

Returns:

The updated tensor.

Return type:

Tensor

class medical_image.utils.image_utils.ImageExporter[source]

Bases: object

Export an Image object to PNG/JPG/TIFF.

static save_as(image, format='PNG')[source]
Parameters:

image (Image)

Return type:

str

class medical_image.utils.image_utils.ImageVisualizer[source]

Bases: object

Visualization utilities for Image objects.

static show(image, cmap='gray', title=None)[source]
Parameters:

image (Image)

static compare(before, after, title_before='Before', title_after='After')[source]
Parameters:
class medical_image.utils.image_utils.MathematicalOperations[source]

Bases: object

static abs(image, out)[source]
Parameters:
Return type:

Image

static euclidean_distance_sq(Z, V)[source]

Compute squared Euclidean distances between N data points and c centroids.

Parameters:

  • Z (Tensor) – (N, d) data matrix.

  • V (Tensor) – (c, d) centroid matrix.

Returns:

(c, N) squared distances.

Return type:

D2

static normalize_12bit(image, out)[source]

Normalize a 12-bit DICOM image to [0, 1] by dividing by 4095.

Parameters:

  • image (Image) – Input Image with raw 12-bit pixel values.

  • out (Image) – Output Image to store the normalized result.

Returns:

The output Image.

Return type:

Image

Logging

medical_image.utils.logging.configure_logging(level=10, log_file=None)[source]

Optional convenience function for users who want console/file logging.

Parameters:

  • level – Logging level (default DEBUG).

  • log_file – Path to a log file. If None, only console output.