slmsuite.hardware.cameraslms.FourierSLM

class FourierSLM(*args, **kwargs)[source]

Bases: CameraSLM

Class for an SLM and camera separated by a Fourier transform. This class includes methods for Fourier space and wavefront calibration.

fourier_calibration

Information for the affine transformation that maps between the k-space of the SLM (kxy) and the pixel-space of the camera (ij). See fourier_calibrate(). In the future, including pincushion or other distortions might be implemented using scipy.ndimage.spline_filter(), though this mapping would be separable.

Type: dict or None

wavefront_calibration_raw

Raw data for wavefront calibration, which corrects for aberrations in the optical system (phase_correction) and measures the amplitude distribution of power on the SLM (measured_amplitude). See wavefront_calibrate().

Type: dict or None

Methods

`fourier_calibrate`	Project and fit a SLM Fourier space (`"knm"`) grid onto camera pixel space (`"ij"`) for affine fitting.
`get_farfield_spot_size`	Calculates the size of a spot produced by blazed patch of size `slm_size` on the SLM.
`ijcam_to_kxyslm`	Converts camera pixel space (`"ij"`) to SLM Fourier space (`"kxy"`).
`kxyslm_to_ijcam`	Converts SLM Fourier space (`"kxy"`) to camera pixel space (`"ij"`).
`load_fourier_calibration`	Loads `fourier_calibration` from a file.
`load_wavefront_calibration`	Loads `wavefront_calibration_raw` from a file.
`measure_settle`	(NotImplemented) Approximates the :math`1/e` settle time of the SLM.
`name_fourier_calibration`	Creates `"<cam.name>-<slm.name>-fourier-calibration"`.
`name_wavefront_calibration`	Creates `"<cam.name>-<slm.name>-wavefront-calibration"`.
`process_wavefront_calibration`	Processes `wavefront_calibration_raw` into the desired phase correction and amplitude measurement.
`project_fourier_grid`	Projects a Fourier space grid (`"knm"`) onto pixel space (`"ij"`).
`save_fourier_calibration`	Saves `fourier_calibration` to a file like `"path/name_id.h5"`.
`save_wavefront_calibration`	Saves `wavefront_calibration_raw` to a file like `"path/name_id.h5"`.
`wavefront_calibrate`	Perform wavefront calibration.

__init__(*args, **kwargs)[source]: See CameraSLM.__init__.

measure_settle(vector=(0.1, 0.1), basis='kxy', size=None, times=None, settle_time_s=1, plot=True)[source]

(NotImplemented) Approximates the :math`1/e` settle time of the SLM. This is done by successively removing and applying a blaze to the SLM, measuring the intensity at the first order spot versus time.

Parameters

vector (array_like) – Point to TODO
basis ({"ij", "kxy"}) – Basis of vector. This is the vector TODO
size (int) – Size in pixels of the integration region. If None, sets to sixteen times the approximate size of a diffraction limited spot.
times (array_like) – List of times to sweep over in search of the \(1/e\) settle time.
settle_time_s (float) – Time inbetween measurements to allow the SLM to re-settle without
plot (bool) – Whether to print debug plots.

fourier_calibrate(array_shape=10, array_pitch=10, array_center=None, plot=False, autofocus=False, autoexposure=False, **kwargs)[source]

Project and fit a SLM Fourier space ("knm") grid onto camera pixel space ("ij") for affine fitting. Sets fourier_calibration. An array produced by make_rectangular_array() is projected for analysis by blob_array_detect().

Important

For best results, array_pitch should be integer data. Otherwise non-uniform rounding to the SLM’s computational \(k\)-space will result in non-uniform pitch and a bad fit.

Parameters

array_shape – Passed to make_rectangular_array() in the "knm" basis.
array_pitch – Passed to make_rectangular_array() in the "knm" basis.
array_center – Passed to make_rectangular_array() in the "knm" basis. array_center is not passed directly, and is processed as being relative to the center of "knm" space, the position of the 0th order.
plot (bool) – Enables debug plots.
autofocus (bool OR dict) – Whether or not to autofocus the camera. If a dictionary is passed, autofocus is performed, and the dictionary is passed to autofocus().
autoexpose (bool OR dict) – Whether or not to automatically set the camera exposure. If a dictionary is passed, autoexposure is performed, and the dictionary is passed to autoexposure().
**kwargs (dict) – Passed to project_fourier_grid().

Returns

fourier_calibration

Return type

dict

name_fourier_calibration()[source]

