1g.region(1)                 GRASS GIS User's Manual                g.region(1)
2
3
4

NAME

6       g.region  - Manages the boundary definitions for the geographic region.
7

KEYWORDS

9       general, settings, computational region, extent, resolution, level1
10

SYNOPSIS

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

DESCRIPTION

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

DEFINITIONS

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

NOTES

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

EXAMPLES

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

SEE ALSO

463        g.access, g.mapsets, g.proj
464       Environment variables: GRASS_REGION and WIND_OVERRIDE
465

AUTHOR

467       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
468

SOURCE CODE

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)
Impressum