; docformat = 'rst'
;
; NAME: 
;    read2MASS
; PURPOSE:
;    Read the 2MASS Asteroid and Comet Survey Catalog.
;
;+
; :Description:
;    Read the 2MASS Asteroid and Comet Survey Catalog.
;
; :Categories:
;    Database, Asteroid, Colors
;    
; :Params:
;    ACS: in, optional, type=string
;        Path to a local version of the 2MASS Asteroid and Comet
;        Survey. Optional if either the config keyword, or initIDL is properly set.
;
; :Keywords:
;    config: in, optional, type=string
;        A configuration file, providing catalog information. 
;          [Repositery from PDS]
;            2mass  = PATH_TO_YOUR_2MASS_FILE
;
; :Returns: A structure with the orbital elements and the absolute
;           magnitude. Fields are::
;      .NUM: Asteroid IAU Number
;      .NAME: Asteroid Name or Provisional Designation
;  
; :Examples:
;        IDL> 2mass=read2MASS()
;
; :Uses:
;    initIDL
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;     Change History::
;        Written in December 2015, B. Carry (OCA)
;-
function read2MASS, ACS, config=config

;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  COMPILE_OPT hidden, idl2

 ;--I.1-- Set Input 2MASS ACS File  -----------------------------------------------------
 ;--I.1.1-- 2MASS Provided as Argument
  if keyword_set(ACS) then begin
     ACS = strtrim(ACS,2)
 ;--I.1.2-- 2MASS From AstroIM Configuration
  endif else begin
    if keyword_set(config) then begin
      confCatalog= initIDL(config, /CATALOG)
    endif else begin
      confAstroIM= initIDL()
      confCatalog= initIDL(confAstroIM.soft.catalog, /CATALOG)
    endelse
    ACS = confCatalog.acs2MASS
  endelse


 ;--I.2-- Test if File Exist  -----------------------------------------------------------
  if not file_test(ACS,/read) then begin
    message, '2MASS file not found: '+ACS
    return, -1
  endif

 ;--I.3-- Open 2MASS File for Reading  --------------------------------------------------
 ;--I.3.1-- Number of Entries
  spawn, 'wc '+ACS, res
  split=strsplit(res,' ',/extract)
  nb2MASS = round(float(split[0]))
 ;--I.3.2-- Open File
  openr, idIn, ACS, /Get_Lun

 ;--I.5-- Define Line Format  -----------------------------------------------------------
 ;--I.5.1-- SSO Identification
  fmt1='I7,1x,A17,1x,A10,1x'
  num=0L
  name=''
  des=''

 ;--I.5.2-- Photometry
  fmt2='F6.3,1x,F5.3,1x,F6.3,1x,F5.3,1x,F6.3,1x,F5.3,1x,F6.3,1x,D13.5,1x'
  jMag=0.
  jUnc=0.
  hMag=0.
  hUnc=0.
  kMag=0.
  kUnc=0.
  vMag=0.
  jdObs=0.d

 ;--I.5.3-- Flags
  fmt3='A1,1x,A3,1x,A3,1x,A3,1x,A3,1x'
  relFlag=''
  readFlag=''
  blendFlag=''
  contFlag=''
  qualFlag=''

 ;--I.5.4-- Measured Astrometry
  fmt4='F10.6,1x,F10.6,1x,F7.3,1x,F7.3,1x,F4.2,1x,F4.2,1x,I3,1x'
  raObs=0.
  deObs=0.
  gLon=0.
  gLat=0.
  obsEllMaj=0.
  obsEllMin=0.
  obsEllAng=0.

 ;--I.5.5-- Predicted Astrometry
  fmt5='F10.6,1x,F10.6,1x,F3.1,1x,F3.1,1x,F5.1,1x,F4.1,1x,F4.1,1x'
  raPred=0.
  dePred=0.
  predEllMaj=0.
  predEllMin=0.
  predEllAng=0.
  raDist=0.
  deDist=0.

 ;--I.5.6-- Motion and Geometry
  fmt6='F5.3,1x,F5.1,1x,F8.5,1x,F8.5,1x,F6.3,1x,F10.7,1x,F9.7,1x,F12.8,1x'
  muRA=0.
  muDE=0.
  dSun=0.
  dObs=0.
  phase=0.
  peri=0.
  orbE=0.
  orbI=0.

 ;--I.5.7-- P & Q Vectors, Ephemeris
  fmt7='F11.8,1x,F11.8,1x,F11.8,1x,F11.8,1x,F11.8,1x,F11.8,1x,F13.5,1x,F9.1,1x,F4.1,1x,F5.2,1x,F5.2,1x'
  pv1=0.
  pv2=0.
  pv3=0.
  qv1=0.
  qv2=0.
  qv3=0.
  tPeri=0.d
  jdElt=0.d
  CEU=0.
  H=0.
  G=0.

 ;--I.5.8-- Source Match Information
  fmt8='F5.2,1x,I1,1x,A1,1x,F4.2,1x,I4,1x,F5.2,1x,F5.2,1x'
  matchConf=0.
  matchN=0
  matchId=''
  matchDist=0.
  matchAng=0.
  matchB=0.
  matchVR=0.

 ;--I.5.9-- Observing Information
  fmt9='A10,1x,A1,1x,I4,1x,I10,1x,I7,1x,I1,1x,A1'
  dateObs=''
  hemis=''
  scanId=0
  pscId=0L
  escId=0L
  catFlat=0
  set=''

 ;--I.5.10-- Build Format String
  fmt='('+fmt1+','+fmt2+','+fmt3+','+fmt4+','+fmt5+','+fmt6+','+fmt7+','+fmt8+','+fmt9+')'

 ;--I.6-- Output Structure  -------------------------------------------------------------
  empty={ ssoNum:0L, ssoName:'', Jmag:0., Junc:0., Hmag:0., Hunc:0., Kmag:0., Kunc:0., Vmag:0., $
          flag:{ reliable:'', read:'', blend:'', contamination:'', quality:''}, $
          obs:{ ra:0., dec:0., ell:{maj:0., min:0., ang:0.}}, $
          pred:{ra:0., dec:0., ell:{maj:0., min:0., ang:0.} }, $
          omc:{ ra:0., dec:0.}, $
          gLon:0., gLat:0., muRA:0., muDec:0., H:0., G:0., $
          dSun:0.d, dObs:0.d, phase:0., peri:0., e:0., i:0., $
          pv1:0., pv2:0., pv3:0., qv1:0., qv2:0., qv3:0., tPeri:0., jdElt:0., CEU:0., $
          match:{ chi2:0., N:0, id:'', dist:0., ang:0., B:0., VR:0. }, $
          date:'', hemis:'', scanId:0, pscId:0L, escId:0, catFlag:0, dataSet:'' }
  ACS = replicate(empty, nb2MASS)


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Read Columns from 2MASS Asteroid and Comet Survey  -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  for kM=0, nb2MASS-1 do begin

   ;--II.1-- Read SDSS MOC3  ---------------------------------------------------------------
    readf, idIn, num, name, des, jMag, jUnc, hMag, hUnc, kMag, kUnc, vMag, jdOBs, $
           relFlag, readFlag, blendFlag, contFlag, qualFlag, $
           raObs, deObs, gLon, gLat, obsEllMaj, obsEllMin, obsEllAng, $
           raPred, dePred, predEllMaj, predEllMin, predEllAng, raDist, deDist, $
           muRa, muDE, dSun, dObs, phase, peri, orbE, orbI, $
           pv1, pv2, pv3, qv1, qv2, qv3, tPeri, jdElt, CEU, H, G, $
           matchConf, matchN, matchId, matchDist, matchAng, matchB, matchVR, $
           dateObs, hemis, scanId, pscId, escId, catFlag, set, $
           format=fmt

   ;--II.2-- Store Values in Structure  ----------------------------------------------------
    ACS[kM].ssoNum  = num
    ACS[kM].ssoName = strtrim(name,2)
    if strcmp(ACS[kM].ssoName,'-',1) then ACS[kM].ssoName = strtrim(des,2)

    ACS[kM].Jmag    = jMag
    ACS[kM].Junc    = jUnc
    ACS[kM].Hmag    = hMag
    ACS[kM].Hunc    = hUnc
    ACS[kM].Kmag    = kMag
    ACS[kM].Kunc    = kUnc
    ACS[kM].Vmag    = vMag

    ACS[kM].flag.reliable      = relFlag
    ACS[kM].flag.read          = readFlag
    ACS[kM].flag.blend         = blendFlag
    ACS[kM].flag.contamination = contFlag
    ACS[kM].flag.quality       = qualFlag

    ACS[kM].obs.ra      = raObs
    ACS[kM].obs.dec     = deObs
    ACS[kM].obs.ell.maj = obsEllMaj
    ACS[kM].obs.ell.min = obsEllMin
    ACS[kM].obs.ell.ang = obsEllAng
    ACS[kM].pred.ra      = raPred
    ACS[kM].pred.dec     = dePred
    ACS[kM].pred.ell.maj = predEllMaj
    ACS[kM].pred.ell.min = predEllMin
    ACS[kM].pred.ell.ang = predEllAng
    ACS[kM].omc.ra      = raDist
    ACS[kM].omc.dec     = deDist

    ACS[kM].gLon  = gLon
    ACS[kM].gLat  = gLat
    ACS[kM].muRA  = muRA
    ACS[kM].muDEC = muDE
    ACS[kM].dSun  = dSun
    ACS[kM].dObs  = dObs
    ACS[kM].phase = phase
    ACS[kM].H     = H
    ACS[kM].G     = G
    ACS[kM].peri  = peri
    ACS[kM].tPeri = tPeri
    ACS[kM].e     = orbE
    ACS[kM].i     = orbI
    ACS[kM].jdElt = jdElt
    ACS[kM].CEU   = CEU

    ACS[kM].pv1   = pv1
    ACS[kM].pv2   = pv2
    ACS[kM].pv3   = pv3
    ACS[kM].qv1   = qv1
    ACS[kM].qv2   = qv2
    ACS[kM].qv3   = qv3

    ACS[kM].match.chi2 = matchConf
    ACS[kM].match.N    = matchN
    ACS[kM].match.Id   = matchId
    ACS[kM].match.dist = matchDist
    ACS[kM].match.ang  = matchAng
    ACS[kM].match.B    = matchB
    ACS[kM].match.VR   = matchVR

    ACS[kM].date   = dateObs
    ACS[kM].hemis  = hemis
    ACS[kM].scanId = scanId
    ACS[kM].pscId  = pscId
    ACS[kM].escId  = escId
    ACS[kM].catFlag= catFlag
    ACS[kM].dataSet= set

  endfor

  close, idIn
  free_lun, idIn
  return, ACS

end