Updated documentation

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

raster3d/r3.in.ascii/r3.in.ascii.html

@@ -1,12 +1,7 @@
 <h2>DESCRIPTION</h2>
 
 <em>r3.in.ascii</em> allows a user to create a (binary) GRASS 3D raster map
-layer from a 3D ASCII raster input file with (optional) TITLE.
-
-<p>Note that for compression the <em>none</em> option only specifies 
-that neither LZW nor RLE is used for compression. It 
-does not turn off the compression all together. 3D raster maps do
-not support non-compressed files.
+layer from a 3D ASCII raster input file.
 
 <p>The <em>tiledimension</em> parameter defines the dimension of the tiles 
 used in the output file. The format is: XxYxZ
@@ -15,78 +10,39 @@ used in the output file. The format is: XxYxZ
 If the specified value is <em>none</em>, no conversion is performed.
 Default is <em>none</em>.
 
+
+<h2>NOTES</h2>
+
+A detailed description of the input format as well as the supported row/depth 
+ordering is available in the <a href="r3.out.ascii.html">r3.out.ascii</a>.
+manual page. The order of the data in the input file does not specifiy the
+data order in the generated output 3D raster map which is in any case 
+<em>north -> south, west -> east, bottom -> top</em> order.
+The data is automatically imported into the correct internal coordinate system,
+that is visualized in the following picture, independently from the specified
+ordering in the ASCII input file:
 <center>
 <img src="g3d_volume_layout.png" border=0><br>
 <table border=0 width=700>
 <tr><td><center>
-<i>The volume coordinate system and tile layout of the inported voxel map</i>
+<i>The volume coordinate system and tile layout of the imported voxel map</i>
 </center></td></tr>
 </table>
 </center>
-
-<h2>NOTES</h2>
-
-The format of the 3D ASCII file:
-<div class="code"><pre>
-version: <i>"grass7"</i>
-order:   <i>"nsbt" or "nstb" or "snbt" or "sntb"</i>
-north:   <i>floating point</i>
-south:   <i>floating point</i>
-east:    <i>floating point</i>
-west:    <i>floating point</i>
-top:     <i>floating point</i>
-bottom:  <i>floating point</i>
-rows:    <i>integer</i>
-cols:    <i>integer</i>
-levels:  <i>integer</i>
-</pre></div>
-
-The version and order option have been introduced in GRASS 7 in June 2011.
-The version option is self explaining. The order option specifies the row
-and depth order of the data in the input file.
-The supported row/depth ordering is documented in the <em>r3.out.ascii</em>
-manual page. The order of the data in the input file does not specifiy the
-data order in the generated output 3D raster map which is in any case 
-<em>north -> south, west -> east, bottom -> top</em> order.
-So dependent on the order information the data is automatically imported
-into the correct internal coordinate system.
-<p>The version and order options are not mandatory. In case no version and
-order option is specified, the default GRASS 6 ASCII format is assumed.
-<p>This header is followed by the cell values in <em>floating point</em> format 
-organized in rows with constant <em>col</em> and <em>level</em> coordinate.
-The rows are organized by constant <em>level</em> coordinate. Individual cell
-values are separated by <em>space</em> or <em>CR</em>.
-
-<h2>EXAMPLES</h2>
-
-4x3x2 sample. Note in case no specific ordering is specified in the input
-file the upper-left (NW) corner of the bottom level comes first. The according
-order option is: nsbt for north -> south, bottom -> top ordering. This is
-identical with <em>r.in.ascii</em> for single level data. So the y coordinate
-is 0 at the northern edge.
-
-<div class="code"><pre>
-north: 3.0
-south: 0.0
-east: 4.0
-west: 0.0
-top: 2.0
-bottom: 0.0
-rows: 3
-cols: 4
-levels: 2
-x1,y1,z1  x2,y1,z1  x3,y1,z1  x4,y1,z1
-x1,y2,z1  x2,y2,z1  x3,y2,z1  x4,y2,z1
-x1,y3,z1  x2,y3,z1  x3,y3,z1  x4,y3,z1
-x1,y1,z2  x2,y1,z2  x3,y1,z2  x4,y1,z2
-x1,y2,z2  x2,y2,z2  x3,y2,z2  x4,y2,z2
-x1,y3,z2  x2,y3,z2  x3,y3,z2  x4,y3,z2
-</pre></div>
-
+<p>
+The version and order information in the header of the input file 
+are not mandatory. In case no version and
+order information was specified, the default GRASS 6 3D ASCII format is assumed.
+<p>
 Note that unit tests for <em>r3.in.ascii</em> are implemented in the
 <em>test.r3.out.ascii.sh</em> script located in the
 <em>r3.out.ascii</em> directory.
 
+<h2>EXAMPLES</h2>
+
+Please have a look at the detailed examples in 
+<a href="r3.out.ascii.html">r3.out.ascii</a>.
+
 <h2>AUTHORS</h2>
 Roman Waupotitsch, Michael Shapiro, 
 Helena Mitasova, Bill Brown, Lubos Mitas, Jaro Hofierka, S&ouml;ren Gebbert

raster3d/r3.out.ascii/r3.out.ascii.html

@@ -11,12 +11,13 @@ module is sensitive to region settings (set with <em>g.region</em>).
 output.
 
 <h2>NOTES</h2>
