r.mask.status: Check mask status through a tool

include/grass/defs/raster.h

@@ -392,6 +392,7 @@ int Rast_option_to_interp_type(const struct Option *);
 
 /* mask_info.c */
 char *Rast_mask_info(void);
+bool Rast_mask_status(char *, char *, bool *, char *, char *);
 int Rast__mask_info(char *, char *);
 
 /* maskfd.c */

lib/init/grass.py

@@ -1728,8 +1728,8 @@
             )
         )
 
+    mask2d_test = 'r.mask.status -t'
     # TODO: have a function and/or module to test this
-    mask2d_test = 'test -f "$MAPSET_PATH/cell/MASK"'
     mask3d_test = 'test -d "$MAPSET_PATH/grid3/RASTER3D_MASK"'
 
     specific_addition = ""

lib/raster/mask_info.c

@@ -1,37 +1,33 @@
-/*
- *************************************************************
- * char * Rast_mask_info ()
+/**
+ * \file lib/raster/mask_info.c
  *
- *   returns a printable text of mask information
+ * \brief Raster Library - Get mask information
  *
- ************************************************************
- * Rast__mask_info (name, mapset)
+ * (C) 1999-2022 by Vaclav Petras and the GRASS Development Team
  *
- *      char name[GNAME_MAX], mapset[GMAPSET_MAX];
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
  *
- * function:
- *   determine the status off the automatic masking
- *   and the name of the cell file which forms the mask
- *
- *   (the mask file is actually MASK in the current mapset,
- *   but is usually a reclassed cell file, and the reclass
- *   name and mapset are returned)
- *
- * returns:
- *   -1   no masking (name, mapset undefined)
- *        name, mapset are undefined
- *
- *    1   mask file present, masking on
- *        name, mapset hold mask file name, mapset
- *
- ***************************************************************/
+ * \author CERL
+ * \author Vaclav Petras, NC State University, Center for Geospatial Analytics
+ */
 
 #include <string.h>
 
 #include <grass/gis.h>
 #include <grass/raster.h>
 #include <grass/glocale.h>
 
+/**
+ * @brief Get a printable text with information about raster mask
+ *
+ * Determines if 2D raster mask is present and returns textual information about
+ * the mask suitable for end-user display. The resulting text is translated.
+ * Caller is responsible for freeing the memory of the returned string.
+ *
+ * @return New string with textual information
+ */
 char *Rast_mask_info(void)
 {
     char text[GNAME_MAX + GMAPSET_MAX + 16];
@@ -53,16 +49,69 @@ char *Rast_mask_info(void)
     return G_store(text);
 }
 
