GRASS GIS 8 Programmer's Manual  8.5.0dev(2025)-060b32d572
mask_info.c
Go to the documentation of this file.
1 /**
2  * \file lib/raster/mask_info.c
3  *
4  * \brief Raster Library - Get mask information
5  *
6  * (C) 1999-2024 by Vaclav Petras and the GRASS Development Team
7  *
8  * This program is free software under the GNU General Public
9  * License (>=v2). Read the file COPYING that comes with GRASS
10  * for details.
11  *
12  * \author CERL
13  * \author Vaclav Petras, NC State University, Center for Geospatial Analytics
14  */
15 
16 #include <string.h>
17 #include <stdlib.h>
18 
19 #include <grass/gis.h>
20 #include <grass/raster.h>
21 #include <grass/glocale.h>
22 
23 /**
24  * @brief Get a printable text with information about raster mask
25  *
26  * Determines if 2D raster mask is present and returns textual information about
27  * the mask suitable for end-user display. The resulting text is translated.
28  * Caller is responsible for freeing the memory of the returned string.
29  *
30  * @return New string with textual information
31  *
32  * @see Rast_mask_status()
33  */
34 char *Rast_mask_info(void)
35 {
36  char text[GNAME_MAX + GMAPSET_MAX + 16];
37  char name[GNAME_MAX];
38  char mapset[GMAPSET_MAX];
39 
40  switch (Rast__mask_info(name, mapset)) {
41  case 1:
42  sprintf(text, _("<%s> in mapset <%s>"), name, mapset);
43  break;
44  case -1:
45  strcpy(text, _("none"));
46  break;
47  default:
48  strcpy(text, _("not known"));
49  break;
50  }
51 
52  return G_store(text);
53 }
54 
55 /**
56  * @brief Retrieves the name of the raster mask to use.
57  *
58  * The returned raster map name is fully qualified, i.e., in the form
59  * "name@mapset". The mask name is returned whether the mask is present or not.
60  *
61  * This function checks if an environment variable "GRASS_MASK" is set.
62  * If it is set, the value of the environment variable is returned
63  * as the mask name. If it is not set, the function will default to the
64  * mask name "MASK@<mapset>", where <mapset> is the current mapset.
65  *
66  * The memory for the returned mask name is dynamically allocated using
67  * G_store(). It is the caller's responsibility to free the memory with
68  * G_free() when it is no longer needed.
69  *
70  * @returns A dynamically allocated string containing the mask name.
71  */
72 char *Rast_mask_name(void)
73 {
74  // First, see if the environment variable is defined.
75  const char *env_variable = getenv("GRASS_MASK");
76  if (env_variable != NULL && strcmp(env_variable, "") != 0) {
77  // Variable exists and is not empty.
78  // While the function does not document that, the provided mapset
79  // is a fallback, so we don't have to parse the name to find out
80  // ourselves what to do.
81  return G_fully_qualified_name(env_variable, G_mapset());
82  }
83 
84  // Mask name defaults to "MASK@<current mapset>".
85  return G_fully_qualified_name("MASK", G_mapset());
86 }
87 
88 /**
89  * @brief Get name of a mask if it is present
90  *
91  * Unlike, Rast__mask_info() this always returns name of the mask
92  * if it is present regardless of the mask being a reclass or not.
93  *
94  * @param[out] name Name of the raster map used as mask
95  * @param[out] mapset Name of the map's mapset
96  *
97  * @return true if mask is present, false otherwise
98  */
99 static bool Rast__get_present_mask(char *name, char *mapset)
100 {
101  char rname[GNAME_MAX], rmapset[GMAPSET_MAX];
102  char *full_name = Rast_mask_name();
103  if (!G_find_raster2(full_name, ""))
104  return false;
105  G_unqualified_name(full_name, "", rname, rmapset);
106  strncpy(name, rname, GMAPSET_MAX);
107  strncpy(mapset, rmapset, GMAPSET_MAX);
108  G_free(full_name);
109  return true;
110 }
111 
112 /**
113  * @brief Get raster mask status information
114  *
115  * _is_mask_reclass_ is a pointer to a bool variable which
116  * will be set to true if mask raster is a reclass and false otherwise.
117  *
118  * If you are not interested in the underlying reclassified raster map,
119  * pass NULL pointers for the three reclass parameters:
120  *
121  * ```
122  * Rast_mask_status(name, mapset, NULL, NULL, NULL);
123  * ```
124  *
125  * @param[out] name Name of the raster map used as mask
126  * @param[out] mapset Name of the mapset the raster is in
127  * @param[out] is_mask_reclass Will be set to true if mask raster is a reclass
128  * @param[out] reclass_name Name of the underlying reclassified raster map
129  * @param[out] reclass_mapset Name of the mapset the reclassified raster is in
130  *
131  * @return true if mask is present, false otherwise
132  */
133 bool Rast_mask_status(char *name, char *mapset, bool *is_mask_reclass,
134  char *reclass_name, char *reclass_mapset)
135 {
136  bool present = Rast__get_present_mask(name, mapset);
137 
138  if (is_mask_reclass && reclass_name && reclass_mapset) {
139  if (present) {
140  *is_mask_reclass =
141  Rast_is_reclass(name, mapset, reclass_name, reclass_mapset) > 0;
142  }
143  else {
144  *is_mask_reclass = false;
145  }
146  }
147  return present;
148 }
149 
150 /**
151  * @brief Get information about the current mask
152  *
153  * Determines the status of the automatic masking and the name of the 2D
154  * raster which forms the mask. Typically, mask is raster called MASK in the
155  * current mapset, but when used with r.mask, it is usually a reclassed
156  * raster, and so when a mask raster is present and it is a reclass raster,
157  * the name and mapset of the underlying reclassed raster are returned.
158  *
159  * The name and mapset is written to the parameter which need to be defined
160  * with a sufficient size, least as `char name[GNAME_MAX], mapset[GMAPSET_MAX]`.
161  *
162  * When the masking is not active, -1 is returned and name and mapset are
163  * undefined. When the masking is active, 1 is returned and name and mapset
164  * will hold the name and mapset of the underlying raster.
165  *
166  * @param[out] name Name of the raster map used as mask
167  * @param[out] mapset Name of the map's mapset
168  *
169  * @return 1 if mask is present, -1 otherwise
170  *
171  * @see Rast_mask_status(), Rast_mask_name()
172  */
173 int Rast__mask_info(char *name, char *mapset)
174 {
175  char rname[GNAME_MAX], rmapset[GMAPSET_MAX];
176  bool present = Rast__get_present_mask(name, mapset);
177  if (!present)
178  return -1;
179 
180  if (Rast_is_reclass(name, mapset, rname, rmapset) > 0) {
181  strcpy(name, rname);
182  strcpy(mapset, rmapset);
183  }
184  return 1;
185 }
186 
187 /**
188  * @brief Check presence of 2D raster mask
189  *
190  * @return true if mask is present, false otherwise
191  */
193 {
194  char *name = Rast_mask_name();
195  bool present = G_find_raster2(name, "") != NULL;
196  return present;
197 }
#define NULL
Definition: ccmath.h:32
void G_free(void *)
Free allocated memory.
Definition: gis/alloc.c:150
int G_unqualified_name(const char *, const char *, char *, char *)
Returns unqualified map name (without @ mapset)
Definition: nme_in_mps.c:134
const char * G_find_raster2(const char *, const char *)
Find a raster map (look but don't touch)
Definition: find_rast.c:76
const char * G_mapset(void)
Get current mapset name.
Definition: gis/mapset.c:33
char * G_fully_qualified_name(const char *, const char *)
Get fully qualified element name.
Definition: nme_in_mps.c:101
char * G_store(const char *)
Copy string to allocated memory.
Definition: strings.c:87
int Rast_is_reclass(const char *, const char *, char *, char *)
Check if raster map is reclassified.
Definition: reclass.c:43
#define GMAPSET_MAX
Definition: gis.h:192
#define GNAME_MAX
Definition: gis.h:191
#define _(str)
Definition: glocale.h:10
char * Rast_mask_name(void)
Retrieves the name of the raster mask to use.
Definition: mask_info.c:72
bool Rast_mask_status(char *name, char *mapset, bool *is_mask_reclass, char *reclass_name, char *reclass_mapset)
Get raster mask status information.
Definition: mask_info.c:133
char * Rast_mask_info(void)
Get a printable text with information about raster mask.
Definition: mask_info.c:34
int Rast__mask_info(char *name, char *mapset)
Get information about the current mask.
Definition: mask_info.c:173
bool Rast_mask_is_present(void)
Check presence of 2D raster mask.
Definition: mask_info.c:192
const char * name
Definition: named_colr.c:6
#define strcpy
Definition: parson.c:62