Code reference

Refocus interface

Refocus is a user-convenient interface for numerical refocusing. Each class implements refocusing for a specific dimensionality (1D or 2D fields) using a specific method for refocusing (e.g. numpy FFT or FFTW).

class nrefocus.RefocusNumpy(field, wavelength, pixel_size, medium_index=1.3333, distance=0, kernel='helmholtz', padding=True)

Refocusing with numpy-based Fourier transform

Parameters

• field (2d complex-valued ndarray) – Input field to be refocused

• wavelength (float) – Wavelength of the used light [m]

• pixel_size (float) – Pixel size of the input image [m]

• medium_index (float) – Refractive index of the medium, defaults to water (1.3333 at 21.5°C)

• distance (float) – Initial focusing distance [m]

• kernel (str) –

  Propagation kernel, one of

  • ”helmholtz”: the optical transfer function \(\exp\left(id\left(\sqrt{k_\mathrm{m}^2 - k_\mathrm{x}^2 - k_\mathrm{y}^2} - k_\mathrm{m}\right)\right)\)

  • ”fresnel”: paraxial approximation \(\exp(-id(k_\mathrm{x}^2+k_\mathrm{y}^2)/2k_\mathrm{m})\)

• padding (bool) – Whether or not to perform zero-padding

autofocus(metric='average gradient', minimizer='legacy', interval=(None, None), roi=None, minimizer_kwargs=None)

Autofocus the initial field

Parameters

• metric (str) –

  • “average gradient” : average gradient metric of amplitude

  • ”rms contrast” : RMS contrast of phase data

  • ”spectrum” : sum of filtered Fourier coefficients

• minimizer (str) –

  • “legacy”: custom nrefocus minimizer

• interval (tuple of floats) – Approximate interval to search for optimal focus in px.

• roi (rectangular region of interest (x1, y1, x2, y2)) – Region of interest of field for which the metric will be minimized. If not given, the entire field will be used.

Returns

• af_field (2d ndarray) – Autofocused field

• af_distance (float) – Autofocusing distance

get_kernel(distance)

Return the current kernel

Ther kernel type self.kernel is used (see Refocus.__init__())

propagate(distance)

Propagate the initial field to a certain distance

Parameters

distance (float) – Absolute focusing distance [m]

Returns

refocused_field – Initial field refocused at distance

Return type

2d ndarray

Notes

Any subclass should perform padding with nrefocus.pad.pad_rem() during initialization.

property shape

Shape of the padded input field or Fourier transform

class nrefocus.RefocusNumpy1D(field, wavelength, pixel_size, medium_index=1.3333, distance=0, kernel='helmholtz', padding=True)

Refocus a 1D field with numpy

Parameters

• field (1d complex-valued ndarray) – Input 1D field to be refocused

• wavelength (float) – Wavelength of the used light [m]

• pixel_size (float) – Pixel size of the input image [m]

• medium_index (float) – Refractive index of the medium, defaults to water (1.3333 at 21.5°C)

• distance (float) – Initial focusing distance [m]

• kernel (str) –

  Propagation kernel, one of

  • ”helmholtz”: the optical transfer function \(\exp\left(id\left(\sqrt{k_\mathrm{m}^2 - k_\mathrm{x}^2} - k_\mathrm{m}\right)\right)\)

  • ”fresnel”: paraxial approximation \(\exp(-idk_\mathrm{x}^2/2k_\mathrm{m})\)

• padding (bool) – Whether or not to perform zero-padding

autofocus(metric='average gradient', minimizer='legacy', interval=(None, None), roi=None, minimizer_kwargs=None)

Autofocus the initial field

Parameters

• metric (str) –

  • “average gradient” : average gradient metric of amplitude

  • ”rms contrast” : RMS contrast of phase data

  • ”spectrum” : sum of filtered Fourier coefficients

• minimizer (str) –

  • “legacy”: custom nrefocus minimizer

• interval (tuple of floats) – Approximate interval to search for optimal focus in px.

• roi (rectangular region of interest (x1, y1, x2, y2)) – Region of interest of field for which the metric will be minimized. If not given, the entire field will be used.

Returns

• af_field (2d ndarray) – Autofocused field

• af_distance (float) – Autofocusing distance

get_kernel(distance)

Return the kernel for a 1D propagation

propagate(distance)

Propagate the initial field to a certain distance

Parameters

distance (float) – Absolute focusing distance [m]

Returns

refocused_field – Initial 1D field refocused at distance

Return type

1d ndarray

property shape

Shape of the padded input field or Fourier transform

Metrics

nrefocus.metrics.metric_average_gradient(rfi, distance, roi=None, *kwargs)

Compute mean average gradient norm of the amplitude

Notes

The absolute value of the gradient is returned.

nrefocus.metrics.metric_rms_contrast(rfi, distance, roi=None, *kwargs)

Compute RMS contrast of the phase

Notes

The negative angle of the field is used for contrast estimation.

