Filters

Filters for adding realistic microscope effects to synthetic images.

This module provides methods to simulate:

  • Phase contrast halo effects (bright/dark halos around bacteria edges)

  • Point Spread Function (PSF) blur from optical systems

  • Poisson noise (shot noise from photon counting)

  • Gaussian noise (camera readout noise)

create_gaussian_psf(size: int = 7, sigma: float = 1.0) → ndarray

Create a 2D Gaussian Point Spread Function kernel.

The PSF models the optical blur caused by the microscope’s optical system, including diffraction and aberrations.

Parameters:

  • size (int) – Size of the PSF kernel (size x size). Should be odd.

  • sigma (float) – Standard deviation of the Gaussian PSF in pixels.

Returns:

2D normalized PSF kernel that sums to 1.

Return type:

np.ndarray

create_airy_psf(size: int = 15, radius: float = 3.0) → ndarray

Create a 2D Airy disk Point Spread Function (more physically accurate).

The Airy pattern is the diffraction pattern from a circular aperture, which is more accurate for microscope optics than a Gaussian.

Parameters:

  • size (int) – Size of the PSF kernel (size x size). Should be odd.

  • radius (float) – Radius parameter for the Airy disk (first zero crossing).

Returns:

2D normalized PSF kernel that sums to 1.

Return type:

np.ndarray

apply_psf_blur(image: ndarray, psf_type: str = 'gaussian', psf_sigma: float = 1.0, psf_size: int = 7, airy_radius: float = 3.0) → ndarray

Apply Point Spread Function blur to simulate optical blur from microscope.

This is crucial for smoothing sharp edges around bacteria that result from compositing rendered cells onto the background. The PSF models diffraction and optical aberrations in the microscope system.

Parameters:

  • image (np.ndarray) – Input image (grayscale or RGB). Can be float [0,1] or uint8 [0,255].

  • psf_type (str) – Type of PSF: ‘gaussian’ (fast, good approximation) or ‘airy’ (more accurate).

  • psf_sigma (float) – Sigma for Gaussian PSF (in pixels). Typical range: 0.5-2.0. Higher values = more blur.

  • psf_size (int) – Size of PSF kernel. Should be large enough to capture PSF extent. Typical range: 5-15.

  • airy_radius (float) – Radius parameter for Airy disk PSF (only used if psf_type=’airy’).

Returns:

Blurred image with same dtype as input.

Return type:

np.ndarray

Notes

PSF blur should be applied BEFORE adding noise (it’s an optical effect). For phase contrast microscopy, sigma=0.8-1.5 is typical at 60-100x magnification. Bacteria edges will be softened, making compositing look more natural.

add_poisson_noise(image: ndarray, peak_signal: float = 1000.0, seed: int | None = None) → ndarray

Add Poisson (shot) noise to simulate photon counting noise.

Poisson noise is signal-dependent: brighter regions have more noise. This is the dominant noise source in well-lit microscopy images. The noise model: noisy_value = Poisson(clean_value * peak_signal) / peak_signal.

Parameters:

  • image (np.ndarray) – Input image (grayscale or RGB). Can be float [0,1] or uint8 [0,255].

  • peak_signal (float) – Peak photon count at maximum intensity. Controls noise strength. Higher values = less noise (more photons collected). Typical range: 100-500 (high noise), 500-2000 (moderate), 2000-10000 (low noise).

  • seed (int) – Random seed for reproducibility. If None, uses random state.

Returns:

Noisy image with same dtype as input.

Return type:

np.ndarray

Notes

Apply AFTER PSF blur (noise happens during photon detection) and BEFORE Gaussian noise. Variance = mean for Poisson, so brighter = noisier in absolute terms.

add_gaussian_noise(image: ndarray, sigma: float = 0.01, seed: int | None = None) → ndarray

Add Gaussian (readout) noise to simulate camera electronics noise.

Gaussian noise is signal-independent: same noise level across all intensities. This represents noise from camera electronics (readout, thermal, etc.).

Parameters:

  • image (np.ndarray) – Input image (grayscale or RGB). Can be float [0,1] or uint8 [0,255].

  • sigma (float) – Standard deviation of Gaussian noise (in range [0,1] for float images). Typical range: 0.001-0.005 (low), 0.01-0.02 (moderate), 0.03-0.05 (high).

  • seed (int) – Random seed for reproducibility. If None, uses random state.

