man: Improve segment library documentation, provide examples

.github/workflows/python-code-quality.yml

@@ -201,6 +201,8 @@ jobs:
       - name: Test compiling example modules
         run: |
           ( cd doc/examples/raster/r.example/ && make )
+          ( cd doc/examples/raster/r.example.segment/ && make )
+          ( cd doc/examples/raster/r.example.segmulti/ && make )
           ( cd doc/examples/vector/v.example/ && make )
 
   python-success:

doc/examples/raster/r.example.segment/Makefile

@@ -0,0 +1,13 @@
+# to use this file, make this relative to GRASS include/ directory
+# or set -DMODULE_TOPDIR=... in make command line
+# or (when everything fails) use absolute path to the GRASS source code
+MODULE_TOPDIR = ../../../..
+
+PGM = r.example.segment
+
+LIBES = $(GISLIB) $(RASTERLIB) $(SEGMENTLIB)
+DEPENDENCIES = $(GISDEP) $(RASTERDEP) $(SEGMENTDEP)
+
+include $(MODULE_TOPDIR)/include/Make/Module.make
+
+default: cmd

doc/examples/raster/r.example.segment/README.md

@@ -0,0 +1,20 @@
+To compile the example simply use `make` (in this directory):
+
+```shell
+make
+```
+
+To run (the asterisks will match your operating system and version
+specific directory and file):
+
+```shell
+../../../../bin.*/grass* --tmp-project XY --exec bash <<EOF
+    g.region res=0.1
+    r.mapcalc -s expression='raster_map_1 = rand(0., 15)'
+    r.example.segment input=raster_map_1 output=raster_map_2
+    r.univar raster_map_1
+    r.univar raster_map_2
+EOF
+```
+
+Both steps assume you have GRASS locally compiled.

doc/examples/raster/r.example.segment/main.c

@@ -0,0 +1,163 @@
+/****************************************************************************
+ *
+ * MODULE:    r.example.segment
+ * AUTHOR(S): Vaclav Petras
+ *
+ * PURPOSE:   Slightly modifies the input data and stores the result
+ *            (Code explains use of Segment Library)
+ *
+ * COPYRIGHT: (C) 2019 by Vaclav Petras 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 <stdlib.h>
+
+#include <grass/gis.h>
+#include <grass/glocale.h>
+#include <grass/raster.h>
+#include <grass/segment.h>
+
+/* function declaration */
+static void process(SEGMENT *raster_seg);
+
+/* main function driving the execution */
+int main(int argc, char *argv[])
+{
+    /* input and output raster names and file descriptors */
+    char *input_name;
+    char *output_name;
+    int input_fd;
+    int output_fd;
+
+    /* buffer for reading and writing rasters */
+    void *buffer;
+
+    /* type we use for reading, processing, and writing */
+    RASTER_MAP_TYPE map_type;
+
+    /* variables for current and maximum rows and columns */
+    int nrows, ncols;
+    int row;
+
+    /* history structure holds meta-data (title, comments,..) */
+    struct History history;
+
+    /* options and description */
+    struct GModule *module;
+    struct Option *input;
+    struct Option *output;
+
+    /* initialize GRASS GIS library */
+    G_gisinit(argv[0]);
+
+    /* initialize module and its description */
+    module = G_define_module();
+    G_add_keyword(_("raster"));
+    G_add_keyword(_("example"));
+    G_add_keyword(_("segment library"));
+    G_add_keyword(_("random access"));
+    module->description =
+        _("Random access to raster using the Segment Library");
+
+    /* define parameters */
+    input = G_define_standard_option(G_OPT_R_INPUT);
+    output = G_define_standard_option(G_OPT_R_OUTPUT);
+
+    /* options and flags parser */
+    if (G_parser(argc, argv))
+        exit(EXIT_FAILURE);
+
+    /* stores options and flags to variables */
+    input_name = input->answer;
+    output_name = output->answer;
+
+    /* we process the raster as doubles (DCELL) regardless of the input
+     * map type; the reading function converts the values accordingly */
+    map_type = DCELL_TYPE;
+    size_t cell_size = Rast_cell_size(map_type);
+
+    /* open existing raster map for reading */
+    input_fd = Rast_open_old(input_name, "");
+
+    /* open the raster for writing (checks if it possible) */
+    output_fd = Rast_open_new(output_name, map_type);
+
+    /* allocate input buffer */
+    buffer = Rast_allocate_buf(map_type);
+
+    nrows = Rast_window_rows();
+    ncols = Rast_window_cols();
+
+    /* size of a segment */
+    int srows = 64;
+    int scols = 64;
+
+    /* number of segments in memory */
+    int num_seg = 4;
+
+    /* segment structure */
+    SEGMENT raster_seg;
+
+    /* initialize the segment structures */
+    if (Segment_open(&raster_seg, G_tempfile(), nrows, ncols, srows, scols,
+                     cell_size, num_seg) != 1)
+        G_fatal_error(_("Unable to create temporary segment file"));
+
+    /* load data into the segment structures */
+    for (row = 0; row < Rast_window_rows(); row++) {
+        Rast_get_row(input_fd, buffer, row, map_type);
+        if (Segment_put_row(&raster_seg, buffer, row) < 1)
+            G_fatal_error(_("Unable to write temporary segment file"));
+    }
+
+    /* run the actual processing */
+    process(&raster_seg);
+
+    /* make sure any pending disk operations take place */
+    Segment_flush(&raster_seg);
+    /* store the data permanently in a raster map */
+    for (row = 0; row < Rast_window_rows(); row++) {
+        Segment_get_row(&raster_seg, buffer, row);
+        Rast_put_row(output_fd, buffer, map_type);
+    }
+
+    /* memory cleanup */
+    G_free(buffer);
+
+    /* closing raster maps and segment structures */
+    Segment_close(&raster_seg);
+    Rast_close(input_fd);
+    Rast_close(output_fd);
+
+    /* add command line incantation to history file */
+    Rast_short_history(output_name, "raster", &history);
+    Rast_command_history(&history);
+    Rast_write_history(output_name, &history);
+
+    exit(EXIT_SUCCESS);
+}
+
+/* This would be the main processing function.
+ * Here we just hardcode a cell to modify.
+ */
+static void process(SEGMENT *raster_seg)
+{
+    /* variable we use to hold the value */
+    DCELL value;
+
+    /* row and column to access */
+    int row = 4;
+    int col = 2;
+
+    /* pass the pointer, get the value */
+    Segment_get(raster_seg, (void *)&value, row, col);
+
+    value = value + 100;
+
+    /* pass the pointer, set the value */
+    Segment_put(raster_seg, (void *)&value, row, col);
+}

