; docformat = 'rst'
;
;+
; NAME: 
;    PDS_lcParam_GetCatalog
; PURPOSE:
;    Returns the content of the catalog of lightcurve derived parameter
;    (from PDS) for a specific target or simply dump the catalog into a structure
;
;+
; :Description:
;    Returns the content of the catalog of lightcurve derived parameter
;    (from PDS) for a specific target or simply dump the catalog into a structure
;
;    The PDS LC catalog list many parameters (period, spin axis,
;    binarity...) of asteroids based on lightcurves analyses.
;    Reference: "Harris, A.W., Warner, B.D., and Pravec, P., Eds.,
;    Asteroid Lightcurve Derived Data
;    V13.0. EAR-A-5-DDR-DERIVED-LIGHTCURVE-V13.0. NASA Planetary Data
;    System, 2012." 
;
; :Categories:
;    PDS, Asteroid, Lightcurve
;    
; :Params:
;    id: in, required, type=integer/string
;        Target identifyer ('*', Name, Provisional designation, Number) 
;
; :Returns: A structure containing the desired content of the
;        Lightcurve Parameter catalog. Fields are::
;
; :Keywords:
;    PDS: in, optional, type=string
;        Path to the PDS catalog file
;    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::
;          [Repositery from PDS]
;             lcparam = PATH_TO_YOUR_PDS_REPOSITERY/data/
;    dump: in, optional, type=boolean, default=0
;        Set this keyword to return the whole PDS file
;    verbose: in, optional, type=boolean, default=0
;        Trigger dialog with user
;
; :Uses:
;    initIdl, astNameFormat, designation, readfmt
;
; :Examples:
;    Retrieve and print the rotation period of (2) Pallas
;      IDL> info = PDS_lcParam_getCatalog( 2 ) 
;      IDL> print, 'Rotation period:'+string(info.p.val,format='(F9.5)')+' h'
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;     Change History::
;       Original Version written in November 2013, B. Carry (IMCCE)
;       2013 Dec. - B.Carry (IMCCE) - Comments compliant idldoc RST format
;       2015 Jan. - B.Carry (OCA) - Added idl2 compile option
;       2016 July - B.Carry (OCA) - Finalize reading of all columns
;-
function PDS_lcParam_getCatalog, ID, PDS=PDS, CONFIG=CONFIG, DUMP=DUMP, VERBOSE=VERBOSE



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

 ;--I.1-- Set IDL to Local Working Environment  -----------------------------------------
  if not keyword_set(PDS) then begin

    if not keyword_set(CONFIG) then begin
      config = initIDL(/CATALOG)
    endif
    PDS = config.pds.lcparam

  endif


 ;--I.2-- Table Selection  --------------------------------------------------------
;  if not keyword_set(DIAMETER) then TIMINGS=1

 ;--I.3-- Dump mode Exception  ----------------------------------------------------
  if keyword_set(DUMP) then ID='*'


 ;--II.4-- Designation Interpretation  ---------------------------------------------
  if not keyword_set(DUMP) and not strcmp(ID,'*') then begin

   ;--II.4.1-- Identify Input Type  ---------------------------------------------------
    trash = astnameformat(ID, TYPE=idType )
 
   ;--II.4.2-- Set Asteroid IAU Number  -----------------------------------------------
    if idType eq 1 then begin
      num = ID
      des = designation(ID)
    endif else begin
      num = designation(ID) 
      des = strtrim(ID,2)
    endelse
    if num eq 0 then num=-1
  endif


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Lightcurve Summary Table                           -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
summary=1
  if keyword_set(summary) then begin


   ;--II.1-- Output Structure Definition  --------------------------------------------
    empty={num: 0L, des: '', alt:'', bin:'', notes:'', $
           p: {val: 0., flag:'', note:'', qual:''}, $
           a: {min: 0., max:0., flag:''}}


   ;--II.2-- Read PDS File  ----------------------------------------------------------
   ;--II.2.1-- Check Existance of the File
    PDS += 'lc_summary.tab'
    if not file_test(PDS,/read) then begin
      message, /INFO, 'PDS file not found: '+strtrim(PDS,2)
      return, empty
    endif

   ;--II.2.2-- Read the content
    readfmt, pds, '(F7,1x,A17,1x,A10,1x,A10,1x,A1,1x,A15,1x,F14.8,1x,A1,1x,F4.2,1x,F4.2,1x,A2,1x,A5,1x,A1)', $
             pdsNUM, pdsNAME, pdsDES, pdsALT, pdsPF, pdsPN, pdsP, $
             pdsAF, pdsAMin, pdsAMax, pdsPQ, pdsNotes, pdsBin, /SILENT
    pdsNUM = round(pdsNUM)
    pdsNAME= strtrim(pdsNAME,2)
    pdsDES = strtrim(pdsDES,2)
    nbPDS = n_elements(pdsNUM)


   ;--II.3-- Line Selection  --------------------------------------------------------
   ;--II.3.1-- Complete Dump of the PDS Archive
    if keyword_set(dump) or strcmp(ID,'*',1) then begin
      sel=indgen(nbPDS)
      nbSel=nbPDS
  
   ;--II.3.2-- Only a Specified Target
    endif else begin
      sel=where( num eq pdsNUM or strcmp(des,pdsNAME,/FOLD) or strcmp(des,pdsDES,/FOLD), nbSel )
  
    endelse
  
  
   ;--II.3.3-- Target not Found Exception  -------------------------------------------
    if nbSel eq 0 then begin
      if keyword_set(VERBOSE) then message, /INFO, 'Target not found: '+strtrim(string(ID,format='(A)'),2)
      return, empty
    endif
  
  
   ;--II.4-- Result Concatenation and Output  ----------------------------------------
   ;--II.4.1-- Create the Output Structure  --------------------------------------------
    result = replicate(empty,nbSel)
  
   ;--II.4.2-- Fill the Structure  -----------------------------------------------------
    for kSel=0, nbSel-1 do begin

     ;--II.4.2/a-- Target Information
      result[kSel].num = pdsNUM[sel[kSel]]
      result[kSel].des = strtrim(pdsName[sel[kSel]],2)
      if strCmp(result[kSel].des,'-',1) then result[kSel].des = strtrim(pdsDES[sel[kSel]],2)
      result[kSel].alt = strtrim(pdsALT[sel[kSel]],2)
      result[kSel].notes = strtrim(pdsNotes[sel[kSel]],2)
      result[kSel].bin = strtrim(pdsBIN[sel[kSel]],2)

     ;--II.4.2/b-- Period 
      result[kSel].p   = {val: pdsP[sel[kSel]], flag: pdsPF[sel[kSel]], $
                          note: strtrim(pdsPN[sel[kSel]],2), qual:strtrim(pdsPQ[sel[kSel]])}

     ;--II.4.2/c-- Amplitude
      result[kSel].a   = {min: pdsAMin[sel[kSel]], max: pdsAMax[sel[kSel]], flag: strtrim(pdsAF[sel[kSel]],2)}

    endfor
  
   ;--II.4.3-- Return the Result  ------------------------------------------------------
    return, result


  endif








end