\renewcommand{\documentID}{\$Id: sourcefiles.tex,v 1.7 2007-06-06 16:30:05 frank Exp $ $}

\chapter{Catchment Source Files Formats}
\label{chap:PredefinedFormats}

{\em Note:} This new format slightly differs from  the original
\GREATER\ 1 format and is therefore not fully compatible.
See the file {\em Changes.txt} of the software package for details.

All 6 catchment source files have to be collected in one directory.

All files are text based
and use the character set ISO 8859-1 (ISO Latin 1).
The format is line-oriented; each line starts with a '\verb"#"'
(comment line) and all empty lines have no meaning for the processing
and can be inserted anywhere.

All coordinates are given in the same projection:
"geographic projection" with unit "dd" (decimal degrees).
A point, rather than a comma, is used as decimal point.
Numbers are not allowed to contain any other delimiters.
Exponential representation uses the letter 'E' or 'e'.

%
%****************************************************************************
%
\section{Info File, File 'catchment.desc'}
\label{sec:catchment.desc}

This file contains general information. Example:

\begin{verbatim}
ID=went
NAME=Catchment of River Went
DESCRIPTION=The Went catchment is a small, rural area in Yorkshire, UK.
IN-VERSION=1.0
OUT-VERSION=1.0
\end{verbatim}

{\bf ID} is the basename for the actual data source files suffixed with 
.drn, .rna, .dsd, .cbp and .bgd. 

{\bf IN-VERSION} defines the format 
for the all catchment source files. 


{\bf OUT-VERSION} defines the output format.

The information set has been enhanced for uploading catchment data into
a \GREATER\ 2.0 database. A sample of additional pairs of keys and values:

\begin{verbatim}
STRETCH_TAB=river2.att
DISCH_TAB=disch.att
GISFILELIST=./upload.list
BACKGROUND=United Kingdom
\end{verbatim}

{\bf STRETCH\_TAB} references the file with stretch specific data to be
uploaded. This is typically {\em river2.att}, as generated by the
preprocessing.

{\bf DISCH\_TAB} references the file with dicharge sites data to be
uploaded. This is typically {\em disch.att}, as generated by the
preprocessing.

{\bf GISFILELIST} specifies a list of all GIS data and related files to be
uploaded. See section \ref{sec:gisfilelist} for details.

{\bf BACKGROUND} links to available background data (binary objects with 
 {\em obj\_type} BACKGROUND). Use a pattern which matches a fraction of the 
{\em remark} field of the relevant binary objects.

%
%****************************************************************************
%
\section{Digital River Network, File 'ID.drn'}

IN-VERSION = 1.0

The river network attributes are stored in a simple tabular structure.
Columns are separated by commas.
The following example illustrates the order of the columns:

\begin{verbatim}
7421
-1.399004,53.718807
-1.374895,53.730835
-1.368942,53.734528
-1.364163,53.736794
-1.363446,53.738102
6787
-1.399046,53.717968
-1.399043,53.718178
[...]
\end{verbatim}

%
%****************************************************************************
%
\section{River Network Attributes, File 'ID.rna'}

IN-VERSION = 1.0

The river network attributes are stored in a simple tabular structure.
Columns are separated by commas. 
The following example illustrates the order of the columns:

\begin{verbatim}
# Aire/Calder Catchment, Yorkshire
# StretchID,Qmean(m^3/s),Q5(m^3/s),vmean(m/s),v5(m/s),
# ... RealLength(m),depthmean(m),depth5(m),Name
26954,34.751000,12.280656,,,2491.655000,,,Unnamed         
22954,0.009000,0.002359,,,1648.222000,,,Unnamed         
7333,34.739000,12.276415,,,1629.885000,,,Unnamed         
22932,0.005000,0.001088,,,540.190000,,,Unnamed         
26950,34.731000,12.274977,,,2336.740000,,,Unnamed         
22923,0.017000,0.002167,,,2447.520000,,,Unnamed         
[...]
\end{verbatim}

In this example no information is available for flow
velocity and depth and hence the corresponding columns are left
empty.

Note: In case of a lake, the field for RealLength should contain
the volume in $m^3$!

%
%****************************************************************************
%
\section{Discharge Site Data, File 'ID.dsd'}

IN-VERSION = 1.0

Each line defines one discharge.
The first column is its unique ID, followed by
the coordinate pair and the attributes. The order of the columns
is shown in this example:

\begin{verbatim}
# ID,X,Y,Pop,DWF(m^3/d),Flow(m^3/d),Type,StretchID,Name
41,-1.390494,53.422081,422677,130000,180000,AS,26842,Blackburn STW
42,-1.349155,53.369724,95750,21800,24506,AS,26843,Woodhouse Mill STW
43,-1.326922,53.445114,107203,31250,32410,AS,26841,Aldwarke STW
\end{verbatim}

%
%****************************************************************************
%
\section{Catchment Boundary Polygon, File 'ID.cbp'}

IN-VERSION = 1.0

The polygon is described linewise by single coordinate pairs (x,y).
The following example illustrates the format:

\begin{verbatim}
-2.052912,53.683811
-2.060483,53.683807
-2.060477,53.679314
-2.068047,53.679310
[...]
-2.045346,53.688309
-2.045342,53.683804
-2.052912,53.683811
\end{verbatim}

This example also shows that the polygon must be closed, cf.
the last and the first point must be identical.

%
%****************************************************************************
%
\section{Lakes, File 'ID.lks'}

IN-VERSION = 1.0

