MieScatterer

class deeptrack.optical.scatterers.MieScatterer(coefficients: callable, input_polarization: float | Quantity | str | None = 0, output_polarization: float | Quantity | None = 0, offset_z: str | float = 'auto', collection_angle: str | float = 'auto', L: str | int = 'auto', refractive_index_medium: float | None = None, wavelength: float | None = None, NA: float | None = None, padding: tuple[int, int, int, int] = (0, 0, 0, 0), output_region: tuple[int, int, int, int] | None = None, polarization_angle: float | None = None, working_distance: float = 1000000, position_objective: tuple[float, float] = (0, 0), return_fft: bool = False, coherence_length: float | None = None, illumination_angle: float = 0, amp_factor: float = 1, phase_shift_correction: bool = False, mode: str = 'geometric', pupil: ndarray | None = None, **kwargs: Any)

Bases: FieldScatterer

Base class for Mie-theory scatterers.

This class implements scattering from spherical particles using Mie theory. New scatterer types can be created by subclassing MieScatterer and providing a function that returns the Mie coefficients. The coefficient function should return the harmonic coefficients up to order L. Specifically, it should be a wrapper that receives the current feature properties and returns a callable. That callable must take a single integer argument L and return the coefficients (an, bn) up to that order. See deeptrack.backend.mie.coefficients for an example implementation.

Parameters

coefficients: callable

Factory function receiving the current feature properties and returning a callable f(L) that yields the Mie coefficients (an, bn) up to order L.

offset_z: “auto” | float

Distance from the particle in the z direction where the field is evaluated. If “auto”, this is calculated from the pixel size and collection_angle.

collection_angle: “auto” | float

Maximum collection angle in radians. If “auto”, this is computed from the objective NA (assuming the objective is the limiting aperture).

input_polarization: float | Quantity | str | None

Polarization angle of the incident illumination in radians. If a float (or Quantity), it specifies the orientation of a linear polarizer before the sample. None represents genuinely unpolarized illumination with no preferred axis. “circular” represents physically circularly polarized illumination (e.g. a standard ISCAT QWP+PBS illumination path); it gives the same phi-independent coefficients as None for intensity purposes here, but is the more physically accurate term when the illumination genuinely is circularly polarized.

output_polarization: float | Quantity | None

Angle of a polarization analyzer placed after the sample, in radians. If a float (or Quantity), the detected field is projected onto the corresponding linear polarization direction. None represents detection with no analyzer (the standard, recommended way).

L: int | str

Number of terms used to evaluate the Mie series. If “auto”, the number of terms is determined automatically.

position: tuple[float, float] | tuple[float, float, float]

Particle position. If three values are provided, the third corresponds to the axial position relative to the camera plane.

z: float

Axial particle position if position is two-dimensional.

return_fft: bool

If True, the feature returns the Fourier transform of the field rather than the spatial field itself.

coherence_length: float | None

Temporal coherence length of the illumination in meters. If None, illumination is assumed to be fully coherent.

amp_factor: float

Scaling factor applied to the scattered field amplitude.

phase_shift_correction: bool

If True, applies a phase correction to the field according to arr *= exp(1j * k * z + 1j * π / 2) This correction is used in ISCAT simulations.

mode{“geometric”, “hybrid”}

Determines how the scattered field is constructed before propagation.

Both modes use the same Mie coefficients but differ in how the scattered field is represented prior to propagation through the optical system. - “geometric”

Evaluates the scattered field as a spherical wave on a virtual plane located at offset_z from the particle. The field includes the geometric propagation factor exp(i k R) / R and is sampled on a finite spatial grid before being propagated through the optical system. Because the field is computed on a finite plane, the result can be sensitive to the simulated field-of-view.

• “hybrid” Constructs the scattered field using the Mie scattering amplitudes S1 and S2 mapped to spatial frequencies corresponding to the objective pupil. The field is then propagated to the detector. This approach is less sensitive to the simulated field-of-view and generally more numerically stable.

pupil: None | ndarray

Optional pupil function applied to the scattered field. This can be used to simulate aberrations or other modifications of the optical system.

Methods Summary

get(*args[, mode])	Evaluate the Mie scatterer field based on the specified mode.
get_detector_mask(X, Y, radius)	Creates a mask based on a circular aperture.
get_xy_grid(shape, voxel_size)	Generates meshgrid for X and Y given the shape and voxel size.
get_xy_size(output_region, padding)	Computes the x and y dimensions of the output region with padding.

Methods Documentation

get(*args, mode=None, **kwargs: Any) → ndarray

Evaluate the Mie scatterer field based on the specified mode.

This method dispatches the field calculation to either the geometric or hybrid implementation based on the mode argument. If mode is not provided, it defaults to the mode specified during initialization.

Parameters

args: Any

Positional arguments passed to the method.

mode: str | None

The mode to use for field calculation. Can be “geometric” or “hybrid”. If None, the mode specified during initialization is used.

kwargs: Any

Keyword arguments passed to the method.

Returns

np.ndarray

The calculated scattered field based on the specified mode.

get_detector_mask(X: ndarray, Y: ndarray, radius: float) → ndarray

Creates a mask based on a circular aperture.

Parameters

X: np.ndarray

X-coordinates of the field.

Y: np.ndarray

Y-coordinates of the field.

radius: float

The radius of the detector aperture.

Returns

np.ndarray

A boolean mask.

get_xy_grid(shape: tuple[int, int], voxel_size: ndarray) → tuple[ndarray, ndarray]

Generates meshgrid for X and Y given the shape and voxel size.

Parameters

shape: tuple[int, int]

The dimensions of the output region.

voxel_size: array-like of float

The size of each voxel in meters.

Returns

tuple[np.ndarray, np.ndarray]

The meshgrid of X and Y coordinates.

get_xy_size(output_region: tuple[int, int, int, int], padding: tuple[int, int, int, int]) → tuple[int, int]

Computes the x and y dimensions of the output region with padding.

Parameters

output_region: tuple[int, int, int, int]

The coordinates defining the output region.

padding: tuple[int, int, int, int]

The padding applied in each direction.

Returns

tuple[int, int]

The total size in x and y directions.