\section{GRASS}\label{sec:grass}\index{GRASS}

While GRASS\cite{GRASSweb} is a full-blown hybrid GIS it can be used to extend
QGIS with the following new features:

\begin{itemize}
\item \includegraphics[width=0.7cm]{add_grass_vector} Add GRASS vector layers
\item \includegraphics[width=0.7cm]{add_grass_raster} Add GRASS raster layers
\item \includegraphics[width=0.7cm]{grass_tools} GRASS Toolbox
\item \includegraphics[width=0.7cm]{grass_edit} Vector layers digitizing
\item \includegraphics[width=0.7cm]{grass_region_edit} Changing the GRASS region
\end{itemize}

\subsection{Starting QGIS with GRASS}\label{sec:starting_grass}
\index{GRASS!starting QGIS}

If you like to use GRASS features from within QGIS, you need to load the 
GRASS plugin with the plugin manager. 
After loading the plugin you can immediately load your GRASS datasets using 
the appropriate toolbar buttons for vector and raster data.

If you want to use the GRASS toolbox you need to add a GRASS mapset where GRASS
will store the resulting datasets.

% NOT NEEDED ANYMORE (SH: 06.05.06)
% 
% When using the GRASS plugin, QGIS can be started in several ways: from the GRASS
% shell or from a regular shell.
% 
% \subsubsection{From GRASS shell}\label{label_grassshell}
% 
% If QGIS is started from the GRASS shell (GRASS started by grass57 command), no
% additional settings are required. \index{GRASS!shell}
% 
% \subsubsection{Outside GRASS shell}\label{label_outsideshell}
% 
% If QGIS is not started from the GRASS shell, the environment variables must be
% properly set before starting QGIS.
%  
% The path to GRASS libraries must be added to LD\_LIBRARY\_PATH environment
% variable. For example (in bash): \index{GRASS!environment settings}
% 
% \begin{verbatim}
%     export
% LD_LIBRARY_PATH=/usr1/grass57/dist.i686-pc-linux-gnu/lib:$LD_LIBRARY_PATH
% \end{verbatim}    
%  
% The GISBASE environment variable must be set to the full path of the directory
% where GRASS is installed (the same as used for --with-grass= option). For
% example (in bash):
% 
% \begin{verbatim}
%     export GISBASE=/usr1/grass57/dist.i686-pc-linux-gnu 
% \end{verbatim}

\subsection{Loading GRASS Data}\label{sec:load_grassdata}\index{GRASS!loading data}

With the GRASS plugin loaded, you can load vector or raster layer using the
appropriate button on the toolbar. 

\begin{Tip}\caption{\textsc{GRASS Data Loading}}
\qgistip{If you have problems loading data or QGIS terminates abnormally,
check to make sure you have loaded the GRASS plugin properly as described in Section
\ref{sec:starting_grass}.
}
\end{Tip} 

\subsection{Vector Data Model}\label{label_vectmodel}\index{GRASS!vector data
model}

It is important to understand the GRASS vector data model prior to
digitizing.\index{GRASS!digitizing} In general, GRASS uses a topological
vector model.\index{GRASS!topology} This means that areas are not represented
as closed polygons, but by one or more boundaries. A boundary between two
adjacent areas is digitized only once, and it is shared by both areas.
Boundaries must be connected without gaps. An area is identified (labeled) by
the centroid of the area.

Besides boundaries and centroids, a vector map can also contain
points and lines. All these geometry elements can be mixed
in one vector and will be represented in different so called 'layers' inside
QGIS.

It is possible to store more 'layers' in one vector dataset. For example,
fields, forests and lakes can be stored in one vector. Adjacent
forest and lake can share the same boundary, but they have separate attribute
tables. It is also possible to attach attributes to boundaries. For example,
the boundary between lake and forest is a road, so it can have a different 
attribute table.
 
%In addition, one geometry element can represent a geometry for more
%features. For example, a road can be a marked turistic route at the same 
%time.

The 'layer' of the feature is defined by 'layer' inside GRASS.
'Layer' is the number which defines if there are more than one layer inside the 
dataset, e.g. if the geometry is forest or lake.
For now, it can be only a number, in the future GRASS will also support  
names as fields in the user interface.

Attributes can be stored in external database tables, for example
DBF, PostgreSQL, MySQL, SQLITE3, etc.\index{GRASS!attribute storage}

Attributes in database tables are linked to geometry elements using
'category'.\index{GRASS!attribute linkage} 'Category' (key, ID) is an
integer attached to geometry primitives, and it is used as the link to one
column in the database table.

