opticks.contrast_model.mtf

Package for Modulation Transfer Function (MTF) related classes and functions.

Classes

MTF_Model_1D(id, mtf_value_func)

Modulation Transfer Function (MTF) Model in 1D.

MTF_Plot_1D(freq_list, mtf_data[, ...])

Generates an MTF Plot.
class MTF_Model_1D(id, mtf_value_func)[source]

Modulation Transfer Function (MTF) Model in 1D.

Usually this is not called by the User. There are other constructors instead.

Parameters:

  • id (str) – Model explanation or identifier

  • mtf_value_func – Function that returns the MTF value for a given input line frequency

static combined(*mtf_models)[source]

Combination MTF models.

The combined MTF is useful when describing a combination of multiple MTF Models. For example, the Imager MTF is a combination of Optical MTF, Detector Sampling MTF and Detector Diffusion MTF.

Return type:

MTF_Model_1D

Parameters:

mtf_models (tuple containing multiple "MTF_Model_1D" objects) – list of MTF Models to be combined

Returns:

MTF_Model_1D – MTF model

static detector_crosstalk(pixel_pitch, crosstalk_xs, crosstalk_xd=0.0)[source]

Detector crosstalk MTF model (center pixel, 8 neighbours).

Computes the MTF due to nearest-neighbour charge sharing using the discrete kernel model with separate side and diagonal crosstalk coefficients.

The 1D MTF (fy=0 slice) is: MTF(f) = 1 - 2(Xs + 2Xd)(1 - cos(2π f P))

When crosstalk_xd = 0, this reduces to the classical nearest-neighbour formula MTF(f) = 1 - 2Xs(1 - cos(2π f P)).

Return type:

MTF_Model_1D

Parameters:

  • pixel_pitch (Quantity[``”length”``]) – Pixel pitch

  • crosstalk_xs (float) – Side-neighbour crosstalk coefficient (dimensionless fraction, e.g. 0.03 for 3%).

  • crosstalk_xd (float, optional) – Diagonal-neighbour crosstalk coefficient (dimensionless fraction, e.g. 0.005 for 0.5%). Default is 0.0 (no diagonal crosstalk).

Returns:

MTF_Model_1D – Crosstalk MTF model

static detector_cte(pixel_pitch, num_pixels, num_phases, cte, tdi_stages=0)[source]

Detector CTE (Charge Transfer Efficiency) MTF model for CCDs.

Models charge transfer inefficiency in the CCD parallel or serial register. The MTF degrades with the total number of transfers and the per-transfer inefficiency (1 - CTE):

MTF(f) = exp(-N * (1 - cte) * (1 - cos(π f / f_nyq)))

where N = (num_pixels + tdi_stages) * num_phases and f_nyq = 1 / (2 * pixel_pitch).

CCD only. CMOS and IR FPAs read out pixels individually and do not suffer from CTE degradation.

Direction-dependent. Instantiate one model per direction:

  • ALT MTF (parallel register): num_pixels = rows from pixel to readout edge; tdi_stages = number of on-chip analog TDI stages (0 for non-TDI sensors).

  • ACT MTF (serial register): num_pixels = columns from pixel to readout amplifier; tdi_stages = 0 (TDI is parallel-register only).

On-chip vs digital TDI. tdi_stages applies only to on-chip analog TDI in CCDs, where each stage is a real charge transfer in the parallel register. For digital (“shift-and-add”) TDI — CMOS sensors that read out each row independently and accumulate in firmware — pass tdi_stages = 0 because no charge transfer occurs between stages.

Convention. The cte parameter follows Janesick (2001): CTE is the fraction of charge successfully transferred per clock cycle (dimensionless, 0 to 1). A high-quality CCD might have cte = 0.99999 (one electron lost per 100 000 transferred). Some references (e.g. Boreman) use ε to mean the inefficiency CTI = 1 − CTE; do not pass 1 - cte here.

Parameters:

  • pixel_pitch (Quantity[``”length”``]) – Pixel pitch.

  • num_pixels (int) – Number of pixels between the target pixel and the readout register (position-dependent, direction-dependent).

  • num_phases (int) – Number of clock phases per pixel (typically 3 for 3-phase CCDs).

  • cte (float) – Charge transfer efficiency per transfer (dimensionless, 0 to 1). Example: cte = 0.99999 for a high-quality CCD.

  • tdi_stages (int, optional) – Number of on-chip analog TDI stages. Default is 0.

