;+
; NAME: 
;  oc_convertid_ucac2
;  
; PURPOSE: (one line)
;  Convert UCAC2 ID's between standard format and SCAT format.
;
; DESCRIPTION:
;  UCAC2 stars are intended to be identified by a sequential number 0 ..
;  48,330,571.  However, WCSTools' SCAT program returns ID's in the form
;  zone.index, where zone is 1 .. 288 and index is a sequential number within
;  that zone.  This program converts between the two ID systems, by using the
;  u2_index.txt file supplied with the UCAC2 catalog.
;
;  The program converts from UCAC2 to SCAT ID's in order to parse
;  the UCAC2 catalog directly.
;
;  The program converts from SCAT to UCAC2 ID's in order to match
;  SCAT's output to the standard stellar ID's.
;
; CATEGORY:
;  Occultation
;  
; CALLING SEQUENCE:
;  result = oc_convertid_ucac2( SCAT=scat | UCAC2=ucac2 [, /VERBOSE] )
;
; INPUTS:
;  SCAT -- SCAT-formatted ID's.  Single string or vector of strings.
;    Floating point is not acceptable: 34.10 and 34.1 are different.
;  UCAC2 -- Standard UCAC2 ID's.  Single string or vector of strings.
;
;  Either SCAT or UCAC2 must be set, but not both.
;
; OPTIONAL INPUT PARAMETERS:
;  None
;  
; KEYWORD INPUT PARAMETERS:
;  /VERBOSE -- Print error messages to screen for incorrect ID's.
;
; KEYWORD OUTPUT PARAMETERS:
;  None
;
; OUTPUTS:
;  Returns a list of ID's matching those passed in.  Input and output
;    lengths are identical.  If a star is not found, 'none' is returned
;    for its ID.
;  
; COMMON BLOCKS:
;  UCAC2_ID_COMMON -- Used to store index file so it is loaded
;    only the first time this routine is called.
;
; SIDE EFFECTS:
;  None
;
; RESTRICTIONS:
;  The file $UCAC2_PATH/u2/u2index.txt must exist.  File is shipped
;  with UCAC2 CD-ROM catalog.
;
; EXAMPLE:
;   print, oc_convertid_ucac2(SCAT=['1.0', '2.10', '999.999'], /VERBOSE)
;   IDL returns:  "none 00000885 none"
;  
; MODIFICATION HISTORY:
;  Written 11-Jan-2006 by Henry Throop, SwRI
;  Modified  1-Feb-2005 by HBT. Improved error handling. 
;  Modified 23-Feb-2006 by HBT. Improved documentation and formatting.
;  Modified 26-Feb-2006 by LAY. Added '/' before 'u2/' (see scat code
;                               usage)
;  Modified 14-Apr-2006 by Leslie Young. Made loop index long.
;-

function oc_convertid_ucac2, SCAT=scat, UCAC2=ucac2, VERBOSE=verbose
common ucac2id_common, ucac2_index_loaded, ucac2_ninbin, ucac2_ninbin_cum

  path_catalog	= getenv('UCAC2_PATH') + '/u2/'

  path_index	= path_catalog + 'u2index.txt'

; Load the catalog if it's not loaded yet

  if not(keyword_set(ucac2_index_loaded)) then begin

    numlines_header	= 10
    numlines_data	= long(file_lines(path_index))
    openr, lun, path_index, lun, /get_lun
    line 	= ''
    for i = 0L, numlines_header-1 do readf, lun, line

; Use a long variable, since even double doesn't have enough precision (?)

    arr	= lonarr(7,numlines_data - numlines_header)		
    for i = 0L, sizey(arr)-1 do begin
      readf, lun, a0, a1, a2, a3, a4, a5, a6
      arr[0,i]	= a0
      arr[1,i]	= a1
      arr[2,i]	= a2
      arr[3,i]	= a3
      arr[4,i]	= a4
      arr[5,i]	= a5
      arr[6,i]	= a6
    end

    naz	= reform(arr[1,*])
    nat	= reform(arr[2,*])
    zn	= reform(arr[3,*])

    wdzn	= where(zn gt shift(zn,+1))
    wdzn	= where(zn gt shift(zn,+1))

