1g.region(1)                   Grass 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  [-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

DESCRIPTION

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

DEFINITIONS

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

NOTES

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

EXAMPLES

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

SEE ALSO

452        g.access, g.mapsets, g.proj
453       Environment variables: GRASS_REGION and WIND_OVERRIDE
454

AUTHOR

456       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
457
458       Last changed: $Date: 2016-08-19 09:39:55 +0200 (Fri, 19 Aug 2016) $
459

SOURCE CODE

461       Available at: g.region source code (history)
462
463       Main index | General index | Topics index | Keywords index |  Graphical
464       index | Full index
465
466       © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual
467
468
469
470GRASS 7.6.0                                                        g.region(1)
Impressum