← Back to branch summary

~ubuntu-branches/ubuntu/wily/grass/wily

« back to all changes in this revision

Viewing changes to general/g.region/g.region.html

Tags: 7.0.0~rc1+ds1-1~exp1
http://bugs.debian.org/776349
* New upstream release candidate.
* Repack upstream tarball, remove precompiled Python objects.
* Add upstream metadata.
* Update gbp.conf and Vcs-Git URL to use the experimental branch.
* Update watch file for GRASS 7.0.
* Drop build dependencies for Tcl/Tk, add build dependencies:
  python-numpy, libnetcdf-dev, netcdf-bin, libblas-dev, liblapack-dev
* Update Vcs-Browser URL to use cgit instead of gitweb.
* Update paths to use grass70.
* Add configure options: --with-netcdf, --with-blas, --with-lapack,
  remove --with-tcltk-includes.
* Update patches for GRASS 7.
* Update copyright file, changes:
  - Update copyright years
  - Group files by license
  - Remove unused license sections
* Add patches for various typos.
* Fix desktop file with patch instead of d/rules.
* Use minimal dh rules.
* Bump Standards-Version to 3.9.6, no changes.
* Use dpkg-maintscript-helper to replace directories with symlinks.
  (closes: #776349)
* Update my email to use @debian.org address.

Show diffs side-by-side

added added

removed removed

Lines of Context:
general/g.region/g.region.html
 
1
<h2>DESCRIPTION</h2>
 
2
 
 
3
The <em>g.region</em> module allows the user to manage the
 
4
settings of the current geographic region.  These regional
 
5
boundaries can be set by the user directly and/or set from
 
6
a region definition file (stored under the
 
7
<kbd>windows</kbd> directory in the user's current
 
8
mapset).  The user can create, modify, and store as many
 
9
geographic region definitions as desired for any given
 
10
mapset.  However, only one of these geographic region
 
11
definitions will be current at any given moment, for a
 
12
specified mapset;  i.e., GRASS programs that respect the
 
13
geographic region settings will use the current geographic
 
14
region settings.
 
15
 
 
16
 
 
17
<h2>DEFINITIONS</h2>
 
18
 
 
19
<dl>
 
20
<dt><b>Region:</b>
 
21
 
 
22
<dd>In GRASS, a <em>region</em> refers to a geographic area
 
23
with some defined boundaries, based on a specific map
 
24
coordinate system and map projection.  Each region also has
 
25
associated with it the specific east-west and north-south
 
26
resolutions of its smallest units (rectangular units called
 
27
"cells").
 
28
 
 
29
<p>
 
30
The region's boundaries are given as the northernmost,
 
31
southernmost, easternmost, and westernmost points that
 
32
define its extent (cell edges).  The north and south boundaries
 
33
are commonly called <em>northings</em>, while the east and west
 
34
boundaries are called <em>eastings</em>.
 
35
 
 
36
<p>
 
37
The region's cell resolution defines the size of the
 
38
smallest piece of data recognized (imported, analyzed,
 
39
displayed, stored, etc.) by GRASS modules affected by the
 
40
current region settings. The north-south and east-west cell
 
41
resolutions need not be the same, thus allowing non-square
 
42
data cells to exist.
 
43
 
 
44
<p>Typically all raster and display modules are affected by the current
 
45
region settings, but not vector modules.
 
46
Some special modules diverge from this rule, for example raster import
 
47
modules and <em>v.in.region</em>.
 
48
 
 
49
 
 
50
<dt><b>Default Region:</b>
 
51
 
 
52
<dd>Each GRASS LOCATION has a fixed
 
53
geographic region, called the default geographic region
 
54
(stored in the region file <kbd>DEFAULT_WIND</kbd> under
 
55
the special mapset <kbd>PERMANENT</kbd>), that defines the
 
56
extent of the data base.  While this provides a starting
 
57
point for defining new geographic regions, user-defined
 
58
geographic regions need not fall within this geographic
 
59
region. The current region can be reset to the default region
 
60
with the <b>-d</b> flag. The default region is initially set
 
61
when the location is first created and can be reset using the
 
62
<b>-s</b> flag.
 
63
 
 
64
<dt><b>Current Region:</b>
 
65
 
 
66
<dd>Each mapset has a current geographic region.  This
 
67
region defines the geographic area in which all GRASS
 
68
displays and raster analyses will be done. Raster data will be
 
69
resampled, if necessary, to meet the cell resolutions of
 
70
the current geographic region setting.
 
71
 
 
72
<dt><b>Saved Regions:</b>
 
73
 
 
74
<dd>Each GRASS MAPSET may contain any number of
 
75
pre-defined, and named, geographic regions.  These region
 
76
definitions are stored in the user's current mapset
 
77
location under the <kbd>windows</kbd> directory (also
 
78
referred to as the user's saved region definitions).
 
79
Any of these pre-defined geographic regions
 
80
may be selected, by name, to become the current geographic
 
81
region.  Users may also access saved region definitions
 
82
stored under other mapsets in the current location, if
 
83
these mapsets are included in the user's mapset search
 
84
path or the '@' operator is used (<tt>region_name@mapset</tt>).
 
85
</dl>
 
86
 
 
87
 
 
88
<h2>NOTES</h2>
 
89
 
 
90
After all updates have been applied, the current region's
 
91
southern and western boundaries are (silently) adjusted so
 
92
that the north/south distance is a multiple of the
 
93
north/south resolution and that the east/west distance is a
 
94
multiple of the east/west resolution.
 
95
 
 
96
<p>With the <b>-a</b> flag all four boundaries are adjusted 
 
97
to be even multiples of the resolution, aligning the region to the
 
98
resolution supplied by the user. The default is to
 
99
align the region resolution to match the region boundaries.
 
100
 
 
101
<p>The <b>-m</b> flag will report the region resolution in meters. The
 
102
resolution is calculated by averaging the resolution at the region
 
103
boundaries. This resolution is calculated by dividing the geodesic 
 
104
distance in meters at the boundary by the number of rows or columns.
 
105
For example the east / west resolution (ewres) is determined from an 
 
106
average of the geodesic distances at the North and South boundaries 
 
107
divided by the number of columns.
 
108
<!-- add'l info. include?
 
109
Print the region resolution in meters (from geodesic). With no other
 
110
flags the default output format is shell stype (-g). The region resolution
 
111
represents the center of the map. The resolutions are calculated at the four
 
112
outside edges, then the two NS edges are averaged and the two EW edges are
 
113
averaged, the results finally printed.
 
114
-->
 
115
 
 
116
 
 
117
<p>The <b>-p</b> (or <b>-g</b>) option is recognized
 
118
last.  This means that all changes are applied to the
 
119
region settings before printing occurs.
 
120
<p>The <b>-g</b> flag prints the current region settings in shell script style.
 
121
This format can be given back to <em>g.region</em> on its command line.
 
122
This may also be used to save region settings as shell environment variables
 
123
with the UNIX eval command, "<tt>eval `g.region -g`</tt>".
 
124
 
 
125
 
 
126
<h3>Additional parameter information:</h3>
 
127
 
 
128
<dl>
 
129
 
 
130
<dt><b>zoom=</b><em>name</em>
 
131
<dd>Shrink current region settings to the smallest region
 
132
encompassing all non-NULL data in the named raster map
 
133
layer that fall inside the user's current region. In this
 
134
way you can tightly zoom in on isolated clumps within a
 
135
bigger map.
 
136
<p>If the user also includes the <b>raster=</b><em>name</em>
 
137
option on the command line, <b>zoom=</b><em>name</em> will
 
138
set the current region settings to the smallest region
 
139
encompassing all non-NULL data in the named <b>zoom</b> map
 
140
that fall inside the region stated in the cell header for
 
141
the named <b>raster</b> map.
 
142
 
 
143
 
 
144
<dt><b>align=</b><em>name</em> 
 
145
 
 
146
<dd>Set the current resolution equal to that of the named
 
147
raster map, and align the current region to a row and
 
148
column edge in the named map.  Alignment only moves the
 
149
existing region edges outward to the edges of the next
 
150
nearest cell in the named raster map - not to the named
 
151
map's edges.  To perform the latter function, use the
 
152
<b>raster=</b><em>name</em> option.
 
153
</dl>
 
154
 
 
155
 
 
156
 
 
157
<h2>EXAMPLES</h2>
 
158
 
 
159
<dl>
 
160
<dt><span class="code"><tt>
 
161
g.region n=7360100 e=699000
 
162
</tt></span>
 
163
 
 
164
<dd> will reset the northing and easting for the current
 
165
region, but leave the south edge, west edge, and the region
 
166
cell resolutions unchanged.
 
167
 
 
168
<p>
 
169
<dt><span class="code"><tt>
 
170
g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01
 
171
</tt></span>
 
172
 
 
173
<dd> will reset the northing, easting, southing, westing and resolution
 
174
for the current region, here in DMS latitude-longitude style
 
175
(decimal degrees and degrees with decimal minutes can also be used).
 
176
 
 
177
<p>
 
178
<dt><span class="code"><tt>
 
179
g.region -dp s=698000
 
180
</tt></span>
 
181
 
 
182
<dd> will set the current region from the default region
 
183
for the GRASS data base location, reset the south edge to
 
184
698000, and then print the result.
 
185
 
 
186
<p>
 
187
<dt><span class="code"><tt>
 
188
g.region n=n+1000 w=w-500
 
189
</tt></span>
 
190
 
 
191
<dd> The n=<em>value</em> may also be specified as a
 
192
function of its current value:  n=n+<em>value</em>
 
193
increases the current northing, while n=n-<em>value</em>
 
194
decreases it.  This is also true for s=<em>value</em>,
 
195
e=<em>value</em>, and w=<em>value</em>.  In this example
 
196
the current region's northern boundary is extended by 1000
 
197
units and the current region's western boundary is
 
198
decreased by 500 units.
 
199
 
 
200
<p>
 
201
<dt><span class="code"><tt>
 
202
g.region n=s+1000 e=w+1000
 
203
</tt></span>
 
204
 
 
205
<dd> This form allows the user to set the region boundary
 
206
values relative to one another.  Here, the northern
 
207
boundary coordinate is set equal to 1000 units larger than
 
208
the southern boundary's coordinate value, and the eastern
 
209
boundary's coordinate value is set equal to 1000 units
 
210
larger than the western boundary's coordinate value.  The
 
211
corresponding forms s=n-<em>value</em> and
 
212
 
 
213
<p>
 
214
w=e-<em>value</em> may be used to set the values of the
 
215
region's southern and western boundaries, relative to the
 
216
northern and eastern boundary values.
 
217
 
 
218
 
 
219
<dt><span class="code"><tt>
 
220
g.region raster=soils
 
221
</tt></span>
 
222
 
 
223
<dd> This form will make the current region settings
 
224
exactly the same as those given in the cell header file for
 
225
the raster map layer <em>soils</em>.
 
226
 
 
227
<p>
 
228
 
 
229
<dt><span class="code"><tt>
 
230
g.region raster=soils zoom=soils
 
231
</tt></span>
 
232
 
 
233
<dd> This form will first look up the cell header file for
 
234
the raster map layer <em>soils</em>, use this as the
 
235
current region setting, and then shrink the region down to
 
236
the smallest region which still encompasses all non-NULL
 
237
data in the map layer <em>soils</em>.  Note that if the
 
238
parameter <em>raster=soils</em> were not specified, the
 
239
zoom would shrink to encompass all non-NULL data values in
 
240
the soils map that were located within the <i>current region</i>
 
241
settings.
 
242
 
 
243
<p>
 
244
 
 
245
<dt><span class="code"><tt>
 
246
g.region -up raster=soils
 
247
</tt></span>
 
248
 
 
249
<dd> The <b>-u</b> option suppresses the re-setting of the
 
250
current region definition.  This can be useful when it is
 
251
desired to only extract region information.  In this case,
 
252
the cell header file for the soils map layer is printed
 
253
without changing the current region settings.
 
254
 
 
255
<p>
 
256
<dt><span class="code"><tt>
 
257
g.region -up zoom=soils save=soils
 
258
</tt></span>
 
259
 
 
260
<dd> This will zoom into the smallest region which
 
261
encompasses all non-NULL soils data values, and save the
 
262
new region settings in a file to be called <em>soils</em>
 
263
and stored under the <kbd>windows</kbd> directory in the
 
264
user's current mapset.  The current region settings are not
 
265
changed.
 
266
<p>
 
267
 
 
268
<dt><span class="code"><tt>
 
269
g.region b=0 t=3000 tbres=200 res3=100
 
270
g.region -p3
 
271
</tt></span>
 
272
 
 
273
<dd> This will define the 3D region for voxel computations.
 
274
In this example a volume with bottom (0m) to top (3000m)
 
275
at horizontal resolution (100m) and vertical resolution (200m)
 
276
is defined.
 
277
 
 
278
<p>
 
279
<dt><span class="code"><tt>
 
280
g.region -p
 
281
</tt></span>
 
282
 
 
283
<dd> This will print the current region in the format:
 
284
 
 
285
<div class="code"><pre>
 
286
projection: 1 (UTM)
 
287
zone:       13
 
288
datum:      nad27
 
289
ellipsoid:  clark66
 
290
north:      4928000
 
291
south:      4914000
 
292
west:       590000
 
293
east:       609000
 
294
nsres:      20
 
295
ewres:      20
 
296
rows:       700
 
297
cols:       950
 
298
</pre></div>
 
299
 
 
300
<p>
 
301
<dt><span class="code"><tt>
 
302
g.region -p3
 
303
</tt></span>
 
304
 
 
305
<dd> This will print the current region and the 3D region (used for voxels)
 
306
in the format:
 
307
 
 
308
<div class="code"><pre>
 
309
projection: 1 (UTM)
 
310
zone:       13
 
311
datum:      nad27
 
312
ellipsoid:  clark66
 
313
north:      4928000
 
314
south:      4914000
 
315
west:       590000
 
316
east:       609000
 
317
top:        1.00000000
 
318
bottom:     0.00000000
 
319
nsres:      20
 
320
nsres3:     20
 
321
ewres:      20
 
322
ewres3:     20
 
323
tbres:      1
 
324
rows:       700
 
325
rows3:      700
 
326
cols:       950
 
327
cols3:      950
 
328
depths:     1
 
329
</pre></div>
 
330
 
 
331
<p>
 
332
<dt><span class="code"><tt>
 
333
g.region -g
 
334
</tt></span>
 
335
 
 
336
<dd> The <b>-g</b> option prints the region in the
 
337
following script style (key=value) format:
 
338
 
 
339
<div class="code"><pre>
 
340
n=4928000
 
341
s=4914000
 
342
w=590000
 
343
e=609000
 
344
nsres=20
 
345
ewres=20
 
346
rows=700
 
347
cols=950
 
348
</pre></div>
 
349
 
 
350
<p>
 
351
<dt><span class="code"><tt>
 
352
g.region -bg
 
353
</tt></span>
 
354
 
 
355
<dd> The <b>-bg</b> option prints the region in the
 
356
following script style (key=value) format plus the
 
357
boundary box in latitude-longitude/WGS84:
 
358
 
 
359
<div class="code"><pre>
 
360
n=4928000
 
361
s=4914000
 
362
w=590000
 
363
e=609000
 
364
nsres=20
 
365
ewres=20
 
366
rows=700
 
367
cols=950
 
368
LL_W=-103.87080682
 
369
LL_E=-103.62942884
 
370
LL_N=44.50164277
 
371
LL_S=44.37302019
 
372
</pre></div>
 
373
 
 
374
<p>
 
375
<dt><span class="code"><tt>
 
376
g.region -l
 
377
</tt></span>
 
378
 
 
379
<dd> The <b>-l</b> option prints the region in the
 
380
following format:
 
381
 
 
382
<div class="code"><pre>
 
383
long: -103.86789484 lat: 44.50165890 (north/west corner)
 
384
long: -103.62895703 lat: 44.49904013 (north/east corner)
 
385
long: -103.63190061 lat: 44.37303558 (south/east corner)
 
386
long: -103.87032572 lat: 44.37564292 (south/west corner)
 
387
rows:       700
 
388
cols:       950
 
389
Center longitude: 103:44:59.170374W [-103.74977]
 
390
Center latitude:  44:26:14.439781N [44.43734]
 
391
</pre></div>
 
392
 
 
393
<p>
 
394
<dt><span class="code"><tt>
 
395
g.region -pm
 
396
</tt></span>
 
397
 
 
398
<dd> This will print the current region in the format
 
399
 (latitude-longitude location):
 
400
 
 
401
<div class="code"><pre>
 
402
projection: 3 (Latitude-Longitude)
 
403
zone:       0
 
404
ellipsoid:  wgs84
 
405
north:      90N
 
406
south:      40N
 
407
west:       20W
 
408
east:       20E
 
409
nsres:      928.73944902
 
410
ewres:      352.74269109
 
411
rows:       6000
 
412
cols:       4800
 
413
</pre></div>
 
414
Note that the resolution is here reported in meters, not decimal degrees.
 
415
 
 
416
</dl>
 
417
 
 
418
<p>Usage example of <em>g.region</em> in a shell with external software:<br>
 
419
<!-- why not 'v.in.ogr spatial=' ?? -->
 
420
Extract spatial subset of external vector map 'soils.shp' to new external
 
421
vector map 'soils_cut.shp' using the OGR 'ogr2ogr' tool:<br>
 
422
 
 
423
<div class="code"><pre>
 
424
eval `g.region -g`
 
425
ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp
 
426
</pre></div>
 
427
 
 
428
This requires that the location/SHAPE file projection match.
 
429
 
 
430
 
 
431
<p>Usage example of <em>g.proj</em> and <em>g.region</em> in a shell with external software:<br>
 
432
Extract spatial subset of external raster map 'p016r035_7t20020524_z17_nn30.tif'
 
433
to new external raster map'p016r035_7t20020524_nc_spm_wake_nn30.tif using the GDAL
 
434
'gdalwarp' tool:<br>
 
435
 
 
436
<div class="code"><pre>
 
437
eval `g.region -g`
 
438
gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \
 
439
         p016r035_7t20020524_z17_nn30.tif \
 
440
         p016r035_7t20020524_nc_spm_wake_nn30.tif
 
441
</pre></div>
 
442
 
 
443
Here the input raster map does not have to match the location
 
444
projection since it is reprojected on the fly.
 
445
 
 
446
 
 
447
 
 
448
<h2>SEE ALSO</h2>
 
449
 
 
450
<em>
 
451
<a href="g.access.html">g.access</a>,
 
452
<a href="g.mapsets.html">g.mapsets</a>,
 
453
<a href="g.proj.html">g.proj</a>,
 
454
<a href="g.setproj.html">g.setproj</a><br>
 
455
Environment variables: <a href="variables.html#internal">GRASS_REGION and WIND_OVERRIDE</a>
 
456
</em>
 
457
 
 
458
 
 
459
<h2>AUTHOR</h2>
 
460
 
 
461
Michael Shapiro,
 
462
U.S.Army Construction Engineering 
 
463
Research Laboratory
 
464
 
 
465
<p><i>Last changed: $Date: 2014-12-19 22:55:37 +0100 (Fri, 19 Dec 2014) $</i>