NAME
g.region - Program to manage the boundary definitions for the geographic region.
SYNOPSIS
g.region
g.region help
g.region [-dgplecmau3] [region=name] [rast=name[,name,...]] [rast3d=name] [vect=name] [3dview=name] [n=value] [s=value] [e=value] [w=value] [t=value] [b=value] [res=value] [res3=value] [nsres=value] [ewres=value] [tbres=value] [zoom=name] [align=name] [save=name]
Flags:
- -d
- Set from default region
- -g
- Print the current region (shell script style)
- -p
- Print the current region
- -l
- Print the current region in lat/long
- -e
- Print the current region extent
- -c
- Print the current region map center coordinates
- -m
- Print region resolution in meters (geodesic)
- -a
- Align region to resolution (default = align to bounds, works only for 2D resolution )
- -u
- Do not update the current region
- -3
- Print also 3D
Parameters:
- region=name
- Set current region from named region
- rast=name[,name,...]
- Set region to match this raster map
- rast3d=name
- Set region to match this 3D raster map (both 2D and 3D values)
- vect=name
- Set region to match this vector map
- 3dview=name
- Set region to match this 3dview file
- n=value
- Value for the northern edge
- s=value
- Value for the southern edge
- e=value
- Value for the eastern edge
- w=value
- Value for the western edge
- t=value
- Value for the top edge
- b=value
- Value for the bottom edge
- res=value
- Grid resolution 2D (both north-south and east-west)
- res3=value
- 3D grid resolution (north-south, east-west and top-bottom)
- nsres=value
- North-south grid resolution 2D
- ewres=value
- East-west grid resolution 2D
- tbres=value
- Top-bottom grid resolution
- zoom=name
- Raster map to zoom into
- align=name
- Raster map to align to
- save=name
- Save the current region to region definition file
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:
- -a
- Align the region to the resolution supplied by the user. The default is to
align the region resolution to match the region boundaries.
- -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.
- -l
- Print the current region settings in lat/long coordinates.
- -c
- Print the current region map center coordinates.
- -m
- Print the region resolution in meters (from geodesic). With no other
flags the default output format is shell stype (-g). The region resolution
represents the center of the map. The resolutions are calculated at the four
outside edges, then the two NS edges are averaged and the two EW edges are
averaged, the results finally printed.
- -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 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 (but also decimal degrees can 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 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 -pm
- This will print the current region in the format:
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 reported in meters not decimal degrees.
- 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
- g.region -l
- The -l option prints the region in the
following format:
long: -103.86815 lat: 44.49980 (north/west corner)
long: -103.62896 lat: 44.49718 (north/east corner)
long: -103.63197 lat: 44.36839 (south/east corner)
long: -103.87063 lat: 44.37100 (south/west corner)
rows: 477
cols: 634
Center Longitude: 103:44:59.741001W [-103.74993]
Center latitude: 44:26:02.724974N [44.43409]
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.
With the -a flag all four boundaries are adjusted
to be even multiples of the resolution.
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.
SEE ALSO
d.zoom
g.access
g.mapsets
g.projinfo
AUTHOR
Michael Shapiro,
U.S.Army Construction Engineering
Research Laboratory
Last changed: $Date: 2005/03/02 11:39:24 $
Help Index