r3.out.ascii(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 r3.out.ascii — the GRASS manual (1grass) but make it cute ✨

okay bestie, listen. you got a 3D raster map and you want it as text? say less. r3.out.ascii is literally the girl for the job. this is her whole manual page, and yes, we're reading the whole thing, no skimming, that's the rule. 🎀

KEYWORDS: raster3d, export, output, voxel, conversion, ASCII

✨ SYNOPSIS ✨

like, the whole vibe in five lines:

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 — shhh 🤫 no header info gets printed, we're keeping it lowkey
  • -r — flips the row order in the output, north->south becomes south->north
  • -d — flips the depth order, bottom->top becomes top->bottom
  • -c — prints the grass6 compatible format. heads up: flags -d and -r get ignored when you use this one 🙈
  • -m — use the 3D raster mask with the input map (if one exists)
  • --overwrite — let output files overwrite files that already exist, no questions asked
  • --help — print the usage summary
  • --verbose — verbose module output (she's chatty)
  • --quiet — quiet module output (she's in her silent era)
  • --ui — force launching the GUI dialog 🖥️

🎀 Parameters

  • input=string — [required] the 3D raster map that's getting converted to ASCII
  • output=name — the name for the ASCII output file
  • precision=integer — how many decimal places for the floats. Options: 0-20, Default: 8
  • null_value=string — the string that represents a 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 living somewhere in your current mapset search path. the output parameter is the name of an ASCII file, and it gets written right into the current working directory. periodt. 📁

If you don't specify output, then standard output (that's stdout, bestie) gets used instead. and the -h flag? that's your girl for suppressing header information. also be aware this module is sensitive to region settings — the ones you set with g.region. so set them first, okay?? 😌

The -c flag will create GRASS 6 r3.in.ascii compatible output. iconic, but make sure that's actually what you want.

📝 NOTES 📝

The default format of the exported ASCII file is equivalent to the one that r3.in.ascii requires. so specifically: files output by r3.out.ascii with header information can be converted back into 3D raster maps using r3.in.ascii. it's giving reversible. 🔁

And here's the format of the ASCII file, character for character:

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 got introduced in GRASS 7, in June 2011. the order option describes the order of rows and depths in the output. you can create output with a different row order using the -r flag, and output with a different depth 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. mutual besties fr fr 🫶

The supported orders, bestie 👑

  • nsbt: north -> south and bottom -> top ordering — this is the default, no flags needed
  • snbt: south -> north and bottom -> top ordering, using the -r flag
  • nstb: north -> south and top -> bottom ordering, using the -d flag
  • sntb: south -> north and top -> bottom ordering, using the -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

One level maps can be imported with r.in.ascii (that's 2D raster) using the default nsbt order and removing the header lines "version", "order", "top", "bottom" and "levels". just pluck them out, slay 💅

🌈 EXAMPLES 🌈

okay let's get hands-on. 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 👀

your other favs, go say hi:

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

👑 AUTHORS 👑

Roman Waupotitsch, Michael Shapiro, Helena Mitasova, Bill Brown, Lubos Mitas, Jaro Hofierka, Sören Gebbert. absolute legends, all of them. 💜

📦 SOURCE CODE 📦

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

Latest change: Wednesday Oct 01 19:33:56 2025 in commit: 2bff9b53785aeeed0248becad0089c3a0ec05479

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

and that's the whole page, bestie!! 🌸 © 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual 🌈 go export some voxels, you're gonna ate 💅✨🦋

📦 where this page comes from