Debian Codegraph @

doc/grass_database.html

raw
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>