[GRASS-SVN] r53831 - in grass/trunk/raster3d: r3.in.ascii r3.out.ascii
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu Nov 15 01:27:53 PST 2012
Author: huhabla
Date: 2012-11-15 01:27:53 -0800 (Thu, 15 Nov 2012)
New Revision: 53831
Added:
grass/trunk/raster3d/r3.out.ascii/g3d_volume_layout.png
Modified:
grass/trunk/raster3d/r3.in.ascii/r3.in.ascii.html
grass/trunk/raster3d/r3.out.ascii/r3.out.ascii.html
Log:
Updated documentation
Modified: grass/trunk/raster3d/r3.in.ascii/r3.in.ascii.html
===================================================================
--- grass/trunk/raster3d/r3.in.ascii/r3.in.ascii.html 2012-11-15 08:34:34 UTC (rev 53830)
+++ grass/trunk/raster3d/r3.in.ascii/r3.in.ascii.html 2012-11-15 09:27:53 UTC (rev 53831)
@@ -1,13 +1,8 @@
<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.
+layer from a 3D ASCII raster input file.
-<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.
-
<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 @@
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ören Gebbert
Copied: grass/trunk/raster3d/r3.out.ascii/g3d_volume_layout.png (from rev 53805, grass/trunk/raster3d/r3.in.ascii/g3d_volume_layout.png)
===================================================================
(Binary files differ)
Modified: grass/trunk/raster3d/r3.out.ascii/r3.out.ascii.html
===================================================================
--- grass/trunk/raster3d/r3.out.ascii/r3.out.ascii.html 2012-11-15 08:34:34 UTC (rev 53830)
+++ grass/trunk/raster3d/r3.out.ascii/r3.out.ascii.html 2012-11-15 09:27:53 UTC (rev 53831)
@@ -11,12 +11,13 @@
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 @@
bottom -> 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 -> column ordering.
@@ -62,10 +68,118 @@
<li><b>nstb</b>: north -> south and top -> bottom ordering using <em>-d</em> flag</li>
<li><b>sntb</b>: south -> north and top -> 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>
More information about the grass-commit
mailing list