g.region(1)	       Grass User's Manual	      g.region(1)



NNAAMMEE
       gg..rreeggiioonn  - Program to manage the boundary definitions for
       the geographic region.
       _(_G_R_A_S_S _R_e_g_i_o_n _M_a_n_a_g_e_m_e_n_t _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       gg..rreeggiioonn
       gg..rreeggiioonn hheellpp
       gg..rreeggiioonn  [--aaddggppllccmmuu]  [rreeggiioonn==_n_a_m_e]  [rraasstteerr==_n_a_m_e]  [vveecc--
       ttoorr==_n_a_m_e]  [ssiitteess==_n_a_m_e]	[33ddvviieeww==_n_a_m_e] [nn==_v_a_l_u_e] [ss==_v_a_l_u_e]
       [ee==_v_a_l_u_e]     [ww==_v_a_l_u_e]	   [rreess==_v_a_l_u_e]	    [nnssrreess==_v_a_l_u_e]
       [eewwrreess==_v_a_l_u_e] [zzoooomm==_n_a_m_e] [aalliiggnn==_n_a_m_e] [ssaavvee==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       The  _g_._r_e_g_i_o_n  program  allows the user to manage the set-
       tings 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  direc-
       tory  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  cur-
       rent geographic region settings.

IINNTTEERRAACCTTIIVVEE PPRROOGGRRAAMM UUSSEE:: MMAAIINN MMEENNUU
       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
       |
       ------------------------------------------------------------


DDEEFFIINNIITTIIOONNSS
       RReeggiioonn::
	      Here,  a	_r_e_g_i_o_n	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 _n_o_r_t_h_i_n_g_s, while the east and west bound-
       aries are called _e_a_s_t_i_n_g_s.


       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.

       DDeeffaauulltt RReeggiioonn::
	      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.

       CCuurrrreenntt RReeggiioonn::
	      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  set-
	      ting.

       RReeggiioonn DDaattaa BBaassee::
	      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 defi-
	      nitions).   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.


RREEGGIIOONN EEDDIITT PPRROOMMPPTT
       Most  of  the options will require the user to edit a geo-
       graphic 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
       _c_a_n_n_o_t 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 refer-
       ence and cannot be changed here by the user.

RREEGGIIOONN MMAANNAAGGEEMMEENNTT MMEENNUU OOPPTTIIOONNSS
	      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 geo-
	      graphic region Allows the user  to  select  a  geo-
	      graphic  region  by name from the data base of geo-
	      graphic 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 geo-
	      graphic region settings in the user's data base  of
	      such  settings.  These files are stored in the win-
	      dows 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_._d_i_s_p_l_a_y).   This
	      option installs an otherwise  temporary  geographic
	      region  setting  into the geographic region defini-
	      tion 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  Modi-
	      fies  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.


NNOONN--IINNTTEERRAACCTTIIVVEE PPRROOGGRRAAMM UUSSEE
       Alternately, the user can modify the settings of the  cur-
       rent geographic region by specifying all needed parameters
       on  the	command  line.	 The  user  enters  the   command
       gg..rreeggiioonn  _p_a_r_m_s,  where _p_a_r_m_s are the following parameters
       and/or flags:

   FFllaaggss::
       --aa     Align the region to the resolution supplied by  the
	      user. The default is to align the region resolution
	      to match the region boundaries.

       --dd     Set current region settings equal to default region
	      settings.

       --gg     Print  the  current  region  settings (shell script
	      style) in a  format  that  can  be  given  back  to
	      _g_._r_e_g_i_o_n on its command line.

       --pp     Print the current region settings.

       --ll     Print the current region settings in lat/long coor-
	      dinates.

       --cc     Print the current region map center coordinates.

       --mm     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.

       --uu     Do not update the  current  region  file	settings.
	      Allows  the  user  to  temporarily  use a different
	      region setting, without saving this setting.


   PPaarraammeetteerrss::
       rreeggiioonn==_n_a_m_e
	      Make current region  settings  same  as  the  named
	      region file settings

       rraasstteerr==_n_a_m_e
	      Make  current  region settings same as those in the
	      named raster map's cell header.  But see	zzoooomm==_n_a_m_e
	      option, below.

       vveeccttoorr==_n_a_m_e
	      Make  the current region settings the same as those
	      of the named vector map.

       ssiitteess==_n_a_m_e
	      Set the  current	region	to  the  smallest  region
	      encompassing   all   coordinates	 in   the   named
	      site_lists file, aligned with the current region.

       33ddvviieeww==_n_a_m_e
	      Make current region settings same as those  in  the
	      named  3dview file, which holds the region that was
	      current when the 3dview was saved.

       nn==_v_a_l_u_e
	      Set map coordinate value for the region's  northern
	      edge to _v_a_l_u_e

       ss==_v_a_l_u_e
	      Set  map coordinate value for the region's southern
	      edge to _v_a_l_u_e

       ee==_v_a_l_u_e
	      Set map coordinate value for the	region's  eastern
	      edge to _v_a_l_u_e

       ww==_v_a_l_u_e
	      Set  map	coordinate value for the region's western
	      edge to _v_a_l_u_e

       rreess==_v_a_l_u_e
	      Set grid resolution  (both  north-south  and  east-
	      west) to _v_a_l_u_e

       nnssrreess==_v_a_l_u_e
	      Set north-south grid resolution value to _v_a_l_u_e

       eewwrreess==_v_a_l_u_e
	      Set east-west grid resolution value to _v_a_l_u_e

       zzoooomm==_n_a_m_e
	      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 rraasstteerr==_n_a_m_e  option  on  the
       command	line,  zzoooomm==_n_a_m_e will set the current region set-
       tings to the smallest  region  encompassing  all  non-zero
       data  in  the  named  zzoooomm map that fall inside the region
       stated in the cell header for the named rraasstteerr map.

       aalliiggnn==_n_a_m_e
	      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 rraasstteerr==_n_a_m_e option.

       ssaavvee==_n_a_m_e
	      Save current region settings in  the  named  region
	      file