Returns:

Noisy image with same dtype as input.

Return type:

np.ndarray

Notes

Apply AFTER Poisson noise (it’s the last noise source in the imaging chain). Also called “additive white Gaussian noise” (AWGN).

apply_gaussian_blur(image: ndarray, sigma: float = 1.0) → ndarray

Apply Gaussian blur to an image.

Simple wrapper around scipy’s gaussian_filter that handles both grayscale and RGB images, and preserves the input dtype.

Parameters:

  • image (np.ndarray) – Input image (grayscale or RGB). Can be float [0,1] or uint8 [0,255].

  • sigma (float) – Standard deviation of the Gaussian kernel (blur strength). Higher values = more blur. Typical range: 0.5-1.0 (slight), 1.0-2.0 (moderate), 2.0-5.0 (strong).

Returns:

Blurred image with same dtype as input.

Return type:

np.ndarray

Notes

This is a simple spatial domain blur. For PSF blur (optical effects), use apply_psf_blur() instead.

create_halo_mask(mask: ndarray, inner_width: float = 2.0, outer_width: float = 8.0) → Tuple[ndarray, ndarray]

Create inner and outer halo regions around bacteria mask boundaries.

Uses distance transform to create ring-shaped regions around mask edges that will be used for halo effects.

Parameters:

  • mask (np.ndarray) – Binary mask where True/1 = bacteria (foreground), False/0 = background.

  • inner_width (float) – Width of inner halo region (in pixels from edge). This is typically the bright part of the halo.

  • outer_width (float) – Width of outer halo region (in pixels from edge). This is typically the darker/fading part.

Returns:

(inner_halo_mask, outer_halo_mask) - Boolean

arrays indicating halo regions.

Return type:

Tuple[np.ndarray, np.ndarray]

create_halo_gradient(mask: ndarray, inner_width: float = 2.0, outer_width: float = 8.0, fade_type: str = 'exponential') → ndarray

Create a smooth gradient field for halo intensity that fades from edge outward.

Parameters:

  • mask (np.ndarray) – Binary mask where True/1 = bacteria (foreground).

  • inner_width (float) – Width of inner bright halo (in pixels).

  • outer_width (float) – Total width of halo region (in pixels).

  • fade_type (str) – Type of fade: ‘linear’, ‘exponential’, or ‘gaussian’.

Returns:

Gradient field with values [0,1] where 1 is at the edge,

fading to 0.

Return type:

np.ndarray

apply_halo_effect(image: ndarray, mask: ndarray, halo_intensity: float = 0.15, halo_type: str = 'bright', inner_width: float = 2.0, outer_width: float = 8.0, fade_type: str = 'exponential', blur_sigma: float = 1.5) → ndarray

Apply phase contrast halo effect around bacteria edges.

Parameters:

  • image (np.ndarray) – Input image (grayscale or RGB). Can be float [0,1] or uint8 [0,255].

  • mask (np.ndarray) – Binary mask where True/1 = bacteria (foreground).

  • halo_intensity (float) – Strength of halo effect (0.0 to 1.0). Higher values create more pronounced halos. Typical range: 0.1-0.3.

  • halo_type (str) – Type of halo: ‘bright’ (positive phase), ‘dark’ (negative phase), or ‘mixed’ (bright inner with bright outer at reduced intensity).

  • inner_width (float) – Width of inner halo in pixels (typically bright).

  • outer_width (float) – Total width of halo region in pixels.

  • fade_type (str) – How halo fades: ‘linear’, ‘exponential’, or ‘gaussian’.

  • blur_sigma (float) – Gaussian blur sigma to smooth the halo transition.

Returns:

Image with halo effect applied (same dtype as input).

Return type:

np.ndarray

Notes

Apply BEFORE final PSF blur and noise for best results.

