add r.path

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@71962 15284696-431f-4ddb-bdfa-cd5b030d7da7

raster/Makefile

@@ -62,6 +62,7 @@ SUBDIRS = \
 	r.out.vtk \
 	r.param.scale \
 	r.patch \
+	r.path \
 	r.profile \
 	r.proj \
 	r.quant \

raster/r.path/Makefile

@@ -0,0 +1,12 @@
+MODULE_TOPDIR = ../..
+
+PGM = r.path
+
+LIBES = $(VECTORLIB) $(RASTERLIB) $(GISLIB)
+DEPENDENCIES = $(VECTORDEP) $(RASTERDEP) $(GISDEP)
+EXTRA_INC = $(VECT_INC)
+EXTRA_CFLAGS = $(VECT_CFLAGS)
+
+include $(MODULE_TOPDIR)/include/Make/Module.make
+
+default: cmd

raster/r.path/local.h

@@ -0,0 +1,10 @@
+
+#define OUT_PID 1
+#define OUT_CNT 2
+#define OUT_CPY 3
+#define OUT_ACC 4
+
+struct metrics
+{
+    double ew_res, ns_res, diag_res;
+};

raster/r.path/pavlrc.c

@@ -0,0 +1,843 @@
+/* Produced by texiweb from libavl.w. */
+
+/* libavl - library for manipulation of binary trees.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004 Free Software
+   Foundation, Inc.
+
+   This library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 3 of the License, or (at your option) any later version.
+
+   This library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with this library; if not, write to the Free Software
+   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+   02110-1301 USA.
+ */
+
+/* Nov 2016, Markus Metz
+ * from libavl-2.0.3
+ * added safety checks and speed optimizations
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include "pavlrc.h"
+
+#define CMP_RC(a, b) ((a)->row == (b)->row ? (a)->col - (b)->col : (a)->row - (b)->row)
+
+/* Creates and returns a new table
+   with comparison function |compare| using parameter |param|
+   and memory allocator |allocator|.
+   Returns |NULL| if memory allocation failed. */
+struct pavlrc_table *pavlrc_create(struct libavl_allocator *allocator)
+{
+    struct pavlrc_table *tree;
+
+    if (allocator == NULL)
+	allocator = &pavlrc_allocator_default;
+
+    tree = allocator->libavl_malloc(allocator, sizeof *tree);
+    if (tree == NULL)
+	return NULL;
+
+    tree->pavl_root = NULL;
+    tree->pavl_alloc = allocator;
+    tree->pavl_count = 0;
+
+    return tree;
+}
+
+/* Search |tree| for an item matching |item|, and return it if found.
+   Otherwise return |NULL|. */
+struct pavlrc *pavlrc_find(const struct pavlrc_table *tree, const struct pavlrc *item)
+{
+    struct pavlrc_node *p;
+
+    assert(tree != NULL && item != NULL);
+
+    p = tree->pavl_root;
+    while (p != NULL) {
+	int cmp = CMP_RC(item, &p->pavl_data);
+
+	if (cmp == 0)
+	    return &p->pavl_data;
+
+	p = p->pavl_link[cmp > 0];
+    }
+
+    return NULL;
+}
+
+/* Inserts |item| into |tree| and returns a pointer to |item|.
+   If a duplicate item is found in the tree,
+   returns a pointer to the duplicate without inserting |item|.
+   Returns |NULL| in case of memory allocation failure. */
+struct pavlrc *pavlrc_probe(struct pavlrc_table *tree, struct pavlrc *item)
+{
+    struct pavlrc_node *y;	/* Top node to update balance factor, and parent. */
+    struct pavlrc_node *p, *q;	/* Iterator, and parent. */
+    struct pavlrc_node *n;	/* Newly inserted node. */
+    struct pavlrc_node *w;	/* New root of rebalanced subtree. */
+    int dir;			/* Direction to descend. */
+
+    assert(tree != NULL && item != NULL);
+
+    y = p = tree->pavl_root;
+    q = NULL;
+    dir = 0;
+    while (p != NULL) {
+	int cmp = CMP_RC(item, &p->pavl_data);
+
+	if (cmp == 0)
+	    return &p->pavl_data;
+
+	dir = cmp > 0;
+
+	if (p->pavl_balance != 0)
+	    y = p;
+
+	q = p, p = p->pavl_link[dir];
+    }
+
+    n = tree->pavl_alloc->libavl_malloc(tree->pavl_alloc, sizeof *p);
+    if (n == NULL)
+	return NULL;
+
+    tree->pavl_count++;
+    n->pavl_link[0] = n->pavl_link[1] = NULL;
+    n->pavl_parent = q;
+    n->pavl_data = *item;
+    n->pavl_balance = 0;
+    if (q == NULL) {
+	tree->pavl_root = n;
+
+	return item /* &n->pavl_data */;
+    }
+    q->pavl_link[dir] = n;
+
+    p = n;
+    while (p != y) {
+	q = p->pavl_parent;
+	/*
+	   dir = q->pavl_link[0] != p;
+	   if (dir == 0)
+	   q->pavl_balance--;
+	   else
+	   q->pavl_balance++;
+	 */
+	if (q->pavl_link[0] != p)
+	    q->pavl_balance++;
+	else
+	    q->pavl_balance--;
+
+	p = q;
+    }
+
+    if (y->pavl_balance == -2) {
+	struct pavlrc_node *x = y->pavl_link[0];
+
+	if (x->pavl_balance == -1) {
+	    w = x;
+	    y->pavl_link[0] = x->pavl_link[1];
+	    x->pavl_link[1] = y;
+	    x->pavl_balance = y->pavl_balance = 0;
+	    x->pavl_parent = y->pavl_parent;
+	    y->pavl_parent = x;
+	    if (y->pavl_link[0] != NULL)
+		y->pavl_link[0]->pavl_parent = y;
+	}
+	else {
+	    assert(x->pavl_balance == +1);
+	    w = x->pavl_link[1];
+	    x->pavl_link[1] = w->pavl_link[0];
+	    w->pavl_link[0] = x;
+	    y->pavl_link[0] = w->pavl_link[1];
+	    w->pavl_link[1] = y;
+	    if (w->pavl_balance == -1)
+		x->pavl_balance = 0, y->pavl_balance = +1;
+	    else if (w->pavl_balance == 0)
+		x->pavl_balance = y->pavl_balance = 0;
+	    else		/* |w->pavl_balance == +1| */
+		x->pavl_balance = -1, y->pavl_balance = 0;
+	    w->pavl_balance = 0;
+	    w->pavl_parent = y->pavl_parent;
+	    x->pavl_parent = y->pavl_parent = w;
+	    if (x->pavl_link[1] != NULL)
+		x->pavl_link[1]->pavl_parent = x;
+	    if (y->pavl_link[0] != NULL)
+		y->pavl_link[0]->pavl_parent = y;
+	}
+    }
+    else if (y->pavl_balance == +2) {
+	struct pavlrc_node *x = y->pavl_link[1];
+
+	if (x->pavl_balance == +1) {
+	    w = x;
+	    y->pavl_link[1] = x->pavl_link[0];
+	    x->pavl_link[0] = y;
+	    x->pavl_balance = y->pavl_balance = 0;
+	    x->pavl_parent = y->pavl_parent;
+	    y->pavl_parent = x;
+	    if (y->pavl_link[1] != NULL)
+		y->pavl_link[1]->pavl_parent = y;
+	}
+	else {
+	    assert(x->pavl_balance == -1);
+	    w = x->pavl_link[0];
+	    x->pavl_link[0] = w->pavl_link[1];
+	    w->pavl_link[1] = x;
+	    y->pavl_link[1] = w->pavl_link[0];
+	    w->pavl_link[0] = y;
+	    if (w->pavl_balance == +1)
+		x->pavl_balance = 0, y->pavl_balance = -1;
+	    else if (w->pavl_balance == 0)
+		x->pavl_balance = y->pavl_balance = 0;
+	    else		/* |w->pavl_balance == -1| */
+		x->pavl_balance = +1, y->pavl_balance = 0;
+	    w->pavl_balance = 0;
+	    w->pavl_parent = y->pavl_parent;
+	    x->pavl_parent = y->pavl_parent = w;
+	    if (x->pavl_link[0] != NULL)
+		x->pavl_link[0]->pavl_parent = x;
+	    if (y->pavl_link[1] != NULL)
+		y->pavl_link[1]->pavl_parent = y;
+	}
+    }
+    else
+	return item /* &n->pavl_data */;
+
+    if (w->pavl_parent != NULL)
+	w->pavl_parent->pavl_link[y != w->pavl_parent->pavl_link[0]] = w;
+    else
+	tree->pavl_root = w;
+
+    return item /* &n->pavl_data */;
+}
+
+/* Inserts |item| into |table|.
+   Returns |NULL| if |item| was successfully inserted
+   or if a memory allocation error occurred.
+   Otherwise, returns the duplicate item. */
+struct pavlrc *pavlrc_insert(struct pavlrc_table *table, struct pavlrc *item)
+{
+    struct pavlrc *p = pavlrc_probe(table, item);
+
+    return p == NULL || p == item ? NULL : p;
+}
+
+/* Inserts |item| into |table|, replacing any duplicate item.
+   Returns |NULL| if |item| was inserted without replacing a duplicate,
+   or if a memory allocation error occurred.
+   Otherwise, returns the item that was replaced. */
+struct pavlrc *pavlrc_replace(struct pavlrc_table *table, struct pavlrc *item)
+{
+    struct pavlrc *p = pavlrc_probe(table, item);
+
+    if (p == NULL || p == item)
+	return NULL;
+    else {
+	struct pavlrc *r = p;
+
+	*p = *item;
+
+	return r;
+    }
+}
+
+/* Deletes from |tree| and returns an item matching |item|.
+   Returns a null pointer if no matching item found. */
+struct pavlrc *pavlrc_delete(struct pavlrc_table *tree, struct pavlrc *item)
+{
+    struct pavlrc_node *p;	/* Traverses tree to find node to delete. */
+    struct pavlrc_node *q;	/* Parent of |p|. */
+    int dir;			/* Side of |q| on which |p| is linked. */
+    int cmp;			/* Result of comparison between |item| and |p|. */
+
+    assert(tree != NULL && item != NULL);
+
+    p = tree->pavl_root;
+    dir = 0;
+    while (p != NULL) {
+	cmp = CMP_RC(item, &p->pavl_data);
+
+	if (cmp == 0)
+	    break;
+
+	dir = cmp > 0;
+	p = p->pavl_link[dir];
+    }
+    if (p == NULL)
+	return NULL;
+
+    /* item = p->pavl_data; */
+
+    q = p->pavl_parent;
+    if (q == NULL) {
+	q = (struct pavlrc_node *)&tree->pavl_root;
+	dir = 0;
+    }
+
+    if (p->pavl_link[1] == NULL) {
+	q->pavl_link[dir] = p->pavl_link[0];
+	if (q->pavl_link[dir] != NULL)
+	    q->pavl_link[dir]->pavl_parent = p->pavl_parent;
+    }
+    else {
+	struct pavlrc_node *r = p->pavl_link[1];
+
+	if (r->pavl_link[0] == NULL) {
+	    r->pavl_link[0] = p->pavl_link[0];
+	    q->pavl_link[dir] = r;
+	    r->pavl_parent = p->pavl_parent;
+	    if (r->pavl_link[0] != NULL)
+		r->pavl_link[0]->pavl_parent = r;
+	    r->pavl_balance = p->pavl_balance;
+	    q = r;
+	    dir = 1;
+	}
+	else {
+	    struct pavlrc_node *s = r->pavl_link[0];
+
+	    while (s->pavl_link[0] != NULL)
+		s = s->pavl_link[0];
+	    r = s->pavl_parent;
+	    r->pavl_link[0] = s->pavl_link[1];
+	    s->pavl_link[0] = p->pavl_link[0];
+	    s->pavl_link[1] = p->pavl_link[1];
+	    q->pavl_link[dir] = s;
+	    if (s->pavl_link[0] != NULL)
+		s->pavl_link[0]->pavl_parent = s;
+	    s->pavl_link[1]->pavl_parent = s;
+	    s->pavl_parent = p->pavl_parent;
+	    if (r->pavl_link[0] != NULL)
+		r->pavl_link[0]->pavl_parent = r;
+	    s->pavl_balance = p->pavl_balance;
+	    q = r;
+	    dir = 0;
+	}
+    }
+    tree->pavl_alloc->libavl_free(tree->pavl_alloc, p);
+
+    while (q != (struct pavlrc_node *)&tree->pavl_root) {
+	struct pavlrc_node *y = q;
+
+	if (y->pavl_parent != NULL)
+	    q = y->pavl_parent;
+	else
+	    q = (struct pavlrc_node *)&tree->pavl_root;
+
+	if (dir == 0) {
+	    dir = q->pavl_link[0] != y;
+	    y->pavl_balance++;
+	    if (y->pavl_balance == +1)
+		break;
+	    else if (y->pavl_balance == +2) {
+		struct pavlrc_node *x = y->pavl_link[1];
+
+		if (x->pavl_balance == -1) {
+		    struct pavlrc_node *w;
+
+		    assert(x->pavl_balance == -1);
+		    w = x->pavl_link[0];
+		    x->pavl_link[0] = w->pavl_link[1];
+		    w->pavl_link[1] = x;
+		    y->pavl_link[1] = w->pavl_link[0];
+		    w->pavl_link[0] = y;
+		    if (w->pavl_balance == +1)
+			x->pavl_balance = 0, y->pavl_balance = -1;
+		    else if (w->pavl_balance == 0)
+			x->pavl_balance = y->pavl_balance = 0;
+		    else	/* |w->pavl_balance == -1| */
+			x->pavl_balance = +1, y->pavl_balance = 0;
+		    w->pavl_balance = 0;
+		    w->pavl_parent = y->pavl_parent;
+		    x->pavl_parent = y->pavl_parent = w;
+		    if (x->pavl_link[0] != NULL)
+			x->pavl_link[0]->pavl_parent = x;
+		    if (y->pavl_link[1] != NULL)
+			y->pavl_link[1]->pavl_parent = y;
+		    q->pavl_link[dir] = w;
+		}
+		else {
+		    y->pavl_link[1] = x->pavl_link[0];
+		    x->pavl_link[0] = y;
+		    x->pavl_parent = y->pavl_parent;
+		    y->pavl_parent = x;
+		    if (y->pavl_link[1] != NULL)
+			y->pavl_link[1]->pavl_parent = y;
+		    q->pavl_link[dir] = x;
+		    if (x->pavl_balance == 0) {
+			x->pavl_balance = -1;
+			y->pavl_balance = +1;
+			break;
+		    }
+		    else {
+			x->pavl_balance = y->pavl_balance = 0;
+			y = x;
+		    }
+		}
+	    }
+	}
+	else {
+	    dir = q->pavl_link[0] != y;
+	    y->pavl_balance--;
+	    if (y->pavl_balance == -1)
+		break;
+	    else if (y->pavl_balance == -2) {
+		struct pavlrc_node *x = y->pavl_link[0];
+
+		if (x->pavl_balance == +1) {
+		    struct pavlrc_node *w;
+
+		    assert(x->pavl_balance == +1);
+		    w = x->pavl_link[1];
+		    x->pavl_link[1] = w->pavl_link[0];
+		    w->pavl_link[0] = x;
+		    y->pavl_link[0] = w->pavl_link[1];
+		    w->pavl_link[1] = y;
+		    if (w->pavl_balance == -1)
+			x->pavl_balance = 0, y->pavl_balance = +1;
+		    else if (w->pavl_balance == 0)
+			x->pavl_balance = y->pavl_balance = 0;
+		    else	/* |w->pavl_balance == +1| */
+			x->pavl_balance = -1, y->pavl_balance = 0;
+		    w->pavl_balance = 0;
+		    w->pavl_parent = y->pavl_parent;
+		    x->pavl_parent = y->pavl_parent = w;
+		    if (x->pavl_link[1] != NULL)
+			x->pavl_link[1]->pavl_parent = x;
+		    if (y->pavl_link[0] != NULL)
+			y->pavl_link[0]->pavl_parent = y;
+		    q->pavl_link[dir] = w;
+		}
+		else {
+		    y->pavl_link[0] = x->pavl_link[1];
+		    x->pavl_link[1] = y;
+		    x->pavl_parent = y->pavl_parent;
+		    y->pavl_parent = x;
+		    if (y->pavl_link[0] != NULL)
+			y->pavl_link[0]->pavl_parent = y;
+		    q->pavl_link[dir] = x;
+		    if (x->pavl_balance == 0) {
+			x->pavl_balance = +1;
+			y->pavl_balance = -1;
+			break;
+		    }
+		    else {
+			x->pavl_balance = y->pavl_balance = 0;
+			y = x;
+		    }
+		}
+	    }
+	}
+    }
+
+    tree->pavl_count--;
+
+    return item;
+}
+
+/* Initializes |trav| for use with |tree|
+   and selects the null node. */
+void pavlrc_t_init(struct pavlrc_traverser *trav, struct pavlrc_table *tree)
+{
+    trav->pavl_table = tree;
+    trav->pavl_node = NULL;
+}
+
+/* Initializes |trav| for |tree|.
+   Returns data item in |tree| with the least value,
+   or |NULL| if |tree| is empty. */
+struct pavlrc *pavlrc_t_first(struct pavlrc_traverser *trav, struct pavlrc_table *tree)
+{
+    assert(tree != NULL && trav != NULL);
+
+    trav->pavl_table = tree;
+    trav->pavl_node = tree->pavl_root;
+    if (trav->pavl_node != NULL) {
+	while (trav->pavl_node->pavl_link[0] != NULL)
+	    trav->pavl_node = trav->pavl_node->pavl_link[0];
+
+	return &trav->pavl_node->pavl_data;
+    }
+    else
+	return NULL;
+}
+
+/* Initializes |trav| for |tree|.
+   Returns data item in |tree| with the greatest value,
+   or |NULL| if |tree| is empty. */
+struct pavlrc *pavlrc_t_last(struct pavlrc_traverser *trav, struct pavlrc_table *tree)
+{
+    assert(tree != NULL && trav != NULL);
+
+    trav->pavl_table = tree;
+    trav->pavl_node = tree->pavl_root;
+    if (trav->pavl_node != NULL) {
+	while (trav->pavl_node->pavl_link[1] != NULL)
+	    trav->pavl_node = trav->pavl_node->pavl_link[1];
+
+	return &trav->pavl_node->pavl_data;
+    }
+    else
+	return NULL;
+}
+
+/* Searches for |item| in |tree|.
+   If found, initializes |trav| to the item found and returns the item
+   as well.
+   If there is no matching item, initializes |trav| to the null item
+   and returns |NULL|. */
+struct pavlrc *pavlrc_t_find(struct pavlrc_traverser *trav, struct pavlrc_table *tree,
+		  struct pavlrc *item)
+{
+    struct pavlrc_node *p;
+
+    assert(trav != NULL && tree != NULL && item != NULL);
+
+    trav->pavl_table = tree;
+    
+    p = tree->pavl_root;
+    while (p != NULL) {
+	int cmp = CMP_RC(item, &p->pavl_data);
+
+	if (cmp == 0) {
+	    trav->pavl_node = p;
+
+	    return &p->pavl_data;
+	}
+
+	p = p->pavl_link[cmp > 0];
+    }
+
+    trav->pavl_node = NULL;
+
+    return NULL;
+}
+
+/* Attempts to insert |item| into |tree|.
+   If |item| is inserted successfully, it is returned and |trav| is
+   initialized to its location.
+   If a duplicate is found, it is returned and |trav| is initialized to
+   its location.  No replacement of the item occurs.
+   If a memory allocation failure occurs, |NULL| is returned and |trav|
+   is initialized to the null item. */
+struct pavlrc *pavlrc_t_insert(struct pavlrc_traverser *trav,
+		    struct pavlrc_table *tree, struct pavlrc *item)
+{
+    struct pavlrc *p;
+
+    assert(trav != NULL && tree != NULL && item != NULL);
+
+    p = pavlrc_probe(tree, item);
+    if (p != NULL) {
+	trav->pavl_table = tree;
+	trav->pavl_node = ((struct pavlrc_node *)((char *)p -
+						offsetof(struct pavlrc_node,
+							 pavl_data)));
+
+	return p;
+    }
+    else {
+	pavlrc_t_init(trav, tree);
+
+	return NULL;
+    }
+}
+
+/* Initializes |trav| to have the same current node as |src|. */
+struct pavlrc *pavlrc_t_copy(struct pavlrc_traverser *trav,
+		  const struct pavlrc_traverser *src)
+{
+    assert(trav != NULL && src != NULL);
+
+    trav->pavl_table = src->pavl_table;
+    trav->pavl_node = src->pavl_node;
+
+    return trav->pavl_node != NULL ? &trav->pavl_node->pavl_data : NULL;
+}
+
+/* Returns the next data item in inorder
+   within the tree being traversed with |trav|,
+   or if there are no more data items returns |NULL|. */
+struct pavlrc *pavlrc_t_next(struct pavlrc_traverser *trav)
+{
+    assert(trav != NULL);
+
+    if (trav->pavl_node == NULL)
+	return pavlrc_t_first(trav, trav->pavl_table);
+    else if (trav->pavl_node->pavl_link[1] == NULL) {
+	struct pavlrc_node *q, *p;	/* Current node and its child. */
+
+	for (p = trav->pavl_node, q = p->pavl_parent;;
+	     p = q, q = q->pavl_parent)
+	    if (q == NULL || p == q->pavl_link[0]) {
+		trav->pavl_node = q;
+
+		return trav->pavl_node != NULL ?
+		    &trav->pavl_node->pavl_data : NULL;
+	    }
+    }
+    else {
+	trav->pavl_node = trav->pavl_node->pavl_link[1];
+	while (trav->pavl_node->pavl_link[0] != NULL)
+	    trav->pavl_node = trav->pavl_node->pavl_link[0];
+
+	return &trav->pavl_node->pavl_data;
+    }
+}
+
+/* Returns the previous data item in inorder
+   within the tree being traversed with |trav|,
+   or if there are no more data items returns |NULL|. */
+struct pavlrc *pavlrc_t_prev(struct pavlrc_traverser *trav)
+{
+    assert(trav != NULL);
+
+    if (trav->pavl_node == NULL)
+	return pavlrc_t_last(trav, trav->pavl_table);
+    else if (trav->pavl_node->pavl_link[0] == NULL) {
+	struct pavlrc_node *q, *p;	/* Current node and its child. */
+
+	for (p = trav->pavl_node, q = p->pavl_parent;;
+	     p = q, q = q->pavl_parent)
+	    if (q == NULL || p == q->pavl_link[1]) {
+		trav->pavl_node = q;
+
+		return trav->pavl_node != NULL ?
+		    &trav->pavl_node->pavl_data : NULL;
+	    }
+    }
+    else {
+	trav->pavl_node = trav->pavl_node->pavl_link[0];
+	while (trav->pavl_node->pavl_link[1] != NULL)
+	    trav->pavl_node = trav->pavl_node->pavl_link[1];
+
+	return &trav->pavl_node->pavl_data;
+    }
+}
+
+/* Returns |trav|'s current item. */
+struct pavlrc *pavlrc_t_cur(struct pavlrc_traverser *trav)
+{
+    assert(trav != NULL);
+
+    return trav->pavl_node != NULL ? &trav->pavl_node->pavl_data : NULL;
+}
+
+/* Replaces the current item in |trav| by |new| and returns the item replaced.
+   |trav| must not have the null item selected.
+   The new item must not upset the ordering of the tree. */
+struct pavlrc *pavlrc_t_replace(struct pavlrc_traverser *trav, struct pavlrc *new)
+{
+    struct pavlrc *old;
+
+    assert(trav != NULL && trav->pavl_node != NULL && new != NULL);
+    old = &trav->pavl_node->pavl_data;
+    trav->pavl_node->pavl_data = *new;
+
+    return old;
+}
+
+/* Destroys |new| with |pavl_destroy (new, destroy)|,
+   first initializing right links in |new| that have
+   not yet been initialized at time of call. */
+static void
+copy_error_recovery(struct pavlrc_node *q,
+		    struct pavlrc_table *new)
+{
+    assert(q != NULL && new != NULL);
+
+    for (;;) {
+	struct pavlrc_node *p = q;
+
+	q = q->pavl_parent;
+	if (q == NULL)
+	    break;
+
+	if (p == q->pavl_link[0])
+	    q->pavl_link[1] = NULL;
+    }
+
+    pavlrc_destroy(new);
+}
+
+/* Copies |org| to a newly created tree, which is returned.
+   If |copy != NULL|, each data item in |org| is first passed to |copy|,
+   and the return values are inserted into the tree;
+   |NULL| return values are taken as indications of failure.
+   On failure, destroys the partially created new tree,
+   applying |destroy|, if non-null, to each item in the new tree so far,
+   and returns |NULL|.
+   If |allocator != NULL|, it is used for allocation in the new tree.
+   Otherwise, the same allocator used for |org| is used. */
+struct pavlrc_table *pavlrc_copy(const struct pavlrc_table *org,
+			     pavlrc_copy_func * copy,
+			     struct libavl_allocator *allocator)
+{
+    struct pavlrc_table *new;
+    struct pavlrc_node *x;
+    struct pavlrc_node *y;
+
+    assert(org != NULL);
+    new = pavlrc_create(allocator != NULL ? allocator : org->pavl_alloc);
+    if (new == NULL)
+	return NULL;
+
+    new->pavl_count = org->pavl_count;
+    if (new->pavl_count == 0)
+	return new;
+
+    x = (struct pavlrc_node *)&org->pavl_root;
+    y = (struct pavlrc_node *)&new->pavl_root;
+    while (x != NULL) {
+	while (x->pavl_link[0] != NULL) {
+	    y->pavl_link[0] =
+		new->pavl_alloc->libavl_malloc(new->pavl_alloc,
+					       sizeof *y->pavl_link[0]);
+	    if (y->pavl_link[0] == NULL) {
+		if (y != (struct pavlrc_node *)&new->pavl_root) {
+		    /* y->pavl_data = NULL; */
+		    y->pavl_link[1] = NULL;
+		}
+
+		copy_error_recovery(y, new);
+
+		return NULL;
+	    }
+	    y->pavl_link[0]->pavl_parent = y;
+
+	    x = x->pavl_link[0];
+	    y = y->pavl_link[0];
+	}
+	y->pavl_link[0] = NULL;
+
+	for (;;) {
+	    y->pavl_balance = x->pavl_balance;
+	    if (copy == NULL)
+		y->pavl_data = x->pavl_data;
+	    else {
+		y->pavl_data = *(struct pavlrc *)copy(&x->pavl_data);
+		/*
+		if (y->pavl_data == NULL) {
+		    y->pavl_link[1] = NULL;
+		    copy_error_recovery(y, new);
+
+		    return NULL;
+		}
+		*/
+	    }
+
+	    if (x->pavl_link[1] != NULL) {
+		y->pavl_link[1] =
+		    new->pavl_alloc->libavl_malloc(new->pavl_alloc,
+						   sizeof *y->pavl_link[1]);
+		if (y->pavl_link[1] == NULL) {
+		    copy_error_recovery(y, new);
+
+		    return NULL;
+		}
+		y->pavl_link[1]->pavl_parent = y;
+
+		x = x->pavl_link[1];
+		y = y->pavl_link[1];
+		break;
+	    }
+	    else
+		y->pavl_link[1] = NULL;
+
+	    for (;;) {
+		const struct pavlrc_node *w = x;
+
+		x = x->pavl_parent;
+		if (x == NULL) {
+		    new->pavl_root->pavl_parent = NULL;
+		    return new;
+		}
+		y = y->pavl_parent;
+
+		if (w == x->pavl_link[0])
+		    break;
+	    }
+	}
+    }
+
+    return new;
+}
+
+/* Frees storage allocated for |tree|.
+   If |destroy != NULL|, applies it to each data item in inorder. */
+void pavlrc_destroy(struct pavlrc_table *tree)
+{
+    struct pavlrc_node *p, *q;
+
+    assert(tree != NULL);
+
+    p = tree->pavl_root;
+    while (p != NULL) {
+	if (p->pavl_link[0] == NULL) {
+	    q = p->pavl_link[1];
+	    tree->pavl_alloc->libavl_free(tree->pavl_alloc, p);
+	}
+	else {
+	    q = p->pavl_link[0];
+	    p->pavl_link[0] = q->pavl_link[1];
+	    q->pavl_link[1] = p;
+	}
+	p = q;
+    }
+
+    tree->pavl_alloc->libavl_free(tree->pavl_alloc, tree);
+}
+
+/* Allocates |size| bytes of space using |malloc()|.
+   Returns a null pointer if allocation fails. */
+void *pavlrc_malloc(struct libavl_allocator *allocator, size_t size)
+{
+    assert(allocator != NULL && size > 0);
+
+    return malloc(size);
+}
+
+/* Frees |block|. */
+void pavlrc_free(struct libavl_allocator *allocator, void *block)
+{
+    assert(allocator != NULL && block != NULL);
+
+    free(block);
+}
+
+/* Default memory allocator that uses |malloc()| and |free()|. */
+struct libavl_allocator pavlrc_allocator_default = {
+    pavlrc_malloc,
+    pavlrc_free
+};
+
+#undef NDEBUG
+#include <assert.h>
+
+/* Asserts that |pavl_insert()| succeeds at inserting |item| into |table|. */
+void (pavlrc_assert_insert) (struct pavlrc_table * table, struct pavlrc *item)
+{
+    struct pavlrc *p = pavlrc_probe(table, item);
+
+    assert(p != NULL && p == item);
+}
+
+/* Asserts that |pavl_delete()| really removes |item| from |table|,
+   and returns the removed item. */
+struct pavlrc *(pavlrc_assert_delete) (struct pavlrc_table * table, struct pavlrc *item)
+{
+    struct pavlrc *p = pavlrc_delete(table, item);
+
+    assert(p != NULL);
+
+    return p;
+}

