slmsuite.holography.toolbox.convert_vector

convert_vector(vector, from_units='norm', to_units='norm', hardware=None, shape=None)

Helper function for vector unit conversions in the \(k\)-space of the SLM.

Currently supported units:

• "rad", "mrad", "deg"

  Angle at which light is blazed in various units. The small angle approximation is assumed.

• "norm", "kxy"

  Blaze \(k_x\) normalized to wavenumber \(k\), i.e. \(\frac{k_x}{k}\). Equivalent to radians "rad" in the small angle approximation. This is the default slmsuite unit.

• "knm"

  Computational blaze units for a given Fourier domain shape. This corresponds to integer points on the grid of this (potentially padded) SLM’s Fourier transform. See Hologram. The "knm" basis is centered at shape/2, unlike all of the other units.

• "freq"

  Pixel frequency of a grating producing the blaze. e.g. 1/16 is a grating with a period of 16 pixels.

• "lpmm"

  Line pairs per mm or lines per mm of a grating producing the blaze. This unit is commonly used to define static diffraction gratings used in spectrometers.

• "zernike"

  The phase coefficients in radians of the tilt zernike terms \(x = Z_2 = Z_1^1\) and \(y = Z_1 = Z_1^{-1}\) necessary to produce a given blaze. The coefficients of these terms are used as weights multiplied directly with the normalized Zernike functions zernike_sum(). For instance, a weight coefficient of \(\pi\) would produce a wavefront offset of \(\pm\pi\) across the unit disk.

  These functions are defined within the unit disk, and canonically have amplitude of \(\pm 1\) at the edges. The size of the disk when scaled onto the SLM is pulled from radial fits derived from the amplitude distribution of the SLM. See get_source_zernike_scaling() and fit_source_amplitude(), especially the extent_threshold keyword which determines the size of the disk. Requires a SLM or FourierSLM to be passed to hardware.

• "ij"

  Camera pixel units, relative to the origin of the camera. Requires a FourierSLM to be passed to hardware. See kxyslm_to_ijcam() and ijcam_to_kxyslm().

• "m", "cm", "mm", "um", "nm"

  Camera position in metric length units, relative to the origin of the camera. Requires a FourierSLM to be passed to hardware, along with knowledge of the camera pixel size pitch_um.

• "mag_m", "mag_cm", "mag_mm", "mag_um", "mag_nm"

  Scales the corresponding metric length unit according to the value stored in mag to match the true dimensions of the experiment plane, apposed to the camera plane. Requires a FourierSLM to be passed to hardware, along with knowledge of the camera pixel size pitch_um.

3D Vectors

If an array of 3D vectors is given, then the depth (\(z\)) direction is handled differently than the field (\(xy\)). Most units use the normalized focal power \(\frac{\lambda}{f}\) on the SLM necessary to produce a spot at the defined depth relative to the focal plane. There are a few units where this differs:

• "zernike"

  The phase coefficient of the \(2(x^2 + y^2) - 1 = Z_4 = Z_2^0\) zernike focus term necessary to focus at the given depth.

• "ij"

  True cartesian distance relative to the camera plane in pixels.

• "m", "cm", "mm", "um", "nm"

  True cartesian distance relative to the camera plane in metric units.

• "mag_m", "mag_cm", "mag_mm", "mag_um", "mag_nm"

  True cartesian distance relative to the experiment plane in metric units. Importantly, \(x\) and \(y\) are divided by mag, while \(z\) is multiplied by it.

Some of these units will not make sense in a system with anisotropic focusing, for instance due to cylindrical lenses in the optical train.

Warning

The units "freq", "knm", and "lpmm" depend on SLM pixel size, so a SLM should be passed to hardware (otherwise returns an array of nan values). The unit "zernike" also requires an SLM. The unit "knm" additionally requires the shape of the computational space. If not included when hardware is passed, shape=slm.shape is assumed. The units "ij", "um", "mag_um", and related refer to distance on the camera and require calibration data stored in a FourierSLM, so this must be passed to hardware.

param vector:

Vectors for which we want to convert units, from from_units to to_units. Processed according to format_2vectors(). Can be shape (2, N) or (3, N).

type vector:

array_like

param from_units:

Units which we are converting between. See the listed units above for options. Defaults to "norm".

type from_units:

str

param to_units:

Units which we are converting between. See the listed units above for options. Defaults to "norm".

type to_units:

str

param hardware:

Relevant hardware to pull calibration data from in the case of "freq", "knm", "lpmm", or "zernike". If FourierSLM, the unit "ij" and other length units can be processed too.

type hardware:

SLM OR FourierSLM OR None

param shape:

Shape of the computational SLM space. Needed for "knm". Defaults to slm.shape if hardware is not None.

type shape:

(int, int) OR None

returns:

vector_converted – Result of the unit conversion, in the cleaned format of format_2vectors().

rtype:

numpy.ndarray