xenial (1) g.region.1grass.gz

Provided by: grass-doc_7.0.3-1build1_all bug

NAME

       g.region  - Manages the boundary definitions for the geographic region.

KEYWORDS

       general, settings

SYNOPSIS

       g.region
       g.region --help
       g.region      [-dsplectwmn3bgau]      [region=name]       [raster=name[,name,...]]       [raster_3d=name]
       [vector=name[,name,...]]    [n=value]    [s=value]    [e=value]     [w=value]     [t=value]     [b=value]
       [rows=value]    [cols=value]   [res=value]   [res3=value]   [nsres=value]   [ewres=value]   [tbres=value]
       [zoom=name]   [align=name]   [save=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -d
           Set from default region

       -s
           Save as default region
           Only possible from the PERMANENT mapset

       -p
           Print the current region

       -l
           Print the current region in lat/long using the current ellipsoid/datum

       -e
           Print the current region extent

       -c
           Print the current region map center coordinates

       -t
           Print the current region in GMT style

       -w
           Print the current region in WMS style

       -m
           Print region resolution in meters (geodesic)

       -n
           Print the convergence angle (degrees CCW)
           The difference between the projection’s grid north and true north, measured at the center coordinates
           of the current region.

       -3
           Print also 3D settings

       -b
           Print the maximum bounding box in lat/long on WGS84

       -g
           Print in shell script style

       -a
           Align region to resolution (default = align to bounds, works only for 2D resolution)

       -u
           Do not update the current region

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       region=name
           Set current region from named region

       raster=name[,name,...]
           Set region to match raster map(s)

       raster_3d=name
           Set region to match 3D raster map(s) (both 2D and 3D values)

       vector=name[,name,...]
           Set region to match vector map(s)

       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

       rows=value
           Number of rows in the new region

       cols=value
           Number of columns in the new region

       res=value
           2D grid resolution (north-south and east-west)

       res3=value
           3D grid resolution (north-south, east-west and top-bottom)

       nsres=value
           North-south 2D grid resolution

       ewres=value
           East-west 2D grid resolution

       tbres=value
           Top-bottom 3D grid resolution

       zoom=name
           Shrink region until it meets non-NULL data from this raster map

       align=name
           Adjust region cells to cleanly align with this raster map

       save=name
           Save current region settings in named region file

DESCRIPTION

       The  g.region  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’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.

DEFINITIONS

       Region:
           In GRASS, 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 (cell edges).  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  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.

       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 v.in.region.

       Default Region:
           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 -d flag. The default region is initially set when the location  is  first
           created and can be reset using the -s flag.

       Current Region:
           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.

       Saved Regions:
           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 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 or the ’@’ operator is used (region_name@mapset).

NOTES

       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,  aligning  the
       region to the resolution supplied by the user. The default is to align the region resolution to match the
       region boundaries.

       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.

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

       The  -g  flag prints the current region settings in shell script style.  This format can be given back to
       g.region on its command line.  This may also be  used  to  save  region  settings  as  shell  environment
       variables with the UNIX eval command, "eval `g.region -g`".

   Additional parameter information:
       zoom=name
           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.

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

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 (decimal degrees and degrees with decimal minutes can also 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-NULL data in the map layer soils.  Note that if the parameter raster=soils were
           not specified, the zoom would shrink to encompass all non-NULL data values in the soils map that were
           located within the current region settings.

        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 -up zoom=soils save=soils
           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 soils and stored under the windows  directory  in  the
           user’s current mapset.  The current region settings are not changed.

        g.region b=0 t=3000 tbres=200 res3=100 g.region -p3
           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.

        g.region -p
           This will print the current region in the format:
           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

        g.region -p3
           This will print the current region and the 3D region (used for voxels) in the format:
           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

        g.region -g
           The -g option prints the region in the following script style (key=value) format:
           n=4928000
           s=4914000
           w=590000
           e=609000
           nsres=20
           ewres=20
           rows=700
           cols=950

        g.region -bg
           The -bg option prints the region in the following script style (key=value) format plus  the  boundary
           box in latitude-longitude/WGS84:
           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

        g.region -l
           The -l option prints the region in the following format:
           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]

        g.region -pm
           This will print the current region in the format (latitude-longitude location):
           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 here reported in meters, not decimal degrees.

       Usage example of g.region in a shell with external software:
       Extract  spatial  subset  of  external  vector map ’soils.shp’ to new external vector map ’soils_cut.shp’
       using the OGR ’ogr2ogr’ tool:
       eval `g.region -g`
       ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp
       This requires that the location/SHAPE file projection match.

       Usage example of g.proj and g.region in a shell with external software:
       Extract spatial subset of external raster map ’p016r035_7t20020524_z17_nn30.tif’ to new  external  raster
       map’p016r035_7t20020524_nc_spm_wake_nn30.tif using the GDAL ’gdalwarp’ tool:
       eval `g.region -g`
       gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \
                p016r035_7t20020524_z17_nn30.tif \
                p016r035_7t20020524_nc_spm_wake_nn30.tif
       Here  the  input raster map does not have to match the location projection since it is reprojected on the
       fly.

SEE ALSO

        g.access, g.mapsets, g.proj
       Environment variables: GRASS_REGION and WIND_OVERRIDE

AUTHOR

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

       Last changed: $Date: 2015-02-14 22:08:31 +0100 (Sat, 14 Feb 2015) $

       Main index | General index | Topics index | Keywords index | Full index

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual