; Time-stamp: <97/12/26 15:34:17 dph> 
; MIT Directory: ~dph/h1/ASC/TG/Anal/3color_spec/
;                            /wiwaxia/d4/ASC/lib/IDL
; File: marx_color_image.pro
; Author: D. Huenemoerder
; Original version: 971226
;
; (this header is ~dph/libidl/time-stamp-template.el)
; to auto-update the stamp in emacs, put this in your .emacs file:
;      (add-hook 'write-file-hooks 'time-stamp)
;====================================================================

PRO marx_color_image, marx_dir, xy_bin, det_id, color_par, im_out, x_out, y_out, rgb_out
;+
; NAME:
;
; marx_color_image
;
; PURPOSE:
;
;  make color-coded image of 2 marx output vectors, using 3rd as color.
;
; CATEGORY:
;
;  
;
; CALLING SEQUENCE:
;
;  marx_color_image, marx_dir, xy_bin, det_id, color_par, im_out, x_out, y_out, rgb_out
; 
; INPUTS:
;
; marx_dir = [string] = marx output directory name
; xy_bin   = [dx,dy] = x,y bin sizes, in mm
; det_id = [id_low,id_high] or [id] = range (or scalar value) of
;                                      detector array element id's
; color_par= [string] = name of marx output color vector file.
;
; OPTIONAL INPUTS:
;
; NONE
;	
; KEYWORD PARAMETERS:
;
; NONE
;
; OUTPUTS:
;
; im_out = [nx,ny] = image array
; x_out  = [nx] = x-axis, for plotting
; y_out  =[ny] =y-axis, for plotting
; rgb_out =[256,3] output color table, in rgb system.
;
;
; OPTIONAL OUTPUTS:
;
;  NONE
;
; COMMON BLOCKS:
;
;  NONE
;
; SIDE EFFECTS:
;
;  NONE
;
; RESTRICTIONS:
;
;  Reads ypos.dat, zpos.dat from marx output directory.
;  Autoscales intensity color-table.
;  Quantizes to 8-bits.
;  Requires read_marx_file
;           mk_color_image
;
; PROCEDURE:
;
;
;
; EXAMPLE:
;
;  marx_dir='./marx_acis-s'
;  xy_bin=[4,2]*0.024 ; bin by 4 pixels in ypos, 2 in zpos.
;  det_id=[7,9] ; zero-order side ccd's only
;  color_par='pha.dat' ; use the pha.dat output file to color the image
;  marx_color_image, marx_dir, xy_bin, det_id, color_par, im_out, x_out, y_out, rgb_out
;  tvlct,rgb
;  tv,im_out
;
; MODIFICATION HISTORY:
;
; 971226 dph original version
;-
   
u_sarray = [$
  'marx_color_image, marx_dir, xy_bin, det_id, color_par, im_out, x_out, y_out, rgb_out', $
  '', $
  'INPUTS:', $
  '', $
  'marx_dir = [string] = marx output directory name', $
  'xy_bin   = [dx,dy] = x,y bin sizes, in mm', $
  'det_id = [id_low,id_high] or [id] = range (or scalar) of detector array element ids',$
  'color_par= [string] = name of marx output color vector file.', $
  '', $
  'OUTPUTS:', $
  '', $
  'im_out = [nx,ny] = image array', $
  'x_out  = [nx] = x-axis, for plotting', $
  'y_out  =[ny] =y-axis, for plotting', $
   'rgb_out =[256,3] output color table, in rgb system.'$
   ]

   np = n_params()
   IF np NE 8 THEN BEGIN
      print, 'USAGE:  '+u_sarray, format = '(a)'
      return
   ENDIF
   
   
   IF (size(xy_bin))[0] NE 1 THEN BEGIN
      print, 'Bad xy_bin: '
      print, 'USAGE:  '+u_sarray, format = '(a)'
      return
   ENDIF
   
   yp = read_marx_file(marx_dir+'/ypos.dat')
   zp = read_marx_file(marx_dir+'/zpos.dat')
   detector = read_marx_file(marx_dir+'/detector.dat')
   cvec = read_marx_file(marx_dir+'/'+color_par)
   
   sz_det = size(det_id)
   IF sz_det[0] EQ 0 THEN BEGIN
      l_det = where(detector EQ det_id)
   ENDIF ELSE BEGIN
      det_id = det_id( sort(det_id) ) ; make ascending
      l_det = where( (detector GE det_id[0]) AND (detector LE det_id[1]) )
   ENDELSE
   

   mk_color_image, yp[l_det], zp[l_det], xy_bin, cvec[l_det], $
    im_out, x_out, y_out, rgb_out
   
END