;+
; NAME:
;      makerho
;
; PURPOSE:
;      Creates an array whose values are the distances
;      from the center of each pixel in the array.
;
; CATEGORY:
;      Geometry, computed holography
;
; CALLING SEQUENCE:
;      rho = makerho()
;
; INPUTS:
;      none
;
; KEYWORD PARAMETERS:
;      cal: [xc,yc,xfac] coordinates of optical axis on SLM face
;          and scale factor for x-coordinate.
;          Setting this parameter overrides global
;          calibrations.
;      nocal: if set, ignore CAL and do not use global
;          calibration constants.
;      dim : one- or two-component specification of the phase-mask's
;          dimensions.  If set, overrides and **overwrites**
;          global calibrations.
;               
; OUTPUTS:
;      rho: arrays of radial distances to the center.
;
; KEYWORD OUTPUTS:
;      x, y: Cartesian coordinates
;
; COMMON BLOCKS:
;      HOLO_COMMON: Contains global calibration constants.
;         
; PROCEDURE:
;      straightforward.
;
; EXAMPLE:
;      IDL> rho = makerho()
;
; MODIFICATION HISTORY:
; 10/8/2004 David G. Grier, New York Universty, created.
; 06/05/2006: DGG. Use calibration constants from HOLO_COMMON.
;    Added NOCAL keyword.
; 11/30/2008: DGG. Optionally return cartesian coordinates.
;    Added X and Y keywords.
; 02/04/2010: DGG. Don't clobber global calibration constants if
;    CAL or DIM are specified.  These should be changed with
;    HOLO_INIT.  Report error if dimensions are not specified.
; 06/10/2010: DGG. Documentation fixes. Added COMPILE_OPT
;
; Copyright 2006-2010 David G. Grier
;
; UPDATES:
;    The most recent version of this program may be obtained from
;    http://physics.nyu.edu/grierlab/software.html
; 
; LICENSE:
;    This program is free software; you can redistribute it and/or
;    modify it under the terms of the GNU General Public License as
;    published by the Free Software Foundation; either version 2 of the
;    License, or (at your option) any later version.
;
;    This program is distributed in the hope that it will be useful,
;    but WITHOUT ANY WARRANTY; without even the implied warranty of
;    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;    General Public License for more details.
;
;    You should have received a copy of the GNU General Public License
;    along with this program; if not, write to the Free Software
;    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
;    02111-1307 USA
;
;    If the Internet and WWW are still functional when you are using
;    this, you should be able to access the GPL here: 
;    http://www.gnu.org/copyleft/gpl.html
;-

function makerho, x = x, y = y, dim = dim, cal = cal, nocal = nocal

COMPILE_OPT IDL2

common holo_common, c

calibrated = n_elements(cal) gt 0

; requested dimensions override calibrated defaults.
if n_elements(dim) ge 1 then begin
   w = dim[0]
   if n_elements(dim) eq 2 then $
      h = dim[1] $
   else $
      h = w
endif else if calibrated then begin
   w = c.doe_w
   h = c.doe_h
endif else begin
   message, "dimensions not specified", /inf
   return, -1
endelse

xc = 0.
yc = 0.
xfac = 1.

if ~keyword_set(nocal) then begin ; use calibration constants
   if n_elements(cal) ge 2 then begin
      xc = double(cal[0])
      yc = double(cal[1])
      if n_elements(cal) ge 3 then $
         xfac = double(cal[2])
   endif else if calibrated then begin
      xc = c.xc
      yc = c.yc
      xfac = c.xscale
   endif
endif

x = (findgen(w, h) mod w) - (w - 1.)/2.
y = floor(findgen(w, h) / w) - (h - 1)/2.
x = xfac * x - xc
y -= yc
rho = sqrt(x^2 + y^2)

return, rho
end