INTERFACE SMap;
(* 
   This interface defines the structure 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 TMC 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;
    delIsolatedVertex(v: Corner) RAISES {ValidationError};
    makeEdge(c: Circle; p: Point:=NIL; q: Point:=NIL) : Corner;
    delEdge(e: Corner);
    pointLocation(p: Point) : REFANY;
    whereTo(v: Corner; c: Circle; VAR e: Corner): REFANY RAISES {ValidationError};
    whichEdge(v: Corner; c: Circle): Corner;
    intersectEdgeAndElement(e: Corner; AlsoBreak: BOOLEAN;
                       elem: REFANY; startingface:Face:=NIL) : ListOfInterPoints; 
    numerate();
    read(name: TEXT);
    write(name: TEXT; comment: TEXT);
    draw(name: TEXT);
  END; 

PROCEDURE Overlay(filename1,filename2 : TEXT) : T;
  (* 
     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.  

  makeEdge(m: T; p,q: VGType; c: Circle) : Corner;
    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".   
     
  whereTo(v: Corner; c: Circle; VAR e: Corner): REFANY;
    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  "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 of its edges 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 points of intersection where each
    item in the list give us the point's coordinates and which corner
    (edge) of the map originated that point. 
    
  *)
    
END SMap.