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

DEFINITION MODULE GridDSIO;

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

    Module  GridDSIO     (Version 1.0)

      Copyright (c) 2001-2006 by Dimitrios Gyalistras and ETH Zurich.

    Purpose   File input/output of gridded data sets.

    Remarks   For general management of gridded data sets see
              module GridDataSets.

              Data sets can be read and written in the following
              formats:

                    1. GDS standard format  (read & write)
                    2. Interchange format   (write only)
                    3. GDS list format      (read & write)
                    4. ARC/INFO format      (read & write)

             IMPORTANT NOTE:

             In the ARC/INFO format the attributes "xllcorner" and
             "yllcorner" denote the location of the LOWER LEFT CORNER of
             the lower left GRID CELL.

             In contrast, in the GDS standard and list formats, these
             attributes denote the LOCATION of the lower left GRIDPOINT.

             Hence, depending on the output format chosen, the attribute
             values given for "xllcorner" and "yllcorner" may differ by
             0.5*cellsize.

             Note also that the attributes of a gridded data set are
             always returned according to the GDS convention, NOT
             according to the ARC/INFO convention.


    Programming

      o Design
        Dimitrios Gyalistras      19/09/2001

      o Implementation
        Dimitrios Gyalistras      19/09/2001


    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:  20/10/2003   DG

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


  FROM DMFiles IMPORT TextFile;
  IMPORT Errors;

  FROM GridDataSets IMPORT GridDataSet;


  CONST
    notDone = Errors.onlyAnInsert;
    (*
      All procedures exported below return errCode = Errors.allOk if the
      call to the procedure was succesfull, and resCode = notDone if not.
    *)

  TYPE
    AtReadDataPointP = PROCEDURE( VAR REAL,          (* the data point *)
                                  VAR ARRAY OF CHAR  (* error text to pass on *)
                                ): BOOLEAN;          (* if false, reading stops *)

  TYPE
    GridDataSetOutputFormat = ( notDefinedFormat,
                                gdsStandardFormat,
                                interchangeFormat,
                                listFormat,      (* no missing values in output *)
                                fullListFormat,  (* missing values also outputed *)
                                arcInfoFormat );


  (***************************)
  (*#####   Auxiliary   #####*)
  (***************************)

  PROCEDURE GetOutputFormatDescr( outputFormat : GridDataSetOutputFormat;
                                  VAR descrStr : ARRAY OF CHAR);

  PROCEDURE GetOutputFormatIdent( outputFormat : GridDataSetOutputFormat;
                                  VAR identStr : ARRAY OF CHAR);

  PROCEDURE OutputFormatForIdent( identStr: ARRAY OF CHAR ): GridDataSetOutputFormat;



  (******************************************)
  (*#####   I/O of gridded data sets   #####*)
  (******************************************)


  PROCEDURE IsGridDataSetFile( inFName    : ARRAY OF CHAR;
                               VAR errTxt : ARRAY OF CHAR ): BOOLEAN;


  PROCEDURE GetGridDataSetHeader( inFileName      : ARRAY OF CHAR;
                                  VAR dataID      : LONGINT;       (* identifier of data *)
                                  VAR dataDescr   : ARRAY OF CHAR; (* description of data *)
                                  VAR sectorID    : LONGINT;       (* identifier of sector *)
                                  VAR sectorDescr : ARRAY OF CHAR; (* description of sector *)
                                  VAR nRows       : INTEGER;       (* Number of points in y-direction *)
                                  VAR nCols       : INTEGER;       (* Number of points in x-direction *)
                                  VAR minLon      : REAL;          (* longitude of lower left corner *)
                                  VAR minLat      : REAL;          (* latitude  of lower left corner *)
                                  VAR cellSize    : REAL;          (* cell size *)
                                  VAR resCode     : INTEGER;
                                  VAR errTxt      : ARRAY OF CHAR);


  PROCEDURE ReadGridDataSet( inFileName      : ARRAY OF CHAR;
                             inDegrees       : BOOLEAN;
                             atReadDataPoint : AtReadDataPointP;
                             progrReprt      : PROC;
                             VAR gds         : GridDataSet;
                             VAR resCode     : INTEGER;
                             VAR errTxt      : ARRAY OF CHAR);
    (*
      Reads a gridded data set from the file "inFileName" and marks it
      with the identifier "gds".  If a data set with this identifier
      already existed, and no error occurrred during reading, it is
      replaced by the newly read one. Specify "inDegrees" as TRUE if the
      attributes minLon/minLat/cellSize  are expected in degrees.
      The procedure "atReadDataPoint" is called each time a data point
      has been read and aborts reading if it returns FALSE. Note, missing
      data are denoted by the value DMConversions.UndefREAL().
      Procedure "progrReprt" is called each time a data set has been
      processed or every 5000 data points read.
      Note: acceptance of x- and y-coordinates as read from a file in
      "listFormat" depends on the current settings for the coordinates'
      relative tolerance (see procedure GridpointCoordRelTol in module
      GridDataSets).
    *)


  PROCEDURE WriteGridDataSet( VAR outF    : TextFile;
                              gds         : GridDataSet;
                              format      : GridDataSetOutputFormat;
                              noDataStr   : ARRAY OF CHAR;
                              nDecDigits  : INTEGER;
                                            (* number of digits behind decimal point
                                            to consider for output *)
                              VAR resCode : INTEGER;
                              VAR errTxt  : ARRAY OF CHAR );
    (*
      Writes the gridded data set with identifier "gds" to file "outF".
      Note: files written in "interchangeFormat" can NOT be re-read
      by means of procedure "ReadGridDataSet".
    *)



END GridDSIO.