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

DEFINITION MODULE RegionsArcs;

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

    Module  RegionsArcs     (Version 1.0)

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

    Purpose   Manage geographical regions (polygons) and arcs
              (x/y coordinate pairs defining a line), plus
              basic operations related to these data types.

    Remarks   This module can read files as generated
              by the ArcInfo software.


    Programming

      o Design
        Dimitrios Gyalistras      26/11/1993
        Andreas Fischlin          23/06/1999

      o Implementation
        Dimitrios Gyalistras      26/11/1993
        Andreas Fischlin          23/06/1999


    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:  30/10/2004  AF

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


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

  TYPE
    RealVecPtr       = POINTER TO RealVec;
    RealVec          = ARRAY [1..MaxPoints] OF REAL;
    RegArcChange     = (regArcDefined, regArcReplaced, regArcRemoved);
    AtRegArcChangeP  = PROCEDURE( RegArcChange,      (* 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 *)
    AtWriteRegArcP   = PROCEDURE( INTEGER,           (* region/arc number *)
                                  VAR ARRAY OF CHAR, (* region/arc name, VAR speed-up only *)
                                  VAR ARRAY OF CHAR  (* error text to return if you return FALSE *)
                                ): BOOLEAN;          (* if false, writing stops *)

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

    OperateOnRegArcP = PROCEDURE( INTEGER            (* region/arc number *)
                                ): BOOLEAN;          (* if false, operation stops *)




  (**********************************************************)
  (*#####   Definition and removal of regions / arcs   #####*)
  (**********************************************************)

  (*-------------------------*)
  (*=====   Via Files   =====*)
  (*-------------------------*)

  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 DefineArcsFromFile( fileName        : ARRAY OF CHAR;
                                atReadDataPoint : AtReadDataPointP;
                                progrReprt      : PROC;
                                replaceExisting : BOOLEAN;
                                VAR nDefined    :INTEGER ;
                                VAR errTxt      : ARRAY OF CHAR);
    (*
      Similar to DefineRegionsFromFile, but expects arcs in the
      input file "fileName".
    *)

  PROCEDURE DefineRegArcsFromFile( fileName        : ARRAY OF CHAR;
                                   atReadDataPoint : AtReadDataPointP;
                                   progrReprt      : PROC;
                                   replaceExisting : BOOLEAN;
                                   VAR nDefined    :INTEGER ;
                                   VAR errTxt      : ARRAY OF CHAR);

    (*
      Similar to DefineRegionsFromFile, but accepts both
      regions as well as arcs in the input file "fileName".
      However, this procedure works only if the input file
      contains a header.
    *)

  PROCEDURE DumpRegionsToFile    ( fileName        : ARRAY OF CHAR;
                                   atWriteARegArc  : AtWriteRegArcP;
                                   overwrite       : BOOLEAN;
                                   VAR nDumped     : INTEGER;
                                   VAR errTxt      : ARRAY OF CHAR);
    (*
      Dumps all regions currently in memory to the file
      "fileName" (the latter may contain a path).  Procedure
      "atWriteARegArc" is called each time a region is about to
      be dumped to the file.  If "overwrite=TRUE" a possibly
      existing file with the same name is overwritten (BE
      AWARE, may result in data loss!!).  "nDumped" returns the
      number of dumped regions.  Any encountered error is
      explained as returned in "errTxt".
    *)

  PROCEDURE DumpArcsToFile    ( fileName        : ARRAY OF CHAR;
                                atWriteARegArc  : AtWriteRegArcP;
                                overwrite       : BOOLEAN;
                                VAR nDumped     : INTEGER;
                                VAR errTxt      : ARRAY OF CHAR);
    (*
      Dumps all arcs currently in memory to the file "fileName"
      (the latter may contain a path).  Procedure
      "atWriteARegArc" is called each time a region is about to
      be dumped to the file.  If "overwrite=TRUE" a possibly
      existing file with the same name is overwritten (BE
      AWARE, may result in data loss!!).  "nDumped" returns the
      number of dumped arcs.  Any encountered error is
      explained as returned in "errTxt".
    *)


  PROCEDURE SimplifyRegArcBoundaries( inFileName,
                                      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 ConvertARCINFODump ( inFileName,
                                 outFileName     : ARRAY OF CHAR;
                                 containsArcs    : BOOLEAN;
                                 atReadDataPoint : AtReadDataPointP;
                                 progrReprt      : PROC;
                                 overwrite       : BOOLEAN;
                                 idOffset        : INTEGER;
                                 VAR nConverted  : INTEGER ;
                                 VAR errTxt      : ARRAY OF CHAR);
    (*
      Reads data from the file "inFileName" and writes them to
      file "outFileName".  This procedure is particularly
      useful if ARCINFO has generated the "inFileName", which
      does not contain the standard header normally expected by
      this module.  The output will contain such a header,
      which lists all regions/arcs read from file "inFileName".
      "containsArcs" denotes wether the input file contains
      arcs or regions (polygons).  If several regions/arcs with
      the same ID number are found in the input file, this
      routine will try to assign a different ID number, which
      is unique to that region/arc.  In the latter case to
      preserve the information on its origin, the original ID
      number will be written to the output file in form of a
      comment.  If "overwrite=TRUE" a possibly existing file
      with the same name is overwritten (BE AWARE, may result
      in data loss!!).  "nConverted" returns the number of
      regions/arcs processed.  Any encountered error is
      explained as returned in "errTxt".
    *)

  PROCEDURE DummyProgressReport; (* draws waiting symbol *)
  PROCEDURE DummyAtReadDataPointP( VAR x,y: REAL;
                                   VAR errTxt: ARRAY OF CHAR): BOOLEAN;
  PROCEDURE DummyAtWriteARegArcP ( regNr: INTEGER;
                                   VAR regName, errTxt: ARRAY OF CHAR): BOOLEAN;


 (*------------------------------------*)
 (*=====   Via Client Interface   =====*)
 (*------------------------------------*)

  PROCEDURE DefineRegion( raNr          : 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 "raNr" already
      exists, it is redefined.  In case of an error the
      procedure returns FALSE and an explanation in "errTxt";
      if a region "raNr" already exists, it is left untouched.
    *)

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

  PROCEDURE RemoveRegArc( raNr: INTEGER);


  PROCEDURE RemoveAllRegArcs;
  PROCEDURE RemoveAllRegions;
  PROCEDURE RemoveAllArcs;


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


  (***************************************************************)
  (*#####   Accessing regions / arcs and their attributes   #####*)
  (***************************************************************)


  PROCEDURE RegArcExists( raNr:INTEGER ): BOOLEAN;

  PROCEDURE NRegArcs(): INTEGER; (* 1, 2, ... NoRegArcs *)
  PROCEDURE NRegions(): INTEGER; (* 1, 2, ... NoRegions *)
  PROCEDURE NArcs(): INTEGER;    (* 1, 2, ... NoArcs *)

  PROCEDURE RegArcNr(i: INTEGER): INTEGER;
    (* returns nr of i'th region/arc, given i IN [1,NoRegArcs] *)
  PROCEDURE RegionNr(i: INTEGER): INTEGER;
    (* returns nr of i'th region, given i IN [1,NoRegions] *)
  PROCEDURE ArcNr(i: INTEGER): INTEGER;
    (* returns nr of i'th arc, given i IN [1,NoArcs] *)


  PROCEDURE SelectFromRegArcs(dowith: OperateOnRegArcP);
    (*
      Brings up a dialog from which you can select regions/arcs.  Use
      shift for multiple selections.  If the users does not cancel the
      dialog, procedure dowith is called for each region/arc which has
      been selected
    *)

  PROCEDURE GetRegionArcAttributes( raNr: INTEGER;
                                    VAR arcinfoNr: INTEGER;
                                    VAR name: ARRAY OF CHAR;
                                    VAR attr: ARRAY OF CHAR;
                                    VAR isArc: BOOLEAN;
                                    VAR left: BOOLEAN;
                                    VAR cntrX, cntrY,
                                        minX, minY,
                                        maxX, maxY,
                                        meanDist: REAL): BOOLEAN;
    (*
      Returns all attributes of region "raNr" or arc "raNr".
      This occurrs according to the optional extended format.
      The latter features an extra attribute in the header and
      can distinguish between regions and arcs.  Returns FALSE
      if the region or arc was not found.
    *)

  PROCEDURE SetRegionArcAttributes( raNr: INTEGER; name, attr: ARRAY OF CHAR);
    (* Sets the name and attribute of region/arc with number raNr *)

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


  (******************************************)
  (*#####   Calculation of distances   #####*)
  (******************************************)


  PROCEDURE SetCalcDistanceP( calcDistP: CalcDistanceP );


  PROCEDURE GetCalcDistanceP( VAR calcDistP: CalcDistanceP );



  (********************************************)
  (*#####   Geographical relationships   #####*)
  (********************************************)


  PROCEDURE InRegion( rNr: INTEGER; xC, yC: REAL ): BOOLEAN;
    (*
      Returns TRUE if point with coordinates "xC,yC" is within
      region "rNr".  If "rNr" denotes actually an arc, this
      routine returns FALSE.
    *)


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


  PROCEDURE ClosestBoundary( raNr: 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 "raNr".  "dist" is the corresponding
      distance.  It is >0, if the point is outside the region,
      otherwise <0.
    *)


END RegionsArcs.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]