zea.models.speckle2self

Speckle2Self self-supervised speckle reduction model for ultrasound images.

Implements the SpeckleReductionNet architecture from the Speckle2Self paper (Li et al., Medical Image Analysis, 2025) as a zea.Model.

Usage

from zea.models.speckle2self import Speckle2Self

model = Speckle2Self.from_preset("speckle2self-invivo")
despeckled = model(bmode_frames)

Architecture notes

• 3 independent encoders (highRes, midRes, lowRes) + 1 shared decoder.

• Encoder: 4 x [Conv2d(stride=2) + InstanceNorm + ReLU + ResidualBlock].

• Decoder: ResidualBlock + 4 x [ConvTranspose2d(stride=2) + InstanceNorm + ReLU].

• fuse=False means the decoder does not use inter-encoder skip connections; I_clean_hr = decoder(encoder_highRes(hr)) depends only on the high-resolution input.

• InstanceNorm is implemented as GroupNormalization(groups=C, scale=False, center=False) which is mathematically equivalent.

Important

This is a zea implementation of the model. For the original paper and ` code <https://github.com/noseefood/speckle2self>`_.

Note

The Keras implementation (_SpeckleReductionNetKeras) is the primary inference backend. The PyTorch classes in _build_torch_classes() are kept for ONNX conversion only and are never imported at runtime. An ONNX fallback is also provided via Speckle2Self.from_onnx() for environments that have onnxruntime but not torch.

Note

For the ONNX fallback, onnxruntime must be installed:

pip install onnxruntime

Functions

convert_to_onnx(pth_path, onnx_path[, ...])

Convert a SpeckleReductionNet .pth checkpoint to ONNX.

Classes

Speckle2Self(*args, **kwargs)

Self-supervised speckle reduction model for ultrasound images.

class zea.models.speckle2self.Speckle2Self(*args, **kwargs)

Bases: BaseModel

Self-supervised speckle reduction model for ultrasound images.

Native Keras 3 implementation of the SpeckleReductionNet (Li et al., Medical Image Analysis, 2025).

Note

The model applies per-image linear normalisation before the network and clips outputs to [0, 1].

Example

import numpy as np
from zea.models.speckle2self import Speckle2Self

model = Speckle2Self.from_preset("speckle2self-invivo")
env = np.random.rand(2, 512, 512, 1).astype("float32")
out = model(env)

call(inputs)

Run speckle reduction on a batch of B-Mode images.

Pads height and width to multiples of 16 (required by the 4-level encoder), runs inference, then crops back and clips to [0, 1].

Parameters:

inputs (array-like) – B-Mode images. Auto-normalization is applied per image inside this method. Shape: (N, H, W, 1).

Returns:

Despeckled images, same shape as input, values in [0, 1].

Return type:

np.ndarray

custom_load_weights(preset, backend='keras', **kwargs)

Load weights from a preset (Hugging Face or local directory).

Parameters:

• preset – Preset identifier passed from from_preset(). Accepts Hugging Face handles (hf://...) or local directory paths.

• backend –

  Which backend to use for loading weights. Options:

  • "keras": Load native Keras weights from model.weights.h5.

  • "torch": Load PyTorch checkpoint from model.pth, original

    source for the weights.

  • "onnx": Load ONNX file from model.onnx using ONNX Runtime.

classmethod from_onnx(onnx_path)

Create a Speckle2Self model from a local ONNX file (legacy fallback).

Use from_pth() or from_preset() when possible.

Parameters:

onnx_path (str) – Path to the .onnx file.

Returns:

Model instance using ONNX Runtime for inference.

Return type:

Speckle2Self

Raises:

ImportError – If onnxruntime is not installed.

classmethod from_pth(pth_path)

Create a Speckle2Self model from a local PyTorch .pth file.

Parameters:

pth_path (str) – Path to the .pth checkpoint.

Returns:

Fully initialised Keras model.

Return type:

Speckle2Self

Raises:

ImportError – If torch is not installed.

zea.models.speckle2self.convert_to_onnx(pth_path, onnx_path, input_size=(1, 1, 512, 512))

Convert a SpeckleReductionNet .pth checkpoint to ONNX.

Uses a single-input wrapper (encoder_highRes + decoder) since the I_clean_hr output does not depend on the lr/mid paths (fuse=False).

Parameters:

• pth_path (str) – Path to the .pth checkpoint file.

• onnx_path (str) – Destination path for the ONNX file.

• input_size (tuple) – Dummy input shape (B, C, H, W). H and W must be multiples of 16.

Raises:

ImportError – If torch is not installed.