+/**
+ * @brief Get raster mask status information
+ *
+ * @param[out] name Name of the raster map used as mask
+ * @param[out] mapset Mapset name of the map
+ * @param[out] is_mask_reclass True, if MASK raster is a reclass
+ *
+ * @return true if mask is present, false otherwise
+ */
+bool Rast_mask_status(char *name, char *mapset, bool *is_mask_reclass,
+                      char *reclass_name, char *reclass_mapset)
+{
+    int present = Rast__mask_info(name, mapset);
+
+    if (is_mask_reclass && reclass_name && reclass_mapset) {
+        if (present) {
+            *is_mask_reclass = Rast_is_reclass("MASK", G_mapset(), reclass_name,
+                                               reclass_mapset) > 0;
+        }
+        else {
+            *is_mask_reclass = false;
+        }
+    }
+
+    if (present == 1)
+        return true;
+    else
+        return false;
+}
+
+/**
+ * @brief Get information about the current mask
+ *
+ * Determines the status of the automatic masking and the name of the 2D
+ * raster which forms the mask. Typically, mask is raster called MASK in the
+ * current mapset, but when used with r.mask, it is usually a reclassed
+ * raster, and so when a MASK raster is present and it is a reclass raster,
+ * the name and mapset of the underlying reclassed raster are returned.
+ *
+ * The name and mapset is written to the parameter which need to be defined
+ * with a suffient size, least as `char name[GNAME_MAX], mapset[GMAPSET_MAX]`.
+ *
+ * When the masking is not active, -1 is returned and name and mapset are
+ * undefined. When the masking is active, 1 is returned and name and mapset
+ * will hold the name and mapset of the underlying raster.
+ *
+ * @param[out] name Name of the raster map used as mask
+ * @param[out] mapset Mapset name of the map
+ *
+ * @return 1 if mask is present, -1 otherwise
+ */
 int Rast__mask_info(char *name, char *mapset)
 {
     char rname[GNAME_MAX], rmapset[GMAPSET_MAX];
 
-    strcpy(name, "MASK");
-    strcpy(mapset, G_mapset());
+    strcpy(rname, "MASK");
+    strcpy(rmapset, G_mapset());
 
-    if (!G_find_raster(name, mapset))
+    if (!G_find_raster(rname, rmapset))
         return -1;
 
+    strcpy(name, rname);
+    strcpy(mapset, rmapset);
     if (Rast_is_reclass(name, mapset, rname, rmapset) > 0) {
         strcpy(name, rname);
         strcpy(mapset, rmapset);

raster/Makefile

@@ -45,6 +45,7 @@ SUBDIRS = \
 	r.lake \
 	r.li \
 	r.mapcalc \
+	r.mask.status \
 	r.mfilter \
 	r.mode \
 	r.neighbors \

raster/r.mask.status/Makefile

@@ -0,0 +1,10 @@
+MODULE_TOPDIR = ../..
+
+PGM = r.mask.status
+
+LIBES = $(MANAGELIB) $(RASTERLIB) $(GISLIB)
+DEPENDENCIES = $(MANAGEDEP) $(RASTERDEP) $(GISDEP)
+
+include $(MODULE_TOPDIR)/include/Make/Module.make
+
+default: cmd

raster/r.mask.status/main.c

@@ -0,0 +1,168 @@
+/****************************************************************************
+ *
+ * MODULE:       r.mask.status
+ * AUTHORS:      Vaclav Petras
+ * PURPOSE:      Report status of raster mask
+ * COPYRIGHT:    (C) 2022 by Vaclav Petras and the GRASS Development Team
+ *
+ *               This program is free software under the GNU General Public
+ *               License (>=v2). Read the file COPYING that comes with GRASS
+ *               for details.
+ *
+ *****************************************************************************/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <grass/gis.h>
+#include <grass/raster.h>
+#include <grass/glocale.h>
+
+struct Parameters {
+    struct Option *format;
+    struct Flag *like_test;
+};
+
+void parse_parameters(struct Parameters *params, int argc, char **argv)
+{
+    struct GModule *module;
+
+    module = G_define_module();
+    G_add_keyword(_("raster"));
+    G_add_keyword(_("reclassification"));
+    module->label = _("Reclassify raster map based on category values.");
+    module->description =
+        _("Creates a new raster map whose category values are based "
+          "upon a reclassification of the categories in an existing "
+          "raster map.");
+
+    params->format = G_define_option();
+    params->format->key = "format";
+    params->format->type = TYPE_STRING;
+    params->format->required = NO;
+    params->format->answer = "yaml";
+    params->format->options = "yaml,json,bash";
+    params->format->description = _("Format for reporting");
+
+    params->like_test = G_define_flag();
+    params->like_test->key = 't';
+    params->like_test->label =
+        _("Return code 0 when mask present, 1 otherwise");
+    params->like_test->description =
+        _("Behave like the test utility, 0 for true, 1 for false, no output");
+    //flags.like_test->guisection = _("");
+    // suppress_required
+
+    if (G_parser(argc, argv))
+        exit(EXIT_FAILURE);
+}
+
+char *min_json_escape(const char *str)
+{
+    char *tmp1 = G_str_replace(str, "\\", "\\\\");
+    char *tmp2 = G_str_replace(tmp1, "\"", "\\\"");
+
+    G_free(tmp1);
+    return tmp2;
+}
+
+void json_print_name_mapset(const char *name, const char *mapset)
+{
+    // Being paranoid about what is in the name.
+    char *escaped_name = min_json_escape(name);
+    char *escaped_mapset = min_json_escape(mapset);
+
+    printf("\"%s@%s\"", name, mapset);
+    G_free(escaped_name);
+    G_free(escaped_mapset);
+}
+
+int report_status(struct Parameters *params)
+{
+
+    char name[GNAME_MAX];
+    char mapset[GMAPSET_MAX];
+    char reclass_name[GNAME_MAX];
+    char reclass_mapset[GMAPSET_MAX];
+
+    bool is_mask_reclass;
+    bool present =
+        Rast_mask_status(name, mapset, &is_mask_reclass, reclass_name, reclass_mapset);
+    // bool present = Rast_mask_present(name, mapset);  // This would check the map presence rather than the automasking state in the library.
+
+    // printf("%s", Rast_mask_info());
+
+    if (params->like_test->answer) {
+        if (present)
+            return 0;
+        else
+            return 1;
+    }
+    else if (strcmp(params->format->answer, "json") == 0) {
+        printf("{\"present\":");
+        if (present)
+            printf("true");
+        else
+            printf("false");
+        printf(",\n\"full_name\":");
+        if (present)
+            json_print_name_mapset("MASK", G_mapset()); // Too much mask details here, move this to the library.
+        else
+            printf("null");
+        printf(",\n\"is_reclass_of\": ");
+        if (is_mask_reclass)
+            json_print_name_mapset(name, mapset);
+        else
+            printf("null");
+        printf("}\n");
+    }
+    else if (strcmp(params->format->answer, "bash") == 0) {
+        printf("present=");
+        if (present)
+            printf("1"); // Good choice here or not?
+        else
+            printf("0");
+        printf("\nfull_name=");
+        if (present) {
+            json_print_name_mapset(name, mapset);
+        }
+        printf("\n");
+    }
+    else {
+        printf("present: ");
+        if (present)
+            printf("true");
+        else
+            printf("false");
+        printf("\nfull_name: ");
+        if (present)
+            printf("|-\n  MASK@%s", G_mapset()); // MASK or MASK@current_mapset
+        else
+            printf("null");
+        printf("\nis_reclass_of: ");
+        // Using block scalar with |- to avoid need for escaping.
+        if (is_mask_reclass)
+            printf("|-\n  %s@%s", name, mapset);
+        else
+            printf("null");
+        // true if MASK in current mapset and is reclass, false otherwise,
+        // then also outputting mask cats is needed to inform user about the portion of the map
+        // printf("\nmask_reclass: ");
+        // if (is_mask_reclass)
+        //     printf("true");
+        // else
+        //     printf("false");
+        printf("\n");
+    }
+    return EXIT_SUCCESS;
+}
+
+int main(int argc, char **argv)
+{
+    struct Parameters params;
+
+    G_gisinit(argv[0]);
+    parse_parameters(&params, argc, argv);
+    return report_status(&params);
+}

raster/r.mask.status/r.mask.status.html

@@ -0,0 +1,35 @@
+<h2>DESCRIPTION</h2>
+
+<em>r.mask.status</em> reports presence or absence of a raster mask.
+
+<h2>NOTES</h2>
+
+<h2>EXAMPLES</h2>
+
+<h3>Generate JSON output</h3>
+
+<div class="code"><pre>
+r.mask.status format=json
+</pre></div>
+
+<h3>Use as the test utility</h3>
+
+The POSIX <em>test</em> utility uses return code 0 to indicate true
+and 1 to indicate false, so testing existence of a file with <code>test -f</code>
+gives return code 0 when the file exists. <em>r.mask.status</em> can be used
+in the same with the the <b>-t</b> flag:
+
+<div class="code"><pre>
+r.mask.status -t
+</pre></div>
+
+<h2>SEE ALSO</h2>
+
+<em>
+<a href="r.mask.html">r.mask</a>,
+<a href="g.region.html">g.region</a>
+</em>
+
+<h2>AUTHORS</h2>
+
+Vaclav Petras, NC State University, Center for Geospatial Analytics