t.rast.patch: allow use of virtual format (#751)

* allow patching to virtual raster maps

* formating and v-flag handling

* add note on color table

src/temporal/t.rast.patch/t.rast.patch.html

@@ -1,17 +1,33 @@
 <h2>DESCRIPTION</h2>
-This module patches raster maps that have gaps in time with subsequent maps (within a space time raster dataset)
-using <em>r.patch</em>. Hence it is a wrapper for <em>r.patch</em> in the temporal domain.
+This module patches raster maps that have gaps in time with subsequent maps
+(within a space time raster dataset) using <em>r.patch</em> or <b>r.buildvrt</b>.
+Hence it is a wrapper for those two modules in the temporal domain.
+<p>
+By default <em>r.patch</em> is used to create a patched raster map.
+Especially for temporary data, using <b>r.buildvrt</b> for patching
+can be advantageous with regards to processing time and storage space.
+<b>r.buildvrt</b> creates a virtual raser map and is used when the
+<b>v-flag</b> is given. The <b>v-flag</b> excludes the <b>z-flag</b>
+(using zero (0) for transperancy) and <b>s-flag (do not create color
+and category files)</b>.
+<p>
 The input of this module is a single space time raster dataset, the
 output is a single raster map layer. A subset of the input space time
 raster dataset can be selected using the <b>where</b> option. The
 sorting of the raster map layer can be set using the <b>sort</b>
 option. Be aware that the sorting of the maps significantly influences
 the result of the patch. By default the maps are
 sorted by <b>desc</b> by the <i>start_time</i> so that the newest raster map
-is the first input map in <b>r.patch</b>.
+is the first input map in <b>r.patch</b>/<b>r.buildvrt</b>.
+<p>
+Please note that the color table of the first input raster is used for the
+resulting map when the <b>v-flag</b> is used. Values in the resulting
+raster map that exeed the range of that first raster map will then be
+rendered on the screen like no data. In that case, please update the
+color table or the resulting map with <b>r.colors</b>
 <p>
 <em>t.rast.patch</em> is a simple wrapper for the raster module
-<b>r.patch</b>.
+<b>r.patch</b> or <b>r.buildvrt</b>.
 
 <h2>EXAMPLE</h2>
 The example uses the North Carolina extra time series of MODIS Land Surface Temperature
@@ -24,10 +40,21 @@ <h2>EXAMPLE</h2>
   where="start_time >= '2016-01' and start_time <= '2016-12'"
 r.info LST_Day_patched_2016
 </pre></div>
+<p>
+Patching the MODIS Land Surface Temperature for 2016 (filling missing pixels by
+subsequent maps in the time series) using a virtual mosaic (<b>r.buildvrt</b>):
+<div class="code"><pre>
+t.rast.patch -v input=LST_Day_monthly@modis_lst output=LST_Day_patched_2016_vrt \
+  where="start_time >= '2016-01' and start_time <= '2016-12'"
+# Assign a new color table that covers the entire range of the resulting map
+r.colors map=LST_Day_patched_2016_vrt color=grey
+r.info LST_Day_patched_2016_vrt
+</pre></div>
 
 <h2>SEE ALSO</h2>
 
 <em>
+<a href="https://grass.osgeo.org/grass-stable/manuals/r.buildvrt.html">r.buildvrt</a>,
 <a href="https://grass.osgeo.org/grass-stable/manuals/r.patch.html">r.patch</a>,
 <a href="https://grass.osgeo.org/grass-stable/manuals/t.rast.series.html">t.rast.series</a>,
 <a href="https://grass.osgeo.org/grass-stable/manuals/t.create.html">t.create</a>,

src/temporal/t.rast.patch/t.rast.patch.py

@@ -55,13 +55,21 @@
 # % description: Do not create color and category files
 # %end
 
+# %flag
+# % key: v
+# % description: Patch to virtual raster map (r.buildvrt)
+# %end
+
 # %option
 # % key: sort
 # % description: Sort order (see sort parameter)
 # % options: asc,desc
 # % answer: desc
 # %end
 
+#%rules
+#% excludes: -v,-s,-z
+#%end
 
 import grass.script as grass
 from grass.exceptions import CalledModuleError
@@ -79,6 +87,7 @@ def main():
     add_time = flags["t"]
     patch_s = flags["s"]
     patch_z = flags["z"]
+    patch_module = "r.buildvrt" if flags["v"] else "r.patch"
 
     # Make sure the temporal database exists
     tgis.init()
@@ -109,7 +118,7 @@ def main():
 
         try:
             grass.run_command(
-                "r.patch",
+                patch_module,
                 overwrite=grass.overwrite(),
                 input=(",").join(ordered_rasts),
                 output=output,