slmsuite.holography.algorithms.SpotHologram
- class SpotHologram(shape, spot_vectors, basis='knm', spot_amp=None, cameraslm=None, null_vectors=None, null_radius=None, null_region=None, null_region_radius_frac=None, subpixel=False, **kwargs)[source]
Bases:
FeedbackHologram
Holography optimized for the generation of optical focal arrays.
Is a subclass of
FeedbackHologram
, but falls back to non-camera-feedback routines ifcameraslm
is not passed.Tip
Quality of life features to generate noise regions for mixed region amplitude freedom (MRAF) algorithms are supported. Specifically, set
null_region
parameters to help specify where the noise region is not.- spot_knm, spot_kxy, spot_ij
Stored vectors with shape
(2, N)
in the style offormat_2vectors()
. These vectors are floats. The subscript refers to the basis of the vectors, the transformations between which are autocomputed. If necessary transformations do not exist,spot_ij
is set toNone
.- Type
array_like of float OR None
- spot_knm_rounded
spot_knm
rounded to nearest integers (indices). These vectors are integers. This is necessary because GS algorithms operate on a pixel grid, and the target for each spot in aSpotHologram
is a single pixel (index).- Type
array_like of int
- spot_kxy_rounded, spot_ij_rounded
Once
spot_knm_rounded
is rounded, the originalspot_kxy
andspot_ij
are no longer accurate. Transformations are again used to backcompute the positions in the"ij"
and"kxy"
bases corresponding to the true computational location of a given spot. These vectors are floats.- Type
array_like of float
- spot_amp
The target amplitude for each spot. Must have length corresponding to the number of spots. For instance, the user can request dimmer or brighter spots.
- Type
array_like of float
- external_spot_amp
When using
"external_spot"
feedback or the"external_spot"
stat group, the user must supply external data. This data is transferred through this attribute. For iterative feedback, have thecallback()
function setexternal_spot_amp
dynamically. By default, this variable is set to even distribution of amplitude.- Type
array_like of float
- spot_integration_width_knm
For spot-specific feedback methods, better SNR is achieved when integrating over many farfield pixels. This variable stores the width of the integration region in
"knm"
(farfield) space.- Type
int
- spot_integration_width_ij
For spot-specific feedback methods, better SNR is achieved when integrating over many camera pixels. This variable stores the width of the integration region in
"ij"
(camera) space.- Type
int
- null_knm
In addition to points where power is desired,
SpotHologram
is equipped with quality of life features to select points where power is undesired. These points are stored innull_knm
with shape(2, M)
in the style offormat_2vectors()
. A region around these points is set to zero (null) and not allowed to participate in the noise region.- Type
array_like of float OR None
- null_radius_knm
The radius in
"knm"
space around the pointsnull_knm
to zero or null (prevent from participating in thenan
noise region). This is useful to prevent power being deflected to very high orders, which are unlikely to be properly represented in practice on a physical SLM.- Type
float
- null_region_knm
Array of shape
shape
. WhereTrue
, sets the background to zero instead of nan. IfNone
, has no effect.- Type
array_like of bool OR
None
- subpixel_beamradius_knm
The radius in knm space corresponding to the beamradius of the Gaussian spot which is targeted when
subpixel
features are enabled. In the future, a non-Gaussian kernel might be used instead. This radius is computed based upon the stored amplitude in the SLM (if passed). This is an experimental feature and should be used with caution.- Type
float
Methods
GPU-accelerated Gerchberg-Saxton (GS) iterative phase retrieval.
Helper function to calculate the shape of the computational space.
Uses
write_h5()
to export the statistics hierarchy to a given h5 file.Collects the current complex farfield from the GPU with
cupy.ndarray.get()
.Collects the current nearfield phase from the GPU with
cupy.ndarray.get()
.Helper function to get the cupy memory pool size.
Convert an image in the camera domain to computational SLM k-space using, in part, the affine transformation stored in a cameraslm's Fourier calibration.
Uses
write_h5()
to import the statistics hierarchy from a given h5 file.Helper function to initialize a rectangular 2D array of spots, with certain size and pitch.
Method to request a measurement to occur.
Optimizers to solve the "phase problem": approximating the near-field phase that transforms a known near-field source amplitude to a desired far-field target amplitude.
Plots an overview (left) and zoom (right) view of
source
.Plots the amplitude (left) and phase (right) of the nearfield (plane of the SLM).
Plots the statistics contained in the given dictionary.
Hones the positions of the produced spots toward the desired targets to compensate for Fourier calibration imperfections.
Resets the hologram to an initial state.
Resets the hologram to a random state or to a provided phase.
Resets the hologram weights to the
target
defaults.Helper function to set the cupy memory pool size.
Calculate statistics corresponding to the desired
stat_groups
.From the spot locations stored in
spot_knm
, update the target pattern.- __init__(shape, spot_vectors, basis='knm', spot_amp=None, cameraslm=None, null_vectors=None, null_radius=None, null_region=None, null_region_radius_frac=None, subpixel=False, **kwargs)[source]
Initializes a
SpotHologram
targeting given spots atspot_vectors
.- Parameters
shape ((int, int)) – Computational shape of the SLM. See
Hologram.__init__()
.spot_vectors (array_like) – Spot position vectors with shape
(2, N)
in the style offormat_2vectors()
.basis (str) –
The spots can be in any of the following bases:
"ij"
for camera coordinates (pixels),"kxy"
for centered normalized SLM k-space (radians)."knm"
for computational SLM k-space (pixels).
Defaults to
"knm"
ifNone
.spot_amp (array_like OR None) – The amplitude to target for each spot. See
SpotHologram.spot_amp
. IfNone
, all spots are assumed to have the same amplitude. Normalization is performed automatically; the user is not required to normalize.cameraslm (slmsuite.hardware.cameraslms.FourierSLM OR None) – If the
"ij"
basis is chosen, and/or if the user wants to make use of camera feedback, a cameraslm must be provided.null_vectors (array_like OR None) – Null position vectors with shape
(2, N)
in the style offormat_2vectors()
. MRAF methods are forced zero around these points.null_radius (float OR None) – Radius to null around in the given
basis
. Note that basis conversions are imperfect for anisotropic basis transformations. The radius will always be set to be circular in"knm"
space, and will attempt to match to the closest circle to the (potentially elliptical) projection into"knm"
from the givenbasis
.null_region (array_like OR None) – Array of shape
shape
. WhereTrue
, sets the background to zero instead of nan. IfNone
, has no effect.null_region_radius_frac (float OR None) – Helper function to set the
null_region
to zero for Fourier space radius fractions abovenull_region_radius_frac
. This is useful to prevent power being deflected to very high orders, which are unlikely to be properly represented in practice on a physical SLM.subpixel (bool) –
If enabled, the
target
is set to a series of Gaussian spots with radiussubpixel_beamradius_knm
instead of a series of single pixel spots (the default forSpotHologram
). The major benefit here is:Greater resolution with limited padding. With 2-3 orders of padding, the farfield has sufficient resolution to render a Gaussian positioned inbetween farfield pixels, allowing for greater resolutions without having to pad further. This is especially important when operating at the memory limits of a system.
Defaults to
False
. This is an experimental feature and should be used with caution. Currently, there are issues with the initial phase causing some spots to be permanently attenuated.**kwargs – Passed to
FeedbackHologram.__init__()
.
- GS(iterations, callback)[source]
GPU-accelerated Gerchberg-Saxton (GS) iterative phase retrieval.
Solves the “phase problem”: approximates the near-field phase that transforms a known near-field source amplitude to a desired far-field target amplitude.
Caution
This function should be called through
optimize()
and not called directly. It is left as a public function exposed in documentation to clarify how the internals ofoptimize()
work.Note
FFTs are not in-place in this algorithm. In both non-
cupy
andcupy
implementations,numpy.fft
does not support in-place operations. However,scipy.fft
does in both. In the future, we may move to the scipy implementation. However, neithernumpy
orscipy
fftshift
support in-place movement (for obvious reasons). For even faster computation, algorithms should consider not shifting the FFT result, and instead shifting measurement data / etc to this unshifted basis. We might also implement get_fft_plan for even faster FFTing.- Parameters
iterations (iterable) – Number of loop iterations to run. Is an iterable to pass a
tqdm
iterable.callback (callable OR None) – See
optimize()
.
- static calculate_padded_shape(slm_shape, padding_order=1, square_padding=True, precision=inf, precision_basis='kxy')[source]
Helper function to calculate the shape of the computational space. For a given base
slm_shape
, pads to the user’s requirements. If the user chooses multiple requirements, the largest dimensions for the shape are selected. By default, pads to the smallest square power of two that encapsulates the originalslm_shape
.Tip
See also the first tip in the constructor of
Hologram
for more information about the importance of padding.Note
Under development: a parameter to pad based on available memory (see
_calculate_memory_constrained_shape()
).- Parameters
slm_shape ((int, int) OR slmsuite.hardware.FourierSLM) – The original shape of the SLM in
numpy
(h, w) form. The user can pass aslmsuite.hardware.FourierSLM
instead, and should pass this when using theprecision
parameter.padding_order (int) – Scales to the
padding_order
th larger power of 2. Apadding_order
of zero does nothing. For instance, an SLM with shape(720, 1280)
would yield(720, 1280)
forpadding_order=0
,(1024, 2048)
forpadding_order=1
, and(2048, 4096)
forpadding_order=2
.square_padding (bool) – If
True
, sets the smaller shape dimension to that of the larger, yielding a square.precision (float) – Returns the shape that produces a computational k-space with resolution smaller than
precision
. The default, infinity, requests a padded shape larger than zero, sopadding_order
will dominate.precision_basis (str) – Basis for the precision. Can be
"ij"
(camera) or"kxy"
(normalized blaze).
- Returns
Shape of the computational space which satisfies the above requirements.
- Return type
(int, int)
- export_stats(file_path, include_state=True)[source]
Uses
write_h5()
to export the statistics hierarchy to a given h5 file.- Parameters
file_path (str) – Full path to the file to read the data from.
include_state (bool) – If
True
, also includes all other attributes ofHologram
except fordtype
(cannot pickle) andamp_ff
(can regenerate). These attributes are converted tonumpy
if necessary. Note that the intent is not to produce a runnableHologram
by default (as this would require pickling hardware interfaces), but rather to provide extra information for debugging.
- extract_farfield()[source]
Collects the current complex farfield from the GPU with
cupy.ndarray.get()
.- Returns
Current farfield computed by GS.
- Return type
numpy.ndarray
- extract_phase()[source]
Collects the current nearfield phase from the GPU with
cupy.ndarray.get()
. Also shifts the \([-\pi, \pi]\) range ofnumpy.arctan2()
to \([0, 2\pi]\) for faster writing to the SLM (seewrite()
).- Returns
Current nearfield phase computed by GS.
- Return type
numpy.ndarray
- static get_mempool_limit(device=0)[source]
Helper function to get the cupy memory pool size.
- Parameters
device (int) – Which GPU to set the limit on. Passed to
cupy.cuda.Device()
.- Returns
Current memory pool limit in bytes
- Return type
int
- ijcam_to_knmslm(img, out=None, blur_ij=None, order=3)[source]
Convert an image in the camera domain to computational SLM k-space using, in part, the affine transformation stored in a cameraslm’s Fourier calibration.
Note
This includes two transformations:
The affine transformation
"ij"
->"kxy"
(camera pixels to normalized k-space).The scaling
"kxy"
->"knm"
(normalized k-space to computational k-space pixels).
- Parameters
img (numpy.ndarray OR cupy.ndarray) – Image to transform. This should be the same shape as images returned by the camera.
out (numpy.ndarray OR cupy.ndarray OR None) – If
out
is notNone
, this array will be used to write the memory in-place.blur_ij (int OR None) – Applies a
blur_ij
pixel-width Gaussian blur toimg
. IfNone
, defaults to the"blur_ij"
flag if present; otherwise zero.order (int) – Order of interpolation used for transformation. Defaults to 3 (cubic).
- Returns
Image transformed into
"knm"
space.- Return type
numpy.ndarray OR cupy.ndarray
- import_stats(file_path, include_state=True)[source]
Uses
write_h5()
to import the statistics hierarchy from a given h5 file.Tip
Enabling the
"raw_stats"
flag will export feedback data from each iteration instead of only derived statistics. Consider enabling this to save more detailed information upon export.- Parameters
file_path (str) – Full path to the file to read the data from.
include_state (bool) – If
True
, also overwrite all other attributes ofHologram
except fordtype
andamp_ff
.
- measure(basis='ij')[source]
Method to request a measurement to occur. If
img_ij
isNone
, then a new image will be grabbed from the camera (this is done automatically in algorithms).- Parameters
basis (str) –
The cached image to be sure to fill with new data. Can be
"ij"
or"knm"
.If
"knm"
, thenimg_ij
andimg_knm
are filled.If
"ij"
, thenimg_ij
is filled, andimg_knm
is ignored.
This is useful to avoid (expensive) transformation from the
"ij"
to the"knm"
basis ifimg_knm
is not needed.
- optimize(method='GS', maxiter=20, verbose=True, callback=None, feedback=None, stat_groups=[], **kwargs)[source]
Optimizers to solve the “phase problem”: approximating the near-field phase that transforms a known near-field source amplitude to a desired far-field target amplitude. Supported optimization methods include:
Gerchberg-Saxton (GS) phase retrieval.
'GS'
An iterative algorithm for phase retrieval, accomplished by moving back and forth between the imaging and Fourier domains, with amplitude corrections applied to each. This is implemented using fast Fourier transforms, potentially GPU-accelerated.
Weighted Gerchberg-Saxton (WGS) phase retrieval algorithms of various flavors. Improves the uniformity of GS-computed focus arrays using weighting methods and techniques from literature. The
method
keywords are:'WGS-Leonardo'
The original WGS algorithm. Weights the target amplitudes by the ratio of mean amplitude to computed amplitude, which amplifies weak spots while attenuating strong spots. Uses the following weighting function:
\[\mathcal{W} = \mathcal{W}\left(\frac{\mathcal{T}}{\mathcal{F}}\right)^p\]where \(\mathcal{W}\), \(\mathcal{T}\), and \(\mathcal{F}\) are the weight amplitudes, target (goal) amplitudes, and feedback (measured) amplitudes, and \(p\) is the power passed as
"feedback_exponent"
inflags
(seekwargs
). The power \(p\) defaults to .9 if not passed. In general, smaller \(p\) will lead to slower yet more stable optimization.'WGS-Kim'
Improves the convergence of
WGS-Leonardo
by fixing the far-field phase strictly after a desired number of net iterations specified by"fix_phase_iteration"
or after exceeding a desired efficiency (fraction of far-field energy at the desired points) specified by"fix_phase_efficiency"
'WGS-Nogrette'
Weights target intensities by a tunable gain factor.
\[\mathcal{W} = \mathcal{W}/\left(1 - f\left(1 - \mathcal{F}/\mathcal{T}\right)\right)\]where \(f\) is the gain factor passed as
"feedback_factor"
inflags
(seekwargs
). The factor \(f\) defaults to .1 if not passed.Note that while Nogrette et al compares powers, this implementation compares amplitudes for speed. These are identical to first order.
The option for Mixed Region Amplitude Freedom (MRAF) feedback. In standard iterative algorithms, the entire Fourier-domain unpatterned field is replaced with zeros. This is disadvantageous because a desired farfield pattern might not be especially compatible with a given nearfield amplitude, or otherwise. MRAF enables “noise regions” where some fraction of the given farfield is not replaced with zeros and instead is allowed to vary. In practice, MRAF is enabled by setting parts of the
target
tonan
; these regions act as the noise regions. The"mraf_factor"
flag inflags
allows the user to partially attenuate the noise regions. A factor of 0 fully attenuates the noise region (normal WGS behavior). A factor of 1 does not attenuate the noise region at all (the default). Middle ground is recommended, but is application-dependent as a tradeoff between improving pattern fidelity and maintaining pattern efficiency.As examples, consider two cases where MRAF can be useful:
Sloping a top hat. Suppose we want very flat amplitude on a beam. Requesting a sharp edge to this beam can lead to fringing effects at the boundary which mitigate flatness both inside and outside the beam. If instead a noise region is defined in a band surrounding the beam, the noise region will be filled with whatever slope best enables the desired flat beam.
Mitigating diffractive orders. Without MRAF, spot patterns with high crystallinity often have “ghost” diffractive orders which continue the pattern past the edges of requested spots. Even though these orders are attenuated during each phase retrieval iteration, they remain part of the best solution for the recovered phase. With MRAF, a noise region can help solve for retrieved phase which does not generate these undesired orders.
Caution
Requesting
stat_groups
will slow the speed of optimization due to the overhead of processing and saving statistics, especially in the case of GPU-accelerated optimization where significant time cost is incurred by moving these statistics to the CPU. This is especially apparent in the case of fully-computational holography, where this effect can slow what is otherwise a fully-GPU-contained loop by an order magnitude.Tip
This function uses a parameter naming convention borrowed from
scipy.optimize.minimize()
and other functions inscipy.optimize
. The parametersmethod
,maxiter
, andcallback
have the same functionality as the equivalently-named parameters inscipy.optimize.minimize()
.- Parameters
method (str) – Optimization method to use. See the list of optimization methods above.
maxiter (int) – Number of iterations to optimize before terminating.
verbose (bool OR int) – Whether to display
tqdm
progress bars. These bars are also not displayed formaxiter <= 1
. Ifverbose
is greater than 1, then flags are printed as a preamble.callback (callable OR None) – Same functionality as the equivalently-named parameter in
scipy.optimize.minimize()
.callback
must accept a Hologram or Hologram subclass as the single argument. Ifcallback
returnsTrue
, then the optimization exits. Ignored ifNone
.feedback (str OR None) –
Type of feedback to use during optimization, for instance when weighting in
"WGS"
. For direct instances ofHologram
, this can only be"computational"
feedback. Subclasses support more types of feedback. Supported feedback options include the following:"computational"
Uses the the projected farfield pattern (transform of the complex nearfield) as feedback."experimental"
Uses a camera contained in a passedcameraslm
as feedback. Specific to subclasses ofFeedbackHologram
."computational_spot"
Takes the computational result (the projected farfield pattern) and integrates regions around the expected positions of spots in an optical focus array. More stable than"computational"
for spots. Specific to subclasses ofSpotHologram
."experimental_spot"
Takes the experimental result (the image from a camera) and integrates regions around the expected positions of spots in an optical focus array. More stable than"experimental"
for spots. Specific to subclasses ofSpotHologram
."external_spot"
Uses some external user-provided metric for spot feedback. Seeexternal_spot_amp
. Specific to subclasses ofSpotHologram
.
stat_groups (list of str OR None) – Strings representing types of feedback (data gathering) upon which statistics should be derived. These strings correspond to valid types of feedback (see above). For instance, if
"experimental"
is passed as a stat group, statistics on the pixels in the experimental feedback image will automatically be computed and stored for each iteration of optimization. However, this comes with overhead (see above warning).**kwargs (dict, optional) – Various weight keywords and values to pass depending on the weight method. These are passed into
flags
. See options documented in the constructor.
- plot_farfield(source=None, title='', limits=None, units='knm', limit_padding=0.1, figsize=(8, 4), cbar=False)[source]
Plots an overview (left) and zoom (right) view of
source
.- Parameters
source (array_like OR None) – Should have shape equal to
shape
. IfNone
, defaults toamp_ff
.title (str) – Title of the plots. If
"phase"
is a substring of title, then the source is treated as a phase.limits (((float, float), (float, float)) OR None) – \(x\) and \(y\) limits for the zoom plot in
"knm"
space. If None,limits
are autocomputed as the smallest bounds that show all non-zero values (pluslimit_padding
). Note that autocomputing ontarget
will perform well, as zero values are set to actually be zero. However, doing so on computational or experimental outputs (e.g.amp_ff
) will likely perform poorly, as values in the field deviate slightly from zero and artificially expand thelimits
.units (str) – Far-field units for plots (see
convert_blaze_vector()
for options). If units requiring a SLM are desired, the attributecameraslm
must be filled.limit_padding (float) – Fraction of the width and height to expand the limits of the zoom plot by, only if the passed
limits
isNone
(autocompute).figsize (tuple) – Size of the plot.
cbar (bool) – Whether to add colorbars to the plots. Defaults to
False
.
- Returns
Used
limits
, which may be autocomputed. Autocomputed limits are returned as integers.- Return type
((float, float), (float, float))
- plot_nearfield(title='', padded=False, figsize=(8, 4), cbar=False)[source]
Plots the amplitude (left) and phase (right) of the nearfield (plane of the SLM). The amplitude is assumed (whether uniform, or experimentally computed) while the phase is the result of optimization.
- Parameters
title (str) – Title of the plots.
padded (bool) – If
True
, shows the full computational nearfield of shapeshape
. Otherwise, shows the region at the center of the computational space of sizeslm_shape
corresponding to the unpadded SLM.figsize (tuple) – Size of the plot.
cbar (bool) – Whether to add colorbars to the plots. Defaults to
False
.
- plot_stats(stats_dict=None, stat_groups=[], ylim=None)[source]
Plots the statistics contained in the given dictionary.
- Parameters
stats_dict (dict OR None) – Stats to plot in dictionary form. If
None
, defaults tostats
.stat_groups (list of str OR None) – Which
ylim ((int, int) OR None) – Allows the user to pass in desired y limits. If
None
, the default y limits are used.
- reset(reset_phase=True, reset_flags=False)[source]
Resets the hologram to an initial state. Does not restore the preconditioned
phase
that may have been passed to the constructor (as this information is lost upon optimization). Also uses the currenttarget
rather than thetarget
that may have been passed to the constructor (e.g. includes currentrefine_offset()
changes, etc).- Parameters
reset_phase (bool) – Whether to additionally call
reset_phase()
.reset_flags (bool:) – Whether to erase the information (including passed
kwargs
) stored inflags
.
- reset_phase(phase=None)[source]
Resets the hologram to a random state or to a provided phase.
- Parameters
phase (array_like OR None) – The near-field initial phase. See
phase
.phase
should only be passed if the user wants to precondition the optimization. Of shapeslm_shape
.
- static set_mempool_limit(device=0, size=None, fraction=None)[source]
Helper function to set the cupy memory pool size.
- Parameters
device (int) – Which GPU to set the limit on. Passed to
cupy.cuda.Device()
.size (int) – Desired number of bytes in the pool. Passed to
cupy.cuda.MemoryPool.set_limit()
.fraction (float) – Fraction of available memory to use. Passed to
cupy.cuda.MemoryPool.set_limit()
.
- static make_rectangular_array(shape, array_shape, array_pitch, array_center=None, basis='knm', orientation_check=False, **kwargs)[source]
Helper function to initialize a rectangular 2D array of spots, with certain size and pitch.
Note
The array can be in SLM k-space coordinates or in camera pixel coordinates, depending upon the choice of
basis
. For the"ij"
basis,cameraslm
must be included as one of thekwargs
. See__init__()
for morebasis
information.Important
Spot positions will be rounded to the grid of computational k-space
"knm"
, to create the target image (of finite size) that algorithms optimize towards. Choosearray_pitch
andarray_center
carefully to avoid undesired pitch non-uniformity caused by this rounding.- Parameters
shape ((int, int)) – Computational shape of the SLM in
numpy
(h, w) form. SeeSpotHologram.__init__()
.array_shape ((int, int) OR int) – The size of the rectangular array in number of spots
(NX, NY)
. If a scalar N is given, assume(N, N)
.array_pitch ((float, float) OR float) – The spacing between spots in the x and y directions
(pitchx, pitchy)
. If a single pitch is given, assume(pitch, pitch)
.array_center ((float, float) OR None) –
The shift of the center of the spot array from the zeroth order. Uses
(x, y)
form in the chosen basis. IfNone
, defaults to the position of the zeroth order, converted into the relevant basis:If
"knm"
, this is(shape[1], shape[0])/2
.If
"kxy"
, this is(0,0)
.If
"ij"
, this is the pixel position of the zeroth order on the camera (calculated via Fourier calibration).
basis (str) – See
__init__()
.orientation_check (bool) – Whether to delete the last two points to check for parity.
**kwargs – Any other arguments are passed to
__init__()
.
- update_target(reset_weights=False, plot=False)[source]
From the spot locations stored in
spot_knm
, update the target pattern.Note
If there’s a cameraslm, updates the
spot_ij_rounded
attribute corresponding to where pixels in the k-space where actually placed (due to rounding to integers, stored inspot_knm_rounded
), rather the idealized floatsspot_knm
.Note
The
target
andweights
matrices are modified in-place for speed, unlikeHologram
orFeedbackHologram
which make new matrices. This is because spot positions are expected to be corrected usingcorrect_spots()
.- Parameters
reset_weights (bool) – Whether to rest the
weights
to this newtarget
.plot (bool) – Whether to enable debug plotting to see the positions of the spots relative to the shape of the camera and slm.
- refine_offset(img=None, basis='kxy', force_affine=True, plot=False)[source]
Hones the positions of the produced spots toward the desired targets to compensate for Fourier calibration imperfections. Works either by moving camera integration regions to the positions where the spots ended up (
basis="ij"
) or by moving the \(k\)-space targets to target the desired camera pixels (basis="knm"
/basis="kxy"
). This should be run at the user’s request inbetweenoptimize()
iterations.- Parameters
img (numpy.ndarray OR None) – Image measured by the camera. If
None
, defaults toimg_ij
viameasure()
.basis (str) –
The correction can be in any of the following bases:
"ij"
changes the pixel that the spot is expected at,"kxy"
,"knm"
changes the k-vector which the SLM targets.
Defaults to
"kxy"
. If basis is set toNone
, no correction is applied to the data in theSpotHologram
.force_affine (bool) – Whether to force the offset refinement to behave as an affine transformation between the original and refined coordinate system. This helps to tame outliers. Defaults to
True
.plot (bool) – Enables debug plots.
- Returns
Spot shift in the
"ij"
basis for each spot.- Return type
numpy.ndarray