RAMSES	Systems Ecology
Start         Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE Regions;

  (*******************************************************************

    Module  Regions     (Version 1.0)

      Copyright (c) 1993-2006 by Dimitrios Gyalistras and ETH Zurich.

    Purpose   Manage geographical regions (polygons), plus
              basic operations related to region data.

    Remarks   --


    Programming

      o Design
        Dimitrios Gyalistras      26/11/1993

      o Implementation
        Dimitrios Gyalistras      26/11/1993


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  18/11/1996  DG

  *******************************************************************)


  CONST
    MaxPoints = 8*1024-1;
    undefinedRegion = MIN(INTEGER);

  TYPE
    RealVecPtr       = POINTER TO RealVec;
    RealVec          = ARRAY [1..MaxPoints] OF REAL;
    RegionChange     = (regionDefined, regionReplaced, regionRemoved);
    AtRegionChangeP  = PROCEDURE( RegionChange,      (* signifies type of change *)
                                  INTEGER        );  (* number of the region affected *)

    AtReadDataPointP = PROCEDURE( VAR REAL,          (* x-Coordinate *)
                                  VAR REAL,          (* y-Coordinate *)
                                  VAR ARRAY OF CHAR  (* error text to pass on *)
                                ): BOOLEAN;          (* if false, reading stops *)

    CalcDistanceP    = PROCEDURE( REAL, REAL,        (* x1/y1 *)
                                  REAL, REAL         (* x2/y2 *)
                                ): REAL;             (* the distance *)


  (*--------------------------------------------------------------------------*)
  (*                         Calculation of distances                         *)
  (*--------------------------------------------------------------------------*)


  PROCEDURE SetCalcDistanceP( calcDistP: CalcDistanceP );


  PROCEDURE GetCalcDistanceP( VAR calcDistP: CalcDistanceP );



  (*--------------------------------------------------------------------------*)
  (*                     Definition and removal of regions                    *)
  (*--------------------------------------------------------------------------*)


  PROCEDURE DefineRegionsFromFile( fileName        : ARRAY OF CHAR;
                                   atReadDataPoint : AtReadDataPointP;
                                   progrReprt      : PROC;
                                   replaceExisting : BOOLEAN;
                                   VAR nDefined    :INTEGER ;
                                   VAR errTxt      : ARRAY OF CHAR );
    (*
      Reads region data from the file "fileName" and returns in
      "nDefined" the number of regions actually (re)defined based
      on the contents of this file. If "nRead=-1", an error
      occurred which is explained in "errTxt".
      If "replaceExisting=TRUE" and in the file was found a region
      with the number of an already defined region, the latter will
      be redefined, i.e. replaced by the newly read region. Otherwise
      the region read from the file is neglected.
      Procedure "progrReprt" is called each time a region has been
      scanned from the file.
    *)


  PROCEDURE SimplifyRegionBoundaries( inFileName      : ARRAY OF CHAR;
                                      outFileName     : ARRAY OF CHAR;
                                      atReadDataPoint : AtReadDataPointP;
                                      progrReprt      : PROC;
                                      minDist         : REAL;
                                      idOffset        : INTEGER;
                                      VAR nSimplified :INTEGER ;
                                      VAR errTxt      : ARRAY OF CHAR );
    (*
      Reads region data from the file "inFileName", simplifies the
      boundaries of all regions by replacing - wherever possible -
      all points less than "minDist" apart by a single point, and
      writes the result to file "outFileName". "nSimplified"
      returns the number of regions processed.
      NOTE: This procedure is particularly usefull, if a region is
      defined by more than "MaxPoints" and can thus not be read
      from file using procedure "DefineRegionsFromFile".
    *)


  PROCEDURE DefineRegion( rNr          : INTEGER;
                          name         : ARRAY OF CHAR;
                          cntrX, cntrY : REAL;
                          nPoints      : INTEGER;
                          xC, yC       : ARRAY OF REAL;
                          VAR errTxt   : ARRAY OF CHAR ): BOOLEAN;
    (*
      Defines a region. If a region with number "rNr" already exists,
      it is redefined.  In case of an error the procedure returns
      FALSE and an explanation in "errTxt"; if a region "rNr" already
      already existed, it is left untouched.
    *)


  PROCEDURE RemoveRegion( rNr: INTEGER );


  PROCEDURE RemoveAllRegions;


  PROCEDURE InstallAtRegionsChangedHandler( rch: AtRegionChangeP );
    (*
      This procedure allows to install a handler "rch" which is called
      each time a change in the regions occurs.
    *)


  (*--------------------------------------------------------------------------*)
  (*                 Retrieval of regions and their attributes                *)
  (*--------------------------------------------------------------------------*)


  PROCEDURE NRegions():INTEGER;


  PROCEDURE RegionExists( rNr:INTEGER ): BOOLEAN;


  PROCEDURE GetRegionNumbers( VAR rNum    : ARRAY OF INTEGER;
                              VAR nRegions: INTEGER);


  PROCEDURE GetRegionAttrs( rNr: INTEGER;
                            VAR name: ARRAY OF CHAR;
                            VAR left: BOOLEAN;
                            VAR cntrX, cntrY,
                                minX, minY,
                                maxX, maxY,
                                meanDist: REAL): BOOLEAN;
    (*
      Returns attributes of region "rNr". Returns FALSE if the
      region was not found.
    *)


  PROCEDURE GetRegionCoords( rNr: INTEGER;
                             VAR nElems: INTEGER;
                             VAR xC, yC: RealVecPtr): BOOLEAN;
    (*
      Returns number of elements and pointers to coordinate vectors
      of region "rNr".  Returns FALSE if the region was not found.
    *)


  (*--------------------------------------------------------------------------*)
  (*                         Geographical relationships                       *)
  (*--------------------------------------------------------------------------*)


  PROCEDURE InRegion( rNr: INTEGER; xC, yC: REAL ): BOOLEAN;
    (*
      Returns TRUE if point with coordinates "xC,yC" is within
      region "rNr".
    *)


  PROCEDURE RegionOfPoint( xC, yC: REAL ): INTEGER;
    (*
      Returns the number of the first found region which contains the
      point with coordinates "xC,yC".  Returns undefinedRegion, if no
      region is found.
    *)


  PROCEDURE ClosestBoundary( rNr: INTEGER; xC, yC: REAL;
                             VAR xB, yB, dist: REAL);
    (*
      Returns in "xS,yS" the coordinates of the closest point to "xC,yC"
      on the boundary of region "rNr".  "dist" is the corresponding
      distance.  It is >0, if the point is outside the region,
      otherwise <0.
    *)


END Regions.