From 116d4ba7946d7d7c37e567d62d1489103d8a2135 Mon Sep 17 00:00:00 2001
From: Paul Garlick <pgarlick@tourbillion-technology.com>
Date: Mon, 13 Jul 2020 13:32:10 +0100
Subject: doc: Add Invoking slope.py section.

* doc/fullswof-utils.texi (Usage): Add section.
---
 doc/fullswof-utils.texi | 66 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 64 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/fullswof-utils.texi b/doc/fullswof-utils.texi
index d32d646..d2412c9 100644
--- a/doc/fullswof-utils.texi
+++ b/doc/fullswof-utils.texi
@@ -147,6 +147,7 @@ ln -s /path/to/installation/directory/python/makeBoundary
 @menu
 * Runtime Dependencies::
 * Invoking makeBoundary::
+* Invoking slope.py::
 @end menu
 
 
@@ -299,11 +300,71 @@ Manning's n coefficients (comma-separated list, ordered by panel index)
 number of height intervals
 @end table
 
-
-
 Comment lines are allowed in the boundary definition file.  Lines that
 start with the @samp{#} character are treated as comments.
 
+@node Invoking slope.py, Demos, Boundary Definition File, Usage
+@comment  node-name,  next,  previous,  up
+@section Invoking slope.py
+
+@command{slope.py} is an interactive program that is able to derive
+local gradient information from elevation data and user input.  To start
+the program the command is:
+
+@example
+./slope.py
+@end example
+
+The program responds with a request for user input:
+
+@example
+Locate markers (m), plot channel profile (p), save profile (s) or exit (q):
+@end example
+
+The derivation of the local gradient is a two-stage process.  Firstly, a
+series of markers are placed on opposite sides of the feature of
+interest.  For example, for a channel feature, markers are placed along
+the channel on either side.  Secondly, a best-fit curve is fitted to the
+data.  A plot is displayed and the gradient printed to standard output.
+Optionally, the one-dimensional elevation data may be saved to an output
+file.
+
+A detailed description of the options follows:
+
+@table @samp
+@item m
+Locate markers.  @command{slope.py} opens a window that displays a
+contour plot of the elevation data on the left hand side and a contour
+plot of the derived slope on the right hand side.  The axes are labeled
+by cell index number.  A legend to the side of each plot shows the range
+of contour values.
+
+The user is required to identify marker locations by positioning the
+mouse pointer within the elevation plot and pressing the @key{SPACE}
+key.  The markers are entered in pairs, one on either side of the
+feature of interest.  To finish the sequence of marker pairs, the user
+is required to move the mouse pointer to a position outside the
+elevation plot and press the @kbd{q} key.
+
+@item p
+Plot channel profile.  @command{slope.py} constructs a straight line
+between each pair of markers and calculates the location of the minimum
+elevation value along each line.  These locations form a channel
+``centre-line''.  @command{slope.py} then uses a best-fit procedure to
+plot a straight line through the centre-line elevation data.  A new
+window opens to show the centre-line data and the best-fit line.  The
+gradient and intercept of the best-fit line are printed to standard
+output.
+
+@item s
+Save profile.  The channel centre-line data is written to the file
+@file{1D.txt}.  The file is formatted in the @emph{FullSWOF} @emph{xyz}
+format.
+
+@item q
+Quit @command{slope.py}.
+@end table
+
 @node Demos, GNU Free Documentation License, Boundary Definition File, Top
 @comment  node-name,  next,  previous,  up
 @chapter Demos
@@ -335,5 +396,6 @@ already exists.
 
 Local Variables:
 mode: texinfo
+eval: (outline-minor-mode)
 TeX-master: t
 End:
-- 
cgit