Creates "<cam.name>-<slm.name>-fourier-calibration".

Returns: name – The generated name.
Return type: str

save_fourier_calibration(path='.', name=None)[source]

Saves fourier_calibration to a file like "path/name_id.h5".

Parameters

path (str) – Path to directory to save in. Default is current directory.
name (str or None) – Name of the save file. If None, will use name_fourier_calibration().

Returns

The file path that the fourier calibration was saved to.

Return type

str

load_fourier_calibration(file_path=None)[source]

Loads fourier_calibration from a file.

Parameters: file_path (str or None) – Full path to the Fourier calibration file. If None, will search the current directory for a file with a name like the one returned by name_fourier_calibration().
Returns: The file path that the fourier calibration was loaded from.
Return type: str
Raises: FileNotFoundError – If a file is not found.

project_fourier_grid(array_shape=10, array_pitch=10, array_center=None, **kwargs)[source]

Projects a Fourier space grid ("knm") onto pixel space ("ij"). The chosen computational k-space "knm" uses a computational shape generated by SpotHologram.calculate_padded_shape() corresponding to the smallest square shape with power-of-two sidelength that is larger than the SLM’s shape.

Parameters

array_shape – Passed to make_rectangular_array() in the "knm" basis.
array_pitch – Passed to make_rectangular_array() in the "knm" basis.
array_center – Passed to make_rectangular_array() in the "knm" basis. array_center is not passed directly, and is processed as being relative to the center of "knm" space, the position of the 0th order.
**kwargs – Passed to optimize().

Returns

Optimized hologram.

Return type

SpotHologram

kxyslm_to_ijcam(kxy)[source]

Converts SLM Fourier space ("kxy") to camera pixel space ("ij"). For blaze vectors \(\vec{x}\) and camera pixel indices \(\vec{y}\), computes:

\[\vec{y} = M \cdot (\vec{x} - \vec{a}) + \vec{b}\]

where \(M\), \(\vec{b}\), and \(\vec{a}\) are stored in fourier_calibration.

Parameters: kxy (array_like) – 2-vector or array of 2-vectors to convert. Cleaned with format_2vectors().
Returns: ij – 2-vector or array of 2-vectors in camera coordinates.
Return type: numpy.ndarray
Raises: AssertionError – If the fourier plane calibration does not exist.

ijcam_to_kxyslm(ij)[source]

Converts camera pixel space ("ij") to SLM Fourier space ("kxy"). For camera pixel indices \(\vec{y}\) and blaze vectors \(\vec{x}\), computes:

\[\vec{x} = M^{-1} \cdot (\vec{y} - \vec{b}) + \vec{a}\]

where \(M\), \(\vec{b}\), and \(\vec{a}\) are stored in fourier_calibration.

Parameters: ij (array_like) – 2-vector or array of 2-vectors to convert. Cleaned with format_2vectors().
Returns: kxy – 2-vector or array of 2-vectors in slm coordinates.
Return type: numpy.ndarray
Raises: AssertionError – If the fourier plane calibration does not exist.

get_farfield_spot_size(slm_size=None, basis='kxy')[source]

Calculates the size of a spot produced by blazed patch of size slm_size on the SLM. If this patch is the size of the SLM, then we will find in the farfield (camera) domain, the size of a diffraction-limited spot for a fully-illuminated surface. As the slm_size of the patch on the SLM decreases, the diffraction limited spot size in the farfield domain will of course increase. This calculation is accomplished using the calibration produced by fourier_calibrate() and stored in fourier_calibration.

Parameters

slm_size ((float, float) OR int OR float OR None) – Size of patch on the SLM in normalized units. A scalar is interpreted as the width and height of a square. If None, defaults to the shape of the SLM.
basis ({"kxy", "ij"}) – Basis of the returned size; "kxy" for SLM size, "ij" for camera size.

Returns

Size in x and y of the spot in the desired basis.

Return type

(float, float)

Raises

ValueError – If the basis argument was malformed.

wavefront_calibrate(interference_point, field_point, field_point_units='ij', superpixel_size=50, phase_steps=10, exclude_superpixels=(0, 0), autoexposure=False, test_superpixel=None, reference_superpixel=None, fresh_calibration=True, plot=0)[source]

Perform wavefront calibration. This procedure involves iteratively interfering light diffracted from superpixels across an SLM with a reference superpixel. Interference occurs at a given interference_point in the camera’s imaging plane. It is at this point where the computed correction is ideal; the further away from this point, the less ideal the correction is. Sets wavefront_calibration_raw. Run process_wavefront_calibration() after to produce the usable calibration which is written to the SLM. This procedure measures the wavefront phase and amplitude.

