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