documentation (r.surf.contour)

[Darrell McCauley]

ATTN: programmers

chuck at castor.GEOG.UCSB.EDU (chuck at castor.GEOG.UCSB.EDU) writes on 08 Mar 93:
>>>When I asked about this, r.surf.contour was described as using a "flood fill
>>>algorithm", what ever that is. 
>
>>my understanding is that r.surf.contour does not do any interpolation---
>>it simply fills areas between raster contour lines. Is this not correct?
>
>r.surf.contour linearly interpolates between contour lines. Unfortunately,
>the program uses a flood fill algorithm to find which contour lines to
>interpolate between (the algorithm is described in most introductory 
>computer graphics textbooks). 
>
>Without going into detail, the flood fill part of the algorithm is what is 

At the very least, could the man page give a reference?
(e.g., Foley et al., page X)

>Chuck Ehlschlaeger

Not to rag on Chuck, but I would advocate that a
bibliographic citation be the minimum for a man page and
that a GRASS tutorial (explaining both usage and theory in
layman's terms when applicable) be written for any new
"advanced" GRASS program.  All users are not typically
well-versed in computer graphics, mathematical statistics,
or image processing...  sometimes it's like giving a shotgun
to a novice: they know it kills things but they don't don't
know the difference between #8 shot and a slug.  They may
wind up hunting deer with #8 shot or birds with slugs and
get bad results. For example, "this shotgun is 20% effective
for killing a bird at 50 feet when aimed directly at it"...
it's obvious to the professional that something is wrong here.
(see PS)

Let shotgun=interpolation algorithm
and effectiveness=interpolation accuracy...

For example, does r.surf.sor use Simultaneous
Over--Relaxation or Some Ordinary Relationship (the latter
is just made-up)?  When should it be used over r.surf.idw?
(My apologies to the author - this is the first example that
I found... BTW - is there a man page in 4.1b?).  What
exactly is the algorithm? My understanding is that z values
are systematically improved by comparing both sign and
magnitude of slope differences in different directions...
but I'm not sure. This is just a general description that I
snagged out of a book.  I suppose that if I was sufficiently
motivated, I could translate the C code back to
English/mathematics, but if this were the case, (and with an
infinite amount of time for each project) I would just write
from scratch any program that I needed myself (so that I was
absolutely sure about the algorithm) and ignore any other
programs that are available but undocumented.

I, for one, would find a tutorial on the nuts and bolts of
future algorithms implemented in GRASS very useful,
especially when it could affect my interpretation of the
output.  (Interpolation programs, for example, fit what I'm
talking about. Mundane tasks, such as that performed by
s.in.ascii or d.font, do not.) If time doesn't permit the
programmer to do this, then I'm curious enough to look up a
reference given in a man page.

--Darrell McCauley

PS: the hunting analogy is not to be construed as an elitest 
    attitude toward GIS as debated among geographers in GIS-L 
    from time to time nor is it making any statement about 
    gun control.  :-)