Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
r.proj(1)		    GRASS GIS User's Manual		     r.proj(1)

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=memory	in MB]
       [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=nameA [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,	 bicu-
	   bic_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=memory in	MB
	   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 loca-
       tion 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 in-
       dexing through cartesian	coordinates.  There are	a wide variety of pro-
       jections,  with common ones divided into	a number of classes, including
       cylindrical and pseudo-cylindrical, conic  and  pseudo-conic,  and  az-
       imuthal	methods,  each	of which may be	conformal, equal-area, or nei-
       ther.

       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 projec-
       tions preserve angular relationships, and better	 preserve  arc-length,
       while equal-area	projections are	more appropriate for statistical stud-
       ies 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 me-
       tres)  is governed by these equations.  Inverse projections can also be
       achieved.  The public-domain Unix software package PROJ	[1]  has  been
       designed	 to  perform these transformations, and	the user's manual con-
       tains 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 arbi-
       trary  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  projec-
       tion into the target.  (Of course the procedure will be one-step	if ei-
       ther the	source or target is in geographic coordinates.)

       Converting a raster map,	or image, between different projections,  how-
       ever,  involves	additional considerations.  A raster may be considered
       to represent a sampling of a process at a regular, ordered set of loca-
       tions.	The set	of locations that lie at the intersections of a	carte-
       sian 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 pack-
       age, prior to import or after export, using  software  such  as	PROJ's
       cs2cs [1]. This is an easy method for converting	an ASCII file contain-
       ing a list of coordinate	points,	since there is no topology to be  pre-
       served  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,  transfer-
       ring 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  assign-
       ment,  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  dis-
       tance  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, result-
       ing in slightly better contrast.

       The bilinear, bicubic and lanczos interpolation methods are most	appro-
       priate  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 ar-
       eas 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  bor-
       ders.  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 resolu-
       tion 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 oper-
       ation.  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 interpo-
       lation step are provided.

       r.proj supports general datum transformations, making use of  the  PROJ
       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 an-
       other separate GRASS database.

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

       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  resolu-
       tion  (g.region	-m can be used in Latitude/Longitude locations to mea-
       sure 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 prepara-
       tion 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 projec-
       tion, then use that to set the region bounds before performing the  re-
       projection:
       # 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 In-
	      terim Report on Release 4, Evenden 1994).

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

       PROJ: Projection/datum support library

       Further reading

	   o   ASPRS Grids and Datum

	   o   Projections Transform List (PROJ)

	   o   Coordinate operations by	PROJ (projections, conversions,	trans-
	       formations, pipeline operator)

	   o   MapRef -	The Collection of Map Projections and  Reference  Sys-
	       tems for	Europe

	   o   Information  and	 Service System	for European Coordinate	Refer-
	       ence Systems - CRS

	   o   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,  Ned-
       lands, 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

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.5 Reference	Manual

GRASS 7.8.5							     r.proj(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLES | REFERENCES | SEE ALSO | AUTHORS | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=r.proj&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help