Returns:

Return type:

MTF_Model_1D

detector_diffusion(absorption_coeff, diffusion_length, field_free_depth=None, depletion_depth=None, surface_recomb_velocity=None, diffusion_coeff=None)[source]

Detector diffusion MTF model (Crowell & Labuda 1969).

Computes the diffusion-limited MTF for a given detector geometry and boundary conditions. Use one of the five simplified model variants (BSI-1/2/3, FSI-1/2) matching your detector type.

Parameters:

  • model (DetectorDiffusionModel) – Diffusion model variant (geometry + boundary conditions)

  • absorption_coeff (Quantity[``”1/length”``]) – Optical absorption coefficient (e.g., in 1/µm or 1/cm)

  • diffusion_length (Quantity[``”length”``]) – Minority carrier diffusion length L_o

  • field_free_depth (Quantity[``”length”``], optional) – Field-free (bulk) region depth L_a. Required for BSI-1/2/3, FSI-1.

  • depletion_depth (Quantity[``”length”``], optional) – Depletion region depth L_b (BSI) or L_D (FSI). Required for BSI-1, BSI-2, FSI-1, FSI-2.

  • surface_recomb_velocity (Quantity[``”speed”``], optional) – Surface recombination velocity S. Required for BSI-3 only.

  • diffusion_coeff (Quantity, optional) – Minority carrier diffusion coefficient D (provide in cm²/s). Required for BSI-3 only.

Returns:

MTF_Model_1D – Diffusion MTF model

detector_diffusion_preset(absorption_coeff, diffusion_length=None, field_free_depth=None, depletion_depth=None, surface_recomb_velocity=None, diffusion_coeff=None)[source]

Detector diffusion MTF model from a predefined detector category preset.

Looks up default parameters for the preset, then applies any supplied overrides. Raises ValueError if an override is incompatible with the preset’s model (e.g., supplying surface_recomb_velocity for a BSI-1 preset).

Parameters:

  • preset (DetectorDiffusionPreset) – Detector category preset

  • absorption_coeff (Quantity[``”1/length”``]) – Optical absorption coefficient

  • diffusion_length (Quantity[``”length”``], optional) – Override for the preset diffusion length L_o

  • field_free_depth (Quantity[``”length”``], optional) – Override for the preset field-free depth L_a

  • depletion_depth (Quantity[``”length”``], optional) – Override for the preset depletion/substrate depth

  • surface_recomb_velocity (Quantity[``”speed”``], optional) – Override for the preset surface recombination velocity (BSI-3 only)

  • diffusion_coeff (Quantity, optional) – Override for the preset diffusion coefficient (BSI-3 only)

Returns:

MTF_Model_1D – Diffusion MTF model

static detector_sampling(pixel_pitch)[source]

Detector sampling MTF model.

MTF value is usually between 0 and 1, though contrast reversal may result in negative values.

Return type:

MTF_Model_1D

Parameters:

pixel_pitch (Quantity) – Pixel pitch (with or without binning)

Returns:

MTF_Model_1D – MTF model

static emp_model_aberrated_optics(spatial_cutoff_freq, w_rms, wavelength=None)[source]

Aberrated optical MTF model with an empirical model.

Uses an empirical model for the optical aberrations, such that: MTF_true = MTF_ideal x ATF. See Shannon’s The Art and Science of Optical Design for more information.

The ‘w_rms’ value corresponds to the RMS of the total wavefront error, or how much the actual wavefront deviates from the ideal wavefront. The unit of this deviation is the multiple wavelengths (such as 0.15 x lambda).

Return type:

MTF_Model_1D

Parameters:

  • spatial_cutoff_freq (Quantity) – Spatial cutoff frequency (in cycles/mm). Can be computed via Optics.spatial_cutoff_freq(wavelength).

  • w_rms (float or ndarray) – RMS of the total wavefront error (in wavelengths)

  • wavelength (Quantity, optional) – Wavelength (used only for the model id string)

Returns:

MTF_Model_1D – MTF model

static external_data(freq_values, mtf_values, id=None)[source]

MTF Model from an external data.

This model is mainly to ingest actual measurements or the results from complex simulations (such as Zemax).

