.TH g.region 1grass "" "GRASS 7.8.5" "GRASS GIS User's Manual"
.SH NAME
\fI\fBg.region\fR\fR  \- Manages the boundary definitions for the geographic region.
.SH KEYWORDS
general, settings, computational region, extent, resolution, level1
.SH SYNOPSIS
\fBg.region\fR
.br
\fBg.region \-\-help\fR
.br
\fBg.region\fR [\-\fBdsplectwmn3bgfau\fR]  [\fBregion\fR=\fIname\fR]   [\fBraster\fR=\fIname\fR[,\fIname\fR,...]]   [\fBraster_3d\fR=\fIname\fR]   [\fBvector\fR=\fIname\fR[,\fIname\fR,...]]   [\fBn\fR=\fIvalue\fR]   [\fBs\fR=\fIvalue\fR]   [\fBe\fR=\fIvalue\fR]   [\fBw\fR=\fIvalue\fR]   [\fBt\fR=\fIvalue\fR]   [\fBb\fR=\fIvalue\fR]   [\fBrows\fR=\fIvalue\fR]   [\fBcols\fR=\fIvalue\fR]   [\fBres\fR=\fIvalue\fR]   [\fBres3\fR=\fIvalue\fR]   [\fBnsres\fR=\fIvalue\fR]   [\fBewres\fR=\fIvalue\fR]   [\fBtbres\fR=\fIvalue\fR]   [\fBzoom\fR=\fIname\fR]   [\fBalign\fR=\fIname\fR]   [\fBgrow\fR=\fIvalue\fR]   [\fBsave\fR=\fIname\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-d\fR" 4m
.br
Set from default region
.IP "\fB\-s\fR" 4m
.br
Save as default region
.br
Only possible from the PERMANENT mapset
.IP "\fB\-p\fR" 4m
.br
Print the current region
.IP "\fB\-l\fR" 4m
.br
Print the current region in lat/long using the current ellipsoid/datum
.IP "\fB\-e\fR" 4m
.br
Print the current region extent
.IP "\fB\-c\fR" 4m
.br
Print the current region map center coordinates
.IP "\fB\-t\fR" 4m
.br
Print the current region in GMT style
.IP "\fB\-w\fR" 4m
.br
Print the current region in WMS style
.IP "\fB\-m\fR" 4m
.br
Print region resolution in meters (geodesic)
.IP "\fB\-n\fR" 4m
.br
Print the convergence angle (degrees CCW)
.br
The difference between the projection\(cqs grid north and true north, measured at the center coordinates of the current region.
.IP "\fB\-3\fR" 4m
.br
Print also 3D settings
.IP "\fB\-b\fR" 4m
.br
Print the maximum bounding box in lat/long on WGS84
.IP "\fB\-g\fR" 4m
.br
Print in shell script style
.IP "\fB\-f\fR" 4m
.br
Print in shell script style, but in one line (flat)
.IP "\fB\-a\fR" 4m
.br
Align region to resolution (default = align to bounds, works only for 2D resolution)
.IP "\fB\-u\fR" 4m
.br
Do not update the current region
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBregion\fR=\fIname\fR" 4m
.br
Set current region from named region
.IP "\fBraster\fR=\fIname[,\fIname\fR,...]\fR" 4m
.br
Set region to match raster map(s)
.IP "\fBraster_3d\fR=\fIname\fR" 4m
.br
Set region to match 3D raster map(s) (both 2D and 3D values)
.IP "\fBvector\fR=\fIname[,\fIname\fR,...]\fR" 4m
.br
Set region to match vector map(s)
.IP "\fBn\fR=\fIvalue\fR" 4m
.br
Value for the northern edge
.IP "\fBs\fR=\fIvalue\fR" 4m
.br
Value for the southern edge
.IP "\fBe\fR=\fIvalue\fR" 4m
.br
Value for the eastern edge
.IP "\fBw\fR=\fIvalue\fR" 4m
.br
Value for the western edge
.IP "\fBt\fR=\fIvalue\fR" 4m
.br
Value for the top edge
.IP "\fBb\fR=\fIvalue\fR" 4m
.br
Value for the bottom edge
.IP "\fBrows\fR=\fIvalue\fR" 4m
.br
Number of rows in the new region
.IP "\fBcols\fR=\fIvalue\fR" 4m
.br
Number of columns in the new region
.IP "\fBres\fR=\fIvalue\fR" 4m
.br
2D grid resolution (north\-south and east\-west)
.IP "\fBres3\fR=\fIvalue\fR" 4m
.br
3D grid resolution (north\-south, east\-west and top\-bottom)
.IP "\fBnsres\fR=\fIvalue\fR" 4m
.br
North\-south 2D grid resolution
.IP "\fBewres\fR=\fIvalue\fR" 4m
.br
East\-west 2D grid resolution
.IP "\fBtbres\fR=\fIvalue\fR" 4m
.br
Top\-bottom 3D grid resolution
.IP "\fBzoom\fR=\fIname\fR" 4m
.br
Shrink region until it meets non\-NULL data from this raster map
.IP "\fBalign\fR=\fIname\fR" 4m
.br
Adjust region cells to cleanly align with this raster map
.IP "\fBgrow\fR=\fIvalue\fR" 4m
.br
Number of cells to add to each side of the current region extent
.br
A negative number shrinks the current region extent
.IP "\fBsave\fR=\fIname\fR" 4m
.br
Save current region settings in named region file
.SH DESCRIPTION
The \fIg.region\fR 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\(cqs 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.
.SH DEFINITIONS
.IP "\fBRegion:\fR  " 4m
.br
In GRASS, a \fIregion\fR 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
\(dqcells\(dq).
.PP
The region\(cqs 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 \fInorthings\fR, while the east and west
boundaries are called \fIeastings\fR.
.PP
The region\(cqs 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.
.PP
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 \fIv.in.region\fR.
.IP "\fBDefault Region:\fR  " 4m
.br
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 \fB\-d\fR flag. The default region is initially set
when the location is first created and can be reset using the
\fB\-s\fR flag.
.IP "\fBCurrent Region:\fR  " 4m
.br
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.
.IP "\fBSaved Regions:\fR  " 4m
.br
Each GRASS MAPSET may contain any number of
pre\-defined, and named, geographic regions.  These region
definitions are stored in the user\(cqs current mapset
location under the windows directory (also
referred to as the user\(cqs 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\(cqs mapset search
path or the \(cq@\(cq operator is used (region_name@mapset).
.SH NOTES
After all updates have been applied, the current region\(cqs
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.
.PP
With the \fB\-a\fR 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.
.PP
The \fB\-m\fR 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.
.PP
The \fB\-p\fR (or \fB\-g\fR) option is recognized
last.  This means that all changes are applied to the
region settings before printing occurs.
.PP
The \fB\-g\fR flag prints the current region settings in shell script style.
This format can be given back to \fIg.region\fR on its command line.
This may also be used to save region settings as shell environment variables
with the UNIX eval command, \(dqeval \(gag.region \-g\(ga\(dq.
.SS Additional parameter information:
.IP "\fBzoom=\fR\fIname\fR " 4m
.br
Shrink current region settings to the smallest region
encompassing all non\-NULL data in the named raster map
layer that fall inside the user\(cqs current region. In this
way you can tightly zoom in on isolated clumps within a
bigger map.
.PP
If the user also includes the \fBraster=\fR\fIname\fR
option on the command line, \fBzoom=\fR\fIname\fR will
set the current region settings to the smallest region
encompassing all non\-NULL data in the named \fBzoom\fR map
that fall inside the region stated in the cell header for
the named \fBraster\fR map.
.IP "\fBalign=\fR\fIname\fR   " 4m
.br
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\(cqs edges.  To perform the latter function, use the
\fBraster=\fR\fIname\fR option.
.SH EXAMPLES
.SS Printing extent and raster resolution in 2D and 3D
.IP "\fC g.region \-p \fR  " 4m
.br
This will print the current region in the format:
.br
.nf
\fC
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
\fR
.fi
.PP
.IP "\fC g.region \-p3 \fR  " 4m
.br
This will print the current region and the 3D region (used for voxels)
in the format:
.br
.nf
\fC
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
\fR
.fi
.PP
.IP "\fC g.region \-g \fR  " 4m
.br
The \fB\-g\fR option prints the region in the
following script style (key=value) format:
.br
.nf
\fC
n=4928000
s=4914000
w=590000
e=609000
nsres=20
ewres=20
rows=700
cols=950
\fR
.fi
.PP
.IP "\fC g.region \-bg \fR  " 4m
.br
The \fB\-bg\fR option prints the region in the
following script style (key=value) format plus the
boundary box in latitude\-longitude/WGS84:
.br
.nf
\fC
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
\fR
.fi
.PP
.IP "\fC g.region \-l \fR  " 4m
.br
The \fB\-l\fR option prints the region in the
following format:
.br
.nf
\fC
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]
\fR
.fi
.PP
.IP "\fC g.region \-pm \fR  " 4m
.br
This will print the current region in the format
(latitude\-longitude location):
.br
.nf
\fC
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
\fR
.fi
Note that the resolution is here reported in meters, not decimal degrees.
.SS Changing extent and raster resolution using values
.IP "\fC g.region n=7360100 e=699000 \fR  " 4m
.br
will reset the northing and easting for the current
region, but leave the south edge, west edge, and the region
cell resolutions unchanged.
.PP
.IP "\fC g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01 \fR  " 4m
.br
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).
.PP
.IP "\fC g.region \-dp s=698000 \fR  " 4m
.br
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.
.PP
.IP "\fC g.region n=n+1000 w=w\-500 \fR  " 4m
.br
The n=\fIvalue\fR may also be specified as a
function of its current value:  n=n+\fIvalue\fR
increases the current northing, while n=n\-\fIvalue\fR
decreases it.  This is also true for s=\fIvalue\fR,
e=\fIvalue\fR, and w=\fIvalue\fR.  In this example
the current region\(cqs northern boundary is extended by 1000
units and the current region\(cqs western boundary is
decreased by 500 units.
.PP
.IP "\fC g.region n=s+1000 e=w+1000 \fR  " 4m
.br
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\(cqs coordinate value, and the eastern
boundary\(cqs coordinate value is set equal to 1000 units
larger than the western boundary\(cqs coordinate value.  The
corresponding forms s=n\-\fIvalue\fR and
.PP
w=e\-\fIvalue\fR may be used to set the values of the
region\(cqs southern and western boundaries, relative to the
northern and eastern boundary values.
.SS Changing extent and raster resolution using maps
.IP "\fC g.region raster=soils \fR  " 4m
.br
This form will make the current region settings
exactly the same as those given in the cell header file for
the raster map layer \fIsoils\fR.
.PP
.IP "\fC g.region raster=soils zoom=soils \fR  " 4m
.br
This form will first look up the cell header file for
the raster map layer \fIsoils\fR, 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 \fIsoils\fR.  Note that if the
parameter \fIraster=soils\fR were not specified, the
zoom would shrink to encompass all non\-NULL data values in
the soils map that were located within the \fIcurrent region\fR
settings.
.PP
.IP "\fC g.region \-up raster=soils \fR  " 4m
.br
The \fB\-u\fR 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.
.PP
.IP "\fC g.region \-up zoom=soils save=soils \fR  " 4m
.br
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 \fIsoils\fR
and stored under the windows directory in the
user\(cqs current mapset.  The current region settings are not
changed.
.SS Changing extent and raster resolution in 3D
.IP "\fC g.region b=0 t=3000 tbres=200 res3=100 g.region \-p3 \fR  " 4m
.br
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.
.SS Using g.region in a shell in combination with OGR
Extracting a spatial subset of the external vector map
soils.shp into new external vector map soils_cut.shp
using the OGR \fIogr2ogr\fR tool:
.br
.br
.nf
\fC
eval \(gag.region \-g\(ga
ogr2ogr \-spat $w $s $e $n soils_cut.shp soils.shp
\fR
.fi
This requires that the location/SHAPE file projection match.
.SS Using g.region in a shell in combination with GDAL
Extracting a spatial subset of the external raster map
p016r035_7t20020524_z17_nn30.tif into new external raster
map p016r035_7t20020524_nc_spm_wake_nn30.tif using the GDAL
\fIgdalwarp\fR tool:
.br
.br
.nf
\fC
eval \(gag.region \-g\(ga
gdalwarp \-t_srs \(dq\(gag.proj \-wf\(ga\(dq \-te $w $s $e $n \(rs
         p016r035_7t20020524_z17_nn30.tif \(rs
         p016r035_7t20020524_nc_spm_wake_nn30.tif
\fR
.fi
Here the input raster map does not have to match the location
projection since it is reprojected on the fly.
.SH SEE ALSO
\fI
g.access,
g.mapsets,
g.proj
.br
Environment variables: GRASS_REGION and WIND_OVERRIDE
\fR
.SH AUTHOR
Michael Shapiro,
U.S.Army Construction Engineering
Research Laboratory
.SH SOURCE CODE
.PP
Available at: g.region source code (history)
.PP
Main index |
General index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2020
GRASS Development Team,
GRASS GIS 7.8.5 Reference Manual