Provided by: grass-doc_7.8.2-1build3_all bug

NAME

       r.proj  - Re-projects a raster map from given location to the current location.

KEYWORDS

       raster, projection, transformation, import

SYNOPSIS

       r.proj
       r.proj --help
       r.proj    [-lnpg]    location=name     [mapset=name]      [input=name]     [dbase=path]     [output=name]
       [method=string]   [memory=integer]    [resolution=float]    [pipeline=string]    [--overwrite]   [--help]
       [--verbose]  [--quiet]  [--ui]

   Flags:
       -l
           List raster maps in input mapset and exit

       -n
           Do not perform region cropping optimization

       -p
           Print input map’s bounds in the current projection and exit

       -g
           Print input map’s bounds in the current projection and exit (shell style)

       --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:
       location=name [required]
           Location containing input raster map
           Location name (not location path)

       mapset=name
           Mapset containing input raster map
           Default: name of current mapset

       input=name
           Name of input raster map to re-project

       dbase=path
           Path to GRASS database of input location
           Default: path to the current GRASS GIS database

       output=name
           Name for output raster map (default: same as ’input’)

       method=string
           Interpolation method to use
           Options: nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f
           Default: nearest
           nearest: nearest neighbor
           bilinear: bilinear interpolation
           bicubic: bicubic interpolation
           lanczos: lanczos filter
           bilinear_f: bilinear interpolation with fallback
           bicubic_f: bicubic interpolation with fallback
           lanczos_f: lanczos filter with fallback

       memory=integer
           Maximum memory to be used (in MB)
           Cache size for raster rows
           Default: 300

       resolution=float
           Resolution of output raster map

       pipeline=string
           PROJ pipeline for coordinate transformation

