g.region

NAME

g.region - Program to manage the boundary definitions for the geographic region.
(GRASS Region Management Program)

SYNOPSIS

g.region
g.region help
g.region [-dgpu] [region=name] [raster=name] [vector=name] [sites=name] [3dview=name] [n=value] [s=value] [e=value] [w=value] [res=value] [nsres=value] [ewres=value] [zoom=name] [align=name] [save=name]

DESCRIPTION

The g.region program allows the user to manage the settings of the current geographic region. These regional boundaries can be set by the user directly and/or set from a region definition file (stored under the windows directory in the user's current mapset). The user can create, modify, and store as many geographic region definitions as desired for any given mapset. However, only one of these geographic region definitions will be current at any given moment, for a specified mapset; i.e., GRASS programs that respect the geographic region settings will use the current geographic region settings.

INTERACTIVE PROGRAM USE: MAIN MENU

The main menu consists of an information section listing the current GRASS data base LOCATION, MAPSET, and CURRENT REGION, followed by user options:

------------------------------------------------------------
|                    REGION FACILITY                       |
| LOCATION: sample                         MAPSET: grass   |
|                                                          |
| CURRENT REGION: N=5167600  S=5156755  RES=50  ROWS=216   |
|                 E=729314   W=705924   RES=50  COLS=467   |
| PROJECTION: 1 (UTM)                                      |
| ZONE: 13                                                 |
| DATUM: WGS84                                             |
|                                                          |
| Please select one of the following options               |
|                                                          |
|     Current Region              Region Database          |
|                                                          |
| 1 Modify current region     6 Save current region in     |
|   directly                    the database               |
|                                                          |
| 2 Set from default region   7 Create a new region        |
|                                                          |
| 3 Set from a database       8 Modify an existing region  |
|   region                                                 |
|                                                          |
| 4 Set from a raster map                                  |
|                                                          |
| 5 Set from a vector map                                  |
|                                                          |
| RETURN to quit                                           |
------------------------------------------------------------

DEFINITIONS

Region:

Here, a region refers to a geographic area with some defined boundaries, based on a specific map coordinate system and map projection. Each region also has associated with it the specific east-west and north-south resolutions of its smallest units (rectangular units called "cells").

The region's boundaries are given as the northernmost, southernmost, easternmost, and westernmost points that define its extent. The north and south boundaries are commonly called northings, while the east and west boundaries are called eastings.

The region's cell resolution defines the size of the smallest piece of data recognized (imported, analyzed, displayed, stored, etc.) by GRASS programs affected by the current region settings. The north-south and east-west cell resolutions need not be the same, thus allowing non-square data cells to exist.

Default Region:

Each GRASS LOCATION_NAME has a fixed geographic region, called the default geographic region (stored in the region file DEFAULT_WIND under the special mapset PERMANENT), that defines the extent of the data base. While this provides a starting point for defining new geographic regions, user-defined geographic regions need not fall within this geographic region.

Current Region:

Each mapset has a current geographic region. This region defines the geographic area in which all GRASS displays and analyses will be done. Data will be resampled, if necessary, to meet the cell resolutions of the current geographic region setting.

Region Data Base:

Each GRASS MAPSET may contain any number of pre-defined, and named, geographic regions. These region definitions are stored in the user's current mapset location under the windows directory (also referred to as the user's data base of region definitions). Any of these pre-defined geographic regions may be selected, by name, to become the current geographic region. Users may also access saved region definitions stored under other mapsets in the current location, if these mapsets are included in the user's mapset search path.

REGION EDIT PROMPT

Most of the options will require the user to edit a geographic region, be it the current geographic region or one stored in the user's data base of region definitions (the windows directory). A standard prompt is used to perform this edit. An example is shown below:

---------------------------------------------------------------
|                         IDENTIFY REGION                     |
|                                                             |
|           ===========  DEFAULT REGION  ==========           |
|           |    Default North: 3402025.00        |           |
|           |                                     |           |
|           |          ===YOUR REGION===          |           |
|           |          |  NORTH EDGE   |          |           |
|           |          |  3402025.00_  |          |           |
|           |          |               |          |           |
| Def West: |WEST EDGE |               |EAST EDGE | Def.East: |
| 233975.00 |233975.00_|               |236025.00_| 236025.00 |
|           |          |  SOUTH EDGE   |          |           |
|           |          |  3399975.00_  |          |           |
|           |          =================          |           |
|           |                                     |           |
|           |    Default South: 3399975.00        |           |
|           =======================================           |
|                                                             |
|              Default   GRID RESOLUTION   Region             |
|               50.00   --- East-West ---  50.00__            |
|               50.00   -- North-South --  50.00__            |
|                                                             |
|                                                             |
|     AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE     |
---------------------------------------------------------------

The fields NORTH EDGE, SOUTH EDGE, WEST EDGE and EAST EDGE, are the boundaries of the geographic region that the user can change. The fields Default North, Default South, Def West and Def East are the boundaries of the default geographic region that are displayed for reference and cannot be changed. The two GRID RESOLUTION Region fields (east-west, and north-south) are the geographic region's cell resolutions that the user can change. The two GRID RESOLUTION Default fields list the resolutions of the default geographic region; these are displayed for reference and cannot be changed here by the user.

REGION MANAGEMENT MENU OPTIONS

