DEFINITION MODULE RegArcHdlr;
(*******************************************************************
Module RegArcHdlr (Version 1.0)
Copyright (c) 1999-2006 by Andreas Fischlin and ETH Zurich.
Purpose Manages regions and arcs for display in a
map window (see MapViewer).
Remarks Regions and arcs to be displayed are
typically generated and output from ArcInfo
(GIS) data bases.
A data base file as generated by ArcInfo can
be directly read by this module. However, it is
highly recommended to translate first the output
files as generated by ArcInfo in order to make
better use of this module. Only minor adjustments
at the begin of each file are needed to conform
to the format required by this module for
full functionality. Note, this module can also
generate files of the required format. The syntax
(in EBNF) of a region/arc input file is (reserved
key words are capitalized):
InputFile = Header
RegionOrArcData {RegionOrArcData} "END"
"END".
Header = ("REGIONS"|"ARCS") "ID_OFFSET" regarcIDOffset
HeaderEntry {HeaderEntry} "END"
HeaderEntry = regarcNr regarcName [regarcAttribute].
RegionOrArcData = regarcNr centerX centerY
BoundCoord {BoundCoord}
"END".
BoundCoord = boundaryX boundaryY.
regarcIDOffset = CARDINAL.
regarcNr = INTEGER.
regarcName = STRING.
regarcAttribute = STRING.
centerX = REAL.
centerY = REAL.
boundaryX = REAL.
boundaryY = REAL.
CARDINAL = {digit}.
INTEGER = ["+"|"-"] {digit}.
STRING = ('"'|"'") {character} ('"'|"'").
REAL = ["+"|"-"] digit {digit} "." digit {digit}
[("E"|"e") ["+"|"-"] digit {digit}].
Any file contains either only regions given in form
of polygons or arcs. Every region or arc is
identified by a unique number = regarcIDOffset +
regarcNr. If the header is missing, it is assumed
that the input file is an ArcInfo output file.
Then it may contain conflicting regarcNr's, which
is not allowed in this module. In this case this
module will try to automatically assign another,
not yet used regarcNr. It is recommended to save
first such data to another file with a header to
avoid any regarcNr conflicts in future uses (the
old ArcInfo number is preserved in form of a
comment). The input file may contain comments
enclosed by "(*" and "*)".
Dependencies: uses RAMSES plus modules MapViewer
and Regions from RAMSES ScienceLib.
Programming
o Design
Andreas Fischlin 16/06/1999
o Implementation
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: 16/06/1999 AF
*******************************************************************)
CONST
undefinedRegArc = MIN(INTEGER);
(**********************************************)
(*##### Management of region handler #####*)
(**********************************************)
PROCEDURE UseRegionArcHandler;
PROCEDURE RegionArcHandlerIsInUse(): BOOLEAN;
PROCEDURE UnuseRegionArcHandler;
(***************************************)
(*##### Management of regions #####*)
(***************************************)
PROCEDURE LoadRegArcs(pfn: ARRAY OF CHAR);
PROCEDURE LoadRegions(pfn: ARRAY OF CHAR);
PROCEDURE LoadArcs(pfn: ARRAY OF CHAR);
(*
Loads all regions or arcs defined in the file denoted by pfn into
memory for subsequent drawing and other operations (e.g. all
routines offered by ScienceLib module RegionsArcs can be used for
this purpose). LoadRegArcs requires a Header in the input file
(see syntax), LoadRegions or LoadArcs accept input files without a
Header, e.g. the can read a file generated by ArcInfo. All
routines require the file to be of the appropriate type, i.e.
either contain only regions (polygons) or only arcs.
Offers a dialog if pfn is the empty string.
Does also compute the so-called base region. The base region is a
unification of all currently loaded regions and is always
(re)computed by this routine.
Any call to a routine simply adds regions/arcs to the already
loaded ones. In case this operation involves a region/arc
which is already loaded, that region/arc is redefined,
i.e. the previously loaded verision is replaced with the new
one. The only criteria for recognizing duplicates is its
regarcNr (see syntax and/or ScienceLib module RegionsArcs).
*)
PROCEDURE UnloadRegArcs;
(*
Unloads all regions currently loaded from previous calls
to LoadRegArcs, LoadRegions, or LoadArcs and frees the memory.
*)
PROCEDURE SaveRegions(VAR (*In/Out*) pfn: ARRAY OF CHAR);
PROCEDURE SaveArcs(VAR (*In/Out*) pfn: ARRAY OF CHAR);
(*
Saves all currently known (loaded) regions or arcs to the file as
given by the path name specification pfn. In accordance with the
ArcInfo convention you can't mix regions and arcs in the same
file.
Offers a dialog if pfn is the empty string and returns the actually
selected path and name in pfn.
*)
PROCEDURE GetBaseRegion(VAR xmin,xmax,ymin,ymax: REAL);
(*
Returns the current base region as given by the
unification of all currently loaded regions
*)
(************************************)
(*##### Drawing of regions #####*)
(************************************)
PROCEDURE DrawRegionsArcs;
(*
Draws all currently known, i.e. into memory loaded, regions
into the current output window. The output window is
typically the one provided by module MapViewer. Note:
DrawRegions does NOT scale the region to fit into the
window, unless no previous drawing into the map window has
ever taken place or its scaling has been cleared (see
routine ForgetDrawRegion from MapViewer). If the map
window is currently without a scaling, DrawRegions will
cause an autoscaling and set the base region as the draw
region (see SetDrawRegion from MapViewer). DrawRegions
uses UC, i.e. the user coordinate system, from module
DMWindIO. Thus you may use the UC-routines from DMWindIO to
implement any additional custom drawing.
To draw an individual region use routine DrawARegion.
Note, the parameters by which a particular region is to be
displayed by DrawRegions is typically defined by using the
optional region attribute (see syntax of region input
files). In case a region is read from the region input
file without such attributes, a default strategy is
followed to assign colors and patterns to the drawing of
regions. Use routine EditRegArcAttributes to change
the appearance of regions interactively. Colors are
interpreted according to current palette (see
EditRegionColorPalette).
*)
PROCEDURE DrawARegionOrArc(raNr: INTEGER);
(*
Draws the region denoted by raNr into the current output
window. The output window is typically the one provided by
module MapViewer. Note: DrawARegion does NOT scale the
region to fit into the window, unless no previous drawing
into the map window has ever taken place or its scaling has
been cleared (see routine ForgetDrawRegion from MapViewer).
Normally DrawARegion does NOT affect the base region. Only
if the map window is currently without a scaling,
DrawARegion will cause an autoscaling, i.e. the borders of
region raNr will be used as the base region (see
DrawRegions) and the latter will be set as the draw region
as well. raNr denotes the region's or arc's number. If a
region/arc with raNr is currently unkonw, i.e. not loaded,
a dialog is first offered to select a region/arc from all
currently known (loaded) ones. This allows e.g. to pass
for raNr undefinedRegArc in order to pick always
interactively a region/arc from the loaded ones.
NOTE: The attribute (color/pattern) used to draw a region
or arc is either controlled by the user (see comment for
procedure EditRegArcAttributes) or follows the default
strategy by setting j = raNr (see comment for procedure
EditRegArcAttributes).
*)
PROCEDURE EditRegArcAttributes(raNr: INTEGER);
(*
Allows to edit interactively the name and attribute of a
region or arc. raNr denotes the region's or arc's
identification number (regarcNr). If a region/arc with
raNr is currently unkonw, i.e. not loaded, a dialog is
first offered to select a region/arc from all currently
known (loaded) ones. This allows e.g. to pass for raNr
undefinedRegArc in order to pick always interactively a
region/arc from the loaded ones.
IMPORTANT NOTE: The attribute of a region can be used to to
control the color and pattern by which a region or arc is
drawn in the map window. The following 16 colors are
offered:
black, white, red, green, blue, cyan, magenta, yellow,
maroon, silver, purple, lime, navy, aqua, teal, olive
The following 5 patterns are offered:
empty (weakest), light (weak), medium (half),
dark (strong), full (strongest)
Synonyms in parantheses. A typical attribute may look like
this:
"color=aqua; pattern=strongest"
In case of no explicit color or pattern specification
provided by the user, the drawing of a region or arc by
DrawRegionsArcs is done according to a default attribute
scheme: color = Color(j) MOD MAX(Color) and pattern =
Pattern(j) MOD MAX(Pattern) where j numbers the sequence in
which regions/arcs are drawn.
*)
END RegArcHdlr.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib