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