[GRASS-SVN] r51533 - grass-addons/grass6/raster/r.vol.dem

[svn_grass at osgeo.org]

Author: neteler
Date: 2012-04-25 01:46:38 -0700 (Wed, 25 Apr 2012)
New Revision: 51533

Modified:
   grass-addons/grass6/raster/r.vol.dem/description.html
Log:
doc added

Modified: grass-addons/grass6/raster/r.vol.dem/description.html
===================================================================
--- grass-addons/grass6/raster/r.vol.dem/description.html	2012-04-25 08:45:29 UTC (rev 51532)
+++ grass-addons/grass6/raster/r.vol.dem/description.html	2012-04-25 08:46:38 UTC (rev 51533)
@@ -1,8 +1,114 @@
-< h2 > DESCRIPTION < /h2 >
-    <em > r.vol.dem < /em >
-    interpolates a voxel model from a series of DEMs by flood filling the
-    voxel space in between. < h2 > NOTES < /h2 > (to be added from main.c)
+<h2>DESCRIPTION</h2>
 
-< h2 > EXAMPLE < /h2 > <div class = "code" >< pre > tbd < /pre >< /div > <h2 > SEE ALSO < /h2 > <h2 > AUTHOR < /h2 > <p > Benjamin Ducke < p > <i > Last changed: $Date: 2012 - 04 - 10 20: 50:03 + 0200(Tue,
-	      10 Apr 2012) $ <
-    /i >
+<em>r.vol.dem</em> interpolates a voxel model from a series of DEMs by
+flood filling the voxel space in between.
+
+The module is able to calculate voxel maps between at least two DEMs.
+The algorithm is based on a so-called "Flood-filling" algorithm. Since
+a date, label or category number of an e.g., archaeological stratum
+represents always the value for the entire stratum it would be more
+suitable to fill the entire 3D unit with this single value.
+<p>
+The input bottom and top DEMs represent each the bottom and top border
+for the "voxeled" stratum, in this case the implicit structure. Before
+running the <em>r.vol.dem</em> module, one needs to adjust the
+three-dimensional extent of the 3D interpolation which works as an
+analytical mask in the GRASS GIS module <em>g.region</em>. This
+procedure adjusts additionally the voxel's size which influences the
+3D resolution of the entire stratum. Furthermore, it is possible to
+adjust the height and width of the voxel in order to obtain a cube or
+cuboid voxel shape. In general, the smaller the voxel's size the higher
+the resolution, the more precise 3D units. 
+
+<h2>NOTES</h2>
+
+The input data for the 3D interpolation which requires at least two
+raster DEMs. They have to be entered in a certain rank, with the lowest,
+according to elevation, DEM first. 
+<p>
+The list of label values is one for each 3D layer (labels=value): Since
+one can enter an infinite number of DEMs it is possible adjust certain
+labels for each 3D layer. If they are not specified, labelling starts
+with layer 0. The numbers are given always upwards disregarding the
+algorithm direction.
+<p>
+The <em>errormap</em> raster map is to represent topology errors in input
+DEMs. This option does not yet create a real map but gives the coordinates
+where intersections of DEMs occur.
+<p>
+The <em>algorithm</em> parameter is used to select the 3D flood fill
+algorithm to use. The user can chose between an up or down filling
+direction. The default adjustment is the upwards algorithm. The results
+can become very different according to the shape and extension of the DEMs.
+<p>
+The <em>-c</em> flag calculates 3D cell counts for each layer: This option 
+counts the number of voxels for each 3D layer label. Unfortunately, this
+count is not stored in the <em>r3.info</em> information. Thus, if one
+needs this information afterwards, one has to repeat the whole calculation. 
+<p>
+The <em>-f</em> flag fills through NULL value areas in DEMs: Null value
+areas are areas which lie outside a 3D layer defined by two successive DEMs
+in the input command. In the case, where a 3D layer is limited not only
+from one unit surface, e.g. on top, this flag allows a further 3D
+interpolation until the next DEM or the region's margin.
+<p>
+The <em>-h</em> flag export convex hull for polygon layers: This option
+creates a 3D polygon out of the voxel model. This means, at first it will
+be generated a voxel model. Afterwards, this will be converted into a
+vector-file. However, the flag does not yet work properly.
+<p>
+The <em>-g</em> flag exports voxel model as vector points: This option
+creates a vector point for each interpolated voxel. This became necessary
+because of the lack of suitable representation in the visualisation module
+nivz in GRASS GIS 6. Nevertheless, the points can be represented virtually
+as cubes in nviz which gives an idea of the voxel layer. Unfortunately,
+there is still an error in the module using this flag (state 01.06.2006)
+that can be corrected by the following procedure:
+The module <em>r.vol.dem</em> creates a temporary txt-file in the HOME
+directory. Opening this file one will find a line which starts with 
+"# v.in.ascii". This line needs to be copied without the #-sign and
+executed in the GRASS bash shell. 
+<p>
+The <em>-p</em> flag exports VTK point data instead of cell data: This
+option reflects the fact that the visualisation program ParaView which
+treats cell data and point data differently in comparison to the program
+GRASS GIS. Hence, if one wants to visualise GRASS voxel in ParaView, this
+flag is recommended.
+<p>
+The <em>-q</em> flag disables on-screen progress display:
+This option does not yet work. 
+<p>
+The <em>-s</em> flag skips topology error checking:
+The module checks the input DEMs for intersection before running the
+algorithm. If such an unwanted intersection is found, the algorithm creates
+an errormap (see <em>errormap</em> option) and stops the entire 3D
+interpolation process. Using this flag one can skip this precaution. 
+<p>
+The <em>-v</em> flag generates a vtk-file for visualisation with e.g.
+ParaView: Since the GRASS visualisation module nviz is unable to show
+voxel as (semitransparent) cubes, the Open Source visualisation
+program ParaView is now commonly used for the visualisation of GRASS GIS
+maps and especially for 3D visualisations. Hence, the output GRASS GIS 
+files have to be converted into a ParaView readable format.
+<p>
+The <em>-z</em> flag fits active region's z range to input DEMs:
+This option does not yet work.
+
+<h2>EXAMPLE</h2>
+
+<div class = "code"><pre>
+tbd
+</pre></div>
+
+<h2>SEE ALSO</h2>
+
+<a href="http://undine-lieberwirth.info/?page_id=8">Screenhot gallery</a>
+
+<h2> AUTHOR</h2>
+
+Software: Benjamin Ducke
+<p>
+Documentation: Undine Lieberwirth
+
+<p>
+<i>Last changed: $Date$</i>