Debian Codegraph @

raster3d/r3.out.ascii/r3.out.ascii.md

raw
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 ![The coordinate system and tile layout](raster3d_layout.png)
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