Debian Codegraph @

general/g.region/g.region.html

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