SLM ToolBox Readme
SLM ToolBox
--------------------------------------------------------------------
GUI software for spatial light modulators
J. P. Lee
Version 0.0.6
2018

End User Agreement
--------------------------------------------------------------------
This software is provided "AS IS" and no warranty or support is provided.
This software can not be changed, sold, or redistributed without the permission of JP Lee.

General usage
--------------------------------------------------------------------
The SLM Toolbox program can run on 32-bit and 64-bit versions of Windows.
For best performance, select the version that matches the OS architecture (32 or 64 bit).

This program assumes that the SLM is connected via the display output of the computer like an extra monitor.
This software does not support special connection types such as USB. Please contact the SLM manufacturer.

When the program is started, it tries to detect the secondary display including SLM.
The position of the detected SLM window can be changed manually by entering the numbers.

Initially, the SLM window is not displayed. This prevents potential problems if SLM window detection is incorrect.
The SLM window can be displayed using one of the following
* Menu: View -> Hide / Show SLM Window (Ctrl + H Shortcut)
* "Show SLM" button on the tool bar
* Uncheck Hide SLM window in SLM setting

The generated phase pattern can be sent to the clipboard or saved as an image file using the menu or toolbar buttons.


SLM Settings
--------------------------------------------------------------------
* Left, Top, Width, Height
	- These numbers control where the SLM window is created and its size within the desktop.
	- The program tries to detect this at the first run. Pressing the "Detect Window" button triggers auto-detection again.
	- Manual changes to these numbers only apply by pressing the "Set Dimensions" button.

* 2 Pi Grey Level Scaling
	- This is the grayscale image pixel value corresponding to what should be 2π on the SLM.
	- The default value is 255, but in general it depends on the SLM device and the wavelength.
	- To set the correct value, refer to your SLM manual.

* Flip Horizontal and Flip Vertical
	- Useful if there are additional mirrors in the optical setting, or if the camera is rotated.
	- It does not affect the SLM correction bitmap.

Phase Pattern
--------------------------------------------------------------------
* All phase patterns have "Enable" checkbox so that they can be switched on or off from SLM.
* You can add several phase patterns to each other:
	- Prism and lens
	- Custom bitmap
	- SLM correction bitmap
	- Binary Grating
	- CGH result (via "Show GS Result" of Phase Retrieval setting)
* Only one can be selected in the following phase patterns
	- Vortex phase
	- Axicon
	- Cubic phase

* Prism and Lens
	- Use this to transform X & Y (prismatic phase) or Z (lens phase) diffraction.

* Custom Bitmap
	- You can use other holograms calculated with external programs like Matlab or Python.
	- The bitmap is in the middle of the SLM, or cropped if it is larger than the SLM area.
	- The gray level of the bitmap corresponding to 2 pi should be set to obtain the expected result.

* SLM Correction Bitmap
	- This will apply wavefront compensation to the SLM (if available).
	- Unlike custom phase bitmaps, this bitmap maintains its orientation even if you flip the SLM.
	- Some SLM manufacturers include this data in the SLM they are selling.
	- The gray level of the bitmap corresponding to 2 pi should be set to obtain the expected result.

* Binary Grating
	- This is a typical example of a textbook phase and generates X, Y and checkerboard grids with known focus outputs.

* Vortex Phase
	- It is used to generate Laguerre Gauss beam. This is explained by a phase function that increases linearly along the azimuth.

* Axicon
	- This is related to Bessel beam. This is explained by a phase function that increases linearly along the radial direction.

* Cubic Phase
	- This is related to the Airy beam. The phase function is related to the cube of X and Y coordinates.

Phase Retrieval Settings
--------------------------------------------------------------------
Check "Show" to include algorithm result to SLM
Phase algorithm can be chosen by dropdown
	* Gerchberg Saxton
	* Random Mask ("Fast generation of holographic optical tweezers by random mask encoding of Fourier components" by Mario Montes-Usategui et al)

GERCHBERG SAXTON ALGORITHM
	* "Show GS Result" determines whether the calculated CGH is added to the final SLM phase pattern.
	* This FFT size can be selected from a drop-down list limited to a power of 2. The default is 1024 (2D 1024 x 1024).
	* When this value is changed, it is applied only after "Set FFT Size" is pressed.
	* The number of iterations performed by the Gerchberg-Saxton algorithm is set using numeric input. The default is 10.
	* Press "Compute" to start calculation, CGH calculation is started, SLM is updated when calculation is completed.
	* The size of the FFT is usually used for scaling the phase calculations.
		- To control this independently, Clear the check box, "Same size for analytic calculations?". Change the number.
	* The initial phase is random. Generally, there is no same CGH for the same target output.