Tip

If only amplitude calibration is desired, set phase_steps=0 to omit the more time consuming phase calibration.

Parameters

interference_point ((float, float)) – Position in the camera domain where interference occurs.
field_point ((float, float)) – Position in the camera domain where pixels not included in superpixels are blazed toward in order to reduce light in the camera’s field. Suggested approach is to set this outside the field of view of the camera and make sure that other diffraction orders are far from the interference_point.
field_point_units (str) –

Default to "ij" which moves first diffraction order
to the camera pixel field_point.

If it is instead a unit compatible with convert_blaze_vector(), then the field_point value is interpreted as a shifting blaze vector. In this case, setting one coordinate of field_point to zero is suggested to minimize higher order diffraction.
superpixel_size (int) – The width and height in pixels of each SLM superpixel. If this is not a devisor of both dimensions of the SLM’s shape, then superpixels at the edge of the SLM may be cropped and give undefined results.
phase_steps (int) – The number of phases measured for the interference pattern. If phase_steps is not strictly positive, phase is not measured: only amplitude is measured.
exclude_superpixels ((int, int)) – Optionally exclude superpixels from the margin, in (nx, ny) form. That is, the nx superpixels are omitted from the left and right sides of the SLM, with the same for ny. As power is typically concentrated in the center of the SLM, this function is useful for excluding points that are known to be blocked, or for quickly testing calibration at the most relevant points.
autoexposure (bool) – Whether or not to perform autoexposure on the camera. See autoexposure().
test_superpixel ((int, int) OR None) – Test an iteration of wavefront calibration using the given superpixel. If None, do not test.
reference_superpixel (None or (int, int)) – The superpixel to reference from. Defaults to the center of the SLM.
fresh_calibration (bool) – If True, the calibration is performed without an existing calibration (any old calibration is wiped from the SLM and CameraSLM). If False, the calibration is performed on top of any existing calibration. This is useful to determine the quality of a previous calibration, as a new calibration should yield zero phase correction needed if the previous was perfect.
plot (int or bool) –
Whether to provide visual feedback, options are:
- -1 : No plots or tqdm prints.
- 0, False : No plots, but tqdm prints.
- 1, True : Plots on fits and essentials.
- 2 : Plots on everything.
- 3 : test_superpixel not None only: returns image frames to make a movie from the phase measurement (not for general use).

Returns

wavefront_calibration_raw

Return type

dict

Raises

AssertionError – If the fourier plane calibration does not exist.

process_wavefront_calibration(smooth=True, r2_threshold=0.9, apply=True, plot=False)[source]

Processes wavefront_calibration_raw into the desired phase correction and amplitude measurement. Applies these parameters to the respective variables in the SLM if apply is True.

Parameters

smooth (bool) – Whether to blur the correction data to avoid aliasing.
r2_threshold (float) – Threshold for a “good fit”. Proxy for whether a datapoint should be used or ignored in the final data, depending upon the rsquared value of the fit. Should be within [0, 1].
apply (bool) – Whether to apply the processed calibration to the associated SLM. Otherwise, this function only returns and maybe plots these results. Defaults to True.
plot (bool) – Whether to enable debug plots.

Returns

A dictionary consisting of the measured_amplitude and phase_correction. With the same names as keys.

Return type

dict

name_wavefront_calibration()[source]

Creates "<cam.name>-<slm.name>-wavefront-calibration".

Returns: name – The generated name.
Return type: str

save_wavefront_calibration(path='.', name=None)[source]

Saves wavefront_calibration_raw to a file like "path/name_id.h5".

Parameters

path (str) – Path to the save location. Default is current directory.
name (str or None) – Name of the save file. If None, will use name_wavefront_calibration().

Returns

The file path that the fourier calibration was saved to.

Return type

str

load_wavefront_calibration(file_path=None, process=True, **kwargs)[source]

Loads wavefront_calibration_raw from a file.

Parameters

file_path (str or None) – Full path to the wavefront calibration file. If None, will search the current directory for a file with a name like the one returned by name_wavefront_calibration().
process (bool) – Whether to immediately process the wavefront calibration. See process_wavefront_calibration().
**kwargs – Passed to process_wavefront_calibration(), if process is true.

Returns

The file path that the wavefront calibration was loaded from.

Return type

str