slmsuite.holography.toolbox.imprint

imprint(matrix, window, function, grid=None, imprint_operation='replace', centered=False, circular=False, clip=True, transform=0, shift=(0, 0), **kwargs)[source]

Imprints a region (defined by window) of a matrix with a function. This function must be in the style of phase phase helper functions, which expect a grid parameter to define the coordinate basis (see blaze() or lens()).

For instance, we can imprint a blaze on a 200 by 200 pixel region of the SLM with:

canvas = np.zeros(shape=slm.shape)  # Matrix to imprint onto.
window = [200, 200, 200, 200]       # Region of the matrix to imprint.
toolbox.imprint(canvas, window=window, function=toolbox.phase.blaze, grid=slm, vector=(.001, .001))

See also Examples.

Parameters

  • matrix (numpy.ndarray) – The data to imprint a function onto.

  • window – See window_slice().

  • function (function OR float) – A function in the style of toolbox helper functions, which accept grid as the first argument. Also accepts floating point values, in which case this value is simply added.

  • grid ((array_like, array_like) OR SLM OR None) – Meshgrids of normalized \(\frac{x}{\lambda}\) coordinates corresponding to SLM pixels, in (x_grid, y_grid) form. These are precalculated and stored in any SLM, so such a class can be passed instead of the grids directly. None can only be passed if a float is passed as function.

  • imprint_operation ({"replace" OR "add"}) –

    Decides how the function is imparted to the matrix.

    • If "replace", then the values of matrix inside window are replaced with function.

    • If "add", then these are instead added together (useful, for instance, for global blazes).

  • centered – See window_slice().

  • circular – See window_slice().

  • clip (bool) – Whether to clip the imprint region if it exceeds the size of matrix. If False, then an error is raised when the size is exceeded. If True, then the out-of-range pixels are instead filled with numpy.nan.

  • transform (float or ((float, float), (float, float))) – Passed to shift_grid(), operating on the cropped imprint grid. This is left as an option such that the user does not have to transform the entire grid to satisfy a tiny imprinted patch. See shift_grid() for more details.

  • shift ((float, float)) – Passed to shift_grid(), operating on the cropped imprint grid. This is left as an option such that the user does not have to transform the entire grid to satisfy a tiny imprinted patch. See shift_grid() for more details.

  • **kwargs – For passing additional arguments accepted by function.

Returns

matrix – The modified image. Note that the matrix is modified in place, and this return is merely a copy of the user’s pointer to the data.

Return type

numpy.ndarray

Raises

ValueError – If invalid window or imprint_operation are provided.