\begin{Tip}\caption{\textsc{Learning the GRASS Vector Model}}
\qgistip{
The best way to learn the GRASS vector model and its capabilities is to 
download one of the many GRASS Tutorials where the vector model is described
more deeply. See \url{http://grass.itc.it/gdp/manuals.php} for more
information, books and tutorials in several languages.
% The best way to learn the GRASS vector model and its capabilities
% is to download the demo mapset from
% \url{http://mpa.itc.it/radim/g51/g51test-12-multi.tar.gz}.
% Extract the mapset, add all layers from vector 'multi' to QGIS, and query
% attributes.
% Finally start editing of vector 'multi', to see how those layers are stored.
}
\end{Tip} 

\subsection{Digitizing and Editing Tools}\index{GRASS!digitizing tools}
\label{grass_digitising}

\includegraphics[width=0.7cm]{grass_edit} The digitizing tools for GRASS vector layers are accessed using the
\textsl{Edit GRASS Vector Layer} tool on the toolbar. Make sure you have
loaded a GRASS vector and it is the selected layer in the legend before
clicking on the edit tool. 
If you like to create a new GRASS vector, you need to use the toolbar-entry
Plugins->GRASS->Create new GRASS vector layer

Figure \ref{fig:grass_edit} shows the GRASS Edit dialog that
is displayed when you click on the edit tool. 

\begin{figure}[h]
   \begin{center}
   \caption{GRASS Edit Dialog}\label{fig:grass_edit}\smallskip
   \includegraphics[clip=true, width=13cm]{grassedit}
\end{center}  
\end{figure}

The tools and settings are discussed in the following sections.

\subsubsection{Toolbar}\label{label_grasstoolbar}

Table \ref{tab:grass_tools} lists the digitizing tools provided by the GRASS
plugin. These correspond to the tool buttons in the toolbar(s) across the top
of the dialog.

\begin{table}[h]\index{GRASS!digitizing tools}
\centering
\caption{GRASS Digitizing Tools}\label{tab:grass_tools}\medskip
 \begin{tabular}{|l|l|p{5in}|}
 \hline \textbf{Icon} & \textbf{Tool} & \textbf{Purpose} \\
\hline \includegraphics[width=0.7cm]{grass_new_point} & New Point & digitize new point \\
\hline \includegraphics[width=0.7cm]{grass_new_line} & New Line &  digitize new line (finish by selecting new tool) \\
\hline \includegraphics[width=0.7cm]{grass_new_boundary} & New Boundary & digitize new boundary (finish by selecting new tool)\\
\hline \includegraphics[width=0.7cm]{grass_new_centroid} & New Centroid & digitize new centroid (label existing area)\\
\hline \includegraphics[width=0.7cm]{grass_move_vertex} & Move vertex & select one vertex of existing line or boundary and
identify new position\\
\hline \includegraphics[width=0.7cm]{grass_add_vertex} & Add vertex & add a new vertex to existing line\\
\hline \includegraphics[width=0.7cm]{grass_delete_vertex} & Delete vertex & delete one vertex from existing line (confirm selected
vertex by another click)\\
\hline \includegraphics[width=0.7cm]{grass_move_line} & Move line & select existing line and click on new position\\
\hline \includegraphics[width=0.7cm]{grass_split_line} & Split line & split an existing line to 2 parts\\
\hline \includegraphics[width=0.7cm]{grass_delete_line} & Delete line & delete existing line (confirm selected line by another
click)\\
\hline \includegraphics[width=0.7cm]{grass_edit_attributes} & Edit attributes & edit attributes of existing element (note that one
element can represent more features, see above)\\
\hline \includegraphics[width=0.7cm]{grass_close_edit} & Exit & close digitizing session (rebuilds topology afterwards)\\
\hline
\end{tabular}
\end{table}

\subsubsection{Category Tab}\index{GRASS!category settings}

This tab allows you to set the way in which the category will be assigned to
each new feature and/or assign a category to a feature.

\begin{itemize}
\item Mode: what category should be attached to geometry
\begin{itemize}
\item Next not used - next category not yet used in vector file
\item Manual entry - define the category in the 'Category'-entry field
\item No category - digitize geometry without entering any category
\end{itemize}
\item Category - a number (ID) attached to digitized feature
\item Field (layer) - feature (attribute table) identification
\end{itemize}

\begin{Tip}\caption{\textsc{Creating additional 'layers' with QGIS}}
\qgistip{If you like to add more layers to your dataset, just add a new
number in the 'Field (layer)' entry box and press return. In the Table tab
you can create your new table connected to your new layer.
}
\end{Tip}

\subsubsection{Settings Tab}\label{label_settingtab}\index{GRASS!snapping
tolerance}

This tab allows you to set the snapping in screen pixels. This is the threshold
in pixels in which new points or line ends are snapped to existing nodes. This
helps prevent gaps or dangles between boundaries. The default is set to 10 
pixels.

\subsubsection{Symbology Tab}\index{GRASS!symbology settings}

This tab allows you to view and set symbology and color settings for various geometry types and
their topological status (e.g. closed / opened boundary).

\subsubsection{Table Tab} \index{GRASS!table editing}
This tab provides information about the database table for
a given 'layer'. Here you can add, modify or create new database tables for the
current layer.

\begin{Tip}\caption{\textsc{GRASS Edit Permissions}}\index{GRASS!edit
permissions}
\qgistip{You must be the owner of the GRASS mapset you want to edit. It is
impossible to edit vectors in mapsets which are not yours, even if you have
write permissions.
}
\end{Tip} 

\subsection{Region Tool}\index{GRASS!region}

\includegraphics[width=0.7cm]{grass_region_edit} The current region (window) in GRASS is very important for all 
raster modules. All new created rasters have the extension and resolution
of the current region, regardless their original region. 
The region is stored in \$LOCATION/\$MAPSET/WIND file, and it defines
north, south, east, west, number of columns, number of rows, 
horizontal and vertical spatial resolution.

It is possible to switch on/off the GRASS region in QGIS canvas
using the \textsl{Display Current GRASS Region}
button. \index{GRASS!region!display}

With the \textsl{Edit Current GRASS Region} you can open a tool 
in which you can change the current region and symbology
of the GRASS region rectangle on the QGIS canvas. When the tool is running,
it is also possible to select a new region interactively with your mouse
on the QGIS canvas.\index{GRASS!region!editing}

% Both tools are available only if QGIS has the GRASS-plugin enabled. 
% was started from a GRASS 
% shell or if the GISRC environment variable pointing to a
% valid GISRC file was set (i.e. only if you are running 
% GRASS within your mapset).

\subsection{GRASS Toolbox}\index{GRASS!toolbox}

\includegraphics[width=0.7cm]{grass_tools} The GRASS toolbox provides analytic functions from GRASS within QGIS. To
use the GRASS toolbox you need to have opened a mapset where you have
write-permission. This is needed because QGIS will most probably create
new datasets which need to be written to a valid mapset.

Therefor you need to start QGIS from within a GRASS session. Then your 
current mapset will be opened for writing.

Another option for opening a mapset for writing is provided through the 
GRASS plugin entry. Use Plugins->GRASS->Open mapset.
 
If you have a greyed out GRASS toolbox button, make sure you open a valid
mapset for writing, since the GRASS plugin needs a mapset to store its
results.

The toolbox also provides a very useful data browser for browsing through your
current location and its containing mapsets.


\subsubsection{Modules inside the toolbox} \index{GRASS!toolbox!modules}

The GRASS toolbox provide a collection of GRASS modules which can be used
from within QGIS. They are grouped to thematic blocks which can be defined 
by yourself (see section \ref{sec:toolbox-customizing}). 

When clicking on a module a new tab will be added to your toolbox which
provides three new sub-tabs:
\begin{enumerate}
\item Options
\item Output 
\item Manual
\end{enumerate}

\minisec{Options}

This tab provides you with a very simplified entry field where you need to 
select the needed maps and enter parameters to run the selected module.
Note, that this options are kept as simple as possible in order to keep
the structure clear. If you need more option of the module feel free to 
use the GRASS shell to run the module.

\minisec{Output}

This tab provides you with the output generated from the running module. After you hit the 
'run' button, the module switches to the Output-tab and you will see information about 
the process. If all goes well, you will see \texttt{Successfully finished} at the end.

\minisec{Manual}

This tab shows the help page of each GRASS module. You can have a look at the manual-page
if you want to get a deeper knowledge about the purpose of the module.
You may have recognized that some modules have more options and parameters than given in
the 'Options' tab. This is correct and done by design. To keep the GUI simple as possible
only the needed options and parameters are put in the Options tab. But you can always 
use the GRASS shell to run the module with all its parameters.

\begin{Tip}\caption{\textsc{Display results immediately}}\index{GRASS!display results}
\qgistip{If you want to display your calculation results immediately in your map canvas,
you can use 'View Output' button at the bottom of the module tab.
}
\end{Tip} 


\subsubsection{GRASS Browser} \index{GRASS!toolbox!Browser}

A very nice feature is the newly added GRASS browser in QGIS \CURRENT. At figure \ref{subfig:grass_browser}
you can see the current location with its mapsets. 

The browser on the left allows you to browse through all you mapsets inside your selected
location. 

The right side of the browser window shows some meta information for the selected dataset, e.g. resolution,
bounding box, data source, attribute table for vector data\dots

The toolbar inside the browser tab gives you the following tools for the selected dataset:
\begin{itemize}
\item \includegraphics[width=0.7cm]{grass_add_map} Add selected map to canvas
\item \includegraphics[width=0.7cm]{grass_copy_map} Copy selected map
\item \includegraphics[width=0.7cm]{grass_rename_map} Rename selected map
\item \includegraphics[width=0.7cm]{grass_delete_map} Delete selected map
\item \includegraphics[width=0.7cm]{grass_set_region} Set current region to selected map
\item \includegraphics[width=0.7cm]{grass_refresh} Refresh browser window
\end{itemize}

The 'Rename' and 'Delete' buttons are only available in your current mapset. All other tools also work on
maps from other mapsets as well.

% Picture from the GRASS-Browser here:
\begin{figure}[h]
\centering
	\caption{GRASS toolbox}
   \subfigure[GRASS browser inside the toolbox]{\label{subfig:grass_browser}\includegraphics[clip=true, width=0.4\textwidth]{grassbrowser}}\goodgap
   \subfigure[GRASS shell inside the toolbox]{\label{subfig:grass_shell}\includegraphics[clip=true, width=0.4\textwidth]{grassshell}}
\end{figure}

\subsubsection{Customizing the modules section} \index{GRASS!toolbox!customize}
\label{sec:toolbox-customizing}

Nearly all GRASS modules can be adopted to the GRASS toolbox. A XML interface is provided to parse
the very simple XML files which configure the modules inside the toolbox.

% TODO: migrating the content of this wiki-page into the manual?
A brief description of adding new modules, changing the modules group, etc. can be found on the QGIS wiki
at \url{http://wiki.qgis.org/qgiswiki/Adding_New_Tools_to_the_GRASS_Toolbox}.

A sample XML file for generating the module \texttt{v.buffer} (v.buffer.qgm) looks like this:
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE qgisgrassmodule SYSTEM "http://mrcc.com/qgisgrassmodule.dtd">

<qgisgrassmodule label="Vector buffer" module="v.buffer">
        <option key="input" typeoption="type" layeroption="layer" />
        <option key="buffer"/>
        <option key="output" />
</qgisgrassmodule>
\end{verbatim}

The parser reads this definition and creates a new tab inside the toolbox when you select 
the module:
\begin{figure}[h]
\centering
\caption{Module generated through parsing the XML-file}\label{fig:buffer-module}
\includegraphics[clip=true, width=0.3\textwidth]{vbuffer}
\end{figure}

\subsection{Creating new vectors}\label{sec:creating_new_grass_vectors}\index{GRASS!Creating new vectors|see{editing!creating a new layer}}

With this version of QGIS it is also possible to create new vectors from within GRASS very
easily.

Just select \textsl{Plugins->GRASS->Create new GRASS layer} from the toolbar, give a new name
in the text box and start digitizing.
If you encounter a greyed-out button, make sure you have a working mapset enabled. If you forgot
how to enable have a look at sec. \ref{sec:load_grassdata}.

Since GRASS is able to organize all sort of geometries in on layer, there is no need to select
the geometry. This only applies to shapefile creation (see sec. \ref{sec:create shape}).

Some hints to make your digitizing more useful:
\begin{itemize}
\item Make sure to create an attribute table with its needed columns before you start digitizing
if you like to assign attributes to  your digitized object. 
Go to the table tab inside the digitize window.
\item If you plan to create to polygon layer, consider setting the mode to \textsl{No category}. 
Then start digitizing the boundaries which actually do not need an entry in the attribute table. 
If you have done this, change back to \textsl{Next not used} and start digitizing the centroids, which 
hold the attribute information of a polygon.

\end{itemize}

%\section{The GRASS Toolbar}
%The GRASS toolbar is displayed when the GRASS plugin is loaded using the
% Plugin Manager (see Section \ref{sec:managing_plugins}, \textsl{Managing
% Plugins}). Figure  shows the toolbar with each function annotated.
