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).

nrefocus.get_best_interface()

Return the fastest refocusing interface available

If pyfftw is installed, nrefocus.RefocusPyFFTW is returned. The fallback is nrefocus.RefocusNumpy.

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

Refocusing with FFTW

New in version 0.4.0.

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 to perform boundary-padding with linear ramp

autofocus(interval, metric='average gradient', minimizer='lmfit', roi=None, minimizer_kwargs=None, ret_grid=False, ret_field=False)

Autofocus the initial field

Parameters

• interval (tuple of floats) – Approximate interval to search for optimal focus [m]

• metric (str) –

  • “average gradient” : average gradient metric of amplitude

  • ”rms contrast” : RMS contrast of phase data

  • ”spectrum” : sum of filtered Fourier coefficients

  • ”std gradient” : standard deviation of gradient of amplitude

  • ”med gradient” : median gradient metric of amplitude

• minimizer (str) –

  • “legacy”: custom nrefocus minimizer

  • ”lmfit”: lmfit-based minimizer (uses lmfit.minimize)

• roi (list or tuple or slice or ndarray) –

  Region of interest for which the metric will be minimized. The axes below use the numpy indexing order. Options are: list or tuple or numpy indexing array (old behaviour):

  [axis_0_start, axis_1_start, axis_0_end, axis_1_end] None can be used if no slicing is desired eg.: [None, None, axis_0_end, axis_1_end]

  list or tuple of slices (will be passed directly as is):

  (slice(axis_0_start, axis_0_end),

  slice(axis_1_start, axis_1_end))

  None

  The entire field will be used.

• minimizer_kwargs (dict) – Any additional keyword arguments for the minimizer

• ret_grid (bool) – return focus positions and metric values of the coarse grid search

• ret_field (bool) – return the optimal refocused field for user convenience

Returns

• af_distance (float) – Autofocusing distance

• (d_grid, metrid_grid) (ndarray) – Coarse grid search values (only if ret_grid is True)

• af_field (ndarray) – Autofocused field (only if ret_field is True)

• [other] – Any other objects returned by minimizer; may be definable via minimizer_kwargs (depends on minimizer)

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.RefocusNumpy(field, wavelength, pixel_size, medium_index=1.3333, distance=0, kernel='helmholtz', padding=True)

Refocusing with numpy-based Fourier transform

New in version 0.3.0.

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 to perform boundary-padding with linear ramp

autofocus(interval, metric='average gradient', minimizer='lmfit', roi=None, minimizer_kwargs=None, ret_grid=False, ret_field=False)

Autofocus the initial field

Parameters

• interval (tuple of floats) – Approximate interval to search for optimal focus [m]

• metric (str) –

  • “average gradient” : average gradient metric of amplitude

  • ”rms contrast” : RMS contrast of phase data

  • ”spectrum” : sum of filtered Fourier coefficients

  • ”std gradient” : standard deviation of gradient of amplitude

  • ”med gradient” : median gradient metric of amplitude

• minimizer (str) –

  • “legacy”: custom nrefocus minimizer

  • ”lmfit”: lmfit-based minimizer (uses lmfit.minimize)

• roi (list or tuple or slice or ndarray) –

  Region of interest for which the metric will be minimized. The axes below use the numpy indexing order. Options are: list or tuple or numpy indexing array (old behaviour):

  [axis_0_start, axis_1_start, axis_0_end, axis_1_end] None can be used if no slicing is desired eg.: [None, None, axis_0_end, axis_1_end]

  list or tuple of slices (will be passed directly as is):

  (slice(axis_0_start, axis_0_end),

  slice(axis_1_start, axis_1_end))

  None

  The entire field will be used.

• minimizer_kwargs (dict) – Any additional keyword arguments for the minimizer

• ret_grid (bool) – return focus positions and metric values of the coarse grid search

• ret_field (bool) – return the optimal refocused field for user convenience

Returns

• af_distance (float) – Autofocusing distance

• (d_grid, metrid_grid) (ndarray) – Coarse grid search values (only if ret_grid is True)

• af_field (ndarray) – Autofocused field (only if ret_field is True)

• [other] – Any other objects returned by minimizer; may be definable via minimizer_kwargs (depends on minimizer)

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

New in version 0.3.0.

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) – Wheter to perform boundary-padding with linear ramp

autofocus(interval, metric='average gradient', minimizer='lmfit', roi=None, minimizer_kwargs=None, ret_grid=False, ret_field=False)

Autofocus the initial field

Parameters

• interval (tuple of floats) – Approximate interval to search for optimal focus [m]

• metric (str) –

  • “average gradient” : average gradient metric of amplitude

  • ”rms contrast” : RMS contrast of phase data

  • ”spectrum” : sum of filtered Fourier coefficients

  • ”std gradient” : standard deviation of gradient of amplitude

  • ”med gradient” : median gradient metric of amplitude

• minimizer (str) –

  • “legacy”: custom nrefocus minimizer

  • ”lmfit”: lmfit-based minimizer (uses lmfit.minimize)

• roi (list or tuple or slice or ndarray) –

  Region of interest for which the metric will be minimized. The axes below use the numpy indexing order. Options are: list or tuple or numpy indexing array (old behaviour):

  [axis_0_start, axis_1_start, axis_0_end, axis_1_end] None can be used if no slicing is desired eg.: [None, None, axis_0_end, axis_1_end]

  list or tuple of slices (will be passed directly as is):

  (slice(axis_0_start, axis_0_end),

  slice(axis_1_start, axis_1_end))

  None

  The entire field will be used.