doc/examples/raster/r.example.segment/r.example.segment.html

@@ -0,0 +1,35 @@
+<h2>DESCRIPTION</h2>
+
+<em>r.example.segment</em> changes one cell value in a hardcoded location.
+It is meant to demonstrate how to use the Segment Library together with
+GRASS raster maps.
+
+<h2>EXAMPLE</h2>
+
+Create a modified version of the raster map "elevation"
+(North Carolina sample dataset):
+
+<div class="code"><pre>
+g.region raster=elevation
+r.example.segment input=elevation output=modified_elevation
+r.univar elevation
+r.univar modified_elevation
+</pre></div>
+
+<h2>SEE ALSO</h2>
+
+<em>
+<a href="r.example.html">r.example</a>,
+<a href="r.example.segmulti.html">r.example.segmulti</a>,
+<a href="v.example.html">v.example</a>
+</em>
+
+<em>
+<a href="https://grass.osgeo.org/programming8/segmentlib.html">Segment Library</a>
+in the
+<a href="https://grass.osgeo.org/programming8/">GRASS Programmer's Manual</a>
+</em>
+
+<h2>AUTHORS</h2>
+
+Vaclav Petras

doc/examples/raster/r.example.segment/r.example.segment.md

@@ -0,0 +1,32 @@
+## DESCRIPTION
+
+*r.example.segment* changes one cell value in a hardcoded location.
+It is meant to demonstrate how to use the Segment Library together with
+GRASS raster maps.
+
+## EXAMPLE
+
+Create a modified version of the raster map "elevation" (North Carolina
+sample dataset) and inspect the single changed cell:
+
+```sh
+g.region raster=elevation
+r.example.segment input=elevation output=modified_elevation
+r.mapcalc expression='difference = modified_elevation - elevation'
+r.univar difference
+```
+
+The difference is zero everywhere except the one hardcoded cell, where
+the value increased by 100.
+
+## SEE ALSO
+
+*[r.example](r.example.md), [r.example.segmulti](r.example.segmulti.md),
+[v.example](v.example.md)*
+
+*[Segment Library](https://grass.osgeo.org/programming8/segmentlib.html)
+in the [GRASS Programmer's Manual](https://grass.osgeo.org/programming8/)*
+
+## AUTHORS
+
+Vaclav Petras

doc/examples/raster/r.example.segmulti/Makefile

@@ -0,0 +1,13 @@
+# to use this file, make this relative to GRASS include/ directory
+# or set -DMODULE_TOPDIR=... in make command line
+# or (when everything fails) use absolute path to the GRASS source code
+MODULE_TOPDIR = ../../../..
+
+PGM = r.example.segmulti
+
+LIBES = $(GISLIB) $(RASTERLIB) $(SEGMENTLIB)
+DEPENDENCIES = $(GISDEP) $(RASTERDEP) $(SEGMENTDEP)
+
+include $(MODULE_TOPDIR)/include/Make/Module.make
+
+default: cmd

doc/examples/raster/r.example.segmulti/README.md

@@ -0,0 +1,33 @@
+To compile the example simply use `make` (in this directory):
+
+```shell
+make
+```
+
+To run (the asterisks will match your operating system and version
+specific directory and file):
+
+```shell
+../../../../bin.*/grass* --tmp-project XY --exec bash <<EOF
+g.region res=0.1
+r.mapcalc -s expression='raster_1 = rand(0., 15)'
+r.mapcalc -s expression='raster_2 = rand(0., 15)'
+r.mapcalc -s expression='raster_3 = rand(0., 15)'
+r.example.segmulti input=raster_1,raster_2,raster_3 output=raster_out
+r.univar raster_1
+r.univar raster_2
+r.univar raster_3
+r.univar raster_out
+r.info -g raster_out
+r.describe raster_out
+g.gui -f
+EOF
+```
+
+Both steps assume you have GRASS locally compiled.
+
+To precisely time the execution, you can use *perf*:
+
+```shell
+perf stat -r 100 r.example.segmulti ... --overwrite
+```