r.kineros(1)		      Grass User's Manual		  r.kineros(1)



AA GGRRAASSSS PPrrooggrraamm ffoorr DDeetteerrmmiinniinngg tthhee TTooppoollooggyy ooff SSttrreeaamm NNeettwwoorrkkss



	John F. Stamm




       Department of Geological Sciences, Case Western Reserve University,


       Cleveland, OH  44106-7216, email:  jfs5@po.cwru.edu



	IInnttrroodduuccttiioonn



	This  paper  presents  a GRASS (geographical resource analysis support
       system; Shapiro et al., 1992; United States Army  Corps	of  Engineers,
       1993)  program  for  determining  the topology of stream networks.  The
       program inputs raster files generated by the GRASS program _r_._w_a_t_e_r_s_h_e_d.
       Because	it  determines	the  relationships of tributary streams, it is
       called _r_._t_r_i_b_s.	The input files required are:




       _s_t_r_e_a_m:	 a raster map of stream segments; stream segments are labelled
       using integer values greater than or equal to 2,


       _a_c_c_u_m_u_l_a_t_i_o_n:   a  raster map of the number of cells that drain through
       each cell; absolute values is the  amount  of  overland	flow  that  is
       routed through a pixel,


       _d_r_a_i_n_a_g_e: a  raster  map  of  drainage  directions; if there is no flow
       direction, a value  of -1  is  assigned.   Otherwise,  the  integers  1
       through 8 are assigned to the compass directions shown below:




       5     6	 7 4	-1   8	   3	 2   1 For example, a value of 2 means
       that the pixel drains south, a value of 5 means the pixel drains to the
       northwest.



	Two  tables  are  output  by _r_._t_r_i_b_s.  The first table list the tribu-
       taries associated with each stream  segment.   The  second  table  list
       streams	and  tributaries in an order such that a stream and its tribu-
       taries are printed only if the tributaries have been previously listed.
       That is, first order streams are listed first, streams with tributaries
       that are first order streams are listed second, and so on.  The program
       can  also  be run in debugging mode, in which more detailed information
       is printed.




       The program _r_._t_r_i_b_s was written so that GRASS can be used  to  generate
       input  for a runoff and erosion model called KINEROS (Smith  et al., in
       press; Woolhiser et al., 1990).	KINEROS represents a  watershed  as  a
       set  of	related  elements.   Elements  may  be hillslopes, channels or
       ponds.  A computational order must be specified so that boundary condi-
       tions  for  an element, such as the amount of water contributed by lat-
       eral hillslopes and upstream tributaries, are available.   The  program
       _r_._t_r_i_b_s provides KINEROS with that computational order.



	IInnppuutt FFiilleess



	We  assume  that  the  program	_r_._w_a_t_e_r_s_h_e_d has been run, and that the
       input files _s_t_r_e_a_m, _a_c_c_u_m_u_l_a_t_i_o_n and  _d_r_a_i_n_a_g_e  are  available.	Assume
       these  files  are  called  _s_t_r_e_a_m_._0, _a_c_c_u_m_._0 and _d_r_a_i_n_._0, respectively.
       The command-line version of r.tribs is:



	    GRASS 4.1 >  r.tribs st=stream.0 ac=accum.0 dr=drain.0



	Alternately, the command _r_._t_r_i_b_s can be entered on the command line:



	     GRASS 4.1 >  r.tribs



	and the user will be prompted for these files.



	MMeetthhooddoollooggyy aanndd EExxaammppllee ooff OOuuttppuutt




       This is followed by a listing of the tributaries associated  with  each
       stream.	 The  tributaries of a stream are determined by using the fol-
       lowing methodology.

	a. The _s_t_r_e_a_m and _a_c_c_u_m_u_l_a_t_i_o_n files  are  scanned  to	determine  the
       locations  of pixels that are stream segments and have the lowest accu-
       mulation of runoff for that segment.  These points mark	the  locations
       of the heads of the stream segments.  Locations of the head of a stream
       are stored for the next step.

	b.  Points within one pixel of the head are scanned  to  determine  if
       they  are part of a different stream segment and if they drain into the
       head of this stream.  The _d_r_a_i_n_a_g_e raster file is used to determine the
       drainage  direction.   Any  point  meeting  this criteria are listed as
       tributary streams.

	c.  All points with no tributaries are first order.  Tributary	values
       are set to zero.

	d.  The label of the stream and its tributaries are stored and printed
       to the screen.



	We have used _r_._t_r_i_b_s to generate output for a  small  watershed  (17.5
       km2)  in  Idaho	(Horse Creek) in which we used _r_._w_a_t_e_r_s_h_e_d to define a
       total of 50 stream segments.  Note that stream segments and tributaries
       are labelled using even integers ranging from 2 to 102.	Stream segment
       2 is located at the mouth of the watershed.



	The _r_._t_r_i_b_s program first outputs the number of rows (nrows) and  col-
       umns  (ncols) in the raster files.  Then the maximum and minimum labels
       of stream segments are printed.	This is followed by two  tables.   The
       first  table  lists  streams and their tributaries.  An example of this
       table is given below.






	nrows: 138

	ncols: 273



	 Max stream index = 102

	 Min stream index = 2

	 Stream:    2	 Tributary 0:	 6    Tributary 1:    4

	 Stream:    4	 Tributary 0:	 0    Tributary 1:    0

	 Stream:    6	 Tributary 0:	14    Tributary 1:    8

	 Stream:    8	 Tributary 0:	12    Tributary 1:   10

	 Stream:   10	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   12	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   14	 Tributary 0:	22    Tributary 1:   16

	 Stream:   16	 Tributary 0:	20    Tributary 1:   18

	 Stream:   18	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   20	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   22	 Tributary 0:  102    Tributary 1:   24

	 Stream:   24	 Tributary 0:	36    Tributary 1:   26

	 Stream:   26	 Tributary 0:	30    Tributary 1:   28

	 Stream:   28	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   30	 Tributary 0:	34    Tributary 1:   32

	 Stream:   32	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   34	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   36	 Tributary 0:  100    Tributary 1:   38

	 Stream:   38	 Tributary 0:	42    Tributary 1:   40

	 Stream:   40	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   42	 Tributary 0:	98    Tributary 1:   44

	 Stream:   44	 Tributary 0:	96    Tributary 1:   46

	 Stream:   46	 Tributary 0:	50    Tributary 1:   48

	 Stream:   48	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   50	 Tributary 0:	58    Tributary 1:   52

	 Stream:   52	 Tributary 0:	56    Tributary 1:   54

	 Stream:   54	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   56	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   58	 Tributary 0:	90    Tributary 1:   60

	 Stream:   60	 Tributary 0:	88    Tributary 1:   62

	 Stream:   62	 Tributary 0:	66    Tributary 1:   64

	 Stream:   64	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   66	 Tributary 0:	74    Tributary 1:   68

	 Stream:   68	 Tributary 0:	72    Tributary 1:   70

	 Stream:   70	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   72	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   74	 Tributary 0:	82    Tributary 1:   76

	 Stream:   76	 Tributary 0:	80    Tributary 1:   78

	 Stream:   78	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   80	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   82	 Tributary 0:	86    Tributary 1:   84

	 Stream:   84	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   86	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   88	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   90	 Tributary 0:	94    Tributary 1:   92

	 Stream:   92	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   94	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   96	 Tributary 0:	 0    Tributary 1:    0

	 Stream:   98	 Tributary 0:	 0    Tributary 1:    0

	 Stream:  100	 Tributary 0:	 0    Tributary 1:    0

	 Stream:  102	 Tributary 0:	 0    Tributary 1:    0



	If the program is run in debugging mode, then the  values  of  _s_t_r_e_a_m,
       _a_c_c_u_m_u_l_a_t_i_o_n  and _d_i_r_e_c_t_i_o_n of the head of the stream and the surround-
       ing 8 pixels are also printed.  Set the value of DB_FIND_TRIBS (defined
       in  the beginning of the routine find_tribs) to a value of 1 and recom-
       pile the program to activate debugging mode.



	The second table that is output by _r_._t_r_i_b_s list the streams and  their
       associated  tributaries	in their proper computational order.  The pro-
       gram loops through the data listed above several times.	First  streams
       with no tributaries are listed (LOOP 1).  Then streams with only first-
       order streams as tributaries are listed (LOOP 2).  Then,  streams  with
       tributaries listed in previous loops are listed.  The program continues
       until all streams have been  listed.   The  variable  "Order"  is  also
       listed,	which  can be interpreted as the computational order.  This is
       the order in which programs, such as KINEROS, must consider streams  in
       the  network such that data for tributaries will be available when con-
       sidering the listed stream.  An example listing	of  the  computational
       order of streams is given below.






	 Computational Order of Stream Segments:



	 LOOP:	 1

	 Order:    0   Stream:	 4   Tributary 0:   0	Tributary 1:   0

	 Order:    1   Stream:	10   Tributary 0:   0	Tributary 1:   0

	 Order:    2   Stream:	12   Tributary 0:   0	Tributary 1:   0

	 Order:    3   Stream:	18   Tributary 0:   0	Tributary 1:   0

	 Order:    4   Stream:	20   Tributary 0:   0	Tributary 1:   0

	 Order:    5   Stream:	28   Tributary 0:   0	Tributary 1:   0

	 Order:    6   Stream:	32   Tributary 0:   0	Tributary 1:   0

	 Order:    7   Stream:	34   Tributary 0:   0	Tributary 1:   0

	 Order:    8   Stream:	40   Tributary 0:   0	Tributary 1:   0

	 Order:    9   Stream:	48   Tributary 0:   0	Tributary 1:   0

	 Order:   10   Stream:	54   Tributary 0:   0	Tributary 1:   0

	 Order:   11   Stream:	56   Tributary 0:   0	Tributary 1:   0

	 Order:   12   Stream:	64   Tributary 0:   0	Tributary 1:   0

	 Order:   13   Stream:	70   Tributary 0:   0	Tributary 1:   0

	 Order:   14   Stream:	72   Tributary 0:   0	Tributary 1:   0

	 Order:   15   Stream:	78   Tributary 0:   0	Tributary 1:   0

	 Order:   16   Stream:	80   Tributary 0:   0	Tributary 1:   0

	 Order:   17   Stream:	84   Tributary 0:   0	Tributary 1:   0

	 Order:   18   Stream:	86   Tributary 0:   0	Tributary 1:   0

	 Order:   19   Stream:	88   Tributary 0:   0	Tributary 1:   0

	 Order:   20   Stream:	92   Tributary 0:   0	Tributary 1:   0

	 Order:   21   Stream:	94   Tributary 0:   0	Tributary 1:   0

	 Order:   22   Stream:	96   Tributary 0:   0	Tributary 1:   0

	 Order:   23   Stream:	98   Tributary 0:   0	Tributary 1:   0

	 Order:   24   Stream: 100   Tributary 0:   0	Tributary 1:   0

	 Order:   25   Stream: 102   Tributary 0:   0	Tributary 1:   0

	 -----------------------------------------------------------------




	 LOOP:	 2

	 Order:   26   Stream:	 8   Tributary 0:  12	Tributary 1:  10

	 Order:   27   Stream:	16   Tributary 0:  20	Tributary 1:  18

	 Order:   28   Stream:	30   Tributary 0:  34	Tributary 1:  32

	 Order:   29   Stream:	52   Tributary 0:  56	Tributary 1:  54

	 Order:   30   Stream:	68   Tributary 0:  72	Tributary 1:  70

	 Order:   31   Stream:	76   Tributary 0:  80	Tributary 1:  78

	 Order:   32   Stream:	82   Tributary 0:  86	Tributary 1:  84

	 Order:   33   Stream:	90   Tributary 0:  94	Tributary 1:  92

	 -----------------------------------------------------------------



	 LOOP:	 3

	 Order:   34   Stream:	26   Tributary 0:  30	Tributary 1:  28

	 Order:   35   Stream:	74   Tributary 0:  82	Tributary 1:  76

	 -----------------------------------------------------------------




	 LOOP:	 4

	 Order:   36   Stream:	66   Tributary 0:  74	Tributary 1:  68

	 -----------------------------------------------------------------



	 LOOP:	 5

	 Order:   37   Stream:	62   Tributary 0:  66	Tributary 1:  64

	 -----------------------------------------------------------------



	 LOOP:	 6

	 Order:   38   Stream:	60   Tributary 0:  88	Tributary 1:  62

	 -----------------------------------------------------------------



	 LOOP:	 7

	 Order:   39   Stream:	58   Tributary 0:  90	Tributary 1:  60

	 -----------------------------------------------------------------



	 LOOP:	 8

	 Order:   40   Stream:	50   Tributary 0:  58	Tributary 1:  52

	 -----------------------------------------------------------------



	 LOOP:	 9

	 Order:   41   Stream:	46   Tributary 0:  50	Tributary 1:  48

	 -----------------------------------------------------------------



	 LOOP:	10

	 Order:   42   Stream:	44   Tributary 0:  96	Tributary 1:  46

	 -----------------------------------------------------------------



	 LOOP:	11

	 Order:   43   Stream:	42   Tributary 0:  98	Tributary 1:  44

	 -----------------------------------------------------------------



	 LOOP:	12

	 Order:   44   Stream:	38   Tributary 0:  42	Tributary 1:  40

	 -----------------------------------------------------------------



	 LOOP:	13

	 Order:   45   Stream:	36   Tributary 0: 100	Tributary 1:  38

	 -----------------------------------------------------------------



	 LOOP:	14

	 Order:   46   Stream:	24   Tributary 0:  36	Tributary 1:  26

	 -----------------------------------------------------------------



	 LOOP:	15

	 Order:   47   Stream:	22   Tributary 0: 102	Tributary 1:  24

	 -----------------------------------------------------------------



	 LOOP:	16

	 Order:   48   Stream:	14   Tributary 0:  22	Tributary 1:  16

	 -----------------------------------------------------------------



	 LOOP:	17

	 Order:   49   Stream:	 6   Tributary 0:  14	Tributary 1:   8

	 -----------------------------------------------------------------



	 LOOP:	18

	 Order:   50   Stream:	 2   Tributary 0:   6	Tributary 1:   4






       OObbttaaiinniinngg rr..ttrriibbss vviiaa FFTTPP oorr eemmaaiill



	The C programs that are required to generate _r_._t_r_i_b_s are available via
       anonymous ftp to moon.cecer.army.mil.  I have printed out the main seg-
       ment of the _r_._t_r_i_b_s program in Appendix I.  This was done to illustrate
       how routines in the GRASS library are used  to  read  in  raster  data.
       Routines  from the GRASS library begin with "G_".  Two utility programs
       are also used: imatrix and ivector.  These are discussed by  Press  and
       others (1989), and are used to allocate space for arrays.   Comments in
       the code discuss the details of each routine.  Appendix	II  lists  the
       makefile  used  to compile _r_._t_r_i_b_s.  Note that the variable GIS must be
       edited so that the proper path to the grass directory is specified.



	As previously mentioned, the program can be obtained by anonymous  ftp
       to  moon.cecer.army.mil.   Change to the "incoming/r.tribs" directly to
       get the files.  The program can also  be  obtained  by  contacting  the
       author  via  email  (jfs5@po.cwru.edu).	The code has been commented to
       help the user to understand the program structure.






       RReeffeerreenncceess



	Press, W.H., Flannery, B.P., Teukolsky, S.A.,  and  Vetterling,  W.T.,
       1989,  Numerical  Recipes  in  C: The Art of Scientific Computing, Cam-
       bridge University Press, 735 pp.



	Shapiro, M., Westervelt, J., Gerdes, D., Larson, M.,  and  Brownfield,
       K.R., 1992, GRASS 4.0 Programmer's Manual, U.S. Army Construction Engi-
       neering Research Laboratory, Champaign, Illinois, 292 pp.



	Smith, R.E., Goodrich, D.C., Woolhiser, D.A., and  Unkrich,  C.L.,  in
       press, A KINematic Runoff and EROSion Model, in: V.P. Singh (Ed.), Com-
       puter Models of Watershed Hydrology, Water  Resources  Pub.,  Highlands
       Ranch, Colorado



	United	States	Army Corps of Engineers, 1993, GRASS4.1 Users's Refer-
       ence Manual, U.S. Army Construction Engineering Research  Laboratories,
       Champaign, Illinois, 556 pp.



	Woolhiser,  D.A.,  Smith, R.E., Goodrich, D.C., 1990, KINEROS, A Kine-
       matic Runoff and Erosion Model: Documentation and  Users  Manual,  U.S.
       Department  of  Agriculture, Agricultural Research Service, ARS-77, 130
       pp.




       AAppppeennddiixx II:: mmaaiinn..cc ccooddee ffoorr rr..ttrriibbss



	#include "gis.h"

	#include



	int **imatrix();

	int  *ivector();



	/*

	 *  Program to determing the topology of a stream network.  A

	 *  table is generated that reports the tributaries that are

	 *  at the head of each stream segement. The computational order

	 *  of streams is also determinted.

	 *

	 *  Written by:

	 *  Dr. John F. Stamm

	 *  Department of Geological Sciences

	 *  Case Western Reserve University

	 *  Cleveland, OH  44106-7216

	 *  email: jfs5@po.cwru.edu

	 */



	main(argc,argv)

	int   argc;

	char *argv[];

	{

	/*

	 *  Matricies

	 */

	    int **accum;

	    int **chann;

	    int **aspect;



	    CELL *cell;



	    char *chann_name;

	    char *accum_name;

	    char *aspect_name;

	    char *mapset;



	    int col;

	    int fd_accum;

	    int fd_chann;

	    int fd_aspect;

	    int ncols;

	    int nrows;

	    int row;



	    struct {

	    struct Option *accum ;

	    struct Option *chann ;

	    struct Option *aspect ;

	    } parm;



	/*

	 *  Allocate memory for the Option structure and return a

	 *  pointer to this structure.	Do this for the structured

	 *  variables parm.accum and parm.chann.


       *

	 *  Set values for parm.accum

	 */

	    parm.accum = G_define_option() ;

	    parm.accum->key	   = "accumulation";

	    parm.accum->type	   = TYPE_STRING;

	    parm.accum->;required   = YES;

	    parm.accum->;gisprompt  = "old,cell,raster" ;

	    parm.accum->;description= "Name of the ACCUMULATION map" ;

	/*

	 *  Set values for parm.chann

	 */

	    parm.chann = G_define_option() ;

	    parm.chann->;key	    = "stream";

	    parm.chann->;type	    = TYPE_STRING;

	    parm.chann->;required   = YES;

	    parm.chann->;gisprompt  = "old,cell,raster" ;

	    parm.chann->;description= "Name of the STREAM map" ;

	/*

	 *  Set values for parm.aspect

	 */

	    parm.aspect = G_define_option() ;

	    parm.aspect->;key	     = "drainage";

	    parm.aspect->;type	     = TYPE_STRING;

	    parm.aspect->;required   = YES;

	    parm.aspect->;gisprompt  = "old,cell,raster" ;

	    parm.aspect->;description= "Name of the DRAINAGE DIRECTION

	map";



	/*

	 *  Initailize GIS library for this program

	 */



	    G_gisinit(argv[0]);



	/*

	 *  Parse values from the command line.  If this is not

	 *  successful, then display a usage statement and exit.

	 */



	    if (G_parser(argc, argv))

		 exit (-1);

	    accum_name = parm.accum->;answer;

	    chann_name = parm.chann->;answer;


       aspect_name = parm.aspect->answer;



	/*

	 *  Find the name of mapset that we are going to use.

	 */



	    mapset = G_find_cell2 (accum_name, "");



	    if (mapset == NULL) {

		char msg[100];

		 sprintf   (msg,    "%s:		     G_program_name(),
       accum_name);

	       G_fatal_error (msg);

		exit(1);

	    }



	/*

	 *  Open the cell files in "mapset".

	 */



	    fd_accum = G_open_cell_old (accum_name, mapset);

	    if (fd_accum =0; row--) {

	       if(G_get_map_row (fd_accum, cell, row) <; 0)

		   exit(1);

	       for (col = 0; col <; ncols; col++) {

		   accum[row][col] = (int)cell[col];

	       }

	       if(G_get_map_row (fd_chann, cell, row) <; 0)

		   exit(1);

	       for (col = 0; col <; ncols; col++) {

		   chann[row][col] = (int)cell[col];

	       }

	       if(G_get_map_row (fd_aspect, cell, row) <; 0)

		   exit(1);

	       for (col = 0; col <; ncols; col++) {

		   aspect[row][col]  = (int)cell[col];

	       }

	    }



	/*

	 *  Compute the topology of the network.

	 */



	    (void)find_tribs(nrows, ncols, accum, chann, aspect);



	    exit(0);

	}









       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0							  r.kineros(1)