EEXXAAMMPPLLEESS
       gg..rreeggiioonn nn==_7_3_6_0_1_0_0 ee==699000
	      will reset the northing and easting for the current
	      region, but leave the south edge,  west  edge,  and
	      the region cell resolutions unchanged.



       gg..rreeggiioonn  --ddpp ss==_6_9_8_0_0_0
	      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.



       gg..rreeggiioonn nn==_n_+_1_0_0_0 ww==_w_-_5_0_0
	      The  n=_v_a_l_u_e may also be specified as a function of
	      its current value:  n=n+_v_a_l_u_e increases the current
	      northing,  while	n=n-_v_a_l_u_e  decreases it.  This is
	      also true for s=_v_a_l_u_e, e=_v_a_l_u_e,  and  w=_v_a_l_u_e.   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.



       gg..rreeggiioonn nn==_s_+_1_0_0_0 ee==_w_+_1_0_0_0
	      This  form allows the user to set the region bound-
	      ary values relative  to  one  another.   Here,  the
	      northern	boundary  coordinate is set equal to 1000
	      units larger than the southern  boundary's  coordi-
	      nate  value,  and the eastern boundary's coordinate
	      value is set equal to 1000 units	larger	than  the
	      western  boundary's  coordinate  value.  The corre-
	      sponding forms s=n-_v_a_l_u_e and


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

       gg..rreeggiioonn rraasstteerr==_s_o_i_l_s
	      This form will make  the	current  region  settings
	      exactly  the same as those given in the cell header
	      file for the raster map layer _s_o_i_l_s.



       gg..rreeggiioonn rraasstteerr==_s_o_i_l_s zzoooomm==_s_o_i_l_s
	      This form will first look up the cell  header  file
	      for  the	raster	map  layer _s_o_i_l_s, 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  _s_o_i_l_s.   Note
	      that  if the parameter _r_a_s_t_e_r_=_s_o_i_l_s were not speci-
	      fied, the zoom would move to encompass all non-zero
	      data  values  in	the  soils  map that were located
	      within the current region setting.



       gg..rreeggiioonn --uupp rraasstteerr==_s_o_i_l_s
	      The --uu option suppresses the re-setting of the cur-
	      rent 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.



       gg..rreeggiioonn --uu rraasstteerr==_s_o_i_l_s zzoooomm==_s_o_i_l_s ssaavvee==_s_o_i_l_s
	      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
	      _s_o_i_l_s and stored under the windows directory in the
	      user's current mapset.  The current region settings
	      are not changed.



       gg..rreeggiioonn  --pp
	      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




       gg..rreeggiioonn  --ppmm
	      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.



       gg..rreeggiioonn  --gg
	      The  --gg  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


       gg..rreeggiioonn  --ll
	      The --ll 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_._r_e_g_i_o_n on its command  line.

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

NNOOTTEE
       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  --aa  flag all four boundaries are adjusted to be
       even multiples of the resolution.


       The --mm 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.

SSEEEE AALLSSOO
       _d_._d_i_s_p_l_a_y

       _d_._z_o_o_m

       _g_._a_c_c_e_s_s

       _g_._m_a_p_s_e_t_s _g_._p_r_o_j_i_n_f_o

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

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_3 _$



GRASS 5.0					      g.region(1)