raster/r.path/pavlrc.h

@@ -0,0 +1,107 @@
+/* Produced by texiweb from libavl.w. */
+
+/* libavl - library for manipulation of binary trees.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004 Free Software
+   Foundation, Inc.
+
+   This library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 3 of the License, or (at your option) any later version.
+
+   This library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with this library; if not, write to the Free Software
+   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+   02110-1301 USA.
+ */
+
+#ifndef PAVLRC_H
+#define PAVLRC_H 1
+
+#include <stddef.h>
+
+struct pavlrc
+{
+    int row, col;
+};
+
+/* Function types. */
+typedef void *pavlrc_copy_func(void *pavl_item);
+
+#ifndef LIBAVL_ALLOCATOR
+#define LIBAVL_ALLOCATOR
+/* Memory allocator. */
+struct libavl_allocator
+{
+    void *(*libavl_malloc) (struct libavl_allocator *, size_t libavl_size);
+    void (*libavl_free) (struct libavl_allocator *, void *libavl_block);
+};
+#endif
+
+/* Default memory allocator. */
+extern struct libavl_allocator pavlrc_allocator_default;
+void *pavlrc_malloc(struct libavl_allocator *, size_t);
+void pavlrc_free(struct libavl_allocator *, void *);
+
+/* Maximum PAVL height, unused. */
+#ifndef PAVL_MAX_HEIGHT
+#define PAVL_MAX_HEIGHT 32
+#endif
+
+/* Tree data structure. */
+struct pavlrc_table
+{
+    struct pavlrc_node *pavl_root;	/* Tree's root. */
+    struct libavl_allocator *pavl_alloc;	/* Memory allocator. */
+    size_t pavl_count;		/* Number of items in tree. */
+};
+
+/* An PAVL tree node. */
+struct pavlrc_node
+{
+    struct pavlrc_node *pavl_link[2];	/* Subtrees. */
+    struct pavlrc_node *pavl_parent;	/* Parent node. */
+    struct pavlrc pavl_data;		/* data. */
+    signed char pavl_balance;	/* Balance factor. */
+};
+
+/* PAVL traverser structure. */
+struct pavlrc_traverser
+{
+    struct pavlrc_table *pavl_table;	/* Tree being traversed. */
+    struct pavlrc_node *pavl_node;	/* Current node in tree. */
+};
+
+/* Table functions. */
+struct pavlrc_table *pavlrc_create(struct libavl_allocator *);
+struct pavlrc_table *pavlrc_copy(const struct pavlrc_table *, pavlrc_copy_func *,
+			         struct libavl_allocator *);
+void pavlrc_destroy(struct pavlrc_table *);
+struct pavlrc *pavlrc_probe(struct pavlrc_table *, struct pavlrc *);
+struct pavlrc *pavlrc_insert(struct pavlrc_table *, struct pavlrc *);
+struct pavlrc *pavlrc_replace(struct pavlrc_table *, struct pavlrc *);
+struct pavlrc *pavlrc_delete(struct pavlrc_table *, struct pavlrc *);
+struct pavlrc *pavlrc_find(const struct pavlrc_table *, const struct pavlrc *);
+void pavlrc_assert_insert(struct pavlrc_table *, struct pavlrc *);
+struct pavlrc *pavlrc_assert_delete(struct pavlrc_table *, struct pavlrc *);
+
+#define pavlrc_count(table) ((size_t) (table)->pavlrc_count)
+
+/* Table traverser functions. */
+void pavlrc_t_init(struct pavlrc_traverser *, struct pavlrc_table *);
+struct pavlrc *pavlrc_t_first(struct pavlrc_traverser *, struct pavlrc_table *);
+struct pavlrc *pavlrc_t_last(struct pavlrc_traverser *, struct pavlrc_table *);
+struct pavlrc *pavlrc_t_find(struct pavlrc_traverser *, struct pavlrc_table *, struct pavlrc *);
+struct pavlrc *pavlrc_t_insert(struct pavlrc_traverser *, struct pavlrc_table *, struct pavlrc *);
+struct pavlrc *pavlrc_t_copy(struct pavlrc_traverser *, const struct pavlrc_traverser *);
+struct pavlrc *pavlrc_t_next(struct pavlrc_traverser *);
+struct pavlrc *pavlrc_t_prev(struct pavlrc_traverser *);
+struct pavlrc *pavlrc_t_cur(struct pavlrc_traverser *);
+struct pavlrc *pavlrc_t_replace(struct pavlrc_traverser *, struct pavlrc *);
+
+#endif /* pavlrc.h */

