[news] r.out.gdal: add offset/scale options (#1992)

* Apply suggestions from code review

Co-authored-by: Markus Metz <33666869+metzm@users.noreply.github.com>

raster/r.out.gdal/export_band.c

@@ -215,7 +215,8 @@ int export_band(GDALDatasetH hMEMDS, int band,
 		const char *name, const char *mapset,
 		struct Cell_head *cellhead, RASTER_MAP_TYPE maptype,
 		double nodataval, int suppress_main_colortable, 
-		int no_metadata, int writenodata)
+		int no_metadata, int writenodata,
+                double offsetval, double scaleval)
 {
     struct Colors sGrassColors;
     GDALColorTableH hCT;
@@ -355,6 +356,16 @@ int export_band(GDALDatasetH hMEMDS, int band,
 		GDALSetMetadataItem(hBand, key, value, NULL);
 	    }
 	}
+
+        /* apply offset factor if not 0 (zero) */
+        if (offsetval) {
+            GDALSetRasterOffset(hBand, offsetval);
+        }
+
+        /* apply scale factor if not 1 */
+        if (scaleval != 1) {
+            GDALSetRasterScale(hBand, scaleval);
+        }
     }
 
     /* Create GRASS raster buffer */

raster/r.out.gdal/local_proto.h

@@ -60,7 +60,7 @@
 /* export_band.c */
 int export_band(GDALDatasetH, int, const char *, 
 		const char *, struct Cell_head *, RASTER_MAP_TYPE, 
-		double, int, int, int);
+		double, int, int, int, double, double);
 int exact_checks(GDALDataType, const char *, const char *,
                  struct Cell_head *, RASTER_MAP_TYPE, double,
 		 const char *, int);

raster/r.out.gdal/main.c

@@ -118,7 +118,7 @@ int main(int argc, char *argv[])
     struct GModule *module;
     struct Flag *flag_l, *flag_c, *flag_m, *flag_f, *flag_t;
     struct Option *input, *format, *type, *output, *createopt, *metaopt,
-	          *nodataopt, *overviewopt;
+        *nodataopt, *overviewopt, *offsetopt, *scaleopt;
 
     struct Cell_head cellhead;
     struct Ref ref;
@@ -251,6 +251,24 @@ int main(int argc, char *argv[])
     overviewopt->required = NO;
     overviewopt->guisection = _("Creation");
 
+    offsetopt = G_define_option();
+    offsetopt->key = "offset";
+    offsetopt->type = TYPE_DOUBLE;
+    offsetopt->description =
+	_("Assign a specified offset value to output bands");
+    offsetopt->multiple = NO;
+    offsetopt->required = NO;
+    offsetopt->guisection = _("Creation");
+
+    scaleopt = G_define_option();
+    scaleopt->key = "scale";
+    scaleopt->type = TYPE_DOUBLE;
+    scaleopt->description =
+	_("Assign a specified scale value to output bands");
+    scaleopt->multiple = NO;
+    scaleopt->required = NO;
+    scaleopt->guisection = _("Creation");
+
     if (G_parser(argc, argv))
 	exit(EXIT_FAILURE);
 
@@ -586,6 +604,18 @@ int main(int argc, char *argv[])
 	    set_default_nodata_value(datatype, export_min, export_max);
     }
 
+    /* Offset value */
+    double offsetval = 0; /* not defined */
+    if (offsetopt->answer != NULL) {
+        offsetval = atof(offsetopt->answer);
+    }
+
+    /* Scale value */
+    double scaleval = 1; /* not defined */
+    if (scaleopt->answer != NULL) {
+        scaleval = atof(scaleopt->answer);
+    }
+
     /* exact range and nodata checks for each band */
     G_message(_("Checking GDAL data type and nodata value..."));
     for (band = 0; band < ref.nfiles; band++) {
@@ -707,7 +737,8 @@ int main(int argc, char *argv[])
 	retval = export_band
 	    (hCurrDS, band + 1, ref.file[band].name,
 	     ref.file[band].mapset, &cellhead, maptype, nodataval,
-	     flag_c->answer, flag_m->answer, (nodataopt->answer != NULL));
+	     flag_c->answer, flag_m->answer, (nodataopt->answer != NULL),
+             offsetval, scaleval);
 
 	/* read/write error */
 	if (retval == -1) {

raster/r.out.gdal/r.out.gdal.html

@@ -180,6 +180,10 @@ Cloud Optimized GeoTIFFs (COG) can be created with the creation options
 <em>gdaladdo</em> to build overviews.
 -->
 
+<h3>Offset/scale parameters</h3>
+
+Offset is only relevant if not zero. Scale is only relevant if not 1.
+
 <h2>EXAMPLES</h2>
 
 <h3>Export the integer raster basin_50K map to GeoTIFF format</h3>
@@ -323,6 +327,34 @@ g.region raster=elevation -p
 r.out.gdal input=elevation output=elelevation.img format=HFA type=Float32
 </pre></div>
 
+<h3>Export raster map with offset/scale assigned</h3>
+
+An offset value can be assigned to output raster data by <b>offset</b>
+parameter. Similarly a scale value can be assigned by <b>scale</b>
+parameter.
+
+<div class="code"><pre>
+# produce raster map
+g.region n=100 s=0 e=100 w=0 res=1
+r.random.cells output=random distance=1.0
+r.info -r random
+
+# export raster data with offset/scale assigned
+r.out.gdal input=random output=random.tif offset=100 scale=0.01
+</pre></div>
+
+Check result by <em>gdalinfo</em> command line tool:
+
+<div class="code"><pre>
+gdalinfo random.tif
+...
+Band 1 Block=100x40 Type=UInt16, ColorInterp=Palette
+  Description = random
+    Computed Min/Max=1.000,3661.000
+  NoData Value=65535
+  Offset: 100,   Scale:0.01
+...
+</pre></div>
 
 <h2>GDAL RELATED ERROR MESSAGES</h2>