; docformat = 'rst'
;
; NAME: 
;    ssoCoordinates
; PURPOSE:
;    Return the celestial coordinates of a Solar System Object 
;
;+
; :Description:
;    Return the celestial coordinates of a Solar System Object
;
;    This function is a simple interface to the ephemcc utility of the
;    Eproc ephemeris generator (IMCCE, Paris Observatory, France). See
;    Eproc documentation for more details:
;    http://vo.imcce.fr/webservices/miriade/?ephemcc
;    If Eproc is installed locally, SSOCOORDINATES uses it, otherwise a
;    request to Eproc webservice Miriade is performed.
;
; :Categories:
;    Coordinates, Ephemeris
;    
; :Params:
;    ID: in, required, type=integer/string
;        Target identifyer ('*', Name, Provisional designation, Number) 
;    EP: in, required, type=double/string
;        The epoch at which the ephemeris should be computed
;
; :Returns: A two-element array containing the coordinates
;
; :Keywords:
;    TYPE: in, optional, type=string, default='aster'
;        Type of target (aster | planet | satel | comet), can be set
;        alternatively with the optional keywords ASTEROID, PLANET,
;        SATELLITE, COMET
;    ASTEROID: in, optional, type=boolean, default=1
;        Set the target type to asteroid  (equiv. to type='aster')
;    PLANET: in, optional, type=boolean, default=0
;        Set the target type to planet    (equiv. to type='planet')
;    SATELLITE: in, optional, type=boolean, default=0
;        Set the target type to satellite (equiv. to type='satel')
;    COMET: in, optional, type=boolean, default=0
;        Set the target type to comet     (equiv. to type='comet')
;    RPLANE: in, optional, type=integer, default=1
;        Reference plane (1:equator, 2: ecliptic)
;    WEB: in, optional, type=boolean, default=0
;        Force the use of Miriade upon a local installation of Eproc
;    OBSERVER: in, optional, type=integer, default=500
;        The IAU Code or geographic coordinates of the
;        observer's location, can be set alternatively with the
;        optional input keywords
;    GEOCENTRIC: in, optional, type=boolean, default=1
;        Compute ephemeris from the geocentre
;    HELIOCENTRIC: in, optional, type=boolean, default=0
;        Compute ephemeris from the heliocentre
;
; :Examples:
;    Compute the geocentric equatorial coordinates of Ceres at J2000.0
;      IDL> radec = ssoCoordinates(1,'2000-01-01T00:00:00.0',type='aster', /geocentric)
;    Compute the heliocentric ecliptic coordinates of Pallas at J2000.0
;      IDL> longlat = ssoCoordinates('Pallas','2000-01-01T00:00:00.0',type='aster', /heliocentric)
;    Compute the gaia-centric equatorial coordinates of Lutetia at on 2016-01-01T00:00:00.0
;      IDL> radec = ssoCoordinates(21,'2016-01-01T00:00:00.0',type='aster', observer='@gaia')
;
; :Uses:
;    date_conv, forprint, call_ephemcc
;
; :Author:
;    B.Carry (IMCCE)
;
; :History:
;     Change History::
;        Written in November 2010, B. Carry (ESA)
;        2013 Sep. - B.Carry (IMCCE) - I/O homogeneous with Miriade
;            (http://vo.imcce.fr/webservices/miriade/?ephemcc)
;-
function ssoCoordinates, ID, EP, type=type, rPlane=rPlane, Web=Web, $
                         planet=planet, asteroid=asteroid, satellite=satellite, comet=comet, $
                         observer=observer, geocentric=geocentric, heliocentric=heliocentric 


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


 ;--I.1-- Analyze the Epoch format and convert in Julian Days if needed  ----------
  dims= size( ep )
  epType = dims( n_elements(dims)-2 )


 ;--I.1.1-- Single Epoch Specified
  tInFile = '/tmp/inputDates.jd'
  if dims(0) eq 0 then begin
    if epType eq 7 then begin
      if strcmp(ep,'now') then ep = systime(/UTC,/JULIAN) 
      epoch = date_conv(ep,'JULIAN')
    endif else begin
      epoch = ep
    endelse

    nbd=0

 ;--I.1.2-- Epoch Array Provided
  endif else begin

   ;--I.1.2/A-- Possible Type Conversion
    nbd = dims(1)
    if epType eq 7 then begin
      epoch = dblarr(nbd)
      for kD=0L, nbd-1 do epoch(kD) = date_conv( ep(kD), 'JULIAN' )
    endif else epoch = ep

   ;--I.1.2/B-- Generate the Date Input File for Eproc
    forprint, epoch, format='(D16.8)', textout=tInFile, /NOCOMMENT, /SILENT
    epoch = tInFile

  endelse


 ;--I.2-- Reference plane (1: Equatorial, 2: Ecliptic)  ---------------------------
  if not keyword_set( RPLANE ) then rPlane='1' $
                               else rPlane=strtrim(string(rPlane,format='(I)'),2)

 ;--I.3-- Observer's Location  ----------------------------------------------------
  if not keyword_set(OBSERVER)     and $
     not keyword_set(GEOCENTRIC)   and $
     not keyword_set(HELIOCENTRIC) then geocentric=1

 ;--I.4-- Type of Target ----------------------------------------------------------
  if not keyword_set(TYPE) then begin

   ;--I.4.1-- If Nothing Specified -> Target is an asteroid
    if not keyword_set(PLANET)    AND $
       not keyword_set(SATELLITE) AND $
       not keyword_set(COMET)     AND $
       not keyword_set(ASTEROID)  then asteroid=1

   ;--I.4.2-- Choose from User-supplied Keywords
    if keyword_set(PLANET)    then type = 'planet'
    if keyword_set(SATELLITE) then type = 'satel'
    if keyword_set(COMET)     then type = 'comet'
    if keyword_set(ASTEROID)  then type = 'aster'

  endif


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Ephemeris Generation       -----------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--II.1-- Heliocentric
  if keyword_set(heliocentric) then $
    eph = call_ephemcc( ID, epoch, type=type, DATELIST=nbd, $
                        /HELIO, /JULIAN, tcoor='1', rPlane=rPlane, Web=keyword_set(Web) )

 ;--II.2-- Geocentric
  if keyword_set(geocentric) then $
    eph = call_ephemcc( ID, epoch, type=type, DATELIST=nbd, $
                        /GEO, /JULIAN, tcoor='1', rPlane=rPlane, Web=keyword_set(Web) )

 ;--II.3-- Topocentric
  if keyword_set(observer) then $
    eph = call_ephemcc( ID, epoch, type=type, DATELIST=nbd, $
                        observer=observer, /JULIAN, tcoor='1', rPlane=rPlane, Web=keyword_set(Web) )

 ;--II.4-- Return
  return, transpose([ [eph.ra.dec], [eph.dec.dec] ])

end