raster/r.path/r.path.html

@@ -0,0 +1,192 @@
+<h2>DESCRIPTION</h2>
+
+<em>r.path</em> traces a path from starting points following input 
+directions. Such a movement direction map can be generated with 
+<em><a href="r.walk.html">r.walk</a></em>, 
+<em><a href="r.cost.html">r.cost</a></em>, 
+<em><a href="r.slope.aspect.html">r.slope.aspect</a></em>,
+<em><a href="r.watershed.html">r.watershed</a></em>, or
+<em><a href="r.fill.dir.html">r.fill.dir</a></em>,
+provided that the direction is in degrees, measured counterclockwise
+from east.
+
+<p>
+Alternatively, bitmask-encoded directions can be provided where each 
+bit position corresponds to a specific neighbour. A path will continue 
+to all neighbours with their bit set. This means a path can split and 
+merge. Such bitmasked directions can be created with the <b>-b</b> 
+flag of <em><a href="r.cost.html">r.cost</a></em> and 
+<em><a href="r.walk.html">r.walk</a></em>. The corresponding <b>-b</b> 
+flag must then be set for <em>r.path</em>.
+
+<div class="code"><pre>
+Direction encoding for neighbors of x
+    
+  135  90  45          7 8 1
+  180  x  360          6 x 2
+  225 270 315          5 4 3
+  
+  degrees           bit positions
+  CCW from East
+</pre></div>
+
+A path stops when the direction is zero or negative, indicating a stop 
+point or outlet.
+<p>
+The <b>output</b> raster map will show one or more least-cost paths
+between each user-provided location(s) and the target points (direction 
+&le; 0). By default, the <b>output</b> will be an integer CELL map with
+the id of the start points along the least cost path, and null cells elsewhere.
+
+<p>
+With the <b>-c</b> (<em>copy</em>) flag, the values raster map cell values are
+copied verbatim along the path. With the <b>-a</b> (<em>accumulate</em>)
+flag, the accumulated cell value from the starting point up to the current
+cell is written on output. With either the <b>-c</b> or the <b>-a</b> flags, the
+<b>raster_path</b> map is created with the same cell type as
+the <b>values</b> raster map (integer, float or double).  With
+the <b>-n</b> (<em>number</em>) flag, the cells are numbered
+consecutively from the starting point to the final point.
+The <b>-c</b>, <b>-a</b>, and <b>-n</b> flags are mutually
+incompatible.
+
+
+<p>
+The <b>start_coordinates</b> parameter consists of map E and N grid 
+coordinates of a starting point. Each x,y pair is the easting and 
+northing (respectively) of a starting point from which a path will be 
+traced following <b>input</b> directions. The <b>start_points</b> 
+parameter can take multiple vector maps containing additional starting 
+points.
+
+<h2>NOTES</h2>
+The directions are recorded as degrees CCW from East, the Knight's move 
+of r.cost and r.walk is considered:
+<div class="code"><pre>
+       112.5     67.5          
+157.5  135   90  45   22.5     
+       180   x   0            
+202.5  225  270  315  337.5
+       247.5     292.5
+</pre></div>
+i.e. a cell with the value 135 means the next cell is to the North-West, 
+and a cell with the value 157.5 means that the next cell is to the 
+West-North-West-
+
+
+<h2>EXAMPLES</h2>
+
+<h3>Hydrological path</h3>
+
+We are using the full North Carolina sample dataset.
+First we create the two points from a text file using
+<em><a href="v.in.ascii.html">v.in.ascii</a></em> module
+(here the text file is CSV and we are using unix here-file syntax
+with EOF, in GUI just enter the values directly for the parameter input):
+
+<div class="code"><pre>
+v.in.ascii input=- output=start format=point separator=comma &lt;&lt;EOF
+638667.15686275,220610.29411765
+638610.78431373,220223.03921569
+EOF
+</pre></div>
+
+We need to supply a direction raster map to the <em>r.path</em> module. 
+To get these directions, we use the
+<em><a href="r.watershed.html">r.watershed</a></em> module:
+
+<div class="code"><pre>
+r.watershed elevation=elev_lid792_1m accumulation=accum drainage=drain_dir
+</pre></div>
+
+The directions are categorical and we convert them to degrees using
+raster algebra:
+
+<div class="code"><pre>
+r.mapcalc "drain_deg = if(drain_dir != 0, 45. * abs(drain_dir), null())"
+</pre></div>
+
+Now we are ready to extract the drainage paths starting at the two points.
+
+<div class="code"><pre>
+r.path input=drain_deg raster_path=drain_path vector_path=drain_path start_points=start
+</pre></div>
+
+Before we visualize the result, we set a color table for the elevation
+we are using and create a shaded relief map:
+
+<div class="code"><pre>
+r.colors map=elev_lid792_1m color=elevation
+r.relief input=elev_lid792_1m output=relief
+</pre></div>
+
+We visualize the input and output data:
+
+<div class="code"><pre>
+d.shade shade=relief color=elev_lid792_1m
+d.vect map=drain_path color=0:0:61 width=4 legend_label="drainage paths"
+d.vect map=start color=none fill_color=224:0:0 icon=basic/circle size=15 legend_label=origins
+d.legend.vect -b
+</pre></div>
+
+<div align="center">
+<a href="r_drain_with_r_watershed_direction.png"><img src="r_drain_with_r_watershed_direction.png" alt="drainage using r.watershed" width="300" height="280"></a>
+<br>
+<i>Figure: Drainage paths from two points where directions from
+r.watershed were used</i>
+</div>
+
+<h3>Least-cost path</h3>
+
+We compute bitmask encoded movement directions using <em>r.walk:</em>
+<div class="code"><pre>
+g.region swwake_30m -p
+
+# create friction map based on land cover
+r.recode landclass96 out=friction &lt;&lt; EOF
+1:3:0.1:0.1
+4:5:10.:10.
+6:6:1000.0:1000.0
+7:7:0.3:0.3
+EOF
+
+# without Knight's move
+r.walk -b elevation=elev_ned_30m friction=friction output=walkcost \
+    outdir=walkdir start_coordinates=635576,216485
+
+r.path -b input=walkdir start_coordinates=640206,222795 \
+    raster_path=walkpath vector_path=walkpath
+
+# with Knight's move
+r.walk -b -k elevation=elev_ned_30m friction=friction output=walkcost_k \
+    outdir=walkdir_k start_coordinates=635576,216485
+
+r.path -b input=walkdir_k start_coordinates=640206,222795 \
+    raster_path=walkpath_k vector_path=walkpath_k
+</pre></div>
+
+The extracted least-cost path splits and merges on the way from 
+the start point to the stop point (start point for r.walk). Note the 
+gaps in the raster path when using the Knight's move.
+<div class="code"><pre>
+</pre></div>
+
+<h2>SEE ALSO</h2>
+
+<em>
+<a href="g.region.html">g.region</a>,
+<a href="r.cost.html">r.cost</a>,
+<a href="r.walk.html">r.walk</a>,
+<a href="r.watershed.html">r.watershed</a>,
+<a href="r.fill.dir.html">r.fill.dir</a>,
+<a href="r.basins.fill.html">r.basins.fill</a>,
+<a href="r.terraflow.html">r.terraflow</a>,
+<a href="r.mapcalc.html">r.mapcalc</a>,
+</em>
+
+<h2>AUTHORS</h2>
+
+Markus Metz
+
+<p>
+<i>Last changed: $Date$</i>