; docformat = 'rst'
;
; NAME:
;    voVizier_query
; PURPOSE:
;    Retrieve the list of stars in a given FOV from CDS VizieR service.
;    The CDS Client tool vizquery is required.
;    See http://vizier.u-strasbg.fr/doc/vizquery.htx for details
;+
; :Description:
;    Retrieve the list of stars in a given FOV from CDS VizieR service.
;    The CDS Client tool vizquery is required.
;    See http://vizier.u-strasbg.fr/doc/vizquery.htx for details
;
; :Categories:
;    Ephemeris, Catalog
;
; :Params:
;    RA: in, required, type=float/string
;        The Right Ascencion of the Field of View (decimal degree)
;    DEC: in, required, type=float/string
;        The Declination of the Field of View
;    FOV: in, required, type=float/string
;        The size of the field of view (default is degrees)
;    catalog: in, optional, type=string, default=GDR2
;        The name of the star catalog to retrieve (GDR2|GDR1|PPMXL|HIP|UCAC3|UCAC4)
;
; :Keywords:
;    VizieR: in, optional, type=string
;        The path to local CDS client: vizquery
;    MAG: in, optional, type=float
;        A limiting magnitude for catalog sources
;    SITE: in, optional, type=string
;        The site where to send the request (cds|cfa|...)
;    EPOCH: in, optional, type=string, default='J2000'
;        The reference epoch for coordinates (e.g., J2000)
;
;    DUMP: in, optional, type=string
;        A path to a file to export the results
;    MIME: in, optional, type=string, default='csv'
;        Format of the catalog (csv)
;
; :Returns: A structure containing the catalog (ra, dec, mag fields mandatory)
;
; :Uses:
;    voVizieR_read(), ten()
;    vizquery client: http://vizier.u-strasbg.fr/vizier/doc/vizquery.htx
;
; :Examples:
;    IDL> cat=voVizier_query( 10.,10.,0.5 )
;    IDL> cgPlot,cat.ra.dec, cat.dec.dec, psym='Star', /Isotropic
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;    Change History::
;      Original Version written in May 2014, B. Carry (IMCCE)
;      2017 Mar. - B. Carry (OCA) - Improved FOV syntax, mime, and idl2 added
;      2017 May  - B. Carry (OCA) - Added Gaia DR1
;      2018 June - B. Carry (OCA) - Added Gaia DR2!
;-
function voVizieR_query, RA, DEC, FOV, catalog, VizieR=VizieR, $
                         mag=mag, site=site, epoch=epoch, $
                         dump=dump, mime=mime, coord=coord
  COMPILE_OPT hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--I.1-- Input Syntax Verification  ----------------------------------------------------
  if n_params() lt 3 then begin
    message, /ioError, 'Syntax : Stars = voVizier_query( RA, DEC, FOV [, catalog, vizier=, mag=])'
    return, -1
  endif


 ;--I.2-- Set Missing Parameters to Default  --------------------------------------------
  if not keyword_set(site)    then site   ='cds'
  if not keyword_set(mime)    then mime   ='csv'
  if not keyword_set(epoch)   then epoch  ='J2000'
  if not keyword_set(catalog) then catalog='GDR2'


 ;--I.3-- Link to VizieR Query  ---------------------------------------------------------
  if not keyword_set(VizieR) then begin
    spawn, 'command -v vizquery', cmdO, cmdE
    if strCmp(cmdO,'') then begin
      message, /Error, 'CDS client vizquery tool cannot be found'
      return, -1
    endif else VizieR=strTrim(cmdO[0],2)
  endif


 ;--I.4-- Format for Values  ------------------------------------------------------------
  cFMT = '(F11.7)'   ;-Coordinates
  fFMT = '(F)'       ;-FOV
  tFMT = '(D16.8)'   ;-Time
  

