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
10
12 g.region
13 g.region help
14 g.region [-dsplecm3bgau] [region=name] [rast=name[,name,...]]
15 [rast3d=name] [vect=name[,name,...]] [3dview=name] [n=value]
16 [s=value] [e=value] [w=value] [t=value] [b=value]
17 [rows=value] [cols=value] [res=value] [res3=value]
18 [nsres=value] [ewres=value] [tbres=value] [zoom=name]
19 [align=name] [save=name] [--overwrite] [--verbose] [--quiet]
20 Flags:
22 -d
23 Set from default region
24 -s
26 Save as default region
27 -p
29 Print the current region
30 -l
32 Print the current region in lat/long using the current ellip‐
33 soid/datum
34 -e
36 Print the current region extent
37 -c
39 Print the current region map center coordinates
40 -m
42 Print region resolution in meters (geodesic)
43 -3
45 Print also 3D settings
46 -b
48 Print the maximum bounding box in lat/long on WGS84
49 -g
51 Print in shell script style
52 -a
54 Align region to resolution (default = align to bounds, works only
55 for 2D resolution)
56 -u
58 Do not update the current region
59 --overwrite
61 Allow output files to overwrite existing files
62 --verbose
64 Verbose module output
65 --quiet
67 Quiet module output
68 Parameters:
70 region=name
71 Set current region from named region
72 rast=name[,name,...]
74 Set region to match this raster map
75 rast3d=name
77 Set region to match this 3D raster map (both 2D and 3D values)
78 vect=name[,name,...]
80 Set region to match this vector map
81 3dview=name
83 Set region to match this 3dview file
84 n=value
86 Value for the northern edge (format dd:mm:ss{N|S})
87 s=value
89 Value for the southern edge (format dd:mm:ss{N|S})
90 e=value
92 Value for the eastern edge (format ddd:mm:ss{E|W})
93 w=value
95 Value for the western edge (format ddd:mm:ss{E|W})
96 t=value
98 Value for the top edge
99 b=value
101 Value for the bottom edge
102 rows=value
104 Number of rows in the new region
105 cols=value
107 Number of columns in the new region
108 res=value
110 Grid resolution 2D (both north-south and east-west)
111 res3=value
113 3D grid resolution (north-south, east-west and top-bottom)
114 nsres=value
116 North-south grid resolution 2D (format dd:mm:ss)
117 ewres=value
119 East-west grid resolution 2D (format dd:mm:ss)
120 tbres=value
122 Top-bottom grid resolution 3D
123 zoom=name
125 Shrink region until it meets non-NULL data from this raster map
126 align=name
128 Adjust region cells to cleanly align with this raster map
129 save=name
131 Save the current region to region definition file
132
134 The g.region module allows the user to manage the settings of the cur‐
135 rent geographic region. These regional boundaries can be set by the
136 user directly and/or set from a region definition file (stored under
137 the windows directory in the user's current mapset). The user can cre‐
138 ate, modify, and store as many geographic region definitions as desired
139 for any given mapset. However, only one of these geographic region
140 definitions will be current at any given moment, for a specified
141 mapset; i.e., GRASS programs that respect the geographic region set‐
142 tings will use the current geographic region settings.
143
145 Region:
146 In GRASS, a region refers to a geographic area with some defined
147 boundaries, based on a specific map coordinate system and map
148 projection. Each region also has associated with it the spe‐
149 cific east-west and north-south resolutions of its smallest
150 units (rectangular units called "cells").
151 The region's boundaries are given as the northernmost, southernmost,
153 easternmost, and westernmost points that define its extent (cell
154 edges). The north and south boundaries are commonly called northings,
155 while the east and west boundaries are called eastings.
156 The region's cell resolution defines the size of the smallest piece of
158 data recognized (imported, analyzed, displayed, stored, etc.) by GRASS
159 modules affected by the current region settings. The north-south and
160 east-west cell resolutions need not be the same, thus allowing non-
161 square data cells to exist.
162 Typically all raster and display modules are affected by the current
164 region settings, but not vector modules. Some special modules diverge
165 from this rule, for example raster import modules and v.in.region.
166 Default Region:
168 Each GRASS LOCATION has a fixed geographic region, called the
169 default geographic region (stored in the region file
170 DEFAULT_WIND under the special mapset PERMANENT), that defines
171 the extent of the data base. While this provides a starting
172 point for defining new geographic regions, user-defined geo‐
173 graphic regions need not fall within this geographic region. The
174 current region can be reset to the default region with the -d
175 flag. The default region is initially set when the location is
176 first created and can be reset using the -s flag.
177 Current Region:
179 Each mapset has a current geographic region. This region
180 defines the geographic area in which all GRASS displays and
181 raster analyses will be done. Raster data will be resampled, if
182 necessary, to meet the cell resolutions of the current geo‐
183 graphic region setting.
184 Saved Regions:
186 Each GRASS MAPSET may contain any number of pre-defined, and
187 named, geographic regions. These region definitions are stored
188 in the user's current mapset location under the windows direc‐
189 tory (also referred to as the user's saved region definitions).
190 Any of these pre-defined geographic regions may be selected, by
191 name, to become the current geographic region. Users may also
192 access saved region definitions stored under other mapsets in
193 the current location, if these mapsets are included in the
194 user's mapset search path or the '@' operator is used
195 (region_name@mapset).
196
198 After all updates have been applied, the current region's southern and
199 western boundaries are (silently) adjusted so that the north/south dis‐
200 tance is a multiple of the north/south resolution and that the
201 east/west distance is a multiple of the east/west resolution.
202 With the -a flag all four boundaries are adjusted to be even multiples
204 of the resolution, aligning the region to the resolution supplied by
205 the user. The default is to align the region resolution to match the
206 region boundaries.
207 The -m flag will report the region resolution in meters. The resolution
209 is calculated by averaging the resolution at the region boundaries.
210 This resolution is calculated by dividing the geodesic distance in
211 meters at the boundary by the number of rows or columns. For example
212 the east / west resolution (ewres) is determined from an average of the
213 geodesic distances at the North and South boundaries divided by the
214 number of columns.
215 The -p (or -g) option is recognized last. This means that all changes
217 are applied to the region settings before printing occurs.
218 The -g flag prints the current region settings in shell script style.
220 This format can be given back to g.region on its command line. This
221 may also be used to save region settings as shell environment variables
222 with the UNIX eval command, "eval `g.region -g`".
223 Additional parameter information:
225 3dview=name
226 Make current region settings same as those in the named 3dview
227 file, which holds the region that was current when the 3dview
228 was saved.
229 zoom=name
231 Shrink current region settings to the smallest region encompass‐
232 ing all non-NULL data in the named raster map layer that fall
233 inside the user's current region. In this way you can tightly
234 zoom in on isolated clumps within a bigger map.
235 If the user also includes the rast=name option on the command line,
237 zoom=name will set the current region settings to the smallest region
238 encompassing all non-NULL data in the named zoom map that fall inside
239 the region stated in the cell header for the named raster map.
240 align=name
242 Set the current resolution equal to that of the named raster
243 map, and align the current region to a row and column edge in
244 the named map. Alignment only moves the existing region edges
245 outward to the edges of the next nearest cell in the named
246 raster map - not to the named map's edges. To perform the lat‐
247 ter function, use the rast=name option.
248
250 g.region n=7360100 e=699000
252 will reset the northing and easting for the current region, but
254 leave the south edge, west edge, and the region cell resolutions
255 unchanged.
256 g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01
259 will reset the northing, easting, southing, westing and resolution for
261 the current region, here in DMS latitude-longitude style (decimal
262 degrees and degrees with decimal minutes can also be used).
263 g.region -dp s=698000
266 will set the current region from the default region for the GRASS data
268 base location, reset the south edge to 698000, and then print the
269 result.
270 g.region n=n+1000 w=w-500
273 The n=value may also be specified as a function of its current value:
275 n=n+value increases the current northing, while n=n-value decreases it.
276 This is also true for s=value, e=value, and w=value. In this example
277 the current region's northern boundary is extended by 1000 units and
278 the current region's western boundary is decreased by 500 units.
279 g.region n=s+1000 e=w+1000
282 This form allows the user to set the region boundary values relative
284 to one another. Here, the northern boundary coordinate is set equal to
285 1000 units larger than the southern boundary's coordinate value, and
286 the eastern boundary's coordinate value is set equal to 1000 units
287 larger than the western boundary's coordinate value. The corresponding
288 forms s=n-value and
289 w=e-value may be used to set the values of the region's southern and
291 western boundaries, relative to the northern and eastern boundary val‐
292 ues.
293 g.region rast=soils
294 This form will make the current region settings exactly the same as
296 those given in the cell header file for the raster map layer soils.
297 g.region rast=soils zoom=soils
300 This form will first look up the cell header file for the raster map
302 layer soils, use this as the current region setting, and then shrink
303 the region down to the smallest region which still encompasses all non-
304 NULL data in the map layer soils. Note that if the parameter
305 rast=soils were not specified, the zoom would shrink to encompass all
306 non-NULL data values in the soils map that were located within the cur‐
307 rent region settings.
308 g.region -up rast=soils
311 The -u option suppresses the re-setting of the current region defini‐
313 tion. This can be useful when it is desired to only extract region
314 information. In this case, the cell header file for the soils map
315 layer is printed without changing the current region settings.
316 g.region -up zoom=soils save=soils
319 This will zoom into the smallest region which encompasses all non-NULL
321 soils data values, and save the new region settings in a file to be
322 called soils and stored under the windows directory in the user's cur‐
323 rent mapset. The current region settings are not changed.
324 g.region b=0 t=3000 tbres=200 res3=100
327 g.region -p3
328 This will define the 3D region for voxel computations. In this exam‐
330 ple a volume with bottom (0m) to top (3000m) at horizontal resolution
331 (100m) and vertical resolution (200m) is defined.
332 g.region -p
335 This will print the current region in the format:
337 projection: 1 (UTM)
338 zone: 13
339 datum: nad27
340 ellipsoid: clark66
341 north: 4928000
342 south: 4914000
343 west: 590000
344 east: 609000
345 nsres: 20
346 ewres: 20
347 rows: 700
348 cols: 950
349 g.region -p3
353 This will print the current region and the 3D region (used for voxels)
355 in the format:
356 projection: 1 (UTM)
357 zone: 13
358 datum: nad27
359 ellipsoid: clark66
360 north: 4928000
361 south: 4914000
362 west: 590000
363 east: 609000
364 top: 1.00000000
365 bottom: 0.00000000
366 nsres: 20
367 nsres3: 20
368 ewres: 20
369 ewres3: 20
370 tbres: 1
371 rows: 700
372 rows3: 700
373 cols: 950
374 cols3: 950
375 depths: 1
376 g.region -g
380 The -g option prints the region in the following script style
382 (key=value) format:
383 n=4928000
384 s=4914000
385 w=590000
386 e=609000
387 nsres=20
388 ewres=20
389 rows=700
390 cols=950
391 g.region -bg
395 The -bg option prints the region in the following script style
397 (key=value) format plus the boundary box in latitude-longitude/WGS84:
398 n=4928000
399 s=4914000
400 w=590000
401 e=609000
402 nsres=20
403 ewres=20
404 rows=700
405 cols=950
406 LL_W=-103.87080682
407 LL_E=-103.62942884
408 LL_N=44.50164277
409 LL_S=44.37302019
410 g.region -l
414 The -l option prints the region in the following format:
416 long: -103.86789484 lat: 44.50165890 (north/west corner)
417 long: -103.62895703 lat: 44.49904013 (north/east corner)
418 long: -103.63190061 lat: 44.37303558 (south/east corner)
419 long: -103.87032572 lat: 44.37564292 (south/west corner)
420 rows: 700
421 cols: 950
422 Center longitude: 103:44:59.170374W [-103.74977]
423 Center latitude: 44:26:14.439781N [44.43734]
424 g.region -pm
428 This will print the current region in the format (latitude-longitude
430 location):
431 projection: 3 (Latitude-Longitude)
432 zone: 0
433 ellipsoid: wgs84
434 north: 90N
435 south: 40N
436 west: 20W
437 east: 20E
438 nsres: 928.73944902
439 ewres: 352.74269109
440 rows: 6000
441 cols: 4800
442 Note that the resolution is here reported in meters, not decimal
443 degrees.
444 Usage example of g.region in a shell with external software:
446 Extract spatial subset of external vector map 'soils.shp' to new exter‐
447 nal vector map 'soils_cut.shp' using the OGR 'ogr2ogr' tool:
448 eval `g.region -g`
450 ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp
451 This requires that the location/SHAPE file projection match.
452 Usage example of g.proj and g.region in a shell with external software:
454 Extract spatial subset of external raster map
455 'p016r035_7t20020524_z17_nn30.tif' to new external raster
456 map'p016r035_7t20020524_nc_spm_wake_nn30.tif using the GDAL ’gdalwarp'
457 tool:
458 eval `g.region -g`
460 gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \
461 p016r035_7t20020524_z17_nn30.tif \
462 p016r035_7t20020524_nc_spm_wake_nn30.tif
463 Here the input raster map does not have to match the location projec‐
464 tion since it is reprojected on the fly.
465
467 d.zoom
468 g.access
469 g.mapsets
470 g.proj
471 g.setproj
472 environment variables: GRASS_REGION and WIND_OVERRIDE
473
475 Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
476 Last changed: $Date: 2008-01-28 08:01:56 +0100 (Mon, 28 Jan 2008) $
478 Full index
480 © 2003-2008 GRASS Development Team
482GRASS 6.3.0 g.region(1)