; docformat = 'rst'
;
; NAME: 
;    angularRes
; PURPOSE:
;    Evaluate the diffraction-limited angular resolution of a
;    telescope given its aperture and the wavelength of the light.
;
;+
; :Description:
;    Evaluate the diffraction-limited angular resolution of a
;    telescope given its aperture and the wavelength of the light.
;
; :Categories:
;    Observations
;    
; :Params:
;    L: in, required, type=float
;        Wavelength of the light (micron)
;    D: in, required, type=float
;        Aperture of the telescope (m)
;
; :Returns: The diffraction-limited angular resolution 
;
; :Keywords:
;    MAS: in, optional, type=boolean, default=0
;        If set, returns the angular resolution in milli-arseconds
;    ARCSEC: in, optional, type=boolean, default=1
;        If set, returns the angular resolution in arseconds
;    DEGREE: in, optional, type=boolean, default=0
;        If set, returns the angular resolution in decimal degrees
;    RADIAN: in, optional, type=boolean, default=0
;        If set, returns the angular resolution in radians
;    AU: in, optional, type=float
;        Distance to the target in AU. If set, returns the spatial resolution in km
;    KM: in, optional, type=float
;        Distance to the target in km. If set, returns the spatial resolution in km
;
; :Examples:
;    Compute the angular resolution of the VLT at 2.2 micron::
;      IDL> print, angularRes(2.2, 8.2, /ARCSEC)
;
; :Author:
;    B.Carry (IMCCE)
;
; :History:
;     Change History::
;        Original Version written in June 2013, B. Carry (IMCCE)
;        2013 Sep. - B.Carry (IMCCE) - Header for idldoc
;-
function angularRes, L, D, $
                    ;-Unit for the angular resolution
                     MAS=MAS, ARCSEC=ARCSEC, DEGREE=DEGREE, RADIAN=RADIAN, $
                    ;-Unit for the distance
                     AU=AU, KM=KM

 ;--I-- Initialization And Input Verification -------------------------------
 ;--I.1-- Check Presence of Arguments
  if N_params() LT 2 then begin
    message, /INFO, ' Syntax -  RES =  ANGULARRES( L, D )'
    return, -1
 endif
  
 ;--I.2-- Default Output Dimension
  if not keyword_set( RADIAN ) and $
     not keyword_set( DEGREE ) and $
     not keyword_set( ARCSEC ) and $
     not keyword_set( MAS    ) and $
     not keyword_set( AU     ) and $
     not keyword_set( KM     ) then ARCSEC=1


 ;--II-- Compute Angular Resolution ------------------------------------------
 ;--II.1-- All units
  thetaRAD = (l*1e-6)/d
  thetaDEG = thetaRAD/!DTOR
  thetaARC = thetaDEG*3600.
  thetaMAS = thetaARC*1000.

 ;--II.2-- Return Angular Resolution 
  if keyword_set( RADIAN ) then return, thetaRAD
  if keyword_set( DEGREE ) then return, thetaDEG
  if keyword_set( ARCSEC ) then return, thetaARC
  if keyword_set( MAS    ) then return, thetaMAS


 ;--III-- Compute Spatial Resolution ------------------------------------------
  AUtoKM    = 149597870.691D
  if keyword_set( KM ) then return, KM*       atan(thetaRAD)
  if keyword_set( AU ) then return, AU*AUtoKM*atan(thetaRAD)


  
end