;+
; NAME: 
;  oc_convertid_2mass
;  
; PURPOSE: (one line)
;  Convert 2MASS ID's between standard format and SCAT format.
;
; DESCRIPTION:
;  2MASS stars are intended to be identified by a standard ID; e.g., 
;  01500687+7211468 (Jhhmmssss+-ddmmsss[ABC]).
;  However, WCSTools' SCAT program returns ID's in the form
;  zone.index, where digits 1-3 of zone are the zone 1..180, digit 4 of
;  zone is the scat file within that zone, and index is the sequential
;  within that file.  
;  This program converts between the two ID systems.
;
;  The program converts from 2MASS to SCAT ID's in order to parse
;  the UCAC2 catalog directly.
;
;  The program converts from SCAT to 2MASS ID's in order to match
;  SCAT's output to the standard stellar ID's.  It does this by 
;  reading Mink's catalog files -- e..g, $TMC_CAT/153/t0000.cat .
;
;  Neither of these formats give the location of a star within the 
;  *real* 2mass catalog.  For that, use oc_getline_2mass(), which reads
;  the binary lookup tables created by oc_make_lookup_2mass.
;
; CATEGORY:
;  Occultation
;  
; CALLING SEQUENCE:
;  result = oc_convertid_2mass( SCAT=scat | TMASS=tmass [, /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.
;
;  2MASS -- Standard 2MASS ID's.  Single string or vector of strings.
;
; 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:
;
; SIDE EFFECTS:
;  None
;
; RESTRICTIONS:
;  2MASS catalog must be at $TMC_PATH
;
; EXAMPLE:
;   print, oc_convertid_2mass(SCAT=['1187.006978', '1191.006729', '400.0'], /VERBOSE)
;   IDL returns:  "none 00000885 none"
;  
; MODIFICATION HISTORY:
;  Created 26-Apr-2006 by Henry Throop, SwRI.  Based on convertid_ucac2.pro.
;-

function oc_convertid_2mass, SCAT=scat, tmass=tmass, VERBOSE=verbose

  path_catalog	= getenv('TMC_PATH')

; If we are converting from SCAT to 2mass (e.g., 4.123 -> 8239+45662)

  if keyword_exists(SCAT) then begin
    scat_s	= string(scat)
    nstars	= sizex(SCAT)
    tmass	= strarr(nstars)
    for i = 0L, nstars-1 do begin
      if (scat_s[i] eq 'none') then tmass[i]	= 'none' $
      else begin
        ids		= ht_str_split(strcompress(scat[i],/remove), char='.')
        zone_scat	= ids[0]/10			; first three digits
	file_scat	= ids[0] - 10*zone_scat		; last digit
        index_scat	= ids[1]-1L			; IDL starts at 0

        zone_scat_str	= str_replace(string(zone_scat, format='(I3)'), $
	                  ' ', '0', /ALL)
	filename	= path_catalog + '/' + zone_scat_str + $
	                          '/t000' + st(file_scat,/nod) + '.cat'
        line		= nthline(filename, index_scat)
	
	if (line eq '') then tmass[i] = 'none' else begin
	  line_split	= ht_str_split(line, char=' ')
	  tmass[i]	= line_split[2]
	end

; Check that the zone and index are within bounds
; If we were out of bounds, set it to an empty flag
        if (tmass[i] eq '') then begin			
          tmass[i]	= 'none'
          if keyword_set(VERBOSE) then print, $
	   'Error: oc_convertid_2mass: 2mass ' + (scat[i]) + ' is invalid ID.'
        end
      end
    end
    return, tmass
  end

; If we are converting from 2mass to SCAT (e.g., 8239+45622 -> 4.123)

  if keyword_exists(tmass) then begin
    tmass_s	= string(tmass)
    nstars	= sizex(tmass_s)
    scat	= strarr(nstars)
    for i = 0L, nstars-1 do begin
      if (tmass_s[i] eq 'none') then scat[i] = 'none' $
      else begin
        id	= long(tmass[i])
; Check that the star ID is within bounds
        if ((id ge tmass_min) and (id le tmass_max)) then begin
          zone_scat	= max(where(tmass_ninbin_cum le id))+1
          index_scat= id - tmass_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_2mass: 2mass ' + 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 2mass is set
  
  print, 'Error: oc_convertid_2mass: Must set either SCAT or 2mass'
  return, -1
end
  
;;;;;;;;;;

pro other

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

   scat=oc_convertid_2mass(tmass=[4,5,6,4d6,5d6,6d6])
   b=oc_convertid_2mass(SCAT=scat)

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

end