-The default format for the ASCII file is equivalent to that required
+The default format of the exported ASCII file is equivalent to that required
 by <em>r3.in.ascii</em>. In particular, files output by
 <em>r3.out.ascii</em> with header information may be converted back to
 3D raster maps with <em>r3.in.ascii</em>.
 
-<p>The format of the ASCII file is:
+<p>
+The format of the ASCII file is:
 <div class="code"><pre>
 version: <i>"grass7"</i>
 order:   <i>"nsbt" or "nstb" or "snbt" or "sntb"</i>
@@ -41,16 +42,21 @@ north -&gt; south for rows
 bottom -&gt; top for depths
 </pre></div>
 The header is followed by cell values in <em>floating point</em> format.
+<p>This header is followed by the cell values in <em>floating point</em> format 
+organized in rows with constant <em>col</em> and <em>level</em> coordinate.
+The rows are organized by constant <em>level</em> coordinate. Individual cell
+values are separated by <em>space</em> or <em>CR</em>.
 Cell values are exported as a series of horizontal slices in row-major
-order. The data starts with the upper left corner (NW) at the bottom of the data set:
+order. The data starts with the upper left corner (NW) at the bottom of the data set.
+The values at the following coordinates are exported:
 
 <div class="code"><pre>
-(x, y + rows,     z), (x + 1, y + rows,     z), ... (x + cols, y + rows,     z)
-(x, y + rows,     z), (x + 1, y + rows - 1, z), ... (x + cols, y + rows - 1, z)
+(x, y + rows,     z) (x + 1, y + rows,     z) ... (x + cols, y + rows,     z)
+(x, y + rows,     z) (x + 1, y + rows - 1, z) ... (x + cols, y + rows - 1, z)
           .                     .                                .
           .                     .                                .
           .                     .                                .
-(x, y,   z + depths), (x + 1, y,   z + depths), ... (x + cols, y,   z + depths)
+(x, y,   z + depths) (x + 1, y,   z + depths) ... (x + cols, y,   z + depths)
 </pre></div>
 
 This order is compatible with the <em>r.in.ascii</em> row -&gt; column ordering.
@@ -62,10 +68,118 @@ Supported orders are:
 <li><b>nstb</b>: north -&gt; south and top -&gt; bottom ordering using <em>-d</em> flag</li>
 <li><b>sntb</b>: south -&gt; north and top -&gt; bottom ordering using <em>-rd</em> flag</li>
 </ul>
-<p>One level maps can be imported with <em>r.in.ascii</em> (2D raster) using
+<p>
+The internal storage scheme of 3D raster maps is visualized in the following picture:
+<center>
+<img src="g3d_volume_layout.png" border=0><br>
+<table border=0 width=700>
+<tr><td><center>
+<i>The coordinate system and tile layout of a voxel map in GRASS</i>
+</center></td></tr>
+</table>
+</center>
+
+<p>
+One level maps can be imported with <em>r.in.ascii</em> (2D raster) using
 the default <b>nsbt</b> order and removing the header lines "version",
 "order", "top", "bottom" and "levels".
 
+<h2>Example</h2>
+We define a small region with 4 columns, 3 rows and 2 depths (4x3x2) and export
+it using different ordering definitions: 
+<div class="code"><pre>
+g.region res3=1 t=2 b=0 w=0 e=4 s=0 n=3
+r3.mapcalc "simple_example = row() + col() + depth()"
+</pre></div>
+
+Default order:
+<div class="code"><pre>
+r3.out.ascii input=simple_example dp=0
+
+version: grass7
+order: nsbt
+north: 3.000000
+south: 0.000000
+east: 4.000000
+west: 0.000000
+top: 2.000000
+bottom: 0.000000
+rows: 3
+cols: 4
+levels: 2
+3 4 5 6 
+4 5 6 7 
+5 6 7 8 
+4 5 6 7 
+5 6 7 8 
+6 7 8 9 
+</pre></div>
+Inverse row order (-r) 
+<div class="code"><pre>
+r3.out.ascii input=simple_example dp=0 -r
+
+version: grass7
+order: snbt
+north: 3.000000
+south: 0.000000
+east: 4.000000
+west: 0.000000
+top: 2.000000
+bottom: 0.000000
+rows: 3
+cols: 4
+levels: 2
+5 6 7 8 
+4 5 6 7 
+3 4 5 6 
+6 7 8 9 
+5 6 7 8 
+4 5 6 7
+</pre></div>
+Inverse depth order (-d) 
+<div class="code"><pre>
+r3.out.ascii input=simple_example dp=0 -d
+version: grass7
+order: nstb
+north: 3.000000
+south: 0.000000
+east: 4.000000
+west: 0.000000
+top: 2.000000
+bottom: 0.000000
+rows: 3
+cols: 4
+levels: 2
+4 5 6 7 
+5 6 7 8 
+6 7 8 9 
+3 4 5 6 
+4 5 6 7 
+5 6 7 8
+</pre></div>
+Inverse row and depth order (-rd) 
+<div class="code"><pre>
+r3.out.ascii input=simple_example dp=0 -rd
+
+version: grass7
+order: sntb
+north: 3.000000
+south: 0.000000
+east: 4.000000
+west: 0.000000
+top: 2.000000
+bottom: 0.000000
+rows: 3
+cols: 4
+levels: 2
+6 7 8 9 
+5 6 7 8 
+4 5 6 7 
+5 6 7 8 
+4 5 6 7 
+3 4 5 6
+</pre></div>
+
 <h2>SEE ALSO</h2>
 
 <em>