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 (a ring) 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 SMCGeo IMPORT PGType, EGType;
FROM SMCTop IMPORT Face, Border, Edge, Vertex;

IMPORT SetOfFaces;

EXCEPTION ValidationError(TEXT);

TYPE 
  T = Face;
  SetOfBorders = Face;
  InterPoint <: REFANY;
  
PROCEDURE CreateMap(): T;
  (*
    Creates an empty map, that is, a map composed by just one face
    consisting of the whole spherical surface.  *)

PROCEDURE MakeVertex(m: T; p: PGType);
  (*
    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".  *)
   
PROCEDURE DelIsolatedVertex(v: Vertex);
  (*
    Deletes the isolated vertex "v". Also, eliminates the border
    corresponding to this vertex.  *)

PROCEDURE MakeRing(m: T; e: EGType);
  (*
    Creates a ring (an entire circle) with geometry given by "e" 
    in the map "m"*)

PROCEDURE DelRing(c: Edge);
  (* 
    Remove the ring (the entire circle) represented by "c"; returns 
    the face corresponding to union of the two faces adjacent 
    to "c" and "c.sym"  *)

(*

PROCEDURE MakeEdge(m: T; p,q: VGType; c: EGType) : Edge;
  (*
    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.
  *)         

PROCEDURE DelEdge(e: Edge);
  (*
    Deletes the edge "e" of the map "m".   *)
     
PROCEDURE InWhichFace(v: Vertex; c: EGType): Face RAISE{ValidationError}; 
  (* 
    Given an scircle "c" passing through the vertex "v", returns the
    face 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". *)

PROCEDURE InWhichEdge(v: Vertex; c: EGType): Face RAISE{ValidationError}; 
  (* 
    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". *)

PROCEDURE PointLocation(m: T; p: PGType) : REFANY;
  (* 
    Given the point "p", returns the element (vertex, edge or face) of
    the map "m" containing "p". *)
  
PROCEDURE BorderLocation(m: T; b: Border) : Face;
  (* 
    Given a border "b" which doesn't intersect any other border of the
    map "m", locates the face of the map where this border have to
    be. *) 
    
*)

PROCEDURE WalkOnBorder(b: Border; P: PROCEDURE (e: Edge; ir: REFANY:=NIL); r: REFANY:=NIL) : SetOfFaces.T;
PROCEDURE WalkOnFace(f: Face; P: PROCEDURE (e: Edge; ir: REFANY); r: REFANY:=NIL) : SetOfFaces.T;
PROCEDURE WalkOnMap(m: T; P: PROCEDURE (e: Edge; 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. *)

PROCEDURE IntersectEdgeWithMap(m: T; e: Edge): 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.