A list of stretch IDs which actually are lakes. Example:

\begin{verbatim}
# StretchID
345
2256
\end{verbatim}

This file can be empty, but must exist.

%
%****************************************************************************
%
\section{Pictures, File 'ID.pic'}

IN-VERSION = 1.0

If pictures are available for the catchment, location
and picture files can be specified:

\begin{verbatim}
# ID,X,Y,File,Name
1,6.860403,51.157661,mgmuendung.jpg,Confluence to the Rhine
3,6.872726,51.158089,mgddorf.jpg,in Duesseldorf
4,6.897292,51.159611,uhilden1.jpg,Below STP Hilden
5,6.899222,51.159081,uhilden2.jpg,Below STP Hilden
\end{verbatim}

This file can be empty, but must exist.

{\bf Note,} that the picture files must be in jpg-format.

%
%****************************************************************************
%
\section{Background Data, File '.bgd'}

IN-VERSION = 1.0 (however, you can leave this file empty for GREAT-ER 2.0)

To support the user with a quick and easy access to
geographic background information, a list of background
data sets can be defined for each catchment.

In the ".bgd" file names of additional background data that are to be
loaded by the menu entry "Display/Add Background Data" are specified.
The data can be given in two ways. In a simple case, a background
data set is only a geographic data set that ArcView can load as a theme, i.e. anArcInfo Coverage, an image, a grid or a shapefile.
This case is indicated by the value "yes" in the field "ctch\_flg"
(see below). In the more complex case
a background data set consists of a set of geographic data, indicated by the
value 'no' in the field 'ctch\_flg'.
In this case, instead of the name of the data set
an ID for a script that knows how to load the geo-data sets is specified.

\subsection*{Name}

This is the name for the corresponding background data.
It is used for user selections in the GREAT-ER system.

\subsection*{Mapname}

In the case of a simple background data set,
this is the file name of the coverage, image or shapefile that
contains the data.
Otherwise this field contains the script which can
load the background data sets.

\subsection*{Type}

In the case of a simple background data set,
this is its feature type.
Valid entries are "point", "line", "polygon", "shape",
"image" and "grid".
Otherwise the field is left empty.

\subsection*{Legendfile}

In the case of a simple background data set,
this is the name of an optional ArcView legend file.
Otherwise this field can contain (optional) parameters for
the script specified in the field "Mapname".

\subsection*{ctch\_flg}

This is a boolean field that contains either "yes" or "no".
"yes" indicates that this background data set consists of one
theme that does not need a special script to load into the active
view of GREAT-ER.
"no" means that a special Avenue script has been developed by
the user which runs within GREAT-ER and loads the backgroud data
set into the active view.

There is one special case:
The DCW data (Digital Chart of the World, a variant of VMAPL0)
are incorporated
in the GREAT-ER project for the whole of Europe.
For this incorporation specific scripts loading the DCW
data in dependence of the viewed country are developed.
If the DCW data are to be a background data set for
a catchment, the following line needs to be inserted
into the file:

\begin{verbatim}
DCW data,,,,
\end{verbatim}

If a user installs the DCW data for countries
that have not yet been included, e.g. France, Spain or Denmark,
these data need to be installed analogous to the included countries.

\subsection*{Example ".bgd" file}

This example file describes background information
for the River Itter (Germany):

\begin{verbatim}
#River Itter background data
#Name,Mapname,Type,Legendfile,ctch_fl
Cities,itter\cities,polygon,itter\cities.avl,yes
Tk25,itter\tk25tiffz.tif,image,,yes
Rhein,itter\rhein,polygon,itter\rhein.avl,yes
DCW data,,,,no
\end{verbatim}

\section{List of files to be uploaded, GISFILELIST}
\label{sec:gisfilelist}

This file with a freely selectable name lists all files to be inserted as
binary objects by the upload of a catchment into \GREATER\ 2.0. 
These are typically the GIS files created by the preprocessing plus e.g. photos
referenced by the pic layer.

The format is
\begin{verbatim}
#PATH,NAME,OBJ_TYPE,OBJ_SUB_TYPE
\end{verbatim}

A typical content of the file (given it is located in the same directory as
the data and the upload is started from this directory), for example to upload
the Aire data:

\begin{verbatim}
#PATH,NAME,OBJ_TYPE,OBJ_SUB_TYPE
#
# CATCHBOUND
#
./catchbound.dbf,aire,CATCHMENT,CATCHBOUND
./catchbound.shp,aire,CATCHMENT,CATCHBOUND
./catchbound.shx,aire,CATCHMENT,CATCHBOUND
#
# RIVERNET
#
./rivernet.dbf,aire,CATCHMENT,RIVERNET
./rivernet.shp,aire,CATCHMENT,RIVERNET
./rivernet.shx,aire,CATCHMENT,RIVERNET
#
# DISCHARGES
#
./discharges.dbf,aire,CATCHMENT,DISCHARGES
./discharges.shp,aire,CATCHMENT,DISCHARGES
./discharges.shx,aire,CATCHMENT,DISCHARGES
#
# DISCH_RIVER
#
./disch_river.dbf,aire,CATCHMENT,DISCHRIVER
./disch_river.shp,aire,CATCHMENT,DISCHRIVER
./disch_river.shx,aire,CATCHMENT,DISCHRIVER
#
# PICS
#
./pics.dbf,aire,CATCHMENT,PICS
./pics.shp,aire,CATCHMENT,PICS
./pics.shx,aire,CATCHMENT,PICS
\end{verbatim}

