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

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