• minimizer_kwargs (dict) – Any additional keyword arguments for the minimizer

• ret_grid (bool) – return focus positions and metric values of the coarse grid search

• ret_field (bool) – return the optimal refocused field for user convenience

Returns

• af_distance (float) – Autofocusing distance

• (d_grid, metrid_grid) (ndarray) – Coarse grid search values (only if ret_grid is True)

• af_field (ndarray) – Autofocused field (only if ret_field is True)

• [other] – Any other objects returned by minimizer; may be definable via minimizer_kwargs (depends on minimizer)

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_med_gradient(rfi, distance, roi=None, **kwargs)

Compute median 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.metric_std_gradient(rfi, distance, roi=None, **kwargs)

Compute standard deviation (std) gradient of the amplitude

Notes

The absolute value of the gradient is returned.

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

Available metrics

Minimizers

nrefocus.minimizers.minimize_legacy(rf, metric_func, interval, roi=None, coarse_acc=1, fine_acc=0.005, ret_grid=False, ret_field=False)

Legacy minimizer

Find the focus by minimizing the metric of an image. This is the implementation of the legacy nrefocus minimizer.

Parameters

• rf (nrefocus.iface.Refocus) – Refocus interface

• metric_func (callable) – metric called during minimization. The metric should take the following arguments: rf, distance, and roi

• interval (tuple of floats) – (minimum, maximum) of interval to search [m]

• roi (tuple of slices or np.ndarray) – Region of interest for which the metric will be minimized. If not given, the entire field will be used.

• coarse_acc (float) – accuracy for determination of global minimum in pixels; coarse_acc=1 means that 100 fields are computed in the initial step; coarse_acc=0.5 means 200 fields are computed

• fine_acc (float) – accuracy for fine localization percentage of gradient change

• ret_grid (bool) – return focus positions and metric values of the coarse grid search

• ret_field (bool) – return the optimal refocused field for user convenience

Returns

• af_dist (float) – Autofocusing distance [m]

• (d_grid, metrid_grid) (ndarray) – Coarse grid search values (only if ret_grid is True)

• af_field (ndarray) – Autofocused field (only if ret_field is True)

nrefocus.minimizers.minimize_lmfit(rf, metric_func, interval, roi=None, lmfitkw=None, ret_grid=False, ret_field=False)

A minimizer that wraps lmfit

Find the focus by minimizing the metric of an image A coarse grid search over interval with step size of 2*rf.wavelength is performed, followed by a “regular” minimization for the best candidate.

Parameters

• rf (nrefocus.iface.Refocus) – Refocus interface

• metric_func (callable) – metric called during minimization. The metric should take the following arguments: rf, distance, and roi

• interval (tuple of floats) – (minimum, maximum) of interval to search [m]

• roi (tuple of slices or np.ndarray) – Region of interest for which the metric will be minimized. If not given, the entire field will be used.

• lmfitkw – Additional keyword arguments for lmfit.minimize used in the fine grid search. The default method is “leastsq”.

• ret_grid (bool) – return focus positions and metric values of the coarse grid search

• ret_field (bool) – return the optimal refocused field for user convenience

Returns

• af_dist (float) – Autofocusing distance [m]

• (d_grid, metrid_grid) (ndarray) – Coarse grid search values (only if ret_grid is True)

• af_field (ndarray) – Autofocused field (only if ret_field is True)

nrefocus.minimizers.MINIMIZERS = {'legacy': <function minimize_legacy>, 'lmfit': <function minimize_lmfit>}

Available minimizers

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.

Notes

This method uses nrefocus.RefocusNumpy for refocusing of 2D fields. This is because the nrefocus.refocus_stack() function uses async which appears to not work with e.g. pyfftw.

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', minimizer='lmfit', minimizer_kwargs=None, padding=True, 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

  • ”std gradient” : standard deviation of gradient metric of amplitude

  • ”med gradient” : median gradient metric of amplitude

• minimizer (str) –

  • “lmfit” : lmfit-based minimizer

  • ”legacy” : only use for reproducing old results

• minimizer_kwargs (dict) – Optional keyword arguments to the minimizer function

• 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

• num_cpus (int) – Not implemented.

Returns

The focusing distance, the field, and optionally any other data returned by the minimizer (specify via minimizer_kwargs).

Return type

d, field [, other]

Notes

This method uses nrefocus.RefocusNumpy for refocusing of 2D fields. This is because the nrefocus.refocus_stack() function uses async which appears to not work with e.g. pyfftw.

nrefocus.autofocus_stack(fieldstack, nm, res, ival, roi=None, metric='average gradient', minimizer='lmfit', minimizer_kwargs=None, padding=True, same_dist=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.

• minimizer (str) –

  • “lmfit” : lmfit-based minimizer

  • ”legacy” : only use for reproducing old results

• minimizer_kwargs (dict) – Optional keyword arguments to the minimizer function

• 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.

• num_cpus (int) – Number of CPUs to use

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

Returns

• dopt (float or list of float) – The focusing distance(s) (only one value if same_dist)

• field_stack (np.ndarray) – The refocused field stack