% Template OSGeo Journal - Article
% Language: Latex
% Template OSGeo Journal Dec. 2007
% Head
\begin{article}
\renewcommand{\bibsection}{\section*{Bibliography}}

\title{\textit{r.in.swisstopo}}
\subtitle{A new module for the GRASS GIS application for importing digital elevation model data of Switzerland in swisstopo format}
\author{Juergen Hansmann}

\maketitle

\section{Abstract}
\label{sec:abstractHansmann}
The Swiss federal office of topography, swisstopo\footnote{Swisstopo: \url{http://www.swisstopo.admin.ch/}}, offers digital elevation models of Switzerland in several different formats. When working with the open source geographic information system software GRASS (Geographic Resources Analysis Support System), these data need to be imported into a GRASS raster layer. For this task a new GRASS module \textit{r.in.swisstopo} has been developed, which detects the format of the swisstopo input elevation data and imports it into a GRASS raster map. Users can run \textit{r.in.swisstopo} from the command line, which provides the means to do automated script runs over a large number of input files. Alternatively, a graphical user interface is provided as well, which provides a more comfortable way of working with the module.

The new module has been tested on an example dataset of digital elevation data of the Matterhorn area in Switzerland, provided by swisstopo free of charge. All three file formats supported by \textit{r.in.swisstopo}, could be imported without any problems.

\section{Introduction}
According to \citet{SonnentagO2009}, the \textit{Geographic Resources Analysis Support System} (GRASS; \url{http://grass.itc.it/}) is probably the most well-known free, open source geographical information system (GIS). Originally, GRASS has been developed in 1985-1995 by the US Army Construction Engineering Research Laboratory (CERL), which is part of the US Army Corps of Engineers. When CERL ceased the GRASS development, further GRASS development was done at Baylor University \citep{Neteler2004,HernandezJ2006}. Today it is released under the General Public License (GNU GPL; http://www.gnu.org/) and is part of the Open Source Geospatial Foundation.\\
GRASS is a software assemblage for processing geospatial raster and vector data. It provides tools for processing, analysis and management of spatial data, spatial modelling (e.g. hydrological modelling), processing of (multi spectral) images and advanced data visualization. According to the GRASS homepage, GRASS is applied in academic and commercial settings and also in governmental agencies, such as for example NASA, NOAA and the USGS.

\section{Swisstopo digital elevation data}
The Swiss 'Bundesamt fuer Landestopographie' (Swiss federal office of topography), swisstopo, offers digital elevation data of Switzerland in several formats, all based on the reference system 'Schweizerisches geodaetisches Datum CH-1903' (swiss geodetic datum CH-1903), with the Bessel (1841) reference ellipsoid and the fundamental point at the coordinates 600000 / 200000 (old observatory in Bern).  The provided datasets have a grid spacing of 25 m. Data with a grid spacing of 50m, 100m and 200m are available as well. Elevation data have an error of $< 2$ in the northern region of Switzerland, whereas in rare cases in the mountainous parts of southern Switzerland, elevation data might have errors of up to $3$ m. Three of the offered data formats are considered for import into a GRASS raster map by the new module \textit{r.in.swisstopo}. This three format types are:
\begin{itemize}
\item MMBLT (*.mlt): elevation data saved sequentially
\item MMBL (*.mbl): elevation data saved in a matrix
\item xyz (*.xyz): elevation data saved in xyz coordinate triples
\end{itemize}
MMBLT and MMBL formats are matrix models with quite a similar file structure. Both file formats consist of a header (see figure 1), followed by data records of integer elevation values (i.e. elevation values in decimeters). The header section starts and ends with the keywords \texttt{NEWHEADER} and \texttt{ENDHEADER} respectively, where all important model parameters, such as the coordinates of the northwestern and the southeastern edge, the matrix model dimensions and the grid spacing are defined.
\begin{figure}
\caption{Sample header section of the example dataset provided by swisstopo.}
\begin{verbatim}
NEWHEADER
--------------------------------------------------------------------------------
DHM25-MATRIXMODELL LEVEL 2                     (c)BUNDESAMT F. LANDESTOPOGRAPHIE
--------------------------------------------------------------------------------
NORD-WEST ECKE     [M]  616000.0   92700.0     ERSTER HOEHENWERT
SUED-OST ECKE      [M]  618000.0   90700.0     LETZTER HOEHENWERT
MASCHENWEITE WE/NS [M]      25.0      25.0
MATRIXDIMENSIONEN WE/NS     81        81       TOTAL      6561 MATRIXPUNKTE
HOEHENBEREICH     [DM]   30368     44780       (6 CHARACTER PRO HOEHENWERT)
--------------------------------------------------------------------------------
FORMAT                   ASCII                 L+T-FORMAT DHM25-MATRIXMODELL
RECORDLAENGE(CHAR.)       2040                 340 HOEHENWERTE PRO RECORD
--------------------------------------------------------------------------------
ENDHEADER
\end{verbatim}
\label{header}
\end{figure}
In the case of the MMBLT format, elevation data is stored sequentially in records, which by default contain 2040 digits, yielding 340 elevation values with 6 digits each. The first line of a digital elevation model of a  region, that consists of m rows with n elevation values, always consists of 340 elevation values. If n was 9 for example, the first line would look like:
$e_{1,1}$ $e_{1,2}$ $e_{1,3}$ $e_{1,4}$ $e_{1,5}$ $e_{1,6}$ $e_{1,7}$ $e_{1,8}$ $e_{1,9}$ $e_{2,1}$ $e_{2,2}$ $e_{2,3}$ $e_{2,4} $ $e_{2,5} \cdots$ until the row contains 340 values, then the next row is written.\\
The indices in ei,j represent the row (i) and column (j) of the matrix.
For a MMBL type matrix model, the number of values per row exactly matches the matrix model dimensions. If the digital elevation model matrix has the format m x n, and n was 9 for example, then the data of the above example would be stored in the following way:\\
$e_{1,1}$ $e_{1,2}$ $e_{1,3}$ $e_{1,4}$ $e_{1,5}$ $e_{1,6}$ $e_{1,7}$ $e_{1,8}$ $e_{1,9}$\\
$e_{2,1}$ $e_{2,2}$ $e_{2,3}$ $e_{2,4} $ $e_{2,5}$ $e_{2,6}$ $e_{2,7}$ $e_{2,8}$ $e_{2,9}$\\
and so on.
Elevation models, that are provided in the xyz format simply consist of one x-, y- and z-coordinate triple per row.

\section{The module r.in.swisstopo}
The module \textit{r.in.swisstopo} imports digital elevation models provided by swisstopo in the three previously mentioned formats. It can be run from the command line, which provides a means to script the command in order to import large number of files automatically. Optionally, the module provides a graphical user interface (GUI) as well, which is shown in figure \ref{screenshot} and is based on the GRASS module \textit{g.parser}.
\begin{figure}[h]
\caption{The graphical user interface of the module r.in.swisstopo.}
\begin{center}$
\begin{array}{c}
\includegraphics[width=120mm]{./Figures/hansmann_fig2.eps}
\end{array}$
\label{screenshot}
\end{center}
\end{figure}

\textit{r.in.swisstopo} extracts information about the DEM matrix model from the header section, by searching for the according keywords, rather than assuming a certain, fixed position of the values inside the header section. Therefore, even if the layout of the header section should change in future, the module should still be able to find the required information in the new header format.\\
In the first step of the automatic import process by \textit{r.in.swisstopo}, the input data is processed with an \textit{awk}-script and converted to a format, that can be read with \textit{r.in.xyz}. After the import of the elevation data, two raster maps will be generated by the module.\\
A first raster map, which has the suffix 'origres', contains the elevation data in its original resolution (which will be 25m in most cases). Whereas a second raster map is generated, that contains the imported elevation data, interpolated to the current GRASS region's resolution, using \textit{r.resamp.interp}. Elevation data in both raster maps will be stored in meters.\\
The first parameter, which has to be set by the user (either at the command line or in the GUI) is the name of the swisstopo input file. Next, the name of the resultant output raster map has to be defined. Since \textit{r.in.swisstopo} invokes the GRASS module \textit{r.in.xyz}, which uses univariate statistics to create a raster map from an assemblage of large amounts of coordinates, a statistical method for this has to be chosen (see the GRASS help page of \textit{r.in.xyz} for details). The default method is 'mean'. Next, the storage type of the resultant raster map has to be defined, as it will be passed to the \textit{r.in.xyz} module. Default type is FCELL, yielding floating point values (again, see GRASS help page of \textit{r.in.xyz} for details). Optionally, the range of elevation data, that is imported by \textit{r.in.xyz}, can be restricted by defining the parameter zrange. For large datasets, the percentage of the map, that is kept in memory, can be chosen as well.\\
The region settings of GRASS GIS are temporarily adjusted in order to cover the input dataset extent completely. When the data import is finished, the region settings will be restored to their original state.
As the module \textit{r.resamp.interp} is invoked for the interpolation of the input data into the current GRASS region's resolution, an interpolation method has to be chosen by the user (see the GRASS help page for \textit{r.resamp.interp} for details). If the flag 'allow overwrite' is set, existing raster maps will be overwritten without further warnings. The 'run quietly' flag reduces the output messages to a minimum.\\
The module \textit{r.in.swisstopo} conducts some error checks on the imported data.  When the number of imported elevation values is less than expected, the process will be cancelled and an error message will appear. If the number of elevation values in the input file exceeds the number that was defined in the header, a warning message will be shown and no further data points will be imported. This could be caused by padding (zero) values in the input file for example.


\section{Test runs of \textit{r.in.swisstopo}}
Test runs of the module \textit{r.in.swisstopo} were done for all three digital elevation model formats on the test datasets, that are provided by swisstopo free of charge at: \url{http://www.swisstopo.admin.ch/internet/swisstopo/en/home/products/downloads/height/dhm25.html}.
All three formats could be imported without any problems. Figure \ref{matterhorn} shows the imported digital elevation model of the Matterhorn.
\begin{figure}[t]
\caption{3D view of the Matterhorn in Valais, Switzerland, created from imported digital elevation data of the swisstopo sample dataset, using the new GRASS module \textit{r.in.swisstopo}.}
\begin{center}$
\begin{array}{c}
\includegraphics[width=110mm]{./Figures/hansmann_fig3.eps}
\end{array}$
\label{matterhorn}
\end{center}
\end{figure}

\section{Download and Installation of the module \textit{r.in.swisstopo}}
The source code of the current version of \textit{r.in.swisstopo} is available at GRASS Addons repository: \url{http://grass.osgeo.org/wiki/GRASS_AddOns#r.in.swisstopo}. Installation can be done via SVN or manually. For a manual installation, the following steps need to be done (users might need to have root (i.e. administrative) privileges for this):
\begin{itemize}
 \item Download the files 'r.in.swisstopo' and 'description.html' to a temporary directory
 \item Copy the file 'r.in.swisstopo' into the \texttt{\$GISBASE/scripts/} directory\\
       (To find out your \texttt{\$GISBASE} directory, call the following command from within a GRASS terminal: \texttt{env \textbar $\,$ grep \$GISBASE)}\\
	Alternatively, directly copy the file from within a GRASS terminal with something like:
	\texttt{cp r.in.swisstopo \$GISBASE/scripts/}
\item	In most cases, the file 'r.in.swisstopo' needs to be made executable with:\\
	\texttt{chmod +x \$GISBASE/scripts/r.in.swisstopo}
\item	Finally, the file 'description.html' should be placed in the \texttt{\$GISBASE/docs/html/} directory and renamed to 'r.in.swisstopo.html'
\end{itemize}

\section{Example shell script for processing large amounts of data}
If a large number of files has to be imported, the user might want to automate this task, rather than importing every file manually, using the GUI. This can be achieved by running the script from the command line of a GRASS terminal. An example shell script, that runs over all input files of a certain file format in a directory, could look like the following:
\begin{lstlisting}[language=sh]
#!/bin/bash
for filename in *.mlt; do
   r.in.swisstopo input=$filename output=$filename method=mean \
                  type=FCELL percent=100 method_resamp=bilinear \
                  --overwrite --quiet
done
\end{lstlisting}
Note that the names of the resultant raster layers in the above example would be the same, as the names of the imported input data file.

\section{Acknowledgments}
The author would like to thank all those individuals who have contributed to the GRASS GIS software project in the past, and who continue to develop it further under the guidance of the Open Source Geospatial Foundation (\url{http://www.osgeo.org/}).


% ------ your information --------

\address{Juergen Hansmann\\
  PhD student at Swiss federal institute of technology (ETH) Zurich, Switzerland, Dept. Earth Sciences\\
  \email{Juergen.Hansmann@erdw.ethz.ch}\\
  \url{http://www.engineeringgeology.ethz.ch/}}

% ------bibliography ---------

\begin{thebibliography}{3}
\bibitem[{Carrera-Hern\'{a}ndez and Gaskin(2006)}]{HernandezJ2006}
Carrera-Hern\'{a}ndez, J., Gaskin, S., Apr. 2006. The groundwater modeling tool
  for grass (gmtg): Open source groundwater flow modeling. Computers \&
  Geosciences 32~(3), 339--351.

\bibitem[{Neteler and Mitasova(2004)}]{Neteler2004}
Neteler, M., Mitasova, H., 2004. Open Source GIS: A GRASS GIS approach. The
  Kluwer International Series in Engineering and Computer Science, 2nd ed.
  Kluwer Academic Publishers, Boston, Dordrecht.

\bibitem[{Sonnentag(2009)}]{SonnentagO2009}
Sonnentag, O., Nov. 2009. Neteler, M., Mitasova, H., 2008. Open Source GIS A
 GRASS GIS Approach, 3rd ed. Springer, NY, USA, ISBN 978-0-387-35767-6,
  406pp., USD 99.00, CDN 128.95, EUR 81.95, hardbound. Computers \& Geosciences
  35~(11), 2282--2282.
\end{thebibliography}


\end{article}
%%% Local Variables: 
%%% mode: latex
%%% TeX-master: main_document.tex
%%% End: 
