deeptrack.optical.scatterers Module#

Classes that implement light-scattering objects.

This module provides implementations of scattering objects with geometries commonly encountered in experimental microscopy, such as ellipsoids, spheres, and point particles.

These scatterers are primarily used together with the Optics module to simulate how an optical system (e.g., brightfield or fluorescence microscopy) images an object under a given configuration (NA, wavelength, refractive index, etc.).

Scatterers produce either voxelized volumes (for geometrical optics models) or complex fields (for wave-optical models such as Mie scattering).

Volume-based scatterers are evaluated on a discrete grid defined by the active optics configuration, and can be supersampled (upsample) for improved accuracy. Upsampling does not change the physical size of the scatterer, but rather the resolution at which it is evaluated. Field-based scatterers are evaluated directly as complex fields without supersampling.

Upsample should not be confused with Optics.upscale, which applies to the entire imaging pipeline and can be used to improve the accuracy of the optics model itself.

Key Features#

  • Customizable Geometries

    Initialization parameters allow full control over shape, size, and spatial positioning. Multiple scatterers can be combined and overlaid using feature composition. For example, two orthogonal ellipses can form a cross, or two concentric spheres can represent a core–shell particle.

  • Defocusing

    The z parameter defines the axial position relative to the focal plane, enabling simulation of defocused imaging by assigning nonzero values.

  • Fluorescence discretization

    Some scatterers include measure corrections to ensure consistent fluorescence scaling under discretization. Point-like emitters are scaled by voxel volume, planar emitters by axial voxel size, while volumetric emitters require no additional correction beyond their voxelized support.

  • Mie Scatterers

    Includes Mie-theory-based scatterers that compute scattering harmonics up to a specified order using utilities from deeptrack.backend.mie. Supported implementations include homogeneous spheres and stratified spheres with multiple concentric layers of distinct refractive indices.

  • Backend Compatibility

    Both geometry-based and Mie-based scatterers support NumPy and PyTorch arrays, with full backend dispatch via deeptrack.backend.xp.

Module Structure#

Classes:

  • Scatterer: Abstract base class for all scatterers.

    Stores positional information and implements utilities for coordinate conversion, upsampling, and cropping.

  • VolumeScatterer: Base class for scatterers that generate voxelized volumes.

    Produces ScatteredVolume outputs representing spatial occupancy.

  • FieldScatterer: Base class for scatterers that generate complex fields.

    Produces ScatteredField outputs representing optical fields.

  • PointParticle: Generates diffraction-limited point particles.

  • Ellipse: Generates 2-D elliptical particles.

  • Sphere: Generates 3-D spheres.

  • Ellipsoid: Generates 3-D ellipsoids.

  • MieScatterer: Mie scatterer base class.

  • MieSphere: Extends MieScatterer to the spherical case.

  • MieStratifiedSphere: Extends MieScatterer to the stratified sphere case.

    A stratified sphere consists of concentric shells with distinct refractive indices.

  • Incoherent: A wrapper to treat coherent scatterers as incoherent sources.

Examples#

Create a ellipse scatterer and resolve it through a microscope:

>>> import numpy as np

>>> import deeptrack as dt

>>> optics = dt.Fluorescence(
...            NA=0.7,
...            wavelength=680e-9,
...            resolution=1e-6,
...            magnification=10,
...            output_region=(0, 0, 64, 64),
...        )

>>> scatterer = dt.Ellipse(
...      intensity=100,
...      position_unit="pixel",
...      position=(32, 32),
...      radius=(1e-6, 0.5e-6),
...      rotation=np.pi / 4,
...      upsample=4,
...  )

>>> imaged_scatterer = optics(scatterer)
>>> imaged_scatterer.plot(cmap="gray")

Combine multiple scatterers to image a core-shell particle:

>>> import numpy as np

>>> import deeptrack as dt

>>> optics = dt.Fluorescence(
...    NA=1.4,
...    wavelength=638.0e-9,
...    refractive_index_medium=1.33,
...    output_region=[0, 0, 64, 64],
...    magnification=1,
...    resolution=100e-9,
...    return_field=False,
... )

>>> inner_sphere = dt.Ellipsoid(
...    position=(32, 32),
...    z=-500e-9, # Defocus slightly.
...    radius=450e-9,
...    intensity=100,
... )

>>> outer_sphere = dt.Ellipsoid(
...    position=inner_sphere.position,
...    z=inner_sphere.z,
...    radius=inner_sphere.radius * 2,
...    intensity= inner_sphere.intensity * -0.25,
... )

>>> combined_scatterer = inner_sphere >> outer_sphere
>>> imaged_scatterer = optics(combined_scatterer)
>>> imaged_scatterer.plot(cmap="gray")

Create a stratified Mie sphere and resolve it through a microscope:

>>> import numpy as np

>>> import deeptrack as dt

>>> optics = dt.Brightfield(
...    NA=0.7,
...    wavelength=680e-9,
...    resolution=1e-6,
...    magnification=5,
...    output_region=(0, 0, 64, 64),
...    return_field=True,
...    upscale=4,
... )

>>> scatterer = dt.MieStratifiedSphere(
...    radius=np.array([0.5e-6, 3e-6]),
...    refractive_index=[1.45 + 0.1j, 1.52],
...    position_unit="pixel",
...    position=(128, 128),
...    aperture_angle=0.1,
... )

>>> imaged_scatterer = optics(scatterer) # Creates an array of complex numbers.
>>> abs_imaged_scatterer = dt.Abs(imaged_scatterer)

>>> abs_imaged_scatterer.plot()

Classes#

Scatterer([position, z, value, ...])

Base abstract class for scatterers.

PointParticle(**kwargs)

Generate a diffraction-limited point particle.

Ellipse([radius, rotation, transpose])

Generate a 2D elliptical scatterer.

Sphere([radius])

Generate a spherical scatterer.

Ellipsoid([radius, rotation, transpose])

Generates an ellipsoidal scatterer.

MieScatterer(coefficients[, ...])

Base class for Mie-theory scatterers.

MieSphere([radius, refractive_index])

Scattered field produced by a homogeneous sphere.

MieStratifiedSphere([radius, refractive_index])

Scattered field produced by a stratified sphere.

Incoherent(feature[, input_unpolarized, ...])

Average intensities over orthogonal polarization states.