magtrack.simulation

magtrack.simulation#

Simulations for generating realistic synthetic images and Z-LUTs of beads.

Functions#

simulate_beads(xyz_nm[, nm_per_px, size_px, ...])

Simulate brightfield images of spherical beads.

simulate_zlut(z_nm[, nm_per_px, size_px, oversample])

Simulate a Z look-up table (Z-LUT) from synthetic bead images.

Module Contents#

magtrack.simulation.simulate_beads(xyz_nm, nm_per_px: float = 100.0, size_px: int = 64, radius_nm: float = 1500.0, wavelength_nm: float = 550.0, n_sphere: float = 1.59, n_medium: float = 1.33, absorption_per_nm: float = 0.0, background_level=0.4, contrast_scale=1.0, pad_factor=2.0)[source]#

Simulate brightfield images of spherical beads.

Generates a 3D stack of normalized brightfield images for beads located at the provided coordinates in nanometers. The simulation models refraction and absorption through a spherical object, applies a sampling-limited pupil defined by the imaging wavelength and medium, and returns images cropped to the requested pixel size.

Parameters:

  • xyz_nm (array_like, shape (n_beads, 3)) – Nanometer coordinates [x_nm, y_nm, z_nm] for each bead.

  • nm_per_px (float, optional) – Nanometers per pixel. Defaults to 100.0 nm/px.

  • size_px (int, optional) – Output image width and height in pixels. Defaults to 64.

  • radius_nm (float, optional) – Bead radius in nanometers. Defaults to 1500.0 nm.

  • wavelength_nm (float, optional) – Illumination wavelength in nanometers. Defaults to 550.0 nm.

  • n_sphere (float, optional) – Refractive index of the bead. Defaults to 1.59.

  • n_medium (float, optional) – Refractive index of the surrounding medium. Defaults to 1.33.

  • absorption_per_nm (float, optional) – Absorption coefficient per nanometer. Defaults to 0.0.

  • background_level (float, optional) – Baseline background intensity scaling. Defaults to 0.4.

  • contrast_scale (float, optional) – Contrast scaling relative to the background. Defaults to 1.0.

  • pad_factor (float, optional) – Factor for zero-padding the pupil function to reduce edge effects. Defaults to 2.0.

Returns:

stack – Normalized simulated bead images with intensities clipped to [0, 1].

Return type:

ndarray, shape (size_px, size_px, n_beads)

magtrack.simulation.simulate_zlut(z_nm, nm_per_px: float = 100.0, size_px: int = 64, oversample: int = 1, **simulate_beads_kwargs)[source]#

Simulate a Z look-up table (Z-LUT) from synthetic bead images.

This convenience function renders a stack of bead images at the supplied axial positions using simulate_beads(), converts each frame into a radial profile via magtrack.core.radial_profile(), and assembles the results into a Z-LUT where the first row stores the z positions.

Parameters:

  • z_nm (array_like, shape (n_planes,)) – Z coordinates in nanometers for the reference stack.

  • nm_per_px (float, optional) – Nanometers per pixel used for the simulation. Defaults to 100.0.

  • size_px (int, optional) – Width/height in pixels of the simulated frames. Defaults to 64.

  • oversample (int, optional) – Oversampling factor passed to magtrack.core.radial_profile(). Defaults to 1.

  • **simulate_beads_kwargs (dict, optional) – Additional keyword arguments forwarded to simulate_beads() (for example radius_nm or wavelength_nm).

Returns:

zlut – Z look-up table where zlut[0, :] contains the reference z positions and the remaining rows contain the corresponding radial profiles.

Return type:

ndarray, shape (1 + n_bins, n_planes)