;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Interpretation of Input Parameters                 -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;


 ;--II.1-- Coordinates Interpretation  ---------------------------------------------------
 ;--II.1.1-- Right Ascencion
  if size(RA, /Type) eq 7 then begin
    if valid_num(ra) then sRA = strTrim(ra,2) $
                     else sRA = strTrim(string(ten(ra)*15.,format=cFMT),2)
  endif else begin
     sRA = strTrim(string(ra,format=cFMT),2)
  endelse

 ;--II.1.2-- Declination
  if size(DEC,/Type) eq 7 then begin
    if valid_num(dec) then sDEC = strTrim(dec,2) $
                      else sDEC = strTrim(string(ten(dec),format=cFMT),2)
  endif else begin
     sDEC = strTrim(string(dec,format=cFMT),2)
  endelse

 ;--II.1.3-- Target Center
  if float(sDec) ge 0. then sRADEC=' -c='+sRA+'+'+sDEC $
                       else sRADEC=' -c='+sRA+sDEC

 ;--II.1.4-- Decimal or Sexagesimal Output
  if not keyword_set(coord) then coord='d'
  if strcmp(coord,'d',1,/fold) then sCoord=' -oc.form=d' $
                               else sCoord=' -oc.form=s'


 ;--II.2-- Field of View Interpretation  -------------------------------------------------
  case size(FOV, /Type) of

   ;--II.2.1-- Input FOV is a string (XxY,unit)
    7: begin
      if valid_num(fov) then begin
        sFOV = ' -c.rd='+strTrim(string(fov,format=fFMT),2)
      endif else begin
  
        split = strsplit(fov,',',/EXTRACT,count=nbField)
  
        if nbField eq 1 then begin
          sFOV = ' -c.rd='+strTrim(split[0],2) 
        endif else begin
  
          unit = strmid(split[1],0,1)
          XxY = strsplit(split[0],'x',/EXTRACT,count=nbXY)
          if nbXY eq 1 then begin
            sFOV = ' -c.r'+unit+'='+strTrim(string(split[0],format=fFMT),2) 
          endif else begin
            
            sFOV = ' -c.r'+unit+'='+strTrim(string(max(float(XxY)),format=fFMT),2)
          endelse
        endelse

      endelse
    end

   ;--II.2.2-- Input FOV is a structure (X:, Y:, PA:, UNIT:)
    8: begin
      unit = strLowCase(strMid(FOV.unit,0,1))
      radius=max(float([FOV.x,FOV.y]))
      sFOV = ' -c.r'+unit+'='+strTrim(string(radius,format=fFMT),2)
    end

   ;--II.2.3-- Input FOV is a float/integer (RADIUS)
    else: sFOV = ' -c.rd='+strTrim(string(fov,format='(F10.6)'),2)
  endcase



 ;--II.3-- Catalog Interpretation  -------------------------------------------------------
  sOUT=''
  case catalog of
    'GDR2': begin
      sSRC=' -source=I/345/gaia2'
      sOUT+=''
      sPhot='Cmag'
    end

    'GDR1': begin
      sSRC=' -source=I/337/gaia'
      sOUT+=''
      sPhot='Cmag'
    end

    'PPMXL': begin
      sSRC=' -source=I/312'
      sOUT+=' -out=_RAJ2000,_DEJ2000,Cmag,PPMXL'
      sPhot='Cmag'
    end

    'HIP': begin
      sSRC=' -source=I/149A'
      sOUT+=' -out=_RAJ2000,_DEJ2000,Vmag,recno'
      sPhot='Vmag'
    end

    'UCAC3': begin
      sSRC=' -source=I/315'
      sOUT+=' -out=_RAJ2000,_DEJ2000,R2mag,3UC'
      sPhot='R2mag'
    end

    'UCAC4': begin
      sSRC=' -source=I/322A'
      sOUT+=' -out=_RAJ2000,_DEJ2000,Vmag,UCAC4'
      sPhot='Vmag'
    end

    else: begin
      message, 'Only Gaia DR1, PPMXL, HIP, UCAC3, and UCAC4 catalogs are allowed, using PPMXL as default'
      sSRC=' -source=I/312'
      sOUT+=',Cmag,PPMXL'
      sPhot='Cmag'
    end
  end



 ;--II.4-- Limiting Magnitude (optional)  ------------------------------------------------
  if keyword_set(mag) then begin
    sMag = ' -sort="'+sPhot+'" '+sPhot+'="<='+strTrim(string(mag,FORMAT='(F)'),2)+'"'
  endif else sMag=' '


 ;--II.5-- General I/O Parameters  -------------------------------------------------------
  sSITE = ' -site='+strTrim(site,2)
  sMIME = ' -mime='+strTrim(mime,2)
  sEPOCH= ' -c.eq='+strTrim(epoch,2)
  if keyword_set(dump) then sDump=' > '+strTrim(dump,2) $
                       else sDump=''







;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---  III -- Request VizieR and Analyze Results                 -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--III.1-- Generate URL line -------------------------------------------------------------
  sTarget = sRADEC+sEPOCH+sFOV
  sOption = sMIME+sSITE+sCoord
  sCatalog= sSRC+sOUT+sMag

 ;--III.2-- Call VizieR  ------------------------------------------------------------------
;  print, VizieR+sTarget+sOption+sCatalog+sDump
  spawn, VizieR+sTarget+sOption+sCatalog+sDump, vizO, vizE

 ;--III.3-- Analyze Results  --------------------------------------------------------------
  if keyword_set(dump) then stars = voVizieR_read( dump, mime=mime ) $
                       else stars = voVizieR_read( vizO, mime=mime )

  return, stars

end