| 1 |
<h2>DESCRIPTION</h2> |
| 2 |
|
| 3 |
The <em>g.region</em> module allows the user to manage the |
| 4 |
settings of the current geographic region. These regional |
| 5 |
boundaries can be set by the user directly and/or set from |
| 6 |
a region definition file (stored under the |
| 7 |
<code>windows</code> directory in the user's current |
| 8 |
mapset). The user can create, modify, and store as many |
| 9 |
geographic region definitions as desired for any given |
| 10 |
mapset. However, only one of these geographic region |
| 11 |
definitions will be current at any given moment, for a |
| 12 |
specified mapset; i.e., GRASS programs that respect the |
| 13 |
geographic region settings will use the current geographic |
| 14 |
region settings. |
| 15 |
|
| 16 |
<h2>DEFINITIONS</h2> |
| 17 |
|
| 18 |
<dl> |
| 19 |
<dt><b>Region:</b> |
| 20 |
|
| 21 |
<dd>In GRASS, a <em>region</em> refers to a geographic area |
| 22 |
with some defined boundaries, based on a specific map |
| 23 |
coordinate system and map projection. Each region also has |
| 24 |
associated with it the specific east-west and north-south |
| 25 |
resolutions of its smallest units (rectangular units called |
| 26 |
"cells"). |
| 27 |
|
| 28 |
<p> |
| 29 |
The region's boundaries are given as the northernmost, |
| 30 |
southernmost, easternmost, and westernmost points that |
| 31 |
define its extent (cell edges). The north and south boundaries |
| 32 |
are commonly called <em>northings</em>, while the east and west |
| 33 |
boundaries are called <em>eastings</em>. |
| 34 |
|
| 35 |
<p> |
| 36 |
The region's cell resolution defines the size of the |
| 37 |
smallest piece of data recognized (imported, analyzed, |
| 38 |
displayed, stored, etc.) by GRASS modules affected by the |
| 39 |
current region settings. The north-south and east-west cell |
| 40 |
resolutions need not be the same, thus allowing non-square |
| 41 |
data cells to exist. |
| 42 |
|
| 43 |
<p>Typically all raster and display modules are affected by the current |
| 44 |
region settings, but not vector modules. |
| 45 |
Some special modules diverge from this rule, for example raster import |
| 46 |
modules and <em>v.in.region</em>. |
| 47 |
|
| 48 |
|
| 49 |
<dt><b>Default Region:</b> |
| 50 |
|
| 51 |
<dd>Each GRASS project (previously called location) has a fixed |
| 52 |
geographic region, called the default geographic region |
| 53 |
(stored in the region file <code>DEFAULT_WIND</code> under |
| 54 |
the special mapset <code>PERMANENT</code>), that defines the |
| 55 |
extent of the data base. While this provides a starting |
| 56 |
point for defining new geographic regions, user-defined |
| 57 |
geographic regions need not fall within this geographic |
| 58 |
region. The current region can be reset to the default region |
| 59 |
with the <b>-d</b> flag. The default region is initially set |
| 60 |
when the project is first created and can be reset using the |
| 61 |
<b>-s</b> flag. |
| 62 |
|
| 63 |
<dt><b>Current Region:</b> |
| 64 |
|
| 65 |
<dd>Each mapset has a current geographic region. This |
| 66 |
region defines the geographic area in which all GRASS |
| 67 |
displays and raster analyses will be done. Raster data will be |
| 68 |
resampled, if necessary, to meet the cell resolutions of |
| 69 |
the current geographic region setting. |
| 70 |
|
| 71 |
<dt><b>Saved Regions:</b> |
| 72 |
|
| 73 |
<dd>Each GRASS MAPSET may contain any number of |
| 74 |
pre-defined, and named, geographic regions. These region |
| 75 |
definitions are stored in the user's current mapset |
| 76 |
location under the <code>windows</code> directory (also |
| 77 |
referred to as the user's saved region definitions). |
| 78 |
Any of these pre-defined geographic regions |
| 79 |
may be selected, by name, to become the current geographic |
| 80 |
region. Users may also access saved region definitions |
| 81 |
stored under other mapsets in the current project, if |
| 82 |
these mapsets are included in the user's mapset search |
| 83 |
path or the '@' operator is used (<code>region_name@mapset</code>). |
| 84 |
</dl> |
| 85 |
|
| 86 |
<h2>NOTES</h2> |
| 87 |
|
| 88 |
After all updates have been applied, the current region's |
| 89 |
southern and western boundaries are (silently) adjusted so |
| 90 |
that the north/south distance is a multiple of the |
| 91 |
north/south resolution and that the east/west distance is a |
| 92 |
multiple of the east/west resolution. |
| 93 |
|
| 94 |
<p>With the <b>-a</b> flag all four boundaries are adjusted |
| 95 |
to be even multiples of the resolution, aligning the region to the |
| 96 |
resolution supplied by the user. The default is to |
| 97 |
align the region resolution to match the region boundaries. |
| 98 |
|
| 99 |
<p>The <b>-m</b> flag will report the region resolution in meters. The |
| 100 |
resolution is calculated by averaging the resolution at the region |
| 101 |
boundaries. This resolution is calculated by dividing the geodesic |
| 102 |
distance in meters at the boundary by the number of rows or columns. |
| 103 |
For example the east / west resolution (ewres) is determined from an |
| 104 |
average of the geodesic distances at the North and South boundaries |
| 105 |
divided by the number of columns. |
| 106 |
<!-- add'l info. include? |
| 107 |
Print the region resolution in meters (from geodesic). With no other |
| 108 |
flags the default output format is shell stype (-g). The region resolution |
| 109 |
represents the center of the map. The resolutions are calculated at the four |
| 110 |
outside edges, then the two NS edges are averaged and the two EW edges are |
| 111 |
averaged, the results finally printed. |
| 112 |
--> |
| 113 |
|
| 114 |
|
| 115 |
<p>The <b>-p</b> (or <b>-g</b>) option is recognized |
| 116 |
last. This means that all changes are applied to the |
| 117 |
region settings before printing occurs. |
| 118 |
<p>The <b>-g</b> flag prints the current region settings in shell script style. |
| 119 |
This format can be given back to <em>g.region</em> on its command line. |
| 120 |
This may also be used to save region settings as shell environment variables |
| 121 |
with the UNIX eval command, "<code>eval `g.region -g`</code>". |
| 122 |
|
| 123 |
<p>With <b>-u</b> flag current region is not updated even if one or more |
| 124 |
options for changing region is used (<b>res=</b>, <b>raster=</b>, etc). |
| 125 |
This can be used for example to print modified region values for further use |
| 126 |
without actually modifying the current region. |
| 127 |
Similarly, <b>-o</b> flag forces to update current region file even when e.g., only |
| 128 |
printing was specified. Flag <b>-o</b> was added in GRASS version 8 to simulate |
| 129 |
<em>g.region</em> behavior in prior versions when current region file was |
| 130 |
always updated unless <b>-u</b> was specified. |
| 131 |
|
| 132 |
<h3>Additional parameter information:</h3> |
| 133 |
|
| 134 |
<dl> |
| 135 |
|
| 136 |
<dt><b>zoom=</b><em>name</em> |
| 137 |
<dd>Shrink current region settings to the smallest region |
| 138 |
encompassing all non-NULL data in the named raster map |
| 139 |
layer that fall inside the user's current region. In this |
| 140 |
way you can tightly zoom in on isolated clumps within a |
| 141 |
bigger map. |
| 142 |
<p>If the user also includes the <b>raster=</b><em>name</em> |
| 143 |
option on the command line, <b>zoom=</b><em>name</em> will |
| 144 |
set the current region settings to the smallest region |
| 145 |
encompassing all non-NULL data in the named <b>zoom</b> map |
| 146 |
that fall inside the region stated in the cell header for |
| 147 |
the named <b>raster</b> map. |
| 148 |
|
| 149 |
|
| 150 |
<dt><b>align=</b><em>name</em> |
| 151 |
|
| 152 |
<dd>Set the current resolution equal to that of the named |
| 153 |
raster map, and align the current region to a row and |
| 154 |
column edge in the named map. Alignment only moves the |
| 155 |
existing region edges outward to the edges of the next |
| 156 |
nearest cell in the named raster map - not to the named |
| 157 |
map's edges. To perform the latter function, use the |
| 158 |
<b>raster=</b><em>name</em> option. |
| 159 |
</dl> |
| 160 |
|
| 161 |
<h2>EXAMPLES</h2> |
| 162 |
|
| 163 |
<h3>Printing extent and raster resolution in 2D and 3D</h3> |
| 164 |
|
| 165 |
<dl> |
| 166 |
<dt><span class="code"><code> |
| 167 |
g.region -p |
| 168 |
</code></span> |
| 169 |
|
| 170 |
<dd> This will print the current region in the format: |
| 171 |
|
| 172 |
<div class="code"><pre> |
| 173 |
projection: 1 (UTM) |
| 174 |
zone: 13 |
| 175 |
datum: nad27 |
| 176 |
ellipsoid: clark66 |
| 177 |
north: 4928000 |
| 178 |
south: 4914000 |
| 179 |
west: 590000 |
| 180 |
east: 609000 |
| 181 |
nsres: 20 |
| 182 |
ewres: 20 |
| 183 |
rows: 700 |
| 184 |
cols: 950 |
| 185 |
</pre></div> |
| 186 |
|
| 187 |
<p> |
| 188 |
<dt><span class="code"><code> |
| 189 |
g.region -p3 |
| 190 |
</code></span> |
| 191 |
|
| 192 |
<dd> This will print the current region and the 3D region (used for voxels) |
| 193 |
in the format: |
| 194 |
|
| 195 |
<div class="code"><pre> |
| 196 |
projection: 1 (UTM) |
| 197 |
zone: 13 |
| 198 |
datum: nad27 |
| 199 |
ellipsoid: clark66 |
| 200 |
north: 4928000 |
| 201 |
south: 4914000 |
| 202 |
west: 590000 |
| 203 |
east: 609000 |
| 204 |
top: 1.00000000 |
| 205 |
bottom: 0.00000000 |
| 206 |
nsres: 20 |
| 207 |
nsres3: 20 |
| 208 |
ewres: 20 |
| 209 |
ewres3: 20 |
| 210 |
tbres: 1 |
| 211 |
rows: 700 |
| 212 |
rows3: 700 |
| 213 |
cols: 950 |
| 214 |
cols3: 950 |
| 215 |
depths: 1 |
| 216 |
</pre></div> |
| 217 |
|
| 218 |
<p> |
| 219 |
<dt><span class="code"><code> |
| 220 |
g.region -g |
| 221 |
</code></span> |
| 222 |
|
| 223 |
<dd> The <b>-g</b> option prints the region in the |
| 224 |
following script style (key=value) format: |
| 225 |
|
| 226 |
<div class="code"><pre> |
| 227 |
n=4928000 |
| 228 |
s=4914000 |
| 229 |
w=590000 |
| 230 |
e=609000 |
| 231 |
nsres=20 |
| 232 |
ewres=20 |
| 233 |
rows=700 |
| 234 |
cols=950 |
| 235 |
</pre></div> |
| 236 |
|
| 237 |
<p> |
| 238 |
<dt><span class="code"><code> |
| 239 |
g.region -bg |
| 240 |
</code></span> |
| 241 |
|
| 242 |
<dd> The <b>-bg</b> option prints the region in the |
| 243 |
following script style (key=value) format plus the |
| 244 |
boundary box in latitude-longitude/WGS84: |
| 245 |
|
| 246 |
<div class="code"><pre> |
| 247 |
n=4928000 |
| 248 |
s=4914000 |
| 249 |
w=590000 |
| 250 |
e=609000 |
| 251 |
nsres=20 |
| 252 |
ewres=20 |
| 253 |
rows=700 |
| 254 |
cols=950 |
| 255 |
LL_W=-103.87080682 |
| 256 |
LL_E=-103.62942884 |
| 257 |
LL_N=44.50164277 |
| 258 |
LL_S=44.37302019 |
| 259 |
</pre></div> |
| 260 |
|
| 261 |
<p> |
| 262 |
<dt><span class="code"><code> |
| 263 |
g.region -l |
| 264 |
</code></span> |
| 265 |
|
| 266 |
<dd> The <b>-l</b> option prints the region in the |
| 267 |
following format: |
| 268 |
|
| 269 |
<div class="code"><pre> |
| 270 |
long: -103.86789484 lat: 44.50165890 (north/west corner) |
| 271 |
long: -103.62895703 lat: 44.49904013 (north/east corner) |
| 272 |
long: -103.63190061 lat: 44.37303558 (south/east corner) |
| 273 |
long: -103.87032572 lat: 44.37564292 (south/west corner) |
| 274 |
rows: 700 |
| 275 |
cols: 950 |
| 276 |
Center longitude: 103:44:59.170374W [-103.74977] |
| 277 |
Center latitude: 44:26:14.439781N [44.43734] |
| 278 |
</pre></div> |
| 279 |
|
| 280 |
<p> |
| 281 |
<dt><span class="code"><code> |
| 282 |
g.region -pm |
| 283 |
</code></span> |
| 284 |
|
| 285 |
<dd> This will print the current region in the format |
| 286 |
(latitude-longitude project): |
| 287 |
|
| 288 |
<div class="code"><pre> |
| 289 |
projection: 3 (Latitude-Longitude) |
| 290 |
zone: 0 |
| 291 |
ellipsoid: wgs84 |
| 292 |
north: 90N |
| 293 |
south: 40N |
| 294 |
west: 20W |
| 295 |
east: 20E |
| 296 |
nsres: 928.73944902 |
| 297 |
ewres: 352.74269109 |
| 298 |
rows: 6000 |
| 299 |
cols: 4800 |
| 300 |
</pre></div> |
| 301 |
Note that the resolution is here reported in meters, not decimal degrees. |
| 302 |
</dl> |
| 303 |
|
| 304 |
<h3>Changing extent and raster resolution using values</h3> |
| 305 |
<dl> |
| 306 |
<dt><span class="code"><code> |
| 307 |
g.region n=7360100 e=699000 |
| 308 |
</code></span> |
| 309 |
|
| 310 |
<dd> will reset the northing and easting for the current |
| 311 |
region, but leave the south edge, west edge, and the region |
| 312 |
cell resolutions unchanged. |
| 313 |
|
| 314 |
<p> |
| 315 |
<dt><span class="code"><code> |
| 316 |
g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01 |
| 317 |
</code></span> |
| 318 |
|
| 319 |
<dd> will reset the northing, easting, southing, westing and resolution |
| 320 |
for the current region, here in DMS latitude-longitude style |
| 321 |
(decimal degrees and degrees with decimal minutes can also be used). |
| 322 |
|
| 323 |
<p> |
| 324 |
<dt><span class="code"><code> |
| 325 |
g.region -dp s=698000 |
| 326 |
</code></span> |
| 327 |
|
| 328 |
<dd> will set the current region from the default region |
| 329 |
for the GRASS project, reset the south edge to |
| 330 |
698000, and then print the result. |
| 331 |
|
| 332 |
<p> |
| 333 |
<dt><span class="code"><code> |
| 334 |
g.region n=n+1000 w=w-500 |
| 335 |
</code></span> |
| 336 |
|
| 337 |
<dd> The n=<em>value</em> may also be specified as a |
| 338 |
function of its current value: n=n+<em>value</em> |
| 339 |
increases the current northing, while n=n-<em>value</em> |
| 340 |
decreases it. This is also true for s=<em>value</em>, |
| 341 |
e=<em>value</em>, and w=<em>value</em>. In this example |
| 342 |
the current region's northern boundary is extended by 1000 |
| 343 |
units and the current region's western boundary is |
| 344 |
decreased by 500 units. |
| 345 |
|
| 346 |
<p> |
| 347 |
<dt><span class="code"><code> |
| 348 |
g.region n=s+1000 e=w+1000 |
| 349 |
</code></span> |
| 350 |
|
| 351 |
<dd> This form allows the user to set the region boundary |
| 352 |
values relative to one another. Here, the northern |
| 353 |
boundary coordinate is set equal to 1000 units larger than |
| 354 |
the southern boundary's coordinate value, and the eastern |
| 355 |
boundary's coordinate value is set equal to 1000 units |
| 356 |
larger than the western boundary's coordinate value. The |
| 357 |
corresponding forms s=n-<em>value</em> and |
| 358 |
|
| 359 |
<p> |
| 360 |
w=e-<em>value</em> may be used to set the values of the |
| 361 |
region's southern and western boundaries, relative to the |
| 362 |
northern and eastern boundary values. |
| 363 |
</dl> |
| 364 |
|
| 365 |
<h3>Changing extent and raster resolution using maps</h3> |
| 366 |
<dl> |
| 367 |
<dt><span class="code"><code> |
| 368 |
g.region raster=soils |
| 369 |
</code></span> |
| 370 |
|
| 371 |
<dd> This form will make the current region settings |
| 372 |
exactly the same as those given in the cell header file for |
| 373 |
the raster map layer <em>soils</em>. |
| 374 |
|
| 375 |
<p> |
| 376 |
<dt><span class="code"><code> |
| 377 |
g.region raster=soils zoom=soils |
| 378 |
</code></span> |
| 379 |
|
| 380 |
<dd> This form will first look up the cell header file for |
| 381 |
the raster map layer <em>soils</em>, use this as the |
| 382 |
current region setting, and then shrink the region down to |
| 383 |
the smallest region which still encompasses all non-NULL |
| 384 |
data in the map layer <em>soils</em>. Note that if the |
| 385 |
parameter <em>raster=soils</em> were not specified, the |
| 386 |
zoom would shrink to encompass all non-NULL data values in |
| 387 |
the soils map that were located within the <em>current region</em> |
| 388 |
settings. |
| 389 |
|
| 390 |
<p> |
| 391 |
<dt><span class="code"><code> |
| 392 |
g.region -up raster=soils |
| 393 |
</code></span> |
| 394 |
|
| 395 |
<dd> The <b>-u</b> option suppresses the re-setting of the |
| 396 |
current region definition. This can be useful when it is |
| 397 |
desired to only extract region information. In this case, |
| 398 |
the cell header file for the soils map layer is printed |
| 399 |
without changing the current region settings. |
| 400 |
|
| 401 |
<p> |
| 402 |
<dt><span class="code"><code> |
| 403 |
g.region -up zoom=soils save=soils |
| 404 |
</code></span> |
| 405 |
|
| 406 |
<dd> This will zoom into the smallest region which |
| 407 |
encompasses all non-NULL soils data values, and save the |
| 408 |
new region settings in a file to be called <em>soils</em> |
| 409 |
and stored under the <code>windows</code> directory in the |
| 410 |
user's current mapset. The current region settings are not |
| 411 |
changed. |
| 412 |
</dl> |
| 413 |
|
| 414 |
<h3>Changing extent and raster resolution in 3D</h3> |
| 415 |
<dl> |
| 416 |
<dt><span class="code"><code> |
| 417 |
g.region b=0 t=3000 tbres=200 res3=100 |
| 418 |
g.region -p3 |
| 419 |
</code></span> |
| 420 |
|
| 421 |
<dd> This will define the 3D region for voxel computations. |
| 422 |
In this example a volume with bottom (0m) to top (3000m) |
| 423 |
at horizontal resolution (100m) and vertical resolution (200m) |
| 424 |
is defined. |
| 425 |
</dl> |
| 426 |
|
| 427 |
<h3>Using g.region in a shell in combination with OGR</h3> |
| 428 |
|
| 429 |
<!-- why not 'v.in.ogr spatial=' ?? --> |
| 430 |
Extracting a spatial subset of the external vector map |
| 431 |
<code>soils.shp</code> into new external vector map <code>soils_cut.shp</code> |
| 432 |
using the OGR <em>ogr2ogr</em> tool:<br> |
| 433 |
|
| 434 |
<div class="code"><pre> |
| 435 |
eval `g.region -g` |
| 436 |
ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp |
| 437 |
</pre></div> |
| 438 |
|
| 439 |
This requires that the project and the SHAPE file CRS' match. |
| 440 |
|
| 441 |
<h3>Using g.region in a shell in combination with GDAL</h3> |
| 442 |
|
| 443 |
Extracting a spatial subset of the external raster map |
| 444 |
<code>p016r035_7t20020524_z17_nn30.tif</code> into new external raster |
| 445 |
map <code>p016r035_7t20020524_nc_spm_wake_nn30.tif</code> using the GDAL |
| 446 |
<em>gdalwarp</em> tool:<br> |
| 447 |
|
| 448 |
<div class="code"><pre> |
| 449 |
eval `g.region -g` |
| 450 |
gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \ |
| 451 |
p016r035_7t20020524_z17_nn30.tif \ |
| 452 |
p016r035_7t20020524_nc_spm_wake_nn30.tif |
| 453 |
</pre></div> |
| 454 |
|
| 455 |
Here the input raster map does not have to match the project's |
| 456 |
coordinate reference system since it is reprojected on the fly. |
| 457 |
|
| 458 |
<h3>JSON Output</h3> |
| 459 |
<div class="code"><pre> |
| 460 |
g.region -p format=json |
| 461 |
</pre></div> |
| 462 |
<div class="code"><pre> |
| 463 |
{ |
| 464 |
"projection": "99 (Lambert Conformal Conic)", |
| 465 |
"zone": 0, |
| 466 |
"datum": "nad83", |
| 467 |
"ellipsoid": "a=6378137 es=0.006694380022900787", |
| 468 |
"region": { |
| 469 |
"north": 320000, |
| 470 |
"south": 10000, |
| 471 |
"west": 120000, |
| 472 |
"east": 935000, |
| 473 |
"ns-res": 500, |
| 474 |
"ns-res3": 1000, |
| 475 |
"ew-res": 500, |
| 476 |
"ew-res3": 1000 |
| 477 |
}, |
| 478 |
"top": 500, |
| 479 |
"bottom": -500, |
| 480 |
"tbres": 100, |
| 481 |
"rows": 620, |
| 482 |
"rows3": 310, |
| 483 |
"cols": 1630, |
| 484 |
"cols3": 815, |
| 485 |
"depths": 10, |
| 486 |
"cells": 1010600, |
| 487 |
"cells3": 2526500 |
| 488 |
} |
| 489 |
</pre></div> |
| 490 |
|
| 491 |
<div class="code"><pre> |
| 492 |
g.region -l format=json |
| 493 |
</pre></div> |
| 494 |
<div class="code"><pre> |
| 495 |
{ |
| 496 |
"nw_long": -78.688888505507336, |
| 497 |
"nw_lat": 35.743893244701788, |
| 498 |
"ne_long": -78.669097826118957, |
| 499 |
"ne_lat": 35.743841072010554, |
| 500 |
"se_long": -78.669158624787542, |
| 501 |
"se_lat": 35.728968779193615, |
| 502 |
"sw_long": -78.688945667963168, |
| 503 |
"sw_lat": 35.729020942542441, |
| 504 |
"center_long": -78.679022655614958, |
| 505 |
"center_lat": 35.736431420327719, |
| 506 |
"rows": 165, |
| 507 |
"cols": 179 |
| 508 |
} |
| 509 |
</pre></div> |
| 510 |
|
| 511 |
<h2>SEE ALSO</h2> |
| 512 |
|
| 513 |
<em> |
| 514 |
<a href="g.access.html">g.access</a>, |
| 515 |
<a href="g.mapsets.html">g.mapsets</a>, |
| 516 |
<a href="g.proj.html">g.proj</a> |
| 517 |
<br> |
| 518 |
Environment variables: <a href="variables.html#internal">GRASS_REGION and WIND_OVERRIDE</a> |
| 519 |
</em> |
| 520 |
|
| 521 |
<h2>AUTHOR</h2> |
| 522 |
|
| 523 |
Michael Shapiro, |
| 524 |
U.S.Army Construction Engineering |
| 525 |
Research Laboratory |