Scene

Single-frame compositing of synthetic microscope images.

Takes a rendered cell image and segmentation mask, then applies a sequence of optical effects to produce a realistic microscope frame:

  1. Generate a phase-contrast background with gradient and texture

  2. Composite foreground cells onto the background

  3. Adjust per-cell brightness (age-based or matched to a real image)

  4. Add halo artifacts around cell boundaries

  5. Apply PSF blur, Poisson shot noise, and Gaussian readout noise

apply_synthetic_effects(raw_image: ndarray, mask: ndarray, bg_base_brightness: float = 0.56, bg_gradient_strength: float = 0.027, bac_halo_intensity: float = 0.3, bg_noise_scale: int = 20, psf_sigma: float = 1.0, peak_signal: float = 1000.0, gaussian_sigma: float = 0.01, seed: int = None, brightness_mode: str = 'original', cell_ages: dict = None, cell_colors_map: dict = None, brightness_range: tuple = (0.8, 0.3), max_age: int = None, num_dark_spots_range: tuple = (0, 5), original_image: ndarray = None, original_mask: ndarray = None, original_colors: list = None, apply_psf: bool = True, apply_poisson: bool = True, apply_gaussian: bool = True, dark_spot_size_range: tuple = (2, 5), num_light_spots_range: tuple = (0, 0), texture_strength: float = 0.02, texture_scale: float = 1.5, bg_blur_sigma: float = 0.8, halo_type: str = 'bright', halo_inner_width: float = 2.0, halo_outer_width: float = 50.0, halo_blur_sigma: float = 0.5, halo_fade_type: str = 'exponential', brightness_noise_strength: float = 0.0, bg_seed: int = None) → ndarray

Apply synthetic microscope effects to a raw rendered image.

This function handles the post-processing pipeline:

  1. Generate phase contrast background

  2. Combine foreground with background

  3. Apply brightness adjustment (original or age-based)

  4. Apply halo effect

  5. Apply microscope effects (PSF, noise)

Parameters:

  • raw_image (np.ndarray) – Raw rendered image from cr_mech_coli (H x W x 3), uint8.

  • mask (np.ndarray) – RGB segmentation mask (H x W x 3).

  • bg_base_brightness (float) – Base brightness for background generation.

  • bg_gradient_strength (float) – Gradient strength for background generation.

  • bac_halo_intensity (float) – Intensity of the halo effect around bacteria.

  • bg_noise_scale (int) – Scale factor for background illumination noise (1-25).

  • psf_sigma (float) – Sigma for Gaussian PSF blur (optical diffraction).

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

  • gaussian_sigma (float) – Sigma for Gaussian readout noise.

  • seed (int) – Random seed for reproducibility. If None, a random seed is generated.

  • brightness_mode (str) – “original” to match brightness from original image, “age” to compute brightness based on cell age.

  • cell_ages (dict) – Dict mapping cell identifier to age (required if brightness_mode=”age”).

  • cell_colors_map (dict) – Dict mapping cell identifier to RGB color (required if brightness_mode=”age”).

  • brightness_range (tuple) – (young_brightness, old_brightness) for age-based mode.

  • max_age (int) – Maximum age for normalization in age-based mode.

  • num_dark_spots_range (tuple) – (min, max) range for number of dark spots in background.

  • original_image (np.ndarray) – Original microscope image (required if brightness_mode=”original”).

  • original_mask (np.ndarray) – Original segmentation mask (required if brightness_mode=”original”).

  • original_colors (list) – List of colors from crm.extract_positions (required if brightness_mode=”original”).

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

  • apply_poisson (bool) – Whether to apply Poisson shot noise.

  • apply_gaussian (bool) – Whether to apply Gaussian readout noise.

  • dark_spot_size_range (tuple) – Range of dark spot sizes (sigma values).

  • num_light_spots_range (tuple) – Range for number of light spots in background.

  • texture_strength (float) – Fine texture strength (0.0-1.0).

  • texture_scale (float) – Texture smoothness (higher = smoother).

  • bg_blur_sigma (float) – Gaussian blur sigma for background optical effects.

  • halo_type (str) – Type of halo: “bright”, “dark”, or “mixed”.

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

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

  • halo_blur_sigma (float) – Gaussian blur sigma for halo transition.

  • halo_fade_type (str) – Fade type: “linear”, “exponential”, or “gaussian”.

  • brightness_noise_strength (float) – Perlin-like noise strength for brightness variation (0-1).

  • bg_seed (int) – Separate seed for background generation. When provided, the background is generated with this seed (enabling consistent backgrounds across frames) while seed is still used for noise and brightness. If None, seed is used for everything (default).

Returns:

Processed synthetic image (H x W x 3), uint8.

Return type:

np.ndarray

create_synthetic_scene(microscope_image_path, segmentation_mask_path, output_dir, n_vertices: int = 8, bg_base_brightness: float = 0.56, bg_gradient_strength: float = 0.027, bac_halo_intensity: float = 0.3, bg_noise_scale: int = 20, psf_sigma: float = 1.0, peak_signal: float = 1000.0, gaussian_sigma: float = 0.01, seed: int = None, brightness_mode: str = 'original', cell_ages: dict = None, cell_colors_map: dict = None, brightness_range: tuple = (0.8, 0.3), max_age: int = None, num_dark_spots_range: tuple = (0, 5), output_prefix: str = 'syn_') → tuple[ndarray, ndarray]

Creates a synthetic microscope image from a real one using cr_mech_coli.

Parameters:

  • microscope_image_path – Path to the real microscope image (TIF).

  • segmentation_mask_path – Path to the segmentation mask (TIF).

  • output_dir – Directory to save synthetic images.

  • n_vertices (int) – Number of vertices to extract per cell.

  • bg_base_brightness (float) – Base brightness for background generation.

  • bg_gradient_strength (float) – Gradient strength for background generation.

  • bac_halo_intensity (float) – Intensity of the halo effect around bacteria.

  • bg_noise_scale (int) – Scale factor for background illumination noise (1-25).

  • psf_sigma (float) – Sigma for Gaussian PSF blur (optical diffraction).

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

  • gaussian_sigma (float) – Sigma for Gaussian readout noise.

  • seed (int) – Random seed for reproducibility. If None, a random seed is generated.

  • brightness_mode (str) – “original” to match brightness from original image, “age” to compute brightness based on cell age.

  • cell_ages (dict) – Dict mapping cell identifier to age (required if brightness_mode=”age”).

  • cell_colors_map (dict) – Dict mapping cell identifier to RGB color (required if brightness_mode=”age”).

  • brightness_range (tuple) – (young_brightness, old_brightness) for age-based mode.

  • max_age (int) – Maximum age for normalization in age-based mode.

  • num_dark_spots_range (tuple) – (min, max) range for number of dark spots in background.

  • output_prefix (str) – Prefix for output filenames.

Returns:

(synthetic_image, synthetic_mask).

Return type:

tuple[np.ndarray, np.ndarray]