;+
; NAME:
;  complex_rgb
; PURPOSE: (one line)
;  get an RGB representation of a complex number
; DESCRIPTION:
;  get an RGB representation of a complex number,
;  by way of Hue/Saturation/Lightness, where the
;  hue represents the phase and the lightness
;  represents the value
; CATEGORY:
;  graphics
; CALLING SEQUENCE:
;  complex_rgb, a, truecolor = truecolor, color24=color24,
;  minabs=minabs, maxabs=maxabs, zerophase=zerophase, 
;  saturation = saturation, square=square, log=log
; INPUTS:
;  a - a 2-D array of complex numbers
; OPTIONAL INPUT PARAMETERS:
;  none
; KEYWORD INPUT PARAMETERS:
;  minabs = darkest value (default = minimum in image)
;  maxabs = brightest value (default = maximum in image)
;  saturation = "purity" of the color (default = 1)
;  zerophase = phase that corresponds to red, in deg (default = 0)
;  square = 1 to generate colors from the square of the absolute value
;  log = 1 to generate colors from the log of the absolute value
; KEYWORD OUTPUT PARAMETERS:
;   truecolor = a 3-D array of bytes, where b[0,*,*] is blue, b[1,*,*] is green
;      and b[2,*,*] is red
;   color24 = 24-bit color, where the least significant
;      byte is the red shade (0 for black, FF for reddest),
;      the next byte is green, and the next byte is blue, 
;  alternate form (3-D bytes if input is 2-D long, or
;  2-D long if input is 3-D bytes)
; OUTPUTS:
;  none
; COMMON BLOCKS:
;  None
; SIDE EFFECTS:
; RESTRICTIONS:
;  None
; PROCEDURE:
; MODIFICATION HISTORY:
;  Written 2006 Jan 13, by Leslie Young, SwRI
;-

pro complex_rgb, a, truecolor = truecolor, color24=color24, $
    minabs=minabs, maxabs=maxabs, lightrange=lightrange, zerophase=zerophase, $
    saturation = saturation, square=square, log=log, phase=phase, abs=abs

    sz = size(a)
    if sz[0] ne 2 then return
    nx = sz[1]
    ny = sz[2]
    
    if not keyword_set(zerophase) then zerophase = 0.
    phase = atan(a, /phase)*180/!pi
    hue = phase - zerophase

    abs = abs(a)
    if n_elements(maxabs) eq 0 then maxabs=max(abs)
    if n_elements(minabs) eq 0 then minabs=min(abs)
    if keyword_set(log) and (minabs) le 0. then minabs = 1e-6 * maxabs
    val = minabs > abs < maxabs
    if not keyword_set(square) and not keyword_set(log) then begin
       lightness = (val - minabs)/(maxabs - minabs)
    endif
    if keyword_set(square) then begin
       lightness = (val^2 - minabs^2)/(maxabs^2 - minabs^2)
    endif
    if keyword_set(log) then begin
       lightness = (alog(val) - alog(minabs))/(alog(maxabs) - alog(minabs))
    endif
    if keyword_set(lightrange) then begin
       lightness = lightness*(lightrange[1]-lightrange[0]) + lightrange[0]
    endif
    lightness = 0 > lightness < 1
 
    if n_elements(saturation) eq 0 then saturation = 1.
    sat = replicate(0. > saturation < 1,nx,ny)

    COLOR_CONVERT, hue, lightness, sat, red, green, blue, /hls_rgb

    truecolor = bytarr(3,nx,ny)
    truecolor[0,*,*] = red
    truecolor[1,*,*] = green
    truecolor[2,*,*] = blue
    
    color24 = blue*'10000'xl + green*'100'xl + red

end