DESCRIPTION

       r.proj  projects  a  raster  map in a specified mapset of a specified location from the projection of the
       input location to a raster map in the current location. The projection  information  is  taken  from  the
       current PROJ_INFO files, as set and viewed with g.proj.

   Introduction
   Map projections
       Map  projections  are  a method of representing information from a curved surface (usually a spheroid) in
       two dimensions, typically to allow indexing through cartesian coordinates.  There are a wide  variety  of
       projections,   with   common   ones   divided  into  a  number  of  classes,  including  cylindrical  and
       pseudo-cylindrical, conic and pseudo-conic, and azimuthal  methods,  each  of  which  may  be  conformal,
       equal-area, or neither.

       The  particular projection chosen depends on the purpose of the project, and the size, shape and location
       of the area of interest.  For example, normal cylindrical projections are good  for  maps  which  are  of
       greater  extent  east-west than north-south and in equatorial regions, while conic projections are better
       in mid-latitudes; transverse cylindrical projections are used  for  maps  which  are  of  greater  extent
       north-south than east-west; azimuthal projections are used for polar regions.  Oblique versions of any of
       these may also be used.  Conformal  projections  preserve  angular  relationships,  and  better  preserve
       arc-length,  while  equal-area projections are more appropriate for statistical studies and work in which
       the amount of material is important.

       Projections are defined by precise mathematical relations, so the method of projecting coordinates from a
       geographic reference frame (latitude-longitude) into a projected cartesian reference frame (eg metres) is
       governed by these equations.  Inverse projections can also be achieved.  The public-domain Unix  software
       package  PROJ.4  [1] has been designed to perform these transformations, and the user’s manual contains a
       detailed description of over 100 useful projections.  This also includes a  programmers  library  of  the
       projection methods to support other software development.

       Thus,  converting a vector map - in which objects are located with arbitrary spatial precision - from one
       projection into another is usually accomplished by a simple two-step process: first the location  of  all
       the   points   in   the   map   are  converted  from  the  source  through  an  inverse  projection  into
       latitude-longitude, and then through a forward projection into the target.  (Of course the procedure will
       be one-step if either the source or target is in geographic coordinates.)

       Converting  a  raster  map,  or  image,  between  different  projections,  however,  involves  additional
       considerations.  A raster may be considered to represent a sampling of a process at  a  regular,  ordered
       set  of  locations.   The  set  of  locations  that  lie  at the intersections of a cartesian grid in one
       projection will not, in general, coincide with the  sample  points  in  another  projection.   Thus,  the
       conversion  of  raster  maps involves an interpolation step in which the values of points at intermediate
       locations relative to the source grid are estimated.

   Projecting vector maps within the GRASS GIS
       GIS data capture, import and transfer often requires a projection step, since the source or  client  will
       frequently be in a different projection to the working projection.

       In some cases it is convenient to do the conversion outside the package, prior to import or after export,
       using software such as PROJ.4’s cs2cs [1]. This is an easy method for converting an ASCII file containing
       a  list of coordinate points, since there is no topology to be preserved and cs2cs can be used to process
       simple lists using a one-line command. The m.proj module provides a handy front end to cs2cs.

       Vector maps is generally more complex, as parts of the data stored in the files will  describe  topology,
       and  not  just  coordinates.  In  GRASS  GIS  the  v.proj  module  is  provided to reproject vector maps,
       transferring topology and attributes as well as node  coordinates.   This  program  uses  the  projection
       definition  and parameters which are stored in the PROJ_INFO and PROJ_UNITS files in the PERMANENT mapset
       directory for every GRASS location.

   Design of r.proj
       As discussed briefly above, the fundamental step in re-projecting a raster is resampling the source  grid
       at  locations  corresponding to the intersections of a grid in the target projection. The basic procedure
       for accomplishing this, therefore, is as follows:

       r.proj converts a map to a new geographic projection. It reads a map from a different location,  projects
       it  and  write it out to the current location. The projected data is resampled with one of four different
       methods: nearest neighbor, bilinear, bicubic iterpolation or lanczos.

       The method=nearest method, which performs a nearest neighbor assignment, is  the  fastest  of  the  three
       resampling methods. It is primarily used for categorical data such as a land use classification, since it
       will not change the values of the data cells. The method=bilinear method determines the new value of  the
       cell based on a weighted distance average of the 4 surrounding cells in the input map. The method=bicubic
       method determines the new value of the cell based on a weighted distance average of  the  16  surrounding
       cells  in  the  input  map.  The  method=lanzcos  method  determines the new value of the cell based on a
       weighted distance average of the 25 surrounding cells in the input map. Compared to bicubic, lanczos puts
       a  higher weight on cells close to the center and a lower weight on cells away from the center, resulting
       in slightly better contrast.

       The bilinear, bicubic and lanczos interpolation methods are most  appropriate  for  continuous  data  and
       cause  some  smoothing.  The  amount  of  smoothing  decreases from bilinear to bicubic to lanczos. These
       options should not be used with categorical data, since the cell values will be altered.

       In the bilinear, bicubic and lanczos methods, if any of the surrounding cells used to interpolate the new
       cell  value  are  null,  the resulting cell will be null, even if the nearest cell is not null. This will
       cause some thinning along null borders, such as the coasts of  land  areas  in  a  DEM.  The  bilinear_f,
       bicubic_f  and  lanczos_f  interpolation methods can be used if thinning along null edges is not desired.
       These methods "fall back" to simpler interpolation methods along null borders.  That is, from lanczos  to
       bicubic to bilinear to nearest.

       If  nearest  neighbor  assignment is used, the output map has the same raster format as the input map. If
       any of the interpolations is used, the output map is written as floating point.

       Note that, following normal GRASS conventions, the coverage and resolution of the resulting grid  is  set
       by  the  current  region  settings,  which  may  be  adjusted  using  g.region. The target raster will be
       relatively unbiased for all cases if its grid has a  similar  resolution  to  the  source,  so  that  the
       resampling/interpolation  step  is  only  a local operation.  If the resolution is changed significantly,
       then the behaviour of the generalisation or refinement will depend on the  model  of  the  process  being
       represented.  This will be very different for categorical versus numerical data.  Note that three methods
       for the local interpolation step are provided.

       r.proj supports general datum transformations, making use of the PROJ.4  co-ordinate  system  translation
       library.

NOTES

       If output is not specified it is set to be the same as input map name.
       If mapset is not specified, its name is assumed to be the same as the current mapset’s name.
       If dbase is not specified it is assumed to be the current database. The user only has to specify dbase if
       the source location is stored in another separate GRASS database.

       To avoid excessive time consumption when reprojecting a map the  region  and  resolution  of  the  target
       location should be set appropriately beforehand.

       A  simple  way  to  do  this  is to check the projected bounds of the input map in the current location’s
       projection using the -p flag. The -g flag reports the same thing, but in a form which can be directly cut
       and  pasted  into  a  g.region  command.  After  setting  the region in that way you might check the cell
       resolution with "g.region -p" then snap it to a regular grid with g.region’s -a flag. E.g.   g.region  -a
       res=5 -p. Note that this is just a rough guide.

       A more involved, but more accurate, way to do this is to generate a vector "box" map of the region in the
       source location using v.in.region -d.  This "box" map is then reprojected into the target  location  with
       v.proj.  Next  the region in the target location is set to the extent of the new vector map with g.region
       along with the desired raster resolution (g.region -m can be  used  in  Latitude/Longitude  locations  to
       measure  the  geodetic  length  of  a  pixel).   r.proj  is then run for the raster map the user wants to
       reproject.  In this case a little preparation goes a long way.

       When reprojecting whole-world maps the user should disable map-trimming with the -n flag. Trimming is not
       useful  here  because the module has the whole map in memory anyway. Besides that, world "edges" are hard
       (or impossible) to find in projections other than latitude-longitude so results may be odd with trimming.

