| 1 |
<!-- meta page description: GRASS Database --> |
| 2 |
|
| 3 |
A GRASS Database is simply a set of directories and files |
| 4 |
with certain structure which GRASS works efficiently with. |
| 5 |
Project is a directory with data related to |
| 6 |
one geographic location or a project. |
| 7 |
All data within one project has the same coordinate reference system. |
| 8 |
A project contains mapsets and each mapset contains data related to |
| 9 |
a specific task, user or a smaller project. |
| 10 |
Within each project, a mandatory PERMANENT mapset exists |
| 11 |
which can contain commonly used data within one GRASS project |
| 12 |
such as base maps. |
| 13 |
The PERMANENT mapset also contains metadata related to the project |
| 14 |
such as the coordinate reference system. |
| 15 |
When GRASS is started it connects to a database, project and mapset |
| 16 |
specified by the user. |
| 17 |
|
| 18 |
<p> |
| 19 |
<!-- original drawing: doc/grass_database.svg --> |
| 20 |
<center> |
| 21 |
<img src="grass_database.png" alt="example: nc_spm - highway - elevation"><br> |
| 22 |
<i>Fig. 1: GRASS Database structure as visible to the user</i> |
| 23 |
</center> |
| 24 |
|
| 25 |
<!-- |
| 26 |
TODO: Introduction/Rationale/Motivation |
| 27 |
|
| 28 |
data format handling separated from analysis |
| 29 |
|
| 30 |
organizing the data |
| 31 |
In geospatial analysis often involves combining data from various sources |
| 32 |
multiple users |
| 33 |
--> |
| 34 |
|
| 35 |
<h3>GRASS Database</h3> |
| 36 |
|
| 37 |
All data for GRASS must be in GRASS Database which is a directory |
| 38 |
(visible on the disk) containing subdirectories which are GRASS projects. |
| 39 |
User can have one or more of Databases on the disk. Typically users have |
| 40 |
one directory called <code>grassdata</code> in their home directory. |
| 41 |
In multi-user environment users often have a <code>grassdata</code> directory |
| 42 |
mounted as a network directory (network file system). |
| 43 |
For teams, a centralized GRASS DATABASE would be defined |
| 44 |
in a shared network file system (e.g. NFS). |
| 45 |
<!-- TODO: above needs some fixes --> |
| 46 |
|
| 47 |
<p> |
| 48 |
GRASS Databases can be safely copied or moved as any other directories. |
| 49 |
Don't be confused with (relational) databases which are used in GRASS |
| 50 |
to hold attribute data and might be part of the GRASS Database. |
| 51 |
From user point of view, GRASS Database with all its data in it |
| 52 |
is similar to, e.g. PostGIS, database, as it stores all information |
| 53 |
inside in a specific format and is accessible by specific tools. |
| 54 |
GRASS Databases is in GRASS often called GISDBASE or DATABASE. |
| 55 |
|
| 56 |
<h3>GRASS Projects</h3> |
| 57 |
|
| 58 |
A project is further organized into mapsets which are subdirectories of |
| 59 |
the project directory. All data in one project have the same coordinate |
| 60 |
reference system (projection, datum). |
| 61 |
Each project contains a mapset called PERMANENT. |
| 62 |
Typically, a project contains all data related to one real-world project |
| 63 |
or a geographic area (geographic location or region). |
| 64 |
Alternatively, a project can simply contain data in a given coordinate |
| 65 |
reference system. |
| 66 |
|
| 67 |
<p> |
| 68 |
GRASS projects can be safely copied or moved as any other directories. |
| 69 |
Compressed projects are usually what GRASS users exchange between each other |
| 70 |
when they want to share a lot of data. |
| 71 |
For example, GRASS sample data are provided as projects. |
| 72 |
|
| 73 |
<p> |
| 74 |
Note that a GRASS project used to be called <em>location</em> and |
| 75 |
this name has not been completely removed from code and documentation yet. |
| 76 |
|
| 77 |
<p> |
| 78 |
Users and programmers familiar with relational databases such as PostgreSQL |
| 79 |
can view projects as individual databases inside a storage area (the GRASS Database). |
| 80 |
Mapsets in a project are like namespaces or schemas inside a database. |
| 81 |
|
| 82 |
<!-- TODO: naming limitations and best practices --> |
| 83 |
|
| 84 |
<h3>GRASS Mapsets</h3> |
| 85 |
|
| 86 |
Mapsets contains the actual data, mostly geospatial data, |
| 87 |
referred to as maps in GRASS. |
| 88 |
Mapsets are a tool for organizing maps in a transparent way |
| 89 |
as well as a tool for isolating different tasks to prevent data loss. |
| 90 |
|
| 91 |
<p> |
| 92 |
GRASS is always connected to one particular mapset. |
| 93 |
GRASS modules can create, modify, change, or delete a data only in |
| 94 |
the current mapset. |
| 95 |
By default, only the data from the current mapset and PERMANENT mapset |
| 96 |
are visible. Using |
| 97 |
<a href="g.mapsets.html"><em>g.mapsets</em></a> |
| 98 |
module or in GUI other mapsets can be made visible and seamlessly accessible. |
| 99 |
All data are available for reading when mapset is specified explicitly, |
| 100 |
for example to access map <code>streets</code> in mapset |
| 101 |
<code>new_highway</code> user can use <code>streets@new_highway</code>. |
| 102 |
For maps which are in the current or PERMAENT mapsets or mapsets |
| 103 |
sets as visible (accessible), there is no need to use |
| 104 |
<code>@mapset</code> syntax. |
| 105 |
|
| 106 |
|
| 107 |
<p> |
| 108 |
Mapsets are used to store maps related to one project, smaller project, |
| 109 |
specific task, issue or subregions. |
| 110 |
In a multi-user environment, where team members work together on a single |
| 111 |
project, individual mapsets support simultaneous access of several users to |
| 112 |
the maps stored within the same project. |
| 113 |
Besides access to their own |
| 114 |
mapset, each user can also read maps in PERMANENT Mapsent |
| 115 |
and in other users' mapsets when set. |
| 116 |
However, each user can modify or remove only the maps |
| 117 |
in his or her own mapset. |
| 118 |
|
| 119 |
<p> |
| 120 |
Besides the geospatial data, mapset holds additional data such as |
| 121 |
color tables (managed e.g. by <a href="r.colors.html"><em>r.colors</em></a>) |
| 122 |
and the current computational region's extent and resolution |
| 123 |
stored in a file called <code>WIND</code> |
| 124 |
and managed by <a href="g.region.html"><em>g.region</em></a>. |
| 125 |
|
| 126 |
<p> |
| 127 |
Mapsets can be copied and moved as directories only when it is clear |
| 128 |
that their coordinate reference systems |
| 129 |
(as reported by <a href="g.proj.html"><em>g.proj</em></a>) |
| 130 |
match. In case of data coming with different coordinate reference systems, |
| 131 |
it is recommended to use <a href="r.proj.html"><em>r.proj</em></a> |
| 132 |
or <a href="v.proj.html"><em>v.proj</em></a> to reproject the data. |
| 133 |
The files and directories should not be moved or modified directly, |
| 134 |
but only using GRASS tools. |
| 135 |
|
| 136 |
<h3>The role of the PERMANENT Mapset</h3> |
| 137 |
|
| 138 |
When creating a new project, GRASS automatically creates a special |
| 139 |
mapset called PERMANENT where the core data for the project are stored. |
| 140 |
|
| 141 |
<p> |
| 142 |
Since the maps in PERMANENT mapset are visible from all the other mapsets, |
| 143 |
it can be used to store the base maps (base cartography), data common |
| 144 |
to all projects or needed for different analyses done is separate mapsets. |
| 145 |
|
| 146 |
<p> |
| 147 |
In multi-user environment, data in the PERMANENT mapset can only be added, |
| 148 |
modified or removed by the owner of the PERMANENT mapset; however, they can be |
| 149 |
accessed, analyzed, and copied into their own mapset by the other |
| 150 |
users. The PERMANENT mapset is useful for providing general spatial |
| 151 |
data (e.g. an elevation model), accessible but write-protected to all |
| 152 |
users who are working with the same GRASS project as the database owner. |
| 153 |
To manipulate or add data to PERMANENT, the owner can start |
| 154 |
GRASS and choose the relevant project and the PERMANENT mapset. |
| 155 |
|
| 156 |
<p> |
| 157 |
The PERMANENT mapset also contains the <code>DEFAULT_WIND</code> file which holds |
| 158 |
the default computational region's extent and resolution values |
| 159 |
for the project (which all mapsets will inherit when they are created). |
| 160 |
Users have the option of switching back to the default region at any time. |
| 161 |
|
| 162 |
<h3>Importing, exporting and linking data</h3> |
| 163 |
|
| 164 |
GRASS works only with data which are imported into a GRASS Database, |
| 165 |
so all data needs to be imported, e.g. by |
| 166 |
<a href="r.in.gdal.html"><em>r.in.gdal</em></a> or |
| 167 |
highly convenient <a href="r.import.html"><em>r.import</em></a>, |
| 168 |
before the actual analysis. |
| 169 |
Data in GRASS Datable can be exported using for example |
| 170 |
<a href="r.in.gdal.html"><em>r.in.gdal</em></a> in case of raster maps. |
| 171 |
|
| 172 |
<p> |
| 173 |
For cases when import is not desirable, an option to link external data exists. |
| 174 |
The coordinate reference system of the linked data must match the project's |
| 175 |
coordinate reference system |
| 176 |
otherwise the external data cannot be linked. (Linking data in different |
| 177 |
projection is not allowed as it would require on-the-fly reprojection |
| 178 |
which could cause inconsistencies in the data. |
| 179 |
|
| 180 |
<p> |
| 181 |
For example, module <a href="r.external.html"><em>r.external</em></a> links |
| 182 |
external raster data, so that the data are accessible in GRASS Database |
| 183 |
as standard raster maps. Similarly for newly created maps, |
| 184 |
<a href="r.external.out.html"><em>r.external.out</em></a> |
| 185 |
setups a format and directory where the actual data will be stored, |
| 186 |
however in GRASS Database the data will be created as standard maps. |
| 187 |
|
| 188 |
<h3>Starting GRASS</h3> |
| 189 |
|
| 190 |
After launching GRASS for the first time, |
| 191 |
the GUI opens in a default project <code>world_latlong_wgs84</code>. |
| 192 |
From there a new project can be created. |
| 193 |
|
| 194 |
<p> |
| 195 |
<center> |
| 196 |
<img src="grass_start.png" alt="GRASS GUI after first start"><br> |
| 197 |
</center> |
| 198 |
|
| 199 |
GRASS can be also started with a given database, project and mapset |
| 200 |
from the command line. For example, the following will start |
| 201 |
in a given mapset with only command line interface: |
| 202 |
|
| 203 |
<div class="code"><pre> |
| 204 |
# Linux, Mac, *BSD, ...: |
| 205 |
grass --text ~/grassdata/nc_spm_08_grass7/user1 |
| 206 |
|
| 207 |
# Windows |
| 208 |
grass --text D:\grassdata\nc_spm_08_grass7\user1 |
| 209 |
</pre></div> |
| 210 |
|
| 211 |
And the following will create the given project with coordinate reference |
| 212 |
system given by the EPSG code and it will start the default interface |
| 213 |
(GUI or command line): |
| 214 |
|
| 215 |
<div class="code"><pre> |
| 216 |
# Linux, Mac, *BSD, ...: |
| 217 |
grass -c EPSG:5514:3 ~/grassdata/myproject |
| 218 |
|
| 219 |
# Windows |
| 220 |
grass -c EPSG:5514:3 D:\grassdata\myproject |
| 221 |
</pre></div> |
| 222 |
|
| 223 |
See <a href="grass.html"><em>grass</em></a> command manual for more details. |
| 224 |
|
| 225 |
<h3>Creating a New Project with the Project Wizard</h3> |
| 226 |
|
| 227 |
The <a href="wxGUI.html">GUI</a> provides a |
| 228 |
graphical <em>Project Wizard</em> which lets you easily create a |
| 229 |
new project for your own data. You will be guided through a series of |
| 230 |
dialogues to browse and select predefined projections or to |
| 231 |
define custom projections. |
| 232 |
|
| 233 |
<p> |
| 234 |
The most convenient way of using the <em>Project Wizard</em> is creating new |
| 235 |
project based on a georeferenced file, such as Shapefile or GeoTIFF, |
| 236 |
or by selecting the corresponding EPSG code of the coordinate reference system. |
| 237 |
In case of using georeferenced file, you are asked whether the data itself |
| 238 |
should be imported into the new project. |
| 239 |
<!-- TODO: some of this should be or already is automatic |
| 240 |
dialog with checkboxes would be also more convenient than multiple questions --> |
| 241 |
The default region is then set to match imported map. |
| 242 |
<!-- TODO: difference rasters versus vectors --> |
| 243 |
|
| 244 |
<!-- |
| 245 |
TODO: some notes about resolution and extent would be nice |
| 246 |
(as well as removing the step from the wizard) |
| 247 |
|
| 248 |
this was in the text pointing to some unknown text: |
| 249 |
* The rules to define the resolution as described above also apply here. |
| 250 |
* Find below also some rules to define the default raster resolution |
| 251 |
for a new project. |
| 252 |
--> |
| 253 |
|
| 254 |
<p> |
| 255 |
If data were already imported, you can add them into the Layer Manager now |
| 256 |
and display them. |
| 257 |
More data can be imported into the project, e.g. using import options in |
| 258 |
the <em>File</em> menu in <em>Layer Manager</em> or |
| 259 |
<a href="r.import.html"><em>r.import</em></a>. |
| 260 |
|
| 261 |
<h2>See also</h2> |
| 262 |
|
| 263 |
<em> |
| 264 |
<a href="index.html">GRASS Reference Manual</a> |
| 265 |
<br> |
| 266 |
<a href="grass.html">GRASS startup program manual page</a> |
| 267 |
<br> |
| 268 |
<a href="https://grasswiki.osgeo.org/wiki/Importing_data">Importing data on GRASS Wiki</a> |
| 269 |
<br> |
| 270 |
<a href="r.import.html">r.import</a>, |
| 271 |
<a href="v.import.html">v.import</a>, |
| 272 |
<a href="r.external.html">r.external</a>, |
| 273 |
<a href="v.external.html">v.external</a>, |
| 274 |
<a href="r.proj.html">r.proj</a>, |
| 275 |
<a href="v.proj.html">v.proj</a>, |
| 276 |
</em> |