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