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

FreeBSD Manual Pages

  
 
  

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

NAME
       r.patch	- Creates a composite raster map layer by using	known category
       values from one (or more) map layer(s) to fill in areas of "no data" in
       another map layer.

KEYWORDS
       raster, geometry, mosaicking, merge, patching, aggregation, series

SYNOPSIS
       r.patch
       r.patch --help
       r.patch	  [-zs]	  input=name[,name,...]	  output=name	 [--overwrite]
       [--help]	 [--verbose]  [--quiet]	 [--ui]

   Flags:
       -z
	   Use zero (0)	for transparency instead of NULL

       -s
	   Do not create color and category files

       --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:
       input=name[,name,...]A [required]
	   Name	of raster maps to be patched together

       output=nameA [required]
	   Name	for resultant raster map

DESCRIPTION
       The GRASS program r.patch allows	the user to build a new	raster map the
       size  and resolution of the current region by assigning known data val-
       ues from	input raster maps to the cells in this region.
       In case of overlapping input raster maps	this is	done by	filling	in "no
       data" cells, those that do not yet contain data,	contain	NULL data, or,
       optionally contain 0 data, with the data	 from  the  first  input  map.
       Once  this  is done the remaining holes are filled in by	the next input
       map, and	so on.
       In case of adjacent input raster	maps the output	map contains  the  map
       mosaic.

       Hence this command is useful for

	   o   making  a  composite raster map layer from two or more adjacent
	       map layers,

	   o   for filling in "holes" in a raster map layer's data  (e.g.,  in
	       digital elevation data),	or

	   o   for updating an older map layer with more recent	data.
       The  current  geographic	 region	 definition  and mask settings are re-
       spected.

       Figure: Result of patching of two raster	maps  containing  NULLs	 using
       the default settings.

   Stacking order
       The  first  name	 listed	 in the	string input=name,name,name,...	is the
       name of the first map whose data	values will be used to fill  in	 cells
       in  the	current	 region.  Then,	the second through the last input maps
       (..., name, name, ...) will be used, in order, to  supply  data	values
       for the remaining "no data" cells (or cells with	value 0	with -z	flag).

       In  other  words, the first raster map is used first and	if it had some
       "no data" cells,	then second raster map is used for these  cells,  then
       the  third  and	so  on.	 So the	formal command line syntax can be also
       written as input=primary,secondary,tertiary,...	For two	 raster	 maps,
       the  first  one can be viewed as	the primary one	or the default one and
       the second one as the secondary one or a	fallback.

       Figure: Result of patching of two raster	maps  using  the  -z  flag  to
       treat  zeros  as	NULLs. Note the	value 1	being preserved	from the first
       raster while the	value 6	is taken from the second raster	instead	of the
       value  0	 from  the first raster	because	zeros are replaced with	the -z
       flag active.

   Relation to SQL COALESCE() function
       The module is corresponds to the	SQL COALESCE() function.   This	 func-
       tion  takes  two	 or  more  arguments  and  returns a copy of its first
       non-NULL	argument. If all arguments  are	 NULL,	the  function  returns
       NULL.

       The  r.patch  module  iterates  over all	cells and for each cell	of the
       output raster map uses the first	corresponding non-NULL cell in the se-
       ries of the input raster	maps.

   Example of filling areas
       Below,  the raster map layer on the far left is patched with the	middle
       (patching) raster map layer, to produce the composite raster map	 layer
       on  the	right.	The example assumes zero values	to be treated as NULLs
       (-z flag).
	 1 1 1 0 2 2 0 0    0 0	1 1 0 0	0 0    1 1 1 1 2 2 0 0
	 1 1 0 2 2 2 0 0    0 0	1 1 0 0	0 0    1 1 1 2 2 2 0 0
	 3 3 3 3 2 2 0 0    0 0	0 0 0 0	0 0    3 3 3 3 2 2 0 0
	 3 3 3 3 0 0 0 0    4 4	4 4 4 4	4 4    3 3 3 3 4 4 4 4
	 3 3 3 0 0 0 0 0    4 4	4 4 4 4	4 4    3 3 3 4 4 4 4 4
	 0 0 0 0 0 0 0 0    4 4	4 4 4 4	4 4    4 4 4 4 4 4 4 4
       Switching the patched and the patching raster map layers	 produces  the
       following results:
	 0 0 1 1 0 0 0 0    1 1	1 0 2 2	0 0    1 1 1 1 2 2 0 0
	 0 0 1 1 0 0 0 0    1 1	0 2 2 2	0 0    1 1 1 1 2 2 0 0
	 0 0 0 0 0 0 0 0    3 3	3 3 2 2	0 0    3 3 3 3 2 2 0 0
	 4 4 4 4 4 4 4 4    3 3	3 3 0 0	0 0    4 4 4 4 4 4 4 4
	 4 4 4 4 4 4 4 4    3 3	3 0 0 0	0 0    4 4 4 4 4 4 4 4
	 4 4 4 4 4 4 4 4    0 0	0 0 0 0	0 0    4 4 4 4 4 4 4 4

