Geografic-Information-System/raster3d/r3.in.ascii/r3.in.ascii.html

<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.

<p>
The <em>tiledimension</em> parameter defines the dimension of the tiles 
used in the output file. The format is: XxYxZ

<p>
The <em>nv</em> parameter specifies which value to convert to NULL-value.
If the specified value is <em>none</em>, no conversion is performed.
Default is <em>none</em>.

<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>
</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>

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>AUTHORS</h2>
Roman Waupotitsch, Michael Shapiro, 
Helena Mitasova, Bill Brown, Lubos Mitas, Jaro Hofierka, S&ouml;ren Gebbert

<h2>SEE ALSO</h2>

<em>
<a href="r.in.ascii.html">r.in.ascii</a>,
<a href="r3.out.ascii.html">r3.out.ascii</a>,
<a href="v.to.rast3.html">v.to.rast3</a>
</em>

<p>
<i>Last changed: $Date$</i>