Uses the scipy ‘Akima1DInterpolator’ (default Akima method) in the background, though withy unit support via the InterpolatorWithUnits wrapper.

Return type:

MTF_Model_1D

Parameters:

  • freq_data (ArrayLike[Quantity]) – List of spatial frequencies (in cy/mm or lp/mm)

  • spatial_freqs (ArrayLike[np.float64]) – List of corresponding MTF values (should be less than or equal to 1)

  • id (str) – id text associated with the data. Default text if None.

  • freq_values (Quantity)

  • mtf_values (ndarray[tuple[Any, ...], dtype[float64]])

Returns:

MTF_Model_1D – MTF model

static fixed(mtf_value)[source]

Fixed value MTF model.

Used for disturbances and imperfections.

Return type:

MTF_Model_1D

Parameters:

mtf_value (float) – MTF value over the spatial frequency domain (between 0 and 1, inclusive)

Returns:

MTF_Model_1D – MTF model

static from_mtf_2d(mtf_2d, slice)[source]

Converts the 2D MTF into a 1D MTF Model object.

The prysm MTF object produces the data in 2D, as the contrast transfer may differ in different directions. This method extracts a slice (usually in x or y directions) and generates an MTF_Model_1D object.

Possible slice strings are x, y, azavg, azavmedian, azmin, azpv, azvar, azstd. The first two are simply slices in the x and y axes. The remaining are different ways of sampling the data in the azimuthal direction.

Return type:

MTF_Model_1D

Parameters:

  • mtf_2d (RichData) – 2D MTF data (line freq should be in cy/mm)

  • slice (str) – slice type (e.g., “x” or “y” direction)

Returns:

MTF_Model_1D – MTF model

static ideal_optics(spatial_cutoff_freq, wavelength=None)[source]

Ideal optical MTF model.

Assumes uniformly illuminated circular aperture, no aberrations.

Return type:

MTF_Model_1D

Parameters:

  • spatial_cutoff_freq (Quantity) – Spatial cutoff frequency (in cycles/mm). Can be computed via Optics.spatial_cutoff_freq(wavelength).

  • wavelength (Quantity, optional) – Wavelength (used only for the model id string)

Returns:

MTF_Model_1D – MTF model

static jitter(pixel_pitch, jitter_stdev)[source]

Jitter MTF model.

The jitter_stdev value is defined as the 1 sigma value of the jitter amplitude, defined in pixels (e.g. 10% of the pixel).

Jitter is defined with respect to the relevant frequency of the imaging problem. For example an imaging system with a 10 msec integration time will have the disturbances at about 100 Hz or higher registered as jitter. Slower ones will be classified as drift/smear.

Return type:

MTF_Model_1D

Parameters:

  • pixel_pitch (Quantity) – Pixel pitch (with or without binning)

  • jitter_stdev (float) – Standard deviation of the jitter value in pixels (e.g. 0.1 or 10% pix)

Returns:

MTF_Model_1D – MTF model

static motion_blur(pixel_pitch, blur_extent)[source]

Motion blur MTF model.

Return type:

MTF_Model_1D

Parameters:

  • pixel_pitch (Quantity) – Pixel pitch (with or without binning)

  • blur_extent (float) – Blur extent on the image, given in pixels (e.g. 0.1 or 10% pix)

Returns:

MTF_Model_1D – MTF model

mtf_value(input_line_freq)[source]

Gets the MTF value for the given input line frequency.

Return type:

float | ndarray[tuple[Any, ...], dtype[double]]

Parameters:

input_line_freq (Quantity | ArrayLike[Quantity]) – Input line frequency (in cycles/mm)

Returns:

float | NDArray[np.float64] – MTF value (usually between 0 and 1, though can be negative)

static resampling(kernel, input_pitch, output_pitch, bicubic_a=None, lanczos_n=None)[source]

Resampling MTF for orthorectification / geometric correction.

Models the MTF of the interpolation step that resamples from a grid of spacing input_pitch (= local SSD on the ground) onto a grid of spacing output_pitch (= ortho grid). The same expression covers both upsampling and downsampling via:

p_eff = max(input_pitch, output_pitch)
MTF(f) = |H_kernel(f · p_eff)|

  • Upsample (input_pitch > output_pitch): kernel scaled to input_pitch, bridges the wide input gap.

  • Downsample (input_pitch < output_pitch): kernel scaled to output_pitch, acts as an anti-alias prefilter.

