grass_database.html

<!-- meta page description: GRASS GIS Database -->

A GRASS GIS Database is simply a set of directories and files
with certain structure which GRASS GIS works efficiently with.
Location is a directory with data related to
one geographic location or a project.
All data within one Location has the same cartographic projection.
A Location contains Mapsets and each Mapset contains data related to
a specific task, user or a smaller project.
Within each Location, a mandatory PERMANENT Mapset exists
which can contain commonly used data within a Location such as base maps.
PERMANENT Mapset also contains metadata related to Location
such as projection.
When GRASS GIS is started it connects to a Database, Location and Mapset
specified by the user.

<p>
<!-- original drawing: doc/grass_database.svg -->
<center>
  <img src="grass_database.png" alt="example: nc_spm - highway - elevation"><br>
  <i>Fig. 1: GRASS GIS Database structure as visible to the user</i>
</center>

<!--
TODO: Introduction/Rationale/Motivation

data format handling separated from analysis

organizing the data
In geospatial analysis often involves combining data from various sources
multiple users
-->


<h3>GRASS GIS Database</h3>

All data for GRASS GIS must be in GRASS GIS Database which is a directory
(visible on the disk) containing subdirectories which are GRASS Locations.
User can have one or more of Databases on the disk. Typically users have
one directory called <code>grassdata</code> in their home directory.
In multi-user environment users often have a <code>grassdata</code> directory
mounted as a network directory (network file system).
For teams, a centralized GRASS DATABASE would be defined
in a shared network file system (e.g. NFS).
<!-- TODO: above needs some fixes -->

<p>
GRASS GIS Databases can be safely copied or moved as any other directories.
Don't be confused with (relational) databases which are used in GRASS GIS
to hold attribute data and might be part of the GRASS GIS Database.
From user point of view, GRASS GIS Database with all its data in it
is similar to, e.g. PostGIS, database, as it stores all information
inside in a specific format and is accessible by specific tools.
GRASS GIS Databases is in GRASS GIS often called GISDBASE or DATABASE.


<h3>GRASS Locations</h3>

Location is a directory which contains GRASS Mapsets which are its subdirectories.
All data in one Location have the same projection (coordinate system, datum).
Each Location must contain Mapset called PERMANENT.
Typically, a Location contains all data related to one project
or a geographic area (geographic location or region).
Alternatively, Location can simply contain all data in a given projection.

<p>
GRASS Locations can be safely copied or moved as any other directories.
Compressed Location is usually what GRASS users exchange between each other
when they want to share a lot of data.
For example, GRASS GIS sample data are provided as Locations.

<p>
Don't be confused with location as a place (file or directory) in a file system.
The word location in GRASS Location refers to a location or area on Earth
(or whatever is applicable).
Users and programmers familiar with relational databases such as PostgreSQL
can view Location as an individual database inside the system or a storage area
which would be equivalent to GRASS GIS Database. Mapsets in a Locations
are like namespaces or schemas inside a database.

<!-- TODO: naming limitations and best practices -->


<h3>GRASS Mapsets</h3>

Mapsets contains the actual data, mostly geospatial data,
referred to as maps in GRASS GIS.
Mapsets are a tool for organizing maps in a transparent way
as well as a tool for isolating different tasks to prevent data loss.

<p>
GRASS GIS is always connected to one particular Mapset.
GRASS GIS modules can create, modify, change, or delete a data only in
the current Mapset.
By default, only the data from the current Mapset and PERMANENT Mapset
are visible. Using
<a href="g.mapsets.html"><em>g.mapsets</em></a>
module or in GUI other Mapsets can be made visible and seamlessly accessible.
All data are available for reading when Mapset is specified explicitly,
for example to access map <code>streets</code> in Mapset
<code>new_highway</code> user can use <code>streets@new_highway</code>.
For maps which are in the current or PERMAENT Mapsets or Mapsets
sets as visible (accessible), there is no need to use
<code>@mapset</code> syntax.


<p>
Mapsets are used to store maps related to one project, smaller project,
specific task, issue or subregions.
In multi-user environment, when a team works together on one project,
Mapsets support simultaneous access of several users to the maps
stored within the same Location.
Besides access to his or her own
Mapset, each user can also read maps in PERMANENT Mapsent
and in other users' Mapsets when set.
However, each user can modify or remove only the maps
in his or her own Mapset.

<p>
Besides the geospatial data, Mapset holds additional data such as
color tables (managed e.g. by <a href="r.colors.html"><em>r.colors</em></a>)
and the current computational region's extent and resolution
stored in a file called <code>WIND</code>
and managed by <a href="g.region.html"><em>g.region</em></a>.

<p>
Mapsets can be copied and moved as directories, however only when it is clear
that the projections of both Locations
(as reported by <a href="g.proj.html"><em>g.proj</em></a>)
match each other. Since this is sometimes hard to to establish,
it is recommended to use <a href="r.proj.html"><em>r.proj</em></a>
or <a href="v.proj.html"><em>v.proj</em></a> to reproject the data.
The files and directories should not be moved or modified directly,
but only using GRASS GIS tools.


<h3>The role of the PERMANENT Mapset</h3>

When creating a new Location, GRASS GIS automatically creates a special
Mapset called PERMANENT where the core data for the Location are stored.

<p>
Since the maps in PERMANENT Mapset are visible from all the other Mapsets,
it can be used to store the base maps (base cartography), data common
to all projects or needed for different analyses done is separate Mapsets.