apply_phase_contrast_pipeline(image: ndarray, mask: ndarray, apply_halo: bool = True, halo_intensity: float = 0.15, halo_type: str = 'mixed', halo_inner_width: float = 2.0, halo_outer_width: float = 8.0, halo_fade_type: str = 'exponential', halo_blur_sigma: float = 1.5, apply_psf: bool = True, psf_type: str = 'gaussian', psf_sigma: float = 1.0, psf_size: int = 7, apply_poisson: bool = True, peak_signal: float = 1000.0, apply_gaussian: bool = True, gaussian_sigma: float = 0.01, seed: int | None = None) → ndarray

Complete phase contrast microscopy pipeline with halo effects.

This pipeline applies effects in the correct order for realistic phase contrast:

  1. Halo effects (optical phase shift at edges)

  2. PSF blur (optical diffraction)

  3. Poisson noise (photon shot noise)

  4. Gaussian noise (camera readout noise)

This should be applied AFTER combining foreground and background.

Parameters:

  • image (np.ndarray) – Input synthetic image (bacteria on background).

  • mask (np.ndarray) – Binary mask where True/1 = bacteria (foreground).

  • apply_halo (bool) – Whether to apply phase contrast halo effect.

  • halo_intensity (float) – Strength of halo effect (0.1-0.3 typical).

  • halo_type (str) – Halo type: ‘bright’, ‘dark’, or ‘mixed’.

  • halo_inner_width (float) – Width of inner bright halo (pixels).

  • halo_outer_width (float) – Total halo width (pixels).

  • halo_fade_type (str) – Fade type: ‘linear’, ‘exponential’, or ‘gaussian’.

  • halo_blur_sigma (float) – Blur sigma for smoothing halo.

  • apply_psf (bool) – Whether to apply PSF blur.

  • psf_type (str) – PSF type: ‘gaussian’ or ‘airy’.

  • psf_sigma (float) – PSF blur strength.

  • psf_size (int) – PSF kernel size.

  • apply_poisson (bool) – Whether to add Poisson noise.

  • peak_signal (float) – Peak photon count for Poisson noise.

  • apply_gaussian (bool) – Whether to add Gaussian noise.

  • gaussian_sigma (float) – Gaussian noise sigma.

  • seed (int) – Random seed for reproducibility. If None, uses random state.

Returns:

Processed image with all effects applied (same dtype as input).

Return type:

np.ndarray

apply_microscope_effects(image: ndarray, mask: ndarray | None = None, apply_psf: bool = True, psf_type: str = 'gaussian', psf_sigma: float = 1.0, psf_size: int = 7, airy_radius: float = 3.0, blur_bacteria_more: bool = False, bacteria_blur_factor: float = 1.5, apply_poisson: bool = True, peak_signal: float = 1000.0, apply_gaussian: bool = True, gaussian_sigma: float = 0.01, seed: int | None = None) → ndarray

Apply complete microscope imaging effects pipeline to synthetic image.

This is the main method that applies all realistic microscope effects in the correct order: PSF blur -> Poisson noise -> Gaussian noise.

Optionally applies stronger blur to bacteria (foreground) to better integrate them with the slightly blurred background.

Parameters:

  • image (np.ndarray) – Input synthetic image.

  • mask (np.ndarray) – Binary mask where True/1 = bacteria (foreground), False/0 = background. Used for differential blurring if blur_bacteria_more=True. If None, uniform blur is applied.

  • apply_psf (bool) – Whether to apply PSF blur.

  • psf_type (str) – Type of PSF: ‘gaussian’ or ‘airy’.

  • psf_sigma (float) – Sigma for Gaussian PSF blur (in pixels).

  • psf_size (int) – Size of PSF kernel.

  • airy_radius (float) – Radius for Airy disk PSF.

  • blur_bacteria_more (bool) – Apply stronger blur to bacteria to smooth sharp edges.

  • bacteria_blur_factor (float) – Multiply PSF sigma by this factor for bacteria regions. Only used if blur_bacteria_more=True and mask is provided.

  • apply_poisson (bool) – Whether to add Poisson noise.

  • peak_signal (float) – Peak photon count for Poisson noise.

  • apply_gaussian (bool) – Whether to add Gaussian noise.

  • gaussian_sigma (float) – Sigma for Gaussian noise.

  • seed (int) – Random seed for reproducibility. If None, uses random state.

Returns:

Processed image with all effects applied (same dtype as input).

Return type:

np.ndarray