Because some kernels (Bicubic with negative a, Lanczos) have negative spatial-domain side-lobes that produce a slight MTF boost above 1 in mid-frequency bands, this model does not enforce a strict upper bound of 1 — the boost is real and represents the kernel’s edge-enhancement / ringing behaviour.

Parameters:

  • kernel (ResamplingKernel or str) – Interpolation kernel. Pass a ResamplingKernel enum member or its string label (e.g. "bilinear").

  • input_pitch (Quantity[``”length”``]) – Local input sample spacing (= SSD on the ground for ortho). Vary this per image region to map the SSD-driven MTF variation.

  • output_pitch (Quantity[``”length”``]) – Output resampling grid pitch (fixed for a given ortho product).

  • bicubic_a (float, optional) – Keys cubic shape parameter in [-1, 0]. Default is -0.5. Only used when kernel == BICUBIC.

  • lanczos_n (int, optional) – Lanczos lobe count (integer >= 2). Default is 3. Only used when kernel == LANCZOS.

Returns:

Return type:

MTF_Model_1D

static smear(pixel_pitch, blur_extent)[source]

Drift/Smear MTF model.

The drift/smear in the along-track and across-track dimensions should be computed separately.

Return type:

MTF_Model_1D

Parameters:

  • pixel_pitch (Quantity) – Pixel pitch (with or without binning)

  • blur_extent (float) – Blur extent on the image, given in pixels (e.g. 0.1 or 10% pix)

Returns:

MTF_Model_1D – MTF model

class MTF_Plot_1D(freq_list, mtf_data, acceptable_limit=0.1, nyq_limit=None)[source]

Generates an MTF Plot.

Each MTF Model is used to generate the plot y values, using the freq_list as the discrete x axis values and the dict key as the label.

Use the set_plot_style method to further detail the style options and decorators like title and axis labels.

Parameters:

  • freq_list (Arraylike) – list of spatial frequency values

  • mtf_data (dict[str, MTF_Model_1D]) – list of MTF models and labels

  • acceptable_limit (float, optional) – horizontal “acceptable limit” line value, by default 0.1

  • nyq_limit (Quantity, optional) – spatial frequency corresponding to the Nyquist limit, by default None

populate_plot(freq_list, mtf_data, acceptable_limit=0.1, nyq_limit=None)[source]

Populates the MTF plot lines using the MTF Models.

This conveniently adds items in addition to those in the constructor.

Each MTF Model is used to generate the plot y values, using the freq_list as the discrete x axis values and the dict key as the label.

If the freq_list has a single column (len(freq_list.shape) == 1) then the same list is used for each MTF Model. If the freq_list has as many columns as the mtf_data (len(freq_list) == len(mtf_data)) then each column is used for the consecutive MTF Model in the dict. The order of the frequency list should therefore match the order of the models in the dict. The dict implementation keeps the insertion order since Python 3.6.

Return type:

Self

Parameters:

  • freq_list (Arraylike) – list of spatial frequency values

  • mtf_data (dict[str, MTF_Model_1D]) – list of MTF models and labels

  • acceptable_limit (float, optional) – horizontal “acceptable limit” line value, by default 0.1

  • nyq_limit (Quantity, optional) – spatial frequency corresponding to the Nyquist limit, by default None

Returns:

MTF_Plot_1D – self object for convenience

set_plot_style(x_max=None, y_min=0, title=None, xlabel='input line freq (cycles/mm)', ylabel='MTF', height=<Quantity 10. cm>, width=<Quantity 15. cm>)[source]

Sets some default style parameters for MTF plots.

Return type:

Self

Parameters:

  • x_max (float, optional) – max value of x axis, by default None

  • y_min (float, optional) – minimum value of y axis, by default 0

  • title (str, optional) – title of the plot, by default None

  • xlabel (str, optional) – x-axis label, by default “input line freq (cycles/mm)”

  • ylabel (str, optional) – y-axis label, by default “MTF”

  • height (int, optional) – height of the figure (in cm), by default 10

  • width (int, optional) – width of the figure (in cm), by default 15

Returns:

MTF_Plot_1D – self object for convenience