deeptrack.scatterers Module#

Classes that implement light-scattering objects.

This module provides implementations of scattering objects with geometries that are commonly observed in experimental setups such as ellipsoids, spheres, or point-particles.

These scatterer objects are primarily used in combination with the Optics module to simulate how a (e.g. brightfield) microscope would resolve the object for a given optical setup (NA, wavelength, Refractive Index etc.).

Key Features#

  • Customizable geometries

    The initialization parameters allow the user to choose proportions and positioning of the scatterer in the image. It is also possible to combine multiple scatterers and overlay them, e.g. two ellipses orthogonal to each other would form a plus-shape or combining two spheres (one small, one large) to simulate a core-shell particle.

  • Defocusing

    As the z parameter represents the scatterers position in relation to the focal point of the microscope, the user can simulate defocusing by setting this parameter to be non-zero.

  • Mie scatterers

    Implements Mie-theory scatterers that calculates harmonics up to a desired order with functions and utilities from deeptrack.backend.mie. Includes the case of a spherical Mie scatterer, and a stratified spherical scatterer which is a sphere with several concentric shells of uniform refractive index.

Module Structure#

Classes:

  • Scatterer: Abstract base class for scatterers.

    This abstract class stores positional information about the scatterer and implements a method to convert the position to voxel units, as well as the a methods to upsample and crop.

  • PointParticle: Generates point particles with the size of 1 pixel.

    Represented as a numpy array of ones.

  • 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 is a sphere with several concentric shells of uniform refractive index.

Examples#

Create a ellipse scatterer and resolve it through a microscope:

>>> import numpy as np

>>> from deeptrack.optics import Fluorescence
>>> from deeptrack.scatterers import Ellipse

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

>>> scatterer = 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

>>> from deeptrack.optics import Fluorescence
>>> from deeptrack.scatterers import Ellipsoid

>>> optics = 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 = Ellipsoid(
...    position=(32, 32),
...    z=-500e-9, # Defocus slightly.
...    radius=450e-9,
...    intensity=100,
... )

>>> outer_sphere = 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

>>> from deeptrack.optics import Brightfield
>>> from deeptrack.scatterers import MieStratifiedSphere
>>> from deeptrack.elementwise import Abs

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

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

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

>>> abs_imaged_scatterer.plot()

Classes#

ConversionTable(**conversions)

Convert a dictionary of values to the desired units.

Ellipse([radius, rotation, transpose])

Generates an elliptical disk scatterer

Ellipsoid([radius, rotation, transpose])

Generates an ellipsoidal scatterer

Feature([_input])

Base feature class.

Image(value[, copy])

Wrapper for array-like values with property tracking.

MieScatterer(coefficients[, ...])

Base implementation of a Mie particle.

MieSphere([radius, refractive_index])

Scattered field by a sphere

MieStratifiedSphere([radius, refractive_index])

Scattered field by a stratified sphere

PointParticle(**kwargs)

Generates a point particle

Quantity()

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

Base abstract class for scatterers.

Sphere([radius])

Generates a spherical scatterer