<p>
In multi-user environment, data in the PERMANENT Mapset can only be added,
modified or removed by the owner of the PERMANENT Mapset; however, they can be
accessed, analyzed, and copied into their own Mapset by the other
users. The PERMANENT Mapset is useful for providing general spatial
data (e.g. an elevation model), accessible but write-protected to all
users who are working in the same Location as the database owner.
To manipulate or add data to PERMANENT, the owner can start
GRASS GIS and choose the relevant Location and the PERMANENT Mapset.

<p>
The PERMANENT Mapset also contains the <code>DEFAULT_WIND</code> file which holds
the default computational region's extent and resolution values
for the Location (which all Mapsets will inherit when they are created).
Users have the option of switching back to the default region at any time.


<h3>Importing, exporting and linking data</h3>

GRASS GIS works only with data which are imported into a GRASS Database,
so all data needs to be imported, e.g. by
<a href="r.in.gdal.html"><em>r.in.gdal</em></a> or
highly convenient <a href="r.import.html"><em>r.import</em></a>,
before the actual analysis.
Data in GRASS Datable can be exported using for example
<a href="r.in.gdal.html"><em>r.in.gdal</em></a> in case of raster maps.

<p>
For cases when import is not desirable, an option to link external data exists.
Projection of the linked data must match the Location's projection
otherwise the external data cannot be linked. (Linking data in different
projection is not allowed as it would require on-the-fly reprojection
which could cause inconsistencies in the data.

<p>
For example, module <a href="r.external.html"><em>r.external</em></a> links
external raster data, so that the data are accessible in GRASS Database
as standard raster maps. Similarly for newly created maps,
<a href="r.external.out.html"><em>r.external.out</em></a>
setups a format and directory where the actual data will be stored,
however in GRASS Database the data will be created as standard maps.


<h3>Starting GRASS GIS using GUI</h3>

After launching GRASS GIS, the startup window will open (Fig. 2).

<p>
<center>
  <img src="grass_start.png" alt="startup window with numbered fields"><br>
  <i>Fig. 2: GRASS GIS startup window</i>
</center>

The startup windows provides these functions:

<ol>
    <li>Selecting the GRASS GIS Database directory.
    <li>Selecting the Location (e.g. a project or area).
        See the <em>Location Wizard</em> (4) for creating new Locations.
    <li>Selecting the Mapset (a subproject or task).
        Creating a new Mapset requires only name.
    <li>The <em>Location Wizard</em> for creating new Locations
        based for example, on existing georeferenced file or EPDS code.
    <li>Start GRASS GIS once you have selected an existing Location and Mapset
        or defined a new one. The graphical user interface
        <a href="wxGUI.html">wxGUI</a> will open and provide you with a
        menu system, map visualization tool, digitizer, and more.
</ol>


<h3>Starting GRASS GIS using command line</h3>

GRASS GIS can be started with given Database, Location and Mapset
from the command line. For example, the following will start
in a given Mapset with only command line interface:

<div class="code"><pre>
grass72 -text ~/grassdata/mylocation/mymapset
</pre></div>

And the following will create the given Location with projection given
by the EPSG code and it will start the default interface
(GUI or command line):

<div class="code"><pre>
grass72 -c EPSG:5514:3 ~/grassdata/mylocation
</pre></div>

See <a href="grass7.html"><em>grass</em></a> command manual for more details.


<h3>Creating a New Location with the Location Wizard</h3>

The <a href="wxGUI.html">wxGUI</a> graphical user interface provides a
graphical <em>Location Wizard</em> which lets you easily create a
new Location for your own data. You will be guided through a series of
dialogues to browse and select predefined projections or to
define custom projections.

<p>
The most convenient way of using <em>Location Wizard</em> is creating new
Location based on a georeferenced file, such as Shapefile or GeoTIFF,
or by selecting the corresponding EPSG projection code.
In case of using georeferenced file, you are asked whether the data itself
should be imported into the new Location.
<!-- TODO: some of this should be or already is automatic
dialog with checkboxes would be also more convenient than multiple questions -->
The default region is then set to match imported map.
<!-- TODO: difference rasters versus vectors -->

<!--
TODO: some notes about resolution and extent would be nice
(as well as removing the step from the wizard)

this was in the text pointing to some unknown text:
* The rules to define the resolution as described above also apply here.
* Find below also some rules to define the default raster resolution
  for a new Location.
-->

<p>
After defining a new Location, wxGUI starts automatically.
<!-- TODO: how GUI start actually works -->
If data were already imported, you can add them into the Layer Manager now
and display them.
More data can be imported into the Location, e.g. using import options in
the <em>File</em> menu in <em>Layer Manager</em> or
<a href="r.import.html"><em>r.import</em></a>.


<h2>See also</h2>

<em>
<a href="index.html">GRASS GIS 7 Reference Manual</a>
<br>
<a href="grass7.html">GRASS GIS 7 startup program manual page</a>
<br>
<a href="http://grasswiki.osgeo.org/wiki/Importing_data">Importing data on GRASS Wiki</a>
<br>
<a href="r.import.html">r.import</a>,
<a href="v.import.html">v.import</a>,
<a href="r.external.html">r.external</a>,
<a href="v.external.html">v.external</a>,
<a href="r.proj.html">r.proj</a>,
<a href="v.proj.html">v.proj</a>,
</em>

<p>
<i>Last changed: $Date$</i>