; Now set the output arrays.  Note that SCAT arrays are from 1..288.  For ease
; of use, we put in a 0th bin, with 0 stars in it, so that the indices line up
; (and thus, SCAT's bin 100 is in element 100).

; Number of stars in each bin
    ninbin	= naz[wdzn-1]		
; Set the last field correctly
    ninbin	= [0,ninbin, max(nat)-total(ninbin,/double)-1]	
; Total umber of stars between start, and end of this bin
    ninbin_cum	= total(ninbin,/cum,/double)	

    ucac2_ninbin	= ninbin
    ucac2_ninbin_cum	= ninbin_cum

    ucac2_index_loaded	= 1

  end

; Set up some constants based on the catalog size.  These will change if we
; update the catalog (e.g., as of Dec-2002, the catalog only goes up to ~45
; deg N, but a newer version improves this.)

  ucac2_min	= 1L				; Min, max of UCAC2 catalog
  ucac2_max	= long(max(ucac2_ninbin_cum))
  ucac2_min_zone= 1L
  ucac2_max_zone= sizex(ucac2_ninbin)-1

; Now that catalog is loaded, do the conversions
; Note that UCAC2=1 -> SCAT=001.001 -- i.e., the indexing consistently starts
; at 1, not 0.  This can be verified by looking at output from "scat -c ucac2
; -r 200 -d -t -j -n 100 0.34622778 -89.657667" and comparing to Vizier output
; on UCAC2 ID=1.

; If we are converting from SCAT to UCAC2 (e.g., 4.123 -> 8239)

  if keyword_exists(SCAT) then begin
    scat_s	= string(scat)
    nstars	= sizex(SCAT)
    ucac2	= strarr(nstars)
    for i = 0L, nstars-1 do begin
      if (scat_s[i] eq 'none') then ucac2[i]	= 'none' $
      else begin
        ids		= ht_str_split(strcompress(scat[i],/remove), char='.')
        zone_scat	= ids[0]
        index_scat	= ids[1]
; Check that the zone and index are within bounds
        if ((zone_scat ge ucac2_min_zone) and $
	  (zone_scat le ucac2_max_zone)) then begin 
          if ((index_scat le ucac2_ninbin[zone_scat]-1) and $
	    (index_scat ge 1)) then begin 
            index_ucac2	= ucac2_ninbin_cum[zone_scat-1] + index_scat
            index_ucac2	= str_replace(string(index_ucac2, format='(I8)'), $
	      ' ', '0', /ALL)
            ucac2[i]	= index_ucac2
	  end
        end 
; If we were out of bounds, set it to an empty flag
        if (ucac2[i] eq '') then begin			
          ucac2[i]	= 'none'
          if keyword_set(VERBOSE) then print, $
	   'Error: oc_convertid_ucac2: UCAC2 ' + (scat[i]) + ' is invalid ID.'
        end
      end
    end
    return, UCAC2
  end

; If we are converting from UCAC2 to SCAT (e.g., 8239 -> 4.123)

  if keyword_exists(UCAC2) then begin
    ucac2_s	= string(ucac2)
    nstars	= sizex(UCAC2_s)
    scat	= strarr(nstars)
    for i = 0L, nstars-1 do begin
      if (ucac2_s[i] eq 'none') then scat[i] = 'none' $
      else begin
        id	= long(ucac2[i])
; Check that the star ID is within bounds
        if ((id ge ucac2_min) and (id le ucac2_max)) then begin
          zone_scat	= max(where(ucac2_ninbin_cum le id))+1
          index_scat= id - ucac2_ninbin_cum(zone_scat-1)
          scat[i]	= str_replace(string(zone_scat,format='(I3)') + $
	           '.' + string(index_scat,format='(I6)'), ' ', '0', /ALL)
        end $
        else begin
          scat[i]	= 'none'
          if keyword_set(VERBOSE) then print, $
	    'Error: oc_convertid_ucac2: UCAC2 ' + st(id) + ' is invalid ID.'
        end
      end

    end
    return, SCAT
  end  

; Need to put in some error-handing here for non-existing stars

; If neither SCAT nor UCAC2 is set
  
  print, 'Error: oc_convertid_ucac2: Must set either SCAT or UCAC2'
  return, -1
end
  
;;;;;;;;;;

pro other

;; Routines here are for development purposes and not intended for end-user ;;

   scat=oc_convertid_ucac2(UCAC2=[4,5,6,4d6,5d6,6d6])
   b=oc_convertid_ucac2(SCAT=scat)

   a=oc_getstar_ucac2(oc_convertid_ucac2(SCAT=['1.0', '1.1', '2.0', '2.1', '3.1', '4.1', '999.999']))
   a=oc_convertid_ucac2(SCAT=['1.0', '1.1', '2.0', '2.1', '3.1', '4.1', '999.999'])
   print,a.id

end