NOTES
       Frequently,  this program is used to patch together adjacent map	layers
       which have been digitized separately.  The program v.mkgrid can be used
       to make adjacent	maps align neatly.

       The  user  should  check	 the current geographic	region settings	before
       running r.patch,	to ensure that the region boundaries encompass all  of
       the data	desired	to be included in the composite	map and	to ensure that
       the region resolution is	the resolution of the desired data. To set the
       geographic  region settings to one or several raster maps, the g.region
       program can be used:
       g.region	raster=map1[,map2[,...]]

       Use of r.patch is generally followed by use of the GRASS	programs g.re-
       move and	g.rename; g.remove is used to remove the original (un-patched)
       raster map layers, while	 g.rename  is  used  to	 then  assign  to  the
       newly-created  composite	 (patched)  raster  map	 layer the name	of the
       original	raster map layer.

       r.patch reads the existing category label files and color  tables  from
       the  input maps and creates these files for the patched,	composite out-
       put map.	 This can be quite time	consuming for certain maps, especially
       if  there  are  many different category values across the patched maps.
       The -s flag allows disabling the	reading	and creation of	these  support
       files,  meaning that the	output map will	have no	category labels	and no
       explicit	color table.

       Number of raster	maps to	be processed is	given by the limit of the  op-
       erating	system.	 For  example, both the	hard and soft limits are typi-
       cally 1024. The soft limit can be changed  with	e.g.  ulimit  -n  1500
       (UNIX-based  operating  systems)	but not	higher than the	hard limit. If
       it is too low, you can as superuser add an entry	in
       /etc/security/limits.conf
       # <domain>      <type>  <item>	      <value>
       your_username  hard    nofile	      1500
       This would raise	the hard limit to 1500 file. Be	warned that more files
       open  need more RAM. See	also the Wiki page Hints for large raster data
       processing.

       Operating systems usually limit the length of the  command  line	 which
       limits  the number of input raster maps user can	pass to	the module us-
       ing the option input. In	that case, r.series can	 be  used  instead  of
       r.patch.

EXAMPLES
   Example with	three maps
       The  input are three maps called	roads, water and forest. Primarily, we
       want to use the values from roads, then from water and if no other val-
       ues  are	available we want to use forest.  First	we set the computation
       region assuming that the	all three maps fully overlap and have the same
       resolution (so we can safely use	the just the one without further modi-
       fications of the	region).  Then we perform the patching.
       g.region	raster=roads
       r.patch input=roads,water,forest	output=result

   Map mosaic example using Bash syntax
       Create a	list of	maps matching a	pattern, extend	the region to  include
       them  all, and patch them together to create a mosaic. Overlapping maps
       will be used in the order listed.
       MAPS=`g.list type=raster	separator=comma	pat="map_*"`
       g.region	raster=$MAPS -p
       r.patch input=$MAPS output=maps_mosaic

SEE ALSO
	g.region, g.remove, g.rename, r.mapcalc, r.support, r.series, v.mkgrid

       Hints for large raster data processing

AUTHOR
       Michael Shapiro,	U.S. Army Construction Engineering Research Laboratory
       -z flag and performance improvement by Huidae Cho

SOURCE CODE
       Available at: r.patch source code (history)

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

       A(C) 2003-2021 GRASS Development	Team, GRASS GIS	7.8.6 Reference	Manual

GRASS 7.8.6							    r.patch(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLES | SEE ALSO | AUTHOR | SOURCE CODE

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

home | help