; docformat = 'rst'
;
; NAME: 
;    evalCircle
; PURPOSE:
;    Evaluate the ordinate (Y) coordinates of points on a circle from an array of
;    abscissa (X) and circle parameters.
;
;+
; :Description:
;    Evaluate the ordinate (Y) coordinates of points on a circle from an array of
;    abscissa (X) and circle parameters.
;
; :Categories:
;    Maths, Evaluation
;    
; :Params:
;    X: in, required, type=float
;        Array (any dimension) of x values.
;    P: in, required, type=float
;        The parameters of the circle::
;          P[0] = X center
;          P[1] = Y center
;          P[2] = Radius
;
; :Returns: The evaluated ordinates at positions X
;
; :Examples:
;    Draw a Circle of radius 10 centered on (50,25) and evaluate the
;    ordinates for integer X.::
;      IDL> x=indgen(100)
;      IDL> p=[50,25,10]
;      IDL> y= evalcircle(x,p)
;      IDL> ; plot the circle
;      IDL> theta=2*!PI*findgen(361)/360.
;      IDL> plot, p(0)+p(2)*cos(theta), p(1)+p(2)*sin(theta), /ISO, xr=[0,100]
;      IDL> ; plot the evaluated points 
;      IDL> oplot, x, y(0,*), psym=4
;      IDL> oplot, x, y(1,*), psym=4
;
; :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 evalCircle, X, P


 ;--I-- Initialization And Input Verification
 ;--I.1-- Check Presence of Arguments
  if N_params() LT 2 then begin
    message, /INFO, ' Syntax -  Y =  EVALCIRCLE( X, P )'
    return, -1
 endif

 ;--I.2-- Convert Inputs to Float
  X=float(X)
  P=float(P)

 ;--II-- Circle Evaluation
  return, y = p(1) + [-1,1.]#sqrt( p(2)*p(2) - (x-p(0))*(x-p(0)) )

end