linumpy.metrics.image_quality#

Image quality assessment functions for slice analysis.

This module provides CPU-based functions for assessing image quality in 3D volumes, including:

  • Structural Similarity Index (SSIM)

  • Edge preservation scoring

  • Variance consistency analysis

  • Overall slice quality assessment

For GPU-accelerated versions, see linumpy.gpu.image_quality.

Usage:

from linumpy.metrics.image_quality import (
    compute_ssim_2d,
    compute_ssim_3d,
    compute_edge_score,
    compute_variance_score,
    assess_slice_quality,
)

# Compare two volumes
ssim = compute_ssim_3d(vol1, vol2)

# Assess overall slice quality
quality, metrics = assess_slice_quality(vol, vol_before, vol_after)

Functions#

normalize_image(img)

Normalize image to [0, 1] range.

compute_ssim_2d(img1, img2[, win_size])

Compute SSIM between two 2D images.

compute_ssim_3d(vol1, vol2[, win_size, sample_depth, ...])

Compute mean SSIM between two 3D volumes.

compute_edge_score(vol, reference[, sample_z])

Compute edge preservation score between volume and reference.

compute_variance_score(vol, reference)

Compute variance consistency score between volume and reference.

assess_slice_quality(vol, vol_before, vol_after[, ...])

Assess overall quality of a slice volume.

detect_calibration_slice(volumes[, thickness_ratio])

Detect calibration slices by their different thickness.

compute_quality_report(slice_qualities[, min_quality])

Generate a quality report from slice quality assessments.

Module Contents#

linumpy.metrics.image_quality.normalize_image(img)[source]#

Normalize image to [0, 1] range.

Parameters:

img (np.ndarray) – Input image.

Returns:

Normalized image as float32.

Return type:

np.ndarray

linumpy.metrics.image_quality.compute_ssim_2d(img1, img2, win_size=7)[source]#

Compute SSIM between two 2D images.

Parameters:

  • img1 (np.ndarray) – Input images (2D).

  • img2 (np.ndarray) – Input images (2D).

  • win_size (int) – Window size for SSIM computation.

Returns:

SSIM score (0 to 1, higher is better).

Return type:

float

linumpy.metrics.image_quality.compute_ssim_3d(vol1, vol2, win_size=7, sample_depth=0, xy_roi=0)[source]#

Compute mean SSIM between two 3D volumes.

Computes SSIM for each z-slice and returns the mean.

Parameters:

  • vol1 (np.ndarray) – Input volumes (Z, Y, X).

  • vol2 (np.ndarray) – Input volumes (Z, Y, X).

  • win_size (int) – Window size for SSIM computation.

  • sample_depth (int) – Number of z-planes to sample. 0 = all planes.

  • xy_roi (int) – Side length of center crop in XY (pixels). 0 = full plane. Use a small value (e.g. 1024) on very large single-resolution zarr arrays to avoid loading gigabytes per plane.

Returns:

Mean SSIM score (0 to 1, higher is better).

Return type:

float

linumpy.metrics.image_quality.compute_edge_score(vol, reference, sample_z=None)[source]#

Compute edge preservation score between volume and reference.

Uses Sobel edge detection to compare edge structures.

Parameters:

  • vol (np.ndarray) – Input volume (Z, Y, X) or 2D image.

  • reference (np.ndarray) – Reference volume or image.

  • sample_z (int, optional) – Z-index to sample for 3D volumes. If None, uses middle slice.

Returns:

Edge preservation score (0 to 1, higher is better).

Return type:

float

linumpy.metrics.image_quality.compute_variance_score(vol, reference)[source]#

Compute variance consistency score between volume and reference.

Low variance may indicate data loss or corruption.

Parameters:

  • vol (np.ndarray) – Input volume.

  • reference (np.ndarray) – Reference volume.

Returns:

Variance score (0 to 1, higher means more similar variance).

Return type:

float

linumpy.metrics.image_quality.assess_slice_quality(vol, vol_before, vol_after, sample_depth=5, weights=None, xy_roi=0)[source]#

Assess overall quality of a slice volume.

Uses multiple metrics to determine slice quality: - SSIM with neighboring slices (50%) - Edge preservation compared to expected structure (30%) - Variance consistency (20%)

Parameters:

  • vol (np.ndarray) – The slice volume (Z, Y, X).

  • vol_before (np.ndarray or None) – The previous slice volume.

  • vol_after (np.ndarray or None) – The next slice volume.

  • sample_depth (int) – Number of z-planes to sample for SSIM. 0 = all.

  • weights (dict, optional) – Custom weights for metrics. Keys: ‘ssim’, ‘edge’, ‘variance’.

  • xy_roi (int) – Side length of center crop in XY (pixels). 0 = full plane. Use a small value (e.g. 1024) on very large single-resolution zarr arrays to avoid loading gigabytes per plane.

Returns:

  • float – Overall quality score (0 to 1).

  • dict – Individual metric values.

Return type:

tuple[float, dict[str, Any]]

linumpy.metrics.image_quality.detect_calibration_slice(volumes, thickness_ratio=1.5)[source]#

Detect calibration slices by their different thickness.

Calibration slices are typically thicker than regular slices.

Parameters:

  • volumes (dict) – Mapping from slice_id to volume array.

  • thickness_ratio (float) – Slices with depth > median * ratio are flagged.

Returns:

List of slice IDs identified as calibration slices.

Return type:

list

linumpy.metrics.image_quality.compute_quality_report(slice_qualities, min_quality=0.0)[source]#

Generate a quality report from slice quality assessments.

Parameters:

  • slice_qualities (dict) – Mapping from slice_id to quality metrics dict.

  • min_quality (float) – Minimum quality threshold for flagging.

Returns:

Summary report with statistics and flagged slices.

Return type:

dict