library: Add imagery Python library module to grass.script

python/grass/script/imagery.py

@@ -26,49 +26,45 @@
 
 def group_to_dict(
     imagery_group_name,
-    dict_key="semantic_label",
-    full_info=True,
     subgroup=None,
+    dict_key="semantic_labels",
+    fill_semantic_label=True,
+    full_info=True,
     env=None,
 ):
-    """Create a dictionary to represent an imagery group, with it`s raster maps
-    and their associated semantic_labels. The dict_key option allows to choose
-    if the semantic_labels should be the keys in the dictionary (the default)
-    or the map IDs (full map names). The function can also operate on the level
-    of subgroups.
-    For raster maps in the imagery (sub-)group that do not have a semantic label
-    a warning is given.
-    If the imagery group is not found, an error message is printed and an empty
-    dictionary is returned. In case of non-existing subgroups no error message
-    is printed and an empty dictionary is returned.
+    """Create a dictionary to represent an imagery group with metadata.
+
+    Defined by the dict_key option, the dictionary uses either the names
+    of the raster maps ("map_names"), their row indices in the group
+    ("indices") or their associated semantic_labels ("semantic_labels") as keys.
+    The default is to use semantic_labels as keys. Note that map metadata
+    of the maps in the group have to be read to get the semantic label,
+    in addition to the group file. The same metadata is read when the
+    "full_info" should be returned.
+
+    The function can also operate on the level of subgroups. In case a
+    non-existing (or empty sub-group) is requested a warning is printed
+    and an empty dictionary is returned (following the behavior of i.group).
 
     Example:
 
     >>> run_command("g.copy", raster="lsat7_2000_10,lsat7_2000_10")
-    0
     >>> run_command("r.support", raster="lsat7_2000_10", semantic_label="L8_1")
-    0
     >>> run_command("g.copy", raster="lsat7_2000_20,lsat7_2000_20")
-    0
     >>> run_command("r.support", raster="lsat7_2000_20", semantic_label="L8_2")
-    0
     >>> run_command("g.copy", raster="lsat7_2000_30,lsat7_2000_30")
-    0
     >>> run_command("r.support", raster="lsat7_2000_30", semantic_label="L8_3")
-    0
     >>> run_command("i.group", group="L8_group",
     >>>             input="lsat7_2000_10,lsat7_2000_20,lsat7_2000_30")
-    0
     >>> group_to_dict("L8_group", full_info=False)  # doctest: +ELLIPSIS
     {"L8_1": "lsat7_2000_10", ... "L8_3": "lsat7_2000_30"}
     >>> run_command("g.remove", flags="f", type="group", name="L8_group")
-    0
     >>> run_command("g.remove", flags="f", type="raster",
     >>>             name="lsat7_2000_10,lsat7_2000_20,lsat7_2000_30")
-    0
 
     :param str table: imagery_group_name: Name of the imagery group to process (or None)
-    :param str dict_key: What to use as key for dictionary "semantic_labels" or map ids
+    :param str dict_key: What to use as key for dictionary. Can bei either
+                         "semantic_labels" (default), "map_names" or "indices"
     :param env: environment
 
     :return: dictionary with maps and their semantic labels (or row indices in the
@@ -89,22 +85,37 @@ def group_to_dict(
             .strip()
             .split()
         )
-    except CalledModuleError:
-        return group_dict
+    except CalledModuleError as cme:
+        raise cme
 
-    for idx, raster_map in enumerate(maps_in_group):
-        raster_map_info = raster_info(raster_map, env=env)
-        semantic_label = raster_map_info["semantic_label"]
-        if not raster_map_info["semantic_label"]:
-            warning(
-                _(
-                    "Raster map {rm} in group {igroup} does not have a semantic label."
-                    "Using the numeric row index in the (sub-) group"
-                ).format(rm=raster_map, igroup=imagery_group_name)
+    if subgroup and not maps_in_group:
+        warning(
+            _("Empty result returned for subgroup <{sg}> in group <{g}>").format(
+                sg=subgroup, g=imagery_group_name
             )
-            semantic_label = idx + 1
-        if dict_key == "semantic_label":
-            group_dict[semantic_label] = raster_map_info if full_info else raster_map
-        else:
-            group_dict[raster_map] = raster_map_info if full_info else semantic_label
+        )
+
+    for idx, raster_map in enumerate(maps_in_group):
+        raster_map_info = None
+        if full_info or dict_key == "semantic_labels":
+            raster_map_info = raster_info(raster_map, env=env)
+
+        if dict_key == "indices":
+            key = str(idx + 1)
+            val = raster_map_info or raster_map
+        elif dict_key == "map_names":
+            key = raster_map
+            val = raster_map_info or str(idx + 1)
+        elif dict_key == "semantic_labels":
+            key = raster_map_info["semantic_label"]
+            if not key or key == '"none"':
+                warning(
+                    _(
+                        "Raster map {m} in group <{g}> does not have a semantic label."
+                    ).format(m=raster_map, g=imagery_group_name)
+                )
+                if fill_semantic_label:
+                    key = str(idx + 1)
+            val = raster_map_info if full_info else raster_map
+        group_dict[key] = val
     return group_dict