INTERFACE SMCircle;
(* 
   In this module, we implement a representation of circles on the
   sphere "S2", named "Scircles", using a quadruple of values
   ((a,b,c,d)). This quadruple corresponds to the coefficients of
   "supporting plane" of the circle whose intersection with "S2"
   determines it.
  
   Let "c" be an "SCircle". We will denote by "splane(c)" the
   supporting plane of "c". The hemisphere that is on the positve side
   of "splane(c)" is named "scap(c)" and the center of "scap(c)" is
   the "scenter(c)". The lenght of the spherical arc that joins
   "scenter(c)" to any point on "c" is called "sradius(c)".

   Created 27/06/95 by Marcus Vinicius A. Andrade.
   Last edited : Nov 01, 97 -- Marcus Vinicius A. Andrade.     *)
   
IMPORT SMPoint, I4, HI3, Rd, Wr, Thread, Lex;

EXCEPTION ValidationError(TEXT);

TYPE T = RECORD 
           s : I4.T;       (* s[0..3] correspond to ((a,b,c,d))     *)
         END;
     
PROCEDURE IsValidScircle(READONLY c: T) : BOOLEAN;
  (* 
    Returns true if "c" defines an Scircle, that is, if and only if 
    c_0^2 <= c_1^2+c_2^2+c_3^2             *)
     
PROCEDURE AreCirclesEqual(READONLY c1,c2: T) : HI3.Sign;
  (*
    Returns +1 if "c1 = c2", -1 if "c1 = -c2" and 0 otherwize.            *)

PROCEDURE InvCircle(READONLY c: T) : T;
  (*
    Returns an Scircle with opposite orientation to "c". *)

PROCEDURE CircleFromPlane(READONLY p: HI3.Plane) : T RAISES {ValidationError};
  (* 
    Returns the coefficients of the Scircle defined by the plane "p",
    that is , the coefficients of the circle corresponding to the 
    intersection between the plane "p" and the sphere "S2". *)

PROCEDURE PlaneFromCircle(READONLY c: T) : HI3.Plane;
  (* 
    Returns the coefficientes of the plane whose intersection with "S2" 
    defines the circle "c". *)
   
PROCEDURE SCenter(READONLY c: T): SMPoint.BT;  
  (* 
    Returns the homogeneous coordinates of the point "p" on the sphere 
    "S2" such that "scenter(c)=p".  *)
       
PROCEDURE SRadius(READONLY c: T): LONGREAL; 
  (* 
    Returns the length of the spherical arc "r" connecting "scenter(c)"
    to another point on "c". *)
   
PROCEDURE DCenter(READONLY c: T): HI3.Point;
  (*
    Returns the "dcenter" of the \Scircle "c" .    *)

PROCEDURE DRadius(READONLY c: T): LONGREAL;
  (*
    Returns the "dradius" of the \Scircle "c" .    *)

PROCEDURE Snormal(READONLY c: T): HI3.Point;
  (*
    Returns the point of "T3" at infinity in the normal direction of 
    the plane "\splane(c)".                                          *)

PROCEDURE Intersection(READONLY c1,c2: T; VAR p: SMPoint.CT; 
                           VAR aretangent: BOOLEAN) : BOOLEAN;  
  (* 
    Returns TRUE if the circles "c1" and "c2" intersects; in this
    case, stores in "p" this intersection point. The parameter "aretangent" 
    is set to TRUE if the circles are tangent. 
    
    Since the circles are oriented, there is only one intersection
    point, and this point is represented by the Plucker coefficients
    of the line "l" such that "exit(l) = p". If the scircles doesn't
    intersect then the value in "p" is set to <<0,0,...,0>>" *)
    
PROCEDURE CircleFromSCenterAndSRadius(READONLY p: SMPoint.BT; READONLY r: LONGREAL; 
                                      READONLY eps: LONGREAL:=1.0d-6): T;
  (* 
    Returns the circle "c" which "scenter(C)" is  "p" and 
    "abs(r - sradius(c)) <= eps".                                  *)

PROCEDURE ApInCircle(READONLY p: SMPoint.AT; READONLY c: T) : BOOLEAN;
  (*
    Returns TRUE if the Apoint "p" lies on the circle "c".             *)
    
PROCEDURE BpInCircle(READONLY p: SMPoint.BT; READONLY c: T) : BOOLEAN;
  (*
    Returns TRUE if the Bpoint "p" lies on the circle "c".             *)
 
PROCEDURE CpInCircle(READONLY p: SMPoint.CT; READONLY c: T) : BOOLEAN;
  (*
    Returns TRUE if the Cpoint "p" lies on the circle "c".             *)

PROCEDURE SpInCircle(READONLY p: SMPoint.S2; READONLY c: T) : BOOLEAN;
  (*
    Returns TRUE if the Spoint "p" lies on the circle "c".             *)

PROCEDURE Read(rd: Rd.T) : T RAISES{Rd.Failure, Thread.Alerted, Lex.Error, ValidationError};
  (* 
    Reads an scircle on the reader "rd".                           *)

PROCEDURE Print(wr: Wr.T; READONLY s: T) RAISES{Wr.Failure, Thread.Alerted};
  (*
    Prints an scircle on the writer "wr".                          *)

END SMCircle.