| 1 |
<h2>DESCRIPTION</h2> |
| 2 |
|
| 3 |
<em>r3.out.ascii</em> exports a 3D raster map in ASCII format. The <em>input</em> parameter is |
| 4 |
a valid 3D raster map in the current mapset search path. The <em>output</em> |
| 5 |
parameter is the name of an ASCII file which will be written in the |
| 6 |
current working directory. |
| 7 |
<p>If <em>output</em> is not specified then standard output (stdout) is used. |
| 8 |
The <em>-h</em> flag may be used to suppress header information. The |
| 9 |
module is sensitive to region settings (set with <em>g.region</em>). |
| 10 |
<p>The <em>-c</em> flag will create GRASS 6 <em>r3.in.ascii</em> compatible |
| 11 |
output. |
| 12 |
|
| 13 |
<h2>NOTES</h2> |
| 14 |
|
| 15 |
The default format of the exported ASCII file is equivalent to that required |
| 16 |
by <em>r3.in.ascii</em>. In particular, files output by |
| 17 |
<em>r3.out.ascii</em> with header information may be converted back to |
| 18 |
3D raster maps with <em>r3.in.ascii</em>. |
| 19 |
|
| 20 |
<p> |
| 21 |
The format of the ASCII file is: |
| 22 |
<div class="code"><pre> |
| 23 |
version: <i>"grass7"</i> |
| 24 |
order: <i>"nsbt" or "nstb" or "snbt" or "sntb"</i> |
| 25 |
north: <i>floating point</i> |
| 26 |
south: <i>floating point</i> |
| 27 |
east: <i>floating point</i> |
| 28 |
west: <i>floating point</i> |
| 29 |
top: <i>floating point</i> |
| 30 |
bottom: <i>floating point</i> |
| 31 |
rows: <i>integer</i> |
| 32 |
cols: <i>integer</i> |
| 33 |
levels: <i>integer</i> |
| 34 |
</pre></div> |
| 35 |
|
| 36 |
The <b>version</b> and <b>order</b> options have been introduced in GRASS 7 in June 2011. |
| 37 |
The <b>order</b> option describes the order of rows and depths in the output. |
| 38 |
It is possible to create output of different row order using the <em>-r</em> flag |
| 39 |
and output of different depths order using the <em>-d</em> flag. The default order is: |
| 40 |
<p><div class="code"><pre> |
| 41 |
west -> east for columns |
| 42 |
north -> south for rows |
| 43 |
bottom -> top for depths |
| 44 |
</pre></div> |
| 45 |
<p> |
| 46 |
This header is followed by the cell values in <em>floating point</em> format |
| 47 |
organized in rows with constant <em>col</em> and <em>level</em> coordinate. |
| 48 |
The rows are organized by constant <em>level</em> coordinate. Individual cell |
| 49 |
values are separated by <em>space</em> or <em>CR</em>. |
| 50 |
Cell values are exported as a series of horizontal slices in row-major |
| 51 |
order. The data starts with the upper left corner (NW) at the bottom of the data set. |
| 52 |
The values at the following coordinates are exported: |
| 53 |
|
| 54 |
<div class="code"><pre> |
| 55 |
(x, y + rows, z) (x + 1, y + rows, z) ... (x + cols, y + rows, z) |
| 56 |
(x, y + rows, z) (x + 1, y + rows - 1, z) ... (x + cols, y + rows - 1, z) |
| 57 |
. . . |
| 58 |
. . . |
| 59 |
. . . |
| 60 |
(x, y, z + depths) (x + 1, y, z + depths) ... (x + cols, y, z + depths) |
| 61 |
</pre></div> |
| 62 |
|
| 63 |
This order is compatible with the <em>r.in.ascii</em> row -> column ordering. |
| 64 |
<p> |
| 65 |
Supported orders are: |
| 66 |
<ul> |
| 67 |
<li><b>nsbt</b>: north -> south and bottom -> top ordering which is the default (no flags)</li> |
| 68 |
<li><b>snbt</b>: south -> north and bottom -> top ordering using <em>-r</em> flag</li> |
| 69 |
<li><b>nstb</b>: north -> south and top -> bottom ordering using <em>-d</em> flag</li> |
| 70 |
<li><b>sntb</b>: south -> north and top -> bottom ordering using <em>-rd</em> flag</li> |
| 71 |
</ul> |
| 72 |
<p> |
| 73 |
The internal storage scheme of 3D raster maps is visualized in the following picture: |
| 74 |
<center> |
| 75 |
<img src="raster3d_layout.png" border="0"><br> |
| 76 |
<table border="0" width=700> |
| 77 |
<tr><td><center> |
| 78 |
<i>The coordinate system and tile layout of a voxel map in GRASS</i> |
| 79 |
</center></td></tr> |
| 80 |
</table> |
| 81 |
</center> |
| 82 |
|
| 83 |
<p> |
| 84 |
One level maps can be imported with <em>r.in.ascii</em> (2D raster) using |
| 85 |
the default <b>nsbt</b> order and removing the header lines "version", |
| 86 |
"order", "top", "bottom" and "levels". |
| 87 |
|
| 88 |
<h2>EXAMPLES</h2> |
| 89 |
|
| 90 |
We define a small region with 4 columns, 3 rows and 2 depths (4x3x2) and export |
| 91 |
it using different ordering definitions: |
| 92 |
<div class="code"><pre> |
| 93 |
g.region res3=1 t=2 b=0 w=0 e=4 s=0 n=3 |
| 94 |
r3.mapcalc "simple_example = row() + col() + depth()" |
| 95 |
</pre></div> |
| 96 |
|
| 97 |
Default order: |
| 98 |
<div class="code"><pre> |
| 99 |
r3.out.ascii input=simple_example dp=0 |
| 100 |
|
| 101 |
version: grass7 |
| 102 |
order: nsbt |
| 103 |
north: 3.000000 |
| 104 |
south: 0.000000 |
| 105 |
east: 4.000000 |
| 106 |
west: 0.000000 |
| 107 |
top: 2.000000 |
| 108 |
bottom: 0.000000 |
| 109 |
rows: 3 |
| 110 |
cols: 4 |
| 111 |
levels: 2 |
| 112 |
3 4 5 6 |
| 113 |
4 5 6 7 |
| 114 |
5 6 7 8 |
| 115 |
4 5 6 7 |
| 116 |
5 6 7 8 |
| 117 |
6 7 8 9 |
| 118 |
</pre></div> |
| 119 |
Inverse row order (-r) |
| 120 |
<div class="code"><pre> |
| 121 |
r3.out.ascii input=simple_example dp=0 -r |
| 122 |
|
| 123 |
version: grass7 |
| 124 |
order: snbt |
| 125 |
north: 3.000000 |
| 126 |
south: 0.000000 |
| 127 |
east: 4.000000 |
| 128 |
west: 0.000000 |
| 129 |
top: 2.000000 |
| 130 |
bottom: 0.000000 |
| 131 |
rows: 3 |
| 132 |
cols: 4 |
| 133 |
levels: 2 |
| 134 |
5 6 7 8 |
| 135 |
4 5 6 7 |
| 136 |
3 4 5 6 |
| 137 |
6 7 8 9 |
| 138 |
5 6 7 8 |
| 139 |
4 5 6 7 |
| 140 |
</pre></div> |
| 141 |
Inverse depth order (-d) |
| 142 |
<div class="code"><pre> |
| 143 |
r3.out.ascii input=simple_example dp=0 -d |
| 144 |
version: grass7 |
| 145 |
order: nstb |
| 146 |
north: 3.000000 |
| 147 |
south: 0.000000 |
| 148 |
east: 4.000000 |
| 149 |
west: 0.000000 |
| 150 |
top: 2.000000 |
| 151 |
bottom: 0.000000 |
| 152 |
rows: 3 |
| 153 |
cols: 4 |
| 154 |
levels: 2 |
| 155 |
4 5 6 7 |
| 156 |
5 6 7 8 |
| 157 |
6 7 8 9 |
| 158 |
3 4 5 6 |
| 159 |
4 5 6 7 |
| 160 |
5 6 7 8 |
| 161 |
</pre></div> |
| 162 |
Inverse row and depth order (-rd) |
| 163 |
<div class="code"><pre> |
| 164 |
r3.out.ascii input=simple_example dp=0 -rd |
| 165 |
|
| 166 |
version: grass7 |
| 167 |
order: sntb |
| 168 |
north: 3.000000 |
| 169 |
south: 0.000000 |
| 170 |
east: 4.000000 |
| 171 |
west: 0.000000 |
| 172 |
top: 2.000000 |
| 173 |
bottom: 0.000000 |
| 174 |
rows: 3 |
| 175 |
cols: 4 |
| 176 |
levels: 2 |
| 177 |
6 7 8 9 |
| 178 |
5 6 7 8 |
| 179 |
4 5 6 7 |
| 180 |
5 6 7 8 |
| 181 |
4 5 6 7 |
| 182 |
3 4 5 6 |
| 183 |
</pre></div> |
| 184 |
|
| 185 |
<h2>SEE ALSO</h2> |
| 186 |
|
| 187 |
<em> |
| 188 |
<a href="r3.in.ascii.html">r3.in.ascii</a>, |
| 189 |
<a href="r.out.ascii.html">r.out.ascii</a>, |
| 190 |
<a href="g.region.html">g.region</a> |
| 191 |
</em> |
| 192 |
|
| 193 |
<h2>AUTHORS</h2> |
| 194 |
|
| 195 |
Roman Waupotitsch, Michael Shapiro, |
| 196 |
Helena Mitasova, Bill Brown, Lubos Mitas, Jaro Hofierka, Sören Gebbert |