|
|
|
|
||
|
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.
|
||
|
|
|