r3.out.ascii(1)

r3.out.ascii 💅✨

okay bestie, so this is a page from the GRASS GIS User's Manual, and it's about r3.out.ascii — the little icon that takes your 3D raster map and dumps it out as plain ASCII text. no cap, it's giving "export but make it readable" energy. 🎀

---

✨ NAME ✨

r3.out.ascii — converts a 3D raster map layer into a ASCII text file. 🦋

🔑 KEYWORDS 🔑

raster3d, export, output, voxel, conversion, ASCII

---

🌸 SYNOPSIS 🌸

r3.out.ascii
r3.out.ascii --help
r3.out.ascii [-hrdcm] input=string  [output=name]   [precision=integer]
[null_value=string]   [--overwrite]  [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags:

• -h — suppress printing of header information. no header, just vibes.
• -r — switch the row order in output from north->south to south->north. flip it, reverse it 💫
• -d — switch the depth order in output from bottom->top to top->bottom. depths but upside down.
• -c — print grass6 compatible format. flags -d and -r are ignored when you do this, bestie, so don't bother.
• -m — use 3D raster mask (if exists) with input map.
• --overwrite — allow output files to overwrite existing files. careful, she's bold.
• --help — print usage summary.
• --verbose — verbose module output. spill the details.
• --quiet — quiet module output. shhh 🤫
• --ui — force launching GUI dialog.

💜 Parameters:

• input=string [required] — 3D raster map to be converted to ASCII. you literally cannot skip this one.
• output=name — name for ASCII output file.
• precision=integer — number of decimal places for floats. Options: 0-20. Default: 8.
• null_value=string — string representing NULL value. Default: *.

---

🌈 DESCRIPTION 🌈

so r3.out.ascii exports a 3D raster map in ASCII format. the input parameter is a valid 3D raster map sitting in the current mapset search path. the output parameter is the name of an ASCII file, and it gets written into the current working directory. periodt.

if output is not specified then standard output (stdout) is used — she just yells into the terminal. the -h flag may be used to suppress header information. the module is sensitive to region settings (set with g.region), so mind your region bestie. 👑

the -c flag will create GRASS 6 r3.in.ascii compatible output.

---

📝 NOTES 📝

the default format of the exported ASCII file is equivalent to that required by r3.in.ascii. in particular, files output by r3.out.ascii with header information may be converted back to 3D raster maps with r3.in.ascii. it's a round trip, we love a round trip. 🔁

the format of the ASCII file is:

version: "grass7"
order:   "nsbt" or "nstb" or "snbt" or "sntb"
north:   floating point
south:   floating point
east:    floating point
west:    floating point
top:     floating point
bottom:  floating point
rows:    integer
cols:    integer
levels:  integer

the version and order options have been introduced in GRASS 7 in June 2011. the order option describes the order of rows and depths in the output. it is possible to create output of different row order using the -r flag and output of different depths order using the -d flag. the default order is:

• west -> east for columns
• north -> south for rows
• bottom -> top for depths

this header is followed by the cell values in floating point format organized in rows with constant col and level coordinate. the rows are organized by constant level coordinate. individual cell values are separated by space or CR. 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. the values at the following coordinates are exported:

(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)

this order is compatible with the r.in.ascii row -> column ordering.

supported orders are:

• nsbt: north -> south and bottom -> top ordering which is the default (no flags)
• snbt: south -> north and bottom -> top ordering using -r flag
• nstb: north -> south and top -> bottom ordering using -d flag
• sntb: south -> north and top -> bottom ordering using -rd flag

the internal storage scheme of 3D raster maps is visualized in the following picture: The coordinate system and tile layout of a voxel map in GRASS. (yes bestie, there's a whole picture, go look at it. 🖼️)

one level maps can be imported with r.in.ascii (2D raster) using the default nsbt order and removing the header lines "version", "order", "top", "bottom" and "levels".

---

🍓 EXAMPLES 🍓

we define a small region with 4 columns, 3 rows and 2 depths (4x3x2) and export it using different ordering definitions:

g.region res3=1 t=2 b=0 w=0 e=4 s=0 n=3
r3.mapcalc "simple_example = row() + col() + depth()"

Default order:

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

Inverse row order (-r)

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

Inverse depth order (-d)

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

Inverse row and depth order (-rd)

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

---

👀 SEE ALSO 👀

r3.in.ascii, r.out.ascii, g.region

---

💖 AUTHORS 💖

Roman Waupotitsch, Michael Shapiro, Helena Mitasova, Bill Brown, Lubos Mitas, Jaro Hofierka, Sören Gebbert — the whole squad, iconic behavior honestly. 🫶

---

💻 SOURCE CODE 💻

Available at: r3.out.ascii source code (history)

Accessed: Saturday Jan 17 05:41:15 2026

Main index | 3D raster index | Topics index | Keywords index | Graphical index | Full index

---

and that's the whole page bestie!! 💅 this came to you straight from the GRASS GIS 8.4.2 Reference Manual, © 2003-2025 GRASS Development Team, accessed Saturday Jan 17 05:41:15 2026. slay, go export some voxels. 🦋✨👑