1g.region(1) GRASS GIS User's Manual g.region(1)
2
3
4
6 g.region - Manages the boundary definitions for the geographic region.
7
9 general, settings, computational region, extent, resolution, level1
10
12 g.region
13 g.region --help
14 g.region [-dsplectwmn3bgfauo] [region=name] [raster=name[,name,...]]
15 [raster_3d=name] [vector=name[,name,...]] [n=value] [s=value]
16 [e=value] [w=value] [t=value] [b=value] [rows=value]
17 [cols=value] [res=value] [res3=value] [nsres=value]
18 [ewres=value] [tbres=value] [zoom=name] [align=name]
19 [grow=value] [save=name] [--overwrite] [--help] [--verbose]
20 [--quiet] [--ui]
21
22 Flags:
23 -d
24 Set from default region
25
26 -s
27 Save as default region
28 Only possible from the PERMANENT mapset
29
30 -p
31 Print the current region
32
33 -l
34 Print the current region in lat/long using the current ellip‐
35 soid/datum
36
37 -e
38 Print the current region extent
39
40 -c
41 Print the current region map center coordinates
42
43 -t
44 Print the current region in GMT style
45
46 -w
47 Print the current region in WMS style
48
49 -m
50 Print region resolution in meters (geodesic)
51
52 -n
53 Print the convergence angle (degrees CCW)
54 The difference between the projection’s grid north and true north,
55 measured at the center coordinates of the current region.
56
57 -3
58 Print also 3D settings
59
60 -b
61 Print the maximum bounding box in lat/long on WGS84
62
63 -g
64 Print in shell script style
65
66 -f
67 Print in shell script style, but in one line (flat)
68
69 -a
70 Align region to resolution (default = align to bounds, works only
71 for 2D resolution)
72
73 -u
74 Do not update the current region
75
76 -o
77 Force update of the current region
78
79 --overwrite
80 Allow output files to overwrite existing files
81
82 --help
83 Print usage summary
84
85 --verbose
86 Verbose module output
87
88 --quiet
89 Quiet module output
90
91 --ui
92 Force launching GUI dialog
93
94 Parameters:
95 region=name
96 Set current region from named region
97
98 raster=name[,name,...]
99 Set region to match raster map(s)
100
101 raster_3d=name
102 Set region to match 3D raster map(s) (both 2D and 3D values)
103
104 vector=name[,name,...]
105 Set region to match vector map(s)
106
107 n=value
108 Value for the northern edge
109
110 s=value
111 Value for the southern edge
112
113 e=value
114 Value for the eastern edge
115
116 w=value
117 Value for the western edge
118
119 t=value
120 Value for the top edge
121
122 b=value
123 Value for the bottom edge
124
125 rows=value
126 Number of rows in the new region
127
128 cols=value
129 Number of columns in the new region
130
131 res=value
132 2D grid resolution (north-south and east-west)
133
134 res3=value
135 3D grid resolution (north-south, east-west and top-bottom)
136
137 nsres=value
138 North-south 2D grid resolution
139
140 ewres=value
141 East-west 2D grid resolution
142
143 tbres=value
144 Top-bottom 3D grid resolution
145
146 zoom=name
147 Shrink region until it meets non-NULL data from this raster map
148
149 align=name
150 Adjust region cells to cleanly align with this raster map
151
152 grow=value
153 Number of cells to add to each side of the current region extent
154 A negative number shrinks the current region extent
155
156 save=name
157 Save current region settings in named region file
158
160 The g.region module allows the user to manage the settings of the cur‐
161 rent geographic region. These regional boundaries can be set by the
162 user directly and/or set from a region definition file (stored under
163 the windows directory in the user’s current mapset). The user can cre‐
164 ate, modify, and store as many geographic region definitions as desired
165 for any given mapset. However, only one of these geographic region
166 definitions will be current at any given moment, for a specified
167 mapset; i.e., GRASS programs that respect the geographic region set‐
168 tings will use the current geographic region settings.
169
171 Region:
172 In GRASS, a region refers to a geographic area with some defined
173 boundaries, based on a specific map coordinate system and map pro‐
174 jection. Each region also has associated with it the specific
175 east-west and north-south resolutions of its smallest units (rec‐
176 tangular units called "cells").
177
178 The region’s boundaries are given as the northernmost, southernmost,
179 easternmost, and westernmost points that define its extent (cell
180 edges). The north and south boundaries are commonly called northings,
181 while the east and west boundaries are called eastings.
182
183 The region’s cell resolution defines the size of the smallest piece of
184 data recognized (imported, analyzed, displayed, stored, etc.) by GRASS
185 modules affected by the current region settings. The north-south and
186 east-west cell resolutions need not be the same, thus allowing
187 non-square data cells to exist.
188
189 Typically all raster and display modules are affected by the current
190 region settings, but not vector modules. Some special modules diverge
191 from this rule, for example raster import modules and v.in.region.
192
193 Default Region:
194 Each GRASS LOCATION has a fixed geographic region, called the de‐
195 fault geographic region (stored in the region file DEFAULT_WIND un‐
196 der the special mapset PERMANENT), that defines the extent of the
197 data base. While this provides a starting point for defining new
198 geographic regions, user-defined geographic regions need not fall
199 within this geographic region. The current region can be reset to
200 the default region with the -d flag. The default region is ini‐
201 tially set when the location is first created and can be reset us‐
202 ing the -s flag.
203
204 Current Region:
205 Each mapset has a current geographic region. This region defines
206 the geographic area in which all GRASS displays and raster analyses
207 will be done. Raster data will be resampled, if necessary, to meet
208 the cell resolutions of the current geographic region setting.
209
210 Saved Regions:
211 Each GRASS MAPSET may contain any number of pre-defined, and named,
212 geographic regions. These region definitions are stored in the
213 user’s current mapset location under the windows directory (also
214 referred to as the user’s saved region definitions). Any of these
215 pre-defined geographic regions may be selected, by name, to become
216 the current geographic region. Users may also access saved region
217 definitions stored under other mapsets in the current location, if
218 these mapsets are included in the user’s mapset search path or the
219 ’@’ operator is used (region_name@mapset).
220
222 After all updates have been applied, the current region’s southern and
223 western boundaries are (silently) adjusted so that the north/south dis‐
224 tance is a multiple of the north/south resolution and that the
225 east/west distance is a multiple of the east/west resolution.
226
227 With the -a flag all four boundaries are adjusted to be even multiples
228 of the resolution, aligning the region to the resolution supplied by
229 the user. The default is to align the region resolution to match the
230 region boundaries.
231
232 The -m flag will report the region resolution in meters. The resolution
233 is calculated by averaging the resolution at the region boundaries.
234 This resolution is calculated by dividing the geodesic distance in me‐
235 ters at the boundary by the number of rows or columns. For example the
236 east / west resolution (ewres) is determined from an average of the ge‐
237 odesic distances at the North and South boundaries divided by the num‐
238 ber of columns.
239
240 The -p (or -g) option is recognized last. This means that all changes
241 are applied to the region settings before printing occurs.
242
243 The -g flag prints the current region settings in shell script style.
244 This format can be given back to g.region on its command line. This
245 may also be used to save region settings as shell environment variables
246 with the UNIX eval command, "eval `g.region -g`".
247
248 With -u flag current region is not updated even if one or more options
249 for changing region is used (res=, raster=, etc). This can be used for
250 example to print modified region values for further use without actu‐
251 ally modifying the current region. Similarly, -o flag forces to update
252 current region file even when e.g., only printing was specified. Flag
253 -o was added in GRASS GIS version 8 to simulate g.region behavior in
254 prior versions when current region file was always updated unless -u
255 was specified.
256
257 Additional parameter information:
258 zoom=name
259 Shrink current region settings to the smallest region encompassing
260 all non-NULL data in the named raster map layer that fall inside
261 the user’s current region. In this way you can tightly zoom in on
262 isolated clumps within a bigger map.
263
264 If the user also includes the raster=name option on the command line,
265 zoom=name will set the current region settings to the smallest region
266 encompassing all non-NULL data in the named zoom map that fall inside
267 the region stated in the cell header for the named raster map.
268
269 align=name
270 Set the current resolution equal to that of the named raster map,
271 and align the current region to a row and column edge in the named
272 map. Alignment only moves the existing region edges outward to the
273 edges of the next nearest cell in the named raster map - not to the
274 named map’s edges. To perform the latter function, use the
275 raster=name option.
276
278 Printing extent and raster resolution in 2D and 3D
279 g.region -p
280 This will print the current region in the format:
281 projection: 1 (UTM)
282 zone: 13
283 datum: nad27
284 ellipsoid: clark66
285 north: 4928000
286 south: 4914000
287 west: 590000
288 east: 609000
289 nsres: 20
290 ewres: 20
291 rows: 700
292 cols: 950
293
294 g.region -p3
295 This will print the current region and the 3D region (used for vox‐
296 els) in the format:
297 projection: 1 (UTM)
298 zone: 13
299 datum: nad27
300 ellipsoid: clark66
301 north: 4928000
302 south: 4914000
303 west: 590000
304 east: 609000
305 top: 1.00000000
306 bottom: 0.00000000
307 nsres: 20
308 nsres3: 20
309 ewres: 20
310 ewres3: 20
311 tbres: 1
312 rows: 700
313 rows3: 700
314 cols: 950
315 cols3: 950
316 depths: 1
317
318 g.region -g
319 The -g option prints the region in the following script style
320 (key=value) format:
321 n=4928000
322 s=4914000
323 w=590000
324 e=609000
325 nsres=20
326 ewres=20
327 rows=700
328 cols=950
329
330 g.region -bg
331 The -bg option prints the region in the following script style
332 (key=value) format plus the boundary box in latitude-longi‐
333 tude/WGS84:
334 n=4928000
335 s=4914000
336 w=590000
337 e=609000
338 nsres=20
339 ewres=20
340 rows=700
341 cols=950
342 LL_W=-103.87080682
343 LL_E=-103.62942884
344 LL_N=44.50164277
345 LL_S=44.37302019
346
347 g.region -l
348 The -l option prints the region in the following format:
349 long: -103.86789484 lat: 44.50165890 (north/west corner)
350 long: -103.62895703 lat: 44.49904013 (north/east corner)
351 long: -103.63190061 lat: 44.37303558 (south/east corner)
352 long: -103.87032572 lat: 44.37564292 (south/west corner)
353 rows: 700
354 cols: 950
355 Center longitude: 103:44:59.170374W [-103.74977]
356 Center latitude: 44:26:14.439781N [44.43734]
357
358 g.region -pm
359 This will print the current region in the format (latitude-longi‐
360 tude location):
361 projection: 3 (Latitude-Longitude)
362 zone: 0
363 ellipsoid: wgs84
364 north: 90N
365 south: 40N
366 west: 20W
367 east: 20E
368 nsres: 928.73944902
369 ewres: 352.74269109
370 rows: 6000
371 cols: 4800
372 Note that the resolution is here reported in meters, not decimal
373 degrees.
374
375 Changing extent and raster resolution using values
376 g.region n=7360100 e=699000
377 will reset the northing and easting for the current region, but
378 leave the south edge, west edge, and the region cell resolutions
379 unchanged.
380
381 g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01
382 will reset the northing, easting, southing, westing and resolution
383 for the current region, here in DMS latitude-longitude style (deci‐
384 mal degrees and degrees with decimal minutes can also be used).
385
386 g.region -dp s=698000
387 will set the current region from the default region for the GRASS
388 data base location, reset the south edge to 698000, and then print
389 the result.
390
391 g.region n=n+1000 w=w-500
392 The n=value may also be specified as a function of its current
393 value: n=n+value increases the current northing, while n=n-value
394 decreases it. This is also true for s=value, e=value, and w=value.
395 In this example the current region’s northern boundary is extended
396 by 1000 units and the current region’s western boundary is de‐
397 creased by 500 units.
398
399 g.region n=s+1000 e=w+1000
400 This form allows the user to set the region boundary values rela‐
401 tive to one another. Here, the northern boundary coordinate is set
402 equal to 1000 units larger than the southern boundary’s coordinate
403 value, and the eastern boundary’s coordinate value is set equal to
404 1000 units larger than the western boundary’s coordinate value.
405 The corresponding forms s=n-value and
406
407 w=e-value may be used to set the values of the region’s southern and
408 western boundaries, relative to the northern and eastern boundary val‐
409 ues.
410
411 Changing extent and raster resolution using maps
412 g.region raster=soils
413 This form will make the current region settings exactly the same as
414 those given in the cell header file for the raster map layer soils.
415
416 g.region raster=soils zoom=soils
417 This form will first look up the cell header file for the raster
418 map layer soils, use this as the current region setting, and then
419 shrink the region down to the smallest region which still encom‐
420 passes all non-NULL data in the map layer soils. Note that if the
421 parameter raster=soils were not specified, the zoom would shrink to
422 encompass all non-NULL data values in the soils map that were lo‐
423 cated within the current region settings.
424
425 g.region -up raster=soils
426 The -u option suppresses the re-setting of the current region defi‐
427 nition. This can be useful when it is desired to only extract re‐
428 gion information. In this case, the cell header file for the soils
429 map layer is printed without changing the current region settings.
430
431 g.region -up zoom=soils save=soils
432 This will zoom into the smallest region which encompasses all
433 non-NULL soils data values, and save the new region settings in a
434 file to be called soils and stored under the windows directory in
435 the user’s current mapset. The current region settings are not
436 changed.
437
438 Changing extent and raster resolution in 3D
439 g.region b=0 t=3000 tbres=200 res3=100 g.region -p3
440 This will define the 3D region for voxel computations. In this ex‐
441 ample a volume with bottom (0m) to top (3000m) at horizontal reso‐
442 lution (100m) and vertical resolution (200m) is defined.
443
444 Using g.region in a shell in combination with OGR
445 Extracting a spatial subset of the external vector map soils.shp into
446 new external vector map soils_cut.shp using the OGR ogr2ogr tool:
447 eval `g.region -g`
448 ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp
449 This requires that the location/SHAPE file projection match.
450
451 Using g.region in a shell in combination with GDAL
452 Extracting a spatial subset of the external raster map
453 p016r035_7t20020524_z17_nn30.tif into new external raster map
454 p016r035_7t20020524_nc_spm_wake_nn30.tif using the GDAL gdalwarp tool:
455 eval `g.region -g`
456 gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \
457 p016r035_7t20020524_z17_nn30.tif \
458 p016r035_7t20020524_nc_spm_wake_nn30.tif
459 Here the input raster map does not have to match the location projec‐
460 tion since it is reprojected on the fly.
461
463 g.access, g.mapsets, g.proj
464 Environment variables: GRASS_REGION and WIND_OVERRIDE
465
467 Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
468
470 Available at: g.region source code (history)
471
472 Accessed: Mon Jun 20 16:45:53 2022
473
474 Main index | General index | Topics index | Keywords index | Graphical
475 index | Full index
476
477 © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
478
479
480
481GRASS 8.2.0 g.region(1)