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.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib