## DESCRIPTION

The g.region module 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.

## DEFINITIONS

Region:
  In GRASS, 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 (cell edges). 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 modules 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.

  Typically all raster and display modules are affected by the current region settings, but not vector modules. Some special modules diverge from this rule, for example raster import modules and v.in.region.

Default Region:
  Each GRASS LOCATION 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. The current region can be reset to the default region with the -d flag. The default region is initially set when the location is first created and can be reset using the -s flag.
Current Region:
  Each mapset has a current geographic region. This region defines the geographic area in which all GRASS displays and raster analyses will be done. Raster data will be resampled, if necessary, to meet the cell resolutions of the current geographic region setting.
Saved Regions:
  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 saved 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 or the '@' operator is used (`region_name@mapset`).

## NOTES

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.

With the -a flag all four boundaries are adjusted to be even multiples of the resolution, aligning the region to the resolution supplied by the user. The default is to align the region resolution to match the region boundaries.

The -m flag will report the region resolution in meters. The resolution is calculated by averaging the resolution at the region boundaries. This resolution is calculated by dividing the geodesic distance in meters at the boundary by the number of rows or columns. For example the east / west resolution (ewres) is determined from an average of the geodesic distances at the North and South boundaries divided by the number of columns.

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

The -g flag prints the current region settings in shell script style. This format can be given back to g.region on its command line. This may also be used to save region settings as shell environment variables with the UNIX eval command, "`eval `g.region -g``".

### Additional parameter information:

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.
zoom=name
  Shrink current region settings to the smallest region encompassing all non-NULL data in the named raster map layer that fall inside the user's current region. In this way you can tightly zoom in on isolated clumps within a bigger map.

  If the user also includes the rast=name option on the command line, zoom=name will set the current region settings to the smallest region encompassing all non-NULL 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 rast=name option.

## 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 n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01`
  will reset the northing, easting, southing, westing and resolution for the current region, here in DMS latitude-longitude style (decimal degrees and degrees with decimal minutes can also be used).

`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 rast=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 rast=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-NULL data in the map layer soils. Note that if the parameter rast=soils were not specified, the zoom would shrink to encompass all non-NULL data values in the soils map that were located within the current region settings.

`g.region -up rast=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 -up zoom=soils save=soils`
  This will zoom into the smallest region which encompasses all non-NULL 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 b=0 t=3000 tbres=200 res3=100 g.region -p3`
  This will define the 3D region for voxel computations. In this example a volume with bottom (0m) to top (3000m) at horizontal resolution (100m) and vertical resolution (200m) is defined.

`g.region -p`
  This will print the current region in the format:

      projection: 1 (UTM)
      zone:       13
      datum:      nad27
      ellipsoid:  clark66
      north:      4928000
      south:      4914000
      west:       590000
      east:       609000
      nsres:      20
      ewres:      20
      rows:       700
      cols:       950

`g.region -p3`
  This will print the current region and the 3D region (used for voxels) in the format:

      projection: 1 (UTM)
      zone:       13
      datum:      nad27
      ellipsoid:  clark66
      north:      4928000
      south:      4914000
      west:       590000
      east:       609000
      top:        1.00000000
      bottom:     0.00000000
      nsres:      20
      nsres3:     20
      ewres:      20
      ewres3:     20
      tbres:      1
      rows:       700
      rows3:      700
      cols:       950
      cols3:      950
      depths:     1

`g.region -g`
  The -g option prints the region in the following script style (key=value) format:

      n=4928000
      s=4914000
      w=590000
      e=609000
      nsres=20
      ewres=20
      rows=700
      cols=950

`g.region -bg`
  The -bg option prints the region in the following script style (key=value) format plus the boundary box in latitude-longitude/WGS84:

      n=4928000
      s=4914000
      w=590000
      e=609000
      nsres=20
      ewres=20
      rows=700
      cols=950
      LL_W=-103.87080682
      LL_E=-103.62942884
      LL_N=44.50164277
      LL_S=44.37302019

`g.region -l`
  The -l option prints the region in the following format:

      long: -103.86789484 lat: 44.50165890 (north/west corner)
      long: -103.62895703 lat: 44.49904013 (north/east corner)
      long: -103.63190061 lat: 44.37303558 (south/east corner)
      long: -103.87032572 lat: 44.37564292 (south/west corner)
      rows:       700
      cols:       950
      Center longitude: 103:44:59.170374W [-103.74977]
      Center latitude:  44:26:14.439781N [44.43734]

`g.region -pm`
  This will print the current region in the format (latitude-longitude location):

      projection: 3 (Latitude-Longitude)
      zone:       0
      ellipsoid:  wgs84
      north:      90N
      south:      40N
      west:       20W
      east:       20E
      nsres:      928.73944902
      ewres:      352.74269109
      rows:       6000
      cols:       4800

  Note that the resolution is here reported in meters, not decimal degrees.

Usage example of g.region in a shell with external software:
Extract spatial subset of external vector map 'soils.shp' to new external vector map 'soils_cut.shp' using the OGR 'ogr2ogr' tool:

    eval `g.region -g`
    ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp

This requires that the location/SHAPE file projection match.

Usage example of g.proj and g.region in a shell with external software:
Extract spatial subset of external raster map 'p016r035_7t20020524_z17_nn30.tif' to new external raster map'p016r035_7t20020524_nc_spm_wake_nn30.tif using the GDAL 'gdalwarp' tool:

    eval `g.region -g`
    gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \
             p016r035_7t20020524_z17_nn30.tif \
             p016r035_7t20020524_nc_spm_wake_nn30.tif

Here the input raster map does not have to match the location projection since it is reprojected on the fly.

## SEE ALSO

d.zoom
g.access
g.mapsets
g.proj
g.setproj
environment variables: GRASS_REGION and WIND_OVERRIDE

## AUTHOR

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

Last changed: $Date$