EXAMPLES

   Inline method
       With GRASS running in the destination location use the -g flag  to  show  the  input  map’s  bounds  once
       projected  into  the current working projection, then use that to set the region bounds before performing
       the reprojection:
       # calculate where output map will be
       r.proj input=elevation location=ll_wgs84 mapset=user1 -p
       Source cols: 8162
       Source rows: 12277
       Local north: -4265502.30382993
       Local south: -4473453.15255565
       Local west: 14271663.19157564
       Local east: 14409956.2693866
       # same calculation, but in a form which can be cut and pasted into a g.region call
       r.proj input=elevation location=ll_wgs84 mapset=user1 -g
       n=-4265502.30382993 s=-4473453.15255565 w=14271663.19157564 e=14409956.2693866 rows=12277 cols=8162
       g.region n=-4265502.30382993 s=-4473453.15255565 \
         w=14271663.19157564 e=14409956.2693866 rows=12277 cols=8162 -p
       projection: 99 (Mercator)
       zone:       0
       datum:      wgs84
       ellipsoid:  wgs84
       north:      -4265502.30382993
       south:      -4473453.15255565
       west:       14271663.19157564
       east:       14409956.2693866
       nsres:      16.93824621
       ewres:      16.94352828
       rows:       12277
       cols:       8162
       cells:      100204874
       # round resolution to something cleaner
       g.region res=17 -a -p
       projection: 99 (Mercator)
       zone:       0
       datum:      wgs84
       ellipsoid:  wgs84
       north:      -4265487
       south:      -4473465
       west:       14271653
       east:       14409965
       nsres:      17
       ewres:      17
       rows:       12234
       cols:       8136
       cells:      99535824
       # finally, perform the reprojection
       r.proj input=elevation location=ll_wgs84 mapset=user1 memory=800

   v.in.region method
       # In the source location, use v.in.region to generate a bounding box around the
       # region of interest:
       v.in.region -d output=bounds type=area
       # Now switch to the target location and import the vector bounding box
       # (you can run v.proj -l to get a list of vector maps in the source location):
       v.proj input=bounds location=source_location_name output=bounds_reprojected
       # Set the region in the target location with that of the newly-imported vector
       # bounds map, and align the resolution to the desired cell resolution of the
       # final, reprojected raster map:
       g.region vector=bounds_reprojected res=5 -a
       # Now reproject the raster into the target location
       r.proj input=elevation.dem output=elevation.dem.reproj \
       location=source_location_name mapset=PERMANENT res=5 method=bicubic

REFERENCES

       1      Evenden, G.I.  (1990) Cartographic projection procedures for  the  UNIX  environment  -  a  user’s
              manual.   USGS  Open-File  Report  90-284  (OF90-284.pdf)  See  also there: Interim Report and 2nd
              Interim Report on Release 4, Evenden 1994).

       2      Richards, John A. (1993), Remote Sensing Digital  Image  Analysis,  Springer-Verlag,  Berlin,  2nd
              edition.

       PROJ 4: Projection/datum support library.

       Further reading

           •   ASPRS Grids and Datum

           •   Projections Transform List (PROJ.4)

           •   MapRef - The Collection of Map Projections and Reference Systems for Europe

           •   Information and Service System for European Coordinate Reference Systems - CRS

           •   Cartographical Map Projections by Carlos A. Furuti

SEE ALSO

        g.region, g.proj, i.rectify, m.proj, r.support, r.stats, v.proj, v.in.region

       The ’gdalwarp’ and ’gdal_translate’ utilities are available from the GDAL project.

AUTHORS

       Martin Schroeder, University of Heidelberg, Germany
       Man page text from S.J.D. Cox, AGCRC, CSIRO Exploration & Mining, Nedlands, WA
       Updated by Morten Hulden
       Datum transformation support and cleanup by Paul Kelly

SOURCE CODE

       Available at: r.proj source code (history)

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual