; docformat = 'rst'
;
; NAME: 
;    READASTORB
; PURPOSE:
;    Read the AstOrb database (Lowell observatory) and store it into an IDL structure.
;
;+
; :Description:
;    Read the AstOrb database (Lowell observatory) and store it into an IDL structure.
;
; :Categories:
;    Database, Asteroid, Orbits
;    
; :Params:
;    ASTORB: in, optional, type=integer/string
;        Path to a local version of AstOrb (Lowell Obs)
;
; :Returns: A structure with the orbital elements and the absolute
;           magnitude. Fields are::
;      .NUM: Asteroid IAU Number
;      .NAME: Asteroid Name or Provisional Designation
;      .H: Absolute magnitude (Bowell HG System)
;      .arcObs: Orbital arc spanned by observations 
;      .nbObs: Number of observations used in the computation
;      .n: Mean anomaly, deg.
;      .o: Argument of perihelion, deg (J2000.0)
;      .Om: Longitude of ascending node, deg (J2000.0)
;      .A: Semi-major axis AU
;      .E: Eccentricity
;      .I: Inclination (deg.)
;      .ceuVal: Current Ephemeris Uncertainty (CEU), arcsec
;      .ceuRate: Rate of change of CEU, arcsec/day
;      .ceuDate: Date of CEU, yyyymmdd (00:00 UT)
;  
; :Keywords:
;    config: in, optional, type=string
;        Path to the configuration file for catalogs, at the
;        minimum this file should contain the 2 following lines to be used
;        by current routine::
;          [Asteroid Orbits]
;            astorb  = PATH_TO_YOUR_ASTORB_FILE
;
; :Examples:
;    Plot the (a,e) distribution of asteroids
;        IDL> astorb=readastorb()
;        IDL> plot, astorb.a, astorb.e, psym=3
;
; :Uses:
;    initIDL
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;     Change History::
;        Written in August 2007, B. Carry (ESO/LESIA)
;        2013 Sep. - B.Carry (IMCCE) - I/O in Structures
;        2014 Oct. - B.Carry (IMCCE) - Now exports HG parameters
;-
function readAstOrb, AstOrb, config=config


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--I.1-- Set IDL Compilation Options  --------------------------------------------------
  COMPILE_OPT hidden, idl2

 ;--I.2-- Set AstOrb File  --------------------------------------------------------------
 ;--I.2.1-- From default configuration
  if not keyword_set(astorb) then begin

    if keyword_set(config) then config= initIDL(config, /CATALOG) $
    else begin
      confAstroIM= initIDL()
      confCatalog= initIDL(confAstroIM.soft.catalog, /CATALOG)
    endelse
    astorb = confCatalog.astorb 

 ;--I.2.2-- From command-line input
  endif else astorb = strtrim(astorb,2)

 ;--I.3-- File Check Out   --------------------------------------------------------------
  if not file_test(astorb,/read) then begin
    message, /ioError, 'AstOrb file not found: '+astorb
    return, -1
  endif


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Read AstOrb File                                   -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  readfmt, astorb, $
           'I6,1x,A18,17x,F5.2,1x,F5.2,'+$
           '42x,F5,1x,I4,10x,'+$
           'F10.6,1x,F10.6,1x,F10.6,1x,'+$
           'F9.6,1x,F10.8,1x,F12.8,10x,'+$
           'F7,1x,F8,1x,A8',$
           iauNum, iauName, hMag, gSlope, $
           obsArc, obsUsed, $
           anom, periArg, node, $
           iIAU, eIAU, aIAU, $
           ceuVal, ceuRate, ceuDate, $ 
           /SILENT
    nbSSO=n_elements(iauNum)


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---  III -- Store AstOrb in an IDL Structure                   -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  empty ={ num: 0L, $      ;-Number
           name: '', $     ;-Designation
           H: 0., $        ;-Bowell HG Absolute Magnitude
           G: 0., $        ;-Bowell HG Slope Parameter
           arcObs: 0., $   ;-Orbital arc spanned by observations 
           nbObs: 0., $    ;-Number of observations used in the computation
           n: 0., $        ;-Mean anomaly, deg.
           o: 0., $        ;-Argument of perihelion, deg (J2000.0)
           Om: 0., $       ;-Longitude of ascending node, deg (J2000.0)
           i: 0.d, $       ;-Inclination, deg (J2000.0)
           e: 0.d, $       ;-Eccentricity
           a: 0.d, $       ;-Semimajor axis, AU
           ceuVal: 0., $   ;-Current Ephemeris Uncertainty (CEU), arcsec
           ceuRate: 0., $  ;-Rate of change of CEU, arcsec/day
           ceuDate: 0.  }  ;-Date of CEU, yyyymmdd (00:00 UT)
  astOrb = replicate( empty, nbSSO)

  astOrb.num     = iauNum              ;-Number
  astOrb.name    = strtrim(iauName,2)  ;-Designation
  astOrb.H       = hMag                ;-Bowell HG Absolute Magnitude
  astOrb.G       = gSlope              ;-Bowell HG Slope Parameter
  astOrb.arcObs  = obsArc              ;-Orbital arc spanned by observations 
  astOrb.nbObs   = obsUsed             ;-Number of observations used in the computation
  astOrb.n       = anom                ;-Mean anomaly, deg.
  astOrb.o       = periArg             ;-Argument of perihelion, deg (J2000.0)
  astOrb.Om      = node                ;-Longitude of ascending node, deg (J2000.0)
  astOrb.i       = iIAU                ;-Inclination, deg (J2000.0)
  astOrb.e       = eIAU                ;-Eccentricity
  astOrb.a       = aIAU                ;-Semimajor axis, AU
  astOrb.ceuVal  = ceuVal              ;-Current Ephemeris Uncertainty (CEU), arcsec
  astOrb.ceuRate = ceuRate             ;-Rate of change of CEU, arcsec/day
  astOrb.ceuDate = ceuDate             ;-Date of CEU, yyyymmdd (00:00 UT)
    
  return, astOrb

end