;+
; NAME:
;	LENS
;
; PURPOSE:
;	To create a the DOE equivalent of a lens (namely, a Fresnel lens).
;
; CATEGORY:
;	Hologram/DOE Generator
;
; CALLING SEQUENCE:
;	squint = lens(z)
;
; INPUTS:
;		(ALL units are in millimeters)
;
;	z: the desired DISPLACEMENT (in millimeters) of the 
;		focal point/optical trap
;		relative to the focal plane,
;		in an optical train with effective focal length f.
;		(As this is in millimeters, a reasonable value is z = 0.001)
;
;	Note that (modulo 2pi) parabolic phase profile given by this program
;	will continue to work as a lens even as the effective focal length
;	of the system is infinite: just put an an arbitrary set of values 
;	for f and z.
;
; OPTIONAL INPUTS (KEYWORD PARAMETERS, which can be abbreviated
;				to the shortest unique form:
;
;	lambda: the wavelength of light in mm
;		(default = 532 nm = 5.32e-4 mm)
;
;	f: the focal length of the lens used to form the image in mm
;
;	SLMpitch: the pixel size of the image describing the input. (in mm) 
;		(Default setting is currently for
;		Gabe's Hamamatsu SLM with 24 micron pitch)
;
;	nbit: provides 2^nbit levels of phase,
;		default setting is 8 (valid for most SLMs)
;
;	xpix: number of pixels on a horizontal side, 
;		default setting is 1920 (for JDC EDK SLM)
;		(Set to 1280 for our Cambridge Correlators SLM)
;		(Set to 1024 or 768 for our Hamamatsu SLM)
;
;	ypix: number of pixels on a horizontal side, 
;		default setting is 1080 (for JDC EDK SLM)
;		(Set to 1024 for our Cambridge Correlators SLM)
;		(Set to 768 for our Hamamatsu SLM)
;
;	maxGSL: the grayscale level corresponding to 2pi of phase, 
;		default setting is 2^nbit-1
;
; OUTPUTS:
;	squint: a xpix by ypix real array giving a Fresnel phase plate
;
; SIDE EFFECTS:
;
; REQUIRES:
;
; RESTRICTIONS:
;	The displacement of a functioning optical trap 
; is limited by aberrations (e.g., an infinity-corrected
; objective lens is not designed for an input containing
; the wavefront curvature that this function introduces). 
; ...Even IF one were to compensate for the aberrations
; there would be another limiting factor: 
; large displacments require extremely large phase gradients
; at the edges of the lens, which will be "aliased" due to
; the discretization of the SLM (the number of phase levels
; and the size of the pixels). The result of this aliasing
; is that a single lens function will produce an array 
; of lenses, which can either be seen as good fun or can
; be spatially filtered.
; In any case, it *_IS_* possible to create useable displacements 
; well beyond the onset of aliasing. (See, e.g., "Axial and
; Lateral Trapping Limits of Holographic Optical Tweezers", by
; G. Sinclair, P. Jordan, J. Leach, J. Cooper, M.J. Padgett)
;
; MODIFICATION HISTORY:
;	Created by Gabe Spalding & Hannah Melville, Nov '02
;	Modified August, 2003-to clarify SLMpix settings (G.S.)
;	Modified Feb, 2005, to introduce lambda (G.S.)
;	Modified Sept. 2021 for use with SLMs with rectangular active areas (G.S.)
;-

FUNCTION lens, z, lambda=lambda, f=f, SLMpitch=SLMpitch, nbit=nbit, $
	xpix=xpix, ypix=ypix, maxGSL=maxGSL

IF NOT keyword_set(lambda) THEN lambda = 5.32e-4

   ; When working DIRECTLY with Hama x8267 (not projecting it down in size)
   ; then the pixel size is:
   ;IF NOT keyword_set(SLMpitch) then SLMpitch=0.024
   ;IF NOT keyword_set(f) then f = 300
   ;IF NOT keyword_set(nbit) THEN nbit = 8
   ;IF NOT keyword_set(xpix) THEN npix = 1024
   ;IF NOT keyword_set(ypix) THEN npix = 768

   ; When working DIRECTLY with BNS 512x512 (not projecting it down in size)
   ; then the pixel size is:
   ;IF NOT keyword_set(SLMpitch) then SLMpitch=0.015
   ;IF NOT keyword_set(f) then f = 300
   ;IF NOT keyword_set(nbit) THEN nbit = 7
   ;IF NOT keyword_set(npix) THEN npix = 512

   ; When projecting down a BNS 512x512 to match the 5.04-mm aperture
   ; of Gabe's 100x infinity-corrected objective,
   ; then the pixel size is effectively reduced to:
   ;IF NOT keyword_set(SLMpitch) then SLMpitch=5.04/512.
   ;IF NOT keyword_set(f) then f=1.8
   ;IF NOT keyword_set(nbit) THEN nbit = 7
   ;IF NOT keyword_set(npix) THEN npix = 512

   ; When projecting down a JDC EDK SLM to match the 5.04-mm aperture
   ; of Gabe's 100x infinity-corrected objective,
   ; then the pixel size is effectively reduced to:
 IF NOT keyword_set(SLMpitch) then SLMpitch=5.04/1080.
 IF NOT keyword_set(f) then f=1.8
 IF NOT keyword_set(nbit) THEN nbit = 8
 IF NOT keyword_set(maxGSL) THEN maxGSL = 2^nbit-1
 IF NOT keyword_set(xpix) THEN xpix = 1920
 IF NOT keyword_set(ypix) THEN ypix = 1080

squint = fltarr(xpix, ypix)
 xoffset = long(0.5 * xpix)
 yoffset = long(0.5 * ypix)

   ; The maximum distance from the center of the DOE is, in millimeters:
rho_max = SLMpitch * SQRT( (xoffset)^2 + (yoffset)^2 )

FOR i=0,xpix-1 DO BEGIN
  FOR j=0,ypix-1 DO BEGIN

	   ; The radial coordinate, from the center of the DOE,
	   ; is given, in millimeters, by:
	rho = SLMpitch * SQRT((i-xoffset)^2 + (j-yoffset)^2)

	   ; The Fresnel phase plate is created as follows
	squint(i,j) = (2*!pi)* ((rho_max)^2-(rho)^2) * z / (lambda * f^2)

  ENDFOR
 ENDFOR

modulo = 2*!pi
squint = squint - (modulo * long(squint/modulo))

   ; Finally, scale everything from units of phase to
   ; units of 'greyscale level'
squint = squint*((maxGSL)/(2*!pi))

return, squint
END