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