nrefocus.metrics.metric_spectrum(rfi, distance, roi=None, **kwargs)

Compute spectral contrast

Performs bandpass filtering in Fourier space according to optical limit of detection system, approximated by twice the wavelength.

nrefocus.metrics.METRICS = {'average gradient': <function metric_average_gradient>, 'rms contrast': <function metric_rms_contrast>, 'spectrum': <function metric_spectrum>}

Available metrics

Legacy methods

These methods are legacy functions which are kept for backwards-compatibility.

Refocusing

nrefocus.refocus(field, d, nm, res, method='helmholtz', padding=True)

Refocus a 1D or 2D field

Parameters

• field (1d or 2d array) – 1D or 2D background corrected electric field (Ex/BEx)

• d (float) – Distance to be propagated in pixels (negative for backwards)

• nm (float) – Refractive index of medium

• res (float) – Wavelenth in pixels

• method (str) –

  Defines the method of propagation; one of

  • ”helmholtz” : the optical transfer function exp(idkₘ(M-1))

  • ”fresnel” : paraxial approximation exp(idk²/kₘ)

• padding (bool) –

  perform padding with linear ramp from edge to average to reduce ringing artifacts.

  New in version 0.1.4.

Returns

Return type

Electric field at d.

nrefocus.refocus_stack(fieldstack, d, nm, res, method='helmholtz', num_cpus=2, copy=True, padding=True)

Refocus a stack of 1D or 2D fields

Parameters

• fieldstack (2d or 3d array) – Stack of 1D or 2D background corrected electric fields (Ex/BEx). The first axis iterates through the individual fields.

• d (float) – Distance to be propagated in pixels (negative for backwards)

• nm (float) – Refractive index of medium

• res (float) – Wavelenth in pixels

• method (str) –

  Defines the method of propagation; one of

  • ”helmholtz” : the optical transfer function exp(idkₘ(M-1))

  • ”fresnel” : paraxial approximation exp(idk²/kₘ)

• num_cpus (int) – Defines the number of CPUs to be used for refocusing.

• copy (bool) – If False, overwrites input stack.

• padding (bool) –

  Perform padding with linear ramp from edge to average to reduce ringing artifacts.

  New in version 0.1.4.

Returns

Return type

Electric field stack at d.

Autofocusing

nrefocus.autofocus(field, nm, res, ival, roi=None, metric='average gradient', padding=True, ret_d=False, ret_grad=False, num_cpus=1)

Numerical autofocusing of a field using the Helmholtz equation.

Parameters

• field (1d or 2d ndarray) – Electric field is BG-Corrected, i.e. field = EX/BEx

• nm (float) – Refractive index of medium.

• res (float) – Size of wavelength in pixels.

• ival (tuple of floats) – Approximate interval to search for optimal focus in px.

• roi (rectangular region of interest (x1, y1, x2, y2)) – Region of interest of field for which the metric will be minimized. If not given, the entire field will be used.

• metric (str) –

  • “average gradient” : average gradient metric of amplitude

  • ”rms contrast” : RMS contrast of phase data

  • ”spectrum” : sum of filtered Fourier coefficients

• padding (bool) –

  Perform padding with linear ramp from edge to average to reduce ringing artifacts.

  Changed in version 0.1.4: improved padding value and padding location

• ret_d (bool) – Return the autofocusing distance in pixels. Defaults to False.

• ret_grad (bool) – Return the computed gradients as a list.

• num_cpus (int) – Not implemented.

Returns

• field, [d, [grad]]

• The focused field and optionally, the optimal focusing distance and

• the computed gradients.

nrefocus.autofocus_stack(fieldstack, nm, res, ival, roi=None, metric='average gradient', padding=True, same_dist=False, ret_ds=False, ret_grads=False, num_cpus=2, copy=True)

Numerical autofocusing of a stack using the Helmholtz equation.

Parameters

• fieldstack (2d or 3d ndarray) – Electric field is BG-Corrected, i.e. Field = EX/BEx

• nm (float) – Refractive index of medium.

• res (float) – Size of wavelength in pixels.

• ival (tuple of floats) – Approximate interval to search for optimal focus in px.

• roi (rectangular region of interest (x1, y1, x2, y2)) – Region of interest of field for which the metric will be minimized. If not given, the entire field will be used.

• metric (str) – see autofocus_field.

• padding (bool) –

  Perform padding with linear ramp from edge to average to reduce ringing artifacts.

  Changed in version 0.1.4: improved padding value and padding location

• same_dist (bool) – Refocus entire sinogram with one distance.

• ret_ds (bool) – Return the autofocusing distances in pixels. Defaults to False. If sam_dist is True, still returns autofocusing distances of first pass. The used refocusing distance is the average.

• ret_grads (bool) – Return the computed gradients as a list.

• num_cpus (int) – Number of CPUs to use

• copy (bool) – If False, overwrites input array.

Returns

Return type

The focused field (and the refocussing distance + data if d is None)