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



NNAAMMEE
       gg..rreeggiioonn   -  Program  to  manage the boundary definitions for the geo-
       graphic 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]	 [vveeccttoorr==_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 settings of the cur-
       rent 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 cre-
       ate, 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  set-
       tings will use the current 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 spe-
	      cific 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 boundaries 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  geo-
	      graphic 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 direc-
	      tory (also referred to as the user's data base of region defini-
	      tions).	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 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 ref-
       erence 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 resolu-
       tions that the user can change.	The two GRID RESOLUTION Default fields
       list  the resolutions of the default geographic region;	these are dis-
       played for reference 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 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_._d_i_s_p_l_a_y).   This  option  installs an otherwise temporary geo-
	      graphic 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 geo-
	      graphic 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 current 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 for-
	      mat 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 coordinates.

       --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  resolu-
	      tions  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 set-
	      tings

       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 cur-
	      rent 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 settings 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 lat-
	      ter 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 boundary values rel-
	      ative 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 coor-
	      dinate value.  The corresponding 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 val-
       ues.

       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 specified, 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  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.



       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 dis-
       tance  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)
