[GRASS-SVN] r29875 -
grass/branches/releasebranch_6_3/general/g.region/cmd
svn_grass at osgeo.org
svn_grass at osgeo.org
Mon Jan 28 02:01:56 EST 2008
Author: hamish
Date: 2008-01-28 02:01:56 -0500 (Mon, 28 Jan 2008)
New Revision: 29875
Modified:
grass/branches/releasebranch_6_3/general/g.region/cmd/description.html
Log:
remove old GRASS 5 cruft, update & fix (merge from TRUNK)
Modified: grass/branches/releasebranch_6_3/general/g.region/cmd/description.html
===================================================================
--- grass/branches/releasebranch_6_3/general/g.region/cmd/description.html 2008-01-28 06:57:10 UTC (rev 29874)
+++ grass/branches/releasebranch_6_3/general/g.region/cmd/description.html 2008-01-28 07:01:56 UTC (rev 29875)
@@ -1,6 +1,6 @@
<h2>DESCRIPTION</h2>
-The <em>g.region</em> program allows the user to manage the
+The <em>g.region</em> 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
@@ -30,286 +30,126 @@
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 <em>northings</em>, while the east and west
+define its extent (cell edges). The north and south boundaries
+are commonly called <em>northings</em>, while the east and west
boundaries are called <em>eastings</em>.
<p>
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.
+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.
+<P>
+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 <em>v.in.region</em>.
+
+
<dt><b>Default Region:</b>
-<dd>Each GRASS <kbd>LOCATION_NAME</kbd> has a fixed
+<dd>Each GRASS LOCATION has a fixed
geographic region, called the default geographic region
(stored in the region file <kbd>DEFAULT_WIND</kbd> under
the special mapset <kbd>PERMANENT</kbd>), 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.
+region. The current region can be reset to the default region
+with the <b>-d</b> flag. The default region is initially set
+when the location is first created and can be reset using the
+<b>-s</b> flag.
-
<dt><b>Current Region:</b>
<dd>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
+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.
-<dt><b>Region Data Base:</b>
+<dt><b>Saved Regions:</b>
<dd>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 <kbd>windows</kbd> directory (also
-referred to as the user's data base of region
-definitions). Any of these pre-defined geographic regions
+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.
-
+path or the '@' operator is used (<tt>region_name at mapset</tt>).
</dl>
-<h2>REGION EDIT PROMPT</h2>
-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 <kbd>windows</kbd> directory). A standard prompt is
-used to perform this edit. An example is shown below:
+<h2>NOTES</h2>
+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.
-
-<pre>
----------------------------------------------------------------
-| 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 |
----------------------------------------------------------------
-</pre>
-
-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
-<em>cannot</em> 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.
-
-<h2>REGION MANAGEMENT MENU OPTIONS</h2>
-
-<ol>
-
-<li>Modify the current geographic region directly Allows
-the user to edit the current region.
-
-
-<li>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.
-
-<li>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.
-
-<br>
-Note: geographic region definition files may be selected
-from other mapsets as well, if accessible and in the user's
-mapset search path.
-
-<li>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.
-
-<li>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 <kbd>windows</kbd> 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., <em><a HREF="d.m.html">d.m</a></em>).
-
-This option installs an otherwise temporary geographic
-region setting into the geographic region definition data
-base for recall when needed.
-
-<li>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 <kbd>windows</kbd>
-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.
-
-<li>Modify a data base geographic region setting Modifies a
-geographic region setting (in the data base of such
-settings in the <kbd>windows</kbd> 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.
-
-
-</ol>
-
-<h2>NON-INTERACTIVE PROGRAM USE</h2>
-
-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 <b>g.region</b> <em>parms</em>, where
-<em>parms</em> are the following parameters and/or flags:
-
-<!--
-<h3>Flags:</h3>
-
-<dl>
-
-<dt><b>-a</b>
-<dd>Align the region to the resolution supplied by the user. The default is to
+<p>
+With the <b>-a</b> 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.
-<dt><b>-d</b>
-<dd>Set current region settings equal to default region settings.
-
-<dt><b>-g</b>
-<dd>Print the current region settings (shell script style) in a
-format that can be given back to <em>g.region</em> on its command line.
-
-<dt><b>-p</b>
-<dd>Print the current region settings.
-
-<dt><b>-l</b>
-
-<dd>Print the current region settings in lat/long coordinates.
-
-<dt><b>-c</b>
-<dd>Print the current region map center coordinates.
-
-<dt><b>-m</b>
-<dd>Print the region resolution in meters (from geodesic). With no other
+<p>
+The <b>-m</b> 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.
+<!-- add'l info. include?
+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.
+-->
-<dt><b>-u</b>
-<dd>Do not update the current region file settings. Allows the user to
-temporarily use a different region setting, without saving this setting.
-</dl>
-<h3>Parameters:</h3>
+<p>
+The <b>-p</b> (or <b>-g</b>) option is recognized
+last. This means that all changes are applied to the
+region settings before printing occurs.
+<P>
+The <b>-g</b> flag prints the current region settings in shell script style.
+This format can be given back to <em>g.region</em> on its command line.
+This may also be used to save region settings as shell environment variables
+with the UNIX eval command, "<tt>eval `g.region -g`</tt>".
-<dl>
-<dt><b>region=</b><em>name</em>
-<dd>Make current region settings same as the named region
-file settings
+<h3>Additional parameter information:</h3>
-<dt><b>rast=</b><em>name</em>
-<dd>Make current region settings same as those in the named
-raster map's cell header. But see
-<a HREF="#parm-zoom"><b>zoom=</b><em>name</em> option</a>, below.
-
-<dt><b>vector=</b><em>name</em>
-<dd>Make the current region settings the same as those of
-the named vector map.
-
-<dt><b>sites=</b><em>name</em>
-
-
-<dd>Set the current region to the smallest region
-encompassing all coordinates in the named
-<kbd>site_lists</kbd> file, aligned with the current
-region.
-
+<dl>
<dt><b>3dview=</b><em>name</em>
<dd>Make current region settings same as those in the named
3dview file, which holds the region that was current when
the 3dview was saved.
-<dt><b>n=</b><em>value</em>
-<dd>Set map coordinate value for the region's northern edge
-to <em>value</em>
-<dt><b>s=</b><em>value</em>
-
-<dd>Set map coordinate value for the region's southern edge
-to <em>value</em>
-
-<dt><b>e=</b><em>value</em>
-<dd>Set map coordinate value for the region's eastern edge
-to <em>value</em>
-
-<dt><b>w=</b><em>value</em>
-<dd>Set map coordinate value for the region's western edge
-to <em>value</em>
-
-<dt><b>res=</b><em>value</em>
-<dd>Set grid resolution (both north-south and east-west) to
-<em>value</em>
-
-<dt><b>nsres=</b><em>value</em>
-<dd>Set north-south grid resolution value to <em>value</em>
-
-<dt><b>ewres=</b><em>value</em>
-
-<dd>Set east-west grid resolution value to <em>value</em>
-
-<a NAME="parm-zoom"><dt><b>zoom=</b><em>name</em></a>
-<dd>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.
-
+<dt><b>zoom=</b><em>name</em>
+<dd>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.
<p>
-
If the user also includes the <b>rast=</b><em>name</em>
option on the command line, <b>zoom=</b><em>name</em> will
set the current region settings to the smallest region
-encompassing all non-zero data in the named <b>zoom</b> map
+encompassing all non-NULL data in the named <b>zoom</b> map
that fall inside the region stated in the cell header for
the named <b>raster</b> map.
@@ -320,16 +160,13 @@
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
+nearest cell in the named raster map - not to the named
map's edges. To perform the latter function, use the
<b>rast=</b><em>name</em> option.
-
-<dt><b>save=</b><em>name</em>
-<dd>Save current region settings in the named region file
</dl>
--->
+
<h2>EXAMPLES</h2>
<dl>
@@ -347,13 +184,14 @@
g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01
</pre></div>
-<dd> 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).
+<dd> 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).
<p>
<dt><div class="code"><pre>
-g.region -dp s=698000
+g.region -dp s=698000
</pre></div>
<dd> will set the current region from the default region
@@ -369,7 +207,6 @@
<dd> The n=<em>value</em> may also be specified as a
function of its current value: n=n+<em>value</em>
increases the current northing, while n=n-<em>value</em>
-
decreases it. This is also true for s=<em>value</em>,
e=<em>value</em>, and w=<em>value</em>. In this example
the current region's northern boundary is extended by 1000
@@ -390,13 +227,13 @@
larger than the western boundary's coordinate value. The
corresponding forms s=n-<em>value</em> and
-
<p>
w=e-<em>value</em> may be used to set the values of the
region's southern and western boundaries, relative to the
northern and eastern boundary values.
+
<dt><div class="code"><pre>
g.region rast=soils
</pre></div>
@@ -407,24 +244,23 @@
<p>
-<!-- how does this work?
+
<dt><div class="code"><pre>
-g.region rast=soils ???
+g.region rast=soils zoom=soils
</pre></div>
<dd> This form will first look up the cell header file for
the raster map layer <em>soils</em>, use this as the
current region setting, and then shrink the region down to
-the smallest region which still encompasses all non-zero
+the smallest region which still encompasses all non-NULL
data in the map layer <em>soils</em>. Note that if the
parameter <em>rast=soils</em> 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.
+zoom would shrink to encompass all non-NULL data values in
+the soils map that were located within the <i>current region</i>
+settings.
<p>
--->
<dt><div class="code"><pre>
g.region -up rast=soils
@@ -439,17 +275,18 @@
<p>
<dt><div class="code"><pre>
-g.region -p rast=soils
+g.region -up zoom=soils save=soils
</pre></div>
<dd> This will zoom into the smallest region which
-encompasses all non-zero soils data values, and save the
+encompasses all non-NULL soils data values, and save the
new region settings in a file to be called <em>soils</em>
and stored under the <kbd>windows</kbd> directory in the
user's current mapset. The current region settings are not
changed.
<p>
+
<dt><div class="code"><pre>
g.region b=0 t=3000 tbres=200 res3=100
g.region -p3
@@ -586,7 +423,8 @@
g.region -pm
</pre></div>
-<dd> This will print the current region in the format (latitude-longitude location):
+<dd> This will print the current region in the format
+ (latitude-longitude location):
<div class="code"><pre>
projection: 3 (Latitude-Longitude)
@@ -605,14 +443,11 @@
</dl>
-The <b>-p</b> (or <b>-g</b>) option is recognized
-last. This means that all changes are applied to the
-region settings before printing occurs.
-
<p>
Usage example of <em>g.region</em> in a shell with external software:<br>
-Extract spatial subset of external vector map 'soils.shp' to new external vector
-map 'soils_cut.shp' using the OGR 'ogr2ogr' tool:<br>
+<!-- why not 'v.in.ogr spatial=' ?? -->
+Extract spatial subset of external vector map 'soils.shp' to new external
+vector map 'soils_cut.shp' using the OGR 'ogr2ogr' tool:<br>
<div class="code"><pre>
eval `g.region -g`
@@ -620,6 +455,8 @@
</pre></div>
This requires that the location/SHAPE file projection match.
+
+
<p>
Usage example of <em>g.proj</em> and <em>g.region</em> in a shell with external software:<br>
Extract spatial subset of external raster map 'p016r035_7t20020524_z17_nn30.tif'
@@ -636,42 +473,25 @@
Here the input raster map does not have to match the location
projection since it is reprojected on the fly.
-<h2>NOTE</h2>
-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.
-<p>
-
-With the <b>-a</b> flag all four boundaries are adjusted
-to be even multiples of the resolution.
-
-<p>
-
-The <b>-m</b> 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.
-
-
-
<h2>SEE ALSO</h2>
-<em><a HREF="d.zoom.html">d.zoom</a></em><br>
-<em><a HREF="g.access.html">g.access</a></em><br>
-<em><a HREF="g.mapsets.html">g.mapsets</a></em><br>
-<em><a HREF="g.projinfo.html">g.projinfo</a></em>
+<em>
+<a HREF="d.zoom.html">d.zoom</a><br>
+<a HREF="g.access.html">g.access</a><br>
+<a HREF="g.mapsets.html">g.mapsets</a><br>
+<a HREF="g.proj.html">g.proj</a><BR>
+<a HREF="g.setproj.html">g.setproj</a><BR>
+environment variables: <a HREF="variables.html#internal">GRASS_REGION and WIND_OVERRIDE</a>
+</em>
+
<h2>AUTHOR</h2>
Michael Shapiro,
U.S.Army Construction Engineering
Research Laboratory
-<p><i>Last changed: $Date$</i>
+<p>
+<i>Last changed: $Date$</i>
More information about the grass-commit
mailing list