INTERFACE SMap;
(* 
   This interface defines the structure of and operations on spherical
   maps. The elements composing a spherical map are:
   
       - a Vertex is a C-point on the sphere and can be either an 
         isolated vertex or a vertex adjacent to an edge. 
         
       - an Edge can be either an entire scircle (an oval) or an arc of
         scircle bounded by two vertices (an origin and a
         destination).  In this case, the edge is defined as the arc
         of circle from origin to destination in the positive
         direction of the scircle.
         
       - a Face is a spherical surface region whose boundary consists
         of a set of borders. Each border is either an isolated vertex
         or a (connected) circular alternate sequence of incident
         edges and vertices (both adjacent to that face).
         
   We will represent a map as a reference to one of its face.         
         
   Created in May 14, 1997 by Marcus Vinicius A. Andrade
   Lasted edited in Sep. 18, 1997 by Marcus Vinicius A. Andrade.     
*)


FROM SMGeo IMPORT Point, Circle;
FROM SMC IMPORT Map, Face, Corner; 

EXCEPTION ValidationError(TEXT);

TYPE 
  InterPoint        <: REFANY;
  ListOfInterPoints <: REFANY;
  
  (* ======== the OBJECT map ======== *)
  T <: PublicMap;
  PublicMap = Map OBJECT 
  METHODS
    init() : T;
    makeVertex(p: Point) : Corner RAISES ANY;
    delIsolatedVertex(v: Corner) RAISES {ValidationError};
    makeEdge(c: Circle; p: Point:=NIL; q: Point:=NIL) : Corner RAISES ANY;
    delEdge(e: Corner);
    pointLocation(p: Point) : REFANY RAISES ANY;
    whereTo(v: Corner; c: Circle; VAR e: Corner): REFANY RAISES ANY;
    whichEdge(v: Corner; c: Circle): Corner RAISES ANY;
    intersectEdgeAndElement(e: Corner; AlsoBreak: BOOLEAN;
                       elem: REFANY; startingface:Face:=NIL) : ListOfInterPoints RAISES ANY; 
    numerate() RAISES ANY;
    read(name: TEXT) RAISES ANY;
    write(name: TEXT; comment: TEXT) RAISES ANY;
    draw(name: TEXT) RAISES ANY;
  END; 

PROCEDURE Overlay(filename1,filename2 : TEXT) : T RAISES ANY;
  (* 
     Reads files "filename1" and "filename2" an returns the map corresponding to 
     the overlay of the maps *)
   

(* ---------------------------------------------------------------- *)
(*                    Methods of the type Map.T                     *)
(* ---------------------------------------------------------------- *)
(*
  init();
    Creates an empty map, that is, a map composed by just one
    face consisting of the whole spherical surface.  

  makeVertex(p: Point) : Corner;
    Creates a vertex with geometry "p" on the map "m".  Firstly,
    locates "p" on the map. If "p" lies on a face "f" then creates an
    isolated vertex on "f". The creation of an isolated vertex implies
    the creation of a new border on the face "f". In this case,
    returns the corner representing the isolated vertex created.
    On the other hand, if "p" lies on an edge "e" then splits "e" and 
    creates two new edges in the map. Returns the corner
    corresponding to the (new) edge in a same direction to the
    original edge "e".  
   
  delIsolatedVertex(v: Corner);
    Deletes the isolated vertex "v". Also, eliminates the border
    corresponding to this vertex.  (---- Not implemented yet ----)

  makeEdge(m: T; p,q: VGType; c: Circle) : Corner RAISES ANY;
    Given two points "p" and "q", inserts these points in the map "m"
    and connects them by an edge whose geometry is given by scircle
    "c".  We have the following cases:
      . if "p" and "q" are "nil" then creates an entire circle;
      . if "p" is equal to "q" then creates a loop
      . if "p" is different to "q" then makes an ordinary edge.
          
  delEdge(e: Corner);
    Deletes the edge "e" of the map "m".  (---- Not implemented yet ----)
     
  whereTo(v: Corner; c: Circle; VAR e: Corner): REFANY RAISES ANY;
    Given an scircle "c" passing through the vertex "v", returns the
    element (face or edge) incident to "v" in which we would be if,
    from "v", we move a sufficiently small distance forward, i.e. in
    the positive direction of "c". Also, stores in "e" the edge whose
    left face is that face.

  whichEdge(v: Corner; c: Circle): REFANY;
    Given an scircle "c" passing through the vertex "v", returns the
    next edge crossing "c" that will be reached when, from "v", we
    move forward, i.e. in the positive direction of "c". 

  locatePoint(m: T; p: Point) : REFANY ;
    Given the point "p", returns the element (vertex, edge or face) of
    the map "m" containing "p". 
  
  walkOnBorder(b: Border; P: PROCEDURE (e: Corner; ir: REFANY:=NIL); 
                          r: REFANY:=NIL) : SetOfFaces.T;
  walkOnFace(f: Face; P: PROCEDURE (e: Corner; ir: REFANY); 
                      r: REFANY:=NIL) : SetOfFaces.T;
  walkOnMap(m: T; P: PROCEDURE (e: Corner; ir: REFANY:=NIL); r: REFANY:=NIL);
    These three procedures walk respectively around the border "b",
    the face "f" and the map "m" passing on all the edges of the
    border, or face or map and performing the procedure P on each
    edge. Besides, the procedure "WalkOnBorder" returns the set of all
    right faces adjacent to the border "b" and "WalkOnFace" returns
    the set of all right faces adjacent to all of its borders.

  intersectEdgeWithMap(m: T; e: Corner): InterPoint;
    Given the edge "e" computes its intersection with all edges of the
    map "m"; returns the list of pairs "(p,c)" where "p" is a point of
    intersection and "c" is the corner (i.e., the edge) of the map that 
    originated that point. The list returned gives us all the
    intersection points.  

  *)
END SMap.