Modify the current geographic region directly Allows the user to edit the current region.
Set current geographic region from default region Copies the default region to the current geographic region, and then lets the user edit the current geographic region.
Set current geographic region from a data base geographic region Allows the user to select a geographic region by name from the data base of geographic regions to become the current geographic region, and then lets the user edit the current geographic region.
Note: geographic region definition files may be selected from other mapsets as well, if accessible and in the user's mapset search path.
Set current geographic region from a raster (cell) map layer Allows the user to select a raster map layer, copies the cell header for this map layer to the current geographic region, and then lets the user edit the current geographic region. This option is useful when subsequent GRASS operations will be used to produce a raster map layer from one input raster map layer and it is necessary that the result coincide with the input raster map layer.
Save the current geographic region (window) in the data base Allows the user to save the current geographic region settings in the user's data base of such settings. These files are stored in the windows directory under the user's current mapset. This option is useful when the current geographic region is set directly using option 2, or even by another GRASS program (e.g., d.display). This option installs an otherwise temporary geographic region setting into the geographic region definition data base for recall when needed.
Create a new data base geographic region setting Creates a new geographic region definition in the user's data base of such settings in the windows directory under the current mapset, using the geographic region edit prompt described above. After the geographic region definition is created, the user is asked if this geographic region setting should also be used as the current geographic region.
Modify a data base geographic region setting Modifies a geographic region setting (in the data base of such settings in the windows directory of the current mapset), using the geographic region edit prompt. After the changes have been made, the user is asked if this geographic region setting should also be used as the current geographic region.

NON-INTERACTIVE PROGRAM USE

Alternately, the user can modify the settings of the current geographic region by specifying all needed parameters on the command line. The user enters the command g.region parms, where parms are the following parameters and/or flags:

Flags:

-d: Set current region settings equal to default region settings.
-g: Print the current region settings (shell script style) in a format that can be given back to g.region on its command line.
-p: Print the current region settings.
-u: Do not update the current region file settings. Allows the user to temporarily use a different region setting, without saving this setting.

Parameters:

region=name: Make current region settings same as the named region file settings
raster=name: Make current region settings same as those in the named raster map's cell header. But see zoom=name option, below.
vector=name: Make the current region settings the same as those of the named vector map.
sites=name: Set the current region to the smallest region encompassing all coordinates in the named site_lists file, aligned with the current region.
3dview=name: Make current region settings same as those in the named 3dview file, which holds the region that was current when the 3dview was saved.
n=value: Set map coordinate value for the region's northern edge to value
s=value: Set map coordinate value for the region's southern edge to value
e=value: Set map coordinate value for the region's eastern edge to value
w=value: Set map coordinate value for the region's western edge to value
res=value: Set grid resolution (both north-south and east-west) to value
nsres=value: Set north-south grid resolution value to value
ewres=value: Set east-west grid resolution value to value
zoom=name: Set current region settings to the smallest region encompassing all non-zero data in the named raster map layer that fall inside the user's current region.
If the user also includes the raster=name option on the command line, zoom=name will set the current region settings to the smallest region encompassing all non-zero data in the named zoom map that fall inside the region stated in the cell header for the named raster map.
align=name: Set the current resolution equal to that of the named raster map, and align the current region to a row and column edge in the named map. Alignment only moves the existing region edges outward to the edges of the next nearest cell in the named raster map -- not to the named map's edges. To perform the latter function, use the raster=name option.
save=name: Save current region settings in the named region file

EXAMPLES

g.region n=7360100 e=699000

will reset the northing and easting for the current region, but leave the south edge, west edge, and the region cell resolutions unchanged.

g.region -dp s=698000

will set the current region from the default region for the GRASS data base location, reset the south edge to 698000, and then print the result.

g.region n=n+1000 w=w-500

The n=value may also be specified as a function of its current value: n=n+value increases the current northing, while n=n-value decreases it. This is also true for s=value, e=value, and w=value. In this example the current region's northern boundary is extended by 1000 units and the current region's western boundary is decreased by 500 units.

g.region n=s+1000 e=w+1000

This form allows the user to set the region boundary values relative to one another. Here, the northern boundary coordinate is set equal to 1000 units larger than the southern boundary's coordinate value, and the eastern boundary's coordinate value is set equal to 1000 units larger than the western boundary's coordinate value. The corresponding forms s=n-value and

w=e-value may be used to set the values of the region's southern and western boundaries, relative to the northern and eastern boundary values.

g.region raster=soils

This form will make the current region settings exactly the same as those given in the cell header file for the raster map layer soils.

g.region raster=soils zoom=soils

This form will first look up the cell header file for the raster map layer soils, use this as the current region setting, and then shrink the region down to the smallest region which still encompasses all non-zero data in the map layer soils. Note that if the parameter raster=soils were not specified, the zoom would move to encompass all non-zero data values in the soils map that were located within the current region setting.

g.region -up raster=soils

The -u option suppresses the re-setting of the current region definition. This can be useful when it is desired to only extract region information. In this case, the cell header file for the soils map layer is printed without changing the current region settings.

g.region -u raster=soils zoom=soils save=soils

This will zoom into the smallest region which encompasses all non-zero soils data values, and save the new region settings in a file to be called soils and stored under the windows directory in the user's current mapset. The current region settings are not changed.

g.region -p

This will print the current region in the format:

projection:	1 (UTM)
zone:	15
datum:  WGS84
north:	4294050.00
south:	4249950.00
east:	526050.00
west:	500950.00
nsres:	100.00
ewres:	100.00
rows:	441
cols:	251

g.region -g

The -g option prints the region in the following format:

n=4294050.00
s=4249950.00
e=526050.00
w=500950.00
nsres=100.00
ewres=100.00

This format does not have the rows and columns, but can be fed back into g.region on its command line.

The -p (or -g) option is recognized last. This means that all changes are applied to the region settings before printing occurs.

NOTE

After all updates have been applied, the current region's southern and western boundaries are (silently) adjusted so that the north/south distance is a multiple of the north/south resolution and that the east/west distance is a multiple of the east/west resolution.

AUTHOR

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