RANDOM MASK ALGORITHM
	* This is fast but noisy with many spots.
	* Only works for spots
	* Useful for real time control of optical tweezers
	* Check "Auto Update" to compute phase atuomatic when target spot drawing change
	* Illumination and spot size ignored

ILLUMINATION
* You can choose a uniform or Gaussian lighting profile.
* Gauss waist: "W" value of exp ( -(X^2 + Y^2) / W^ 2). Like X and Y, this is measured in samples or SLM pixels.
* Aperture masks the imposed CGH input illumination with the specified rectangle or ellipse.
* When you press the "Set Illumination" button, the illumination parameters are applied.

Target Spots
--------------------------------------------------------------------
* This allows you to define the spot position of CGH generated by Gerchberg-Saxton using input like a spreadsheet.
* After entering the spot, press "Draw" to apply it to the target. Spots are displayed on the "Target Image" tab.
* Spots on target canvas, including mouse drawn spots can be listed by pressing "Get Canvas"
* To clear spots from target and grid, press "Clear".
* Formatted text from external applications such as Excel can be imported from the clipboard by pressing "Clipboard -> Import" button.
* Listed spots can be copied to clipboard by pressing "Clipboard -> Export" button.

Target Image
--------------------------------------------------------------------
* Displays Gerchberg-Saxton target image and spots imposed on the algorithm.
* The target can be acquired from the image file or can be obtained from the clipboard from the toolbar buttons and menus.
* You can also use rectangles and ellipses instead of images.
	- The size of the target image, rectangle, or ellipse can be changed by changing the width and height values
* The width and height used to display the target can be set using "Canvas width x height" on the right side of the toolbar.
	- This need not be the same as the FFT dimension.
	- Before applying the new 'width' or 'height' you need to press "Set Area".
* You can use the trash can icon to clear the contents in the target image.
* Object Width x Height can be set by changing numbers
* Spot mouse drawing operation (new in version 0.0.6)
	- Single mouse click drawing uses following buttons:
		* "+" adds spot
		* "-" removes clicked spot
	- If not pressed down "+" and "-" buttons then
		* Double click to draw spot
		* Drag spot to move
	- Pressing "X" button removes all spots
	- Slider & Size number change spot size
		* Gerchberg Saxton computation uses display spot size
		* For random mask algorithm, only spot location use

Reconstruction Output
--------------------------------------------------------------------
* To save memory and minimize calculations, hologram output is not calculated by default.
* Press "Update" to calculate the CGH Fourier output and display the result.
* If "Auto Update" is checked, output reconstruction is calculated each time CGH is calculated.
* You can copy the output to the clipboard or save it using the "Copy" button and "Save" button or its shortcut.

Batch CGH
--------------------------------------------------------------------
* Batch enables calculating multiple holograms from multiple target image files.
* Batch CGH is default hidden. Show using "View" menu or toolbar button.
* Settings of "SLM Settings" settings and "Phase Retrieval" settings are used.
* When calculating batch, other phase are disabled.
* Output CGH can be exported to "Image Player" with "Export to Player" button.

Image Player
--------------------------------------------------------------------
* Image Player enables animation using multiple CGH image files.
* Image Player is default hidden. Show using "View" menu or toolbar button.
* Settings of Custom Phase Bitmap are used.
* Image file names are listed and can be arrange with different buttons and menus.
* Player frame per second speed can be set with FPS number. But computer must be fast for high FPS.
* Because of added phases, unexpected CGH might appear if CGH from calculation is also enabled while Image Player playing files.

Known Issues / Workarounds:
--------------------------------------------------------------------
* On Windows 8 and later, "odd" numbers in the SLM window may be detected.
	- You can fix this by entering the SLM window number manually.
	- For later versions of Windows, different DPI scaling can be used for each monitor. Future versions of SLM Toolbox will try to solve this problem.
	- Windows application compatibility settings may also solve this problem.
* When the SLM window is displayed in the wrong place and hides the main interface, pressing "Ctrl + H" hides the SLM window.
* Do not change the dimensions of the SLM window frequently. This operation reallocates memory and may fail if it is repeatedly executed.
	- In normal use, the size of the SLM is fixed, so it is not necessary to do it frequently.
* Like SLM window, do not change "FFT size" and target "Canvas Width x Height" frequently. This also reserves memory.

Contact
--------------------------------------------------------------------
jplee [at] yandex.com