r3.in.ascii(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 r3.in.ascii 💖

okay bestie, gather round, because r3.in.ascii is the GRASS GIS manual page we're vibing with today, and honestly? it's giving glow-up for your ASCII data. ✨

🌸 NAME 🌸

r3.in.ascii — converts a 3D ASCII raster text file into a (binary) 3D raster map. that's it, that's the whole job, and it does it flawlessly. 💅

🏷️ KEYWORDS 🏷️

raster3d, import, voxel, conversion, ASCII

✨ SYNOPSIS ✨

r3.in.ascii
r3.in.ascii --help
r3.in.ascii input=name output=name  [null_value=string]   [type=string]
[precision=string]   [compression=string]   [tiledimension=XxYxZ]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

  • --overwrite — lets the output files just bulldoze any existing files in their way. no cap, it will replace them.
  • --help — prints the usage summary so you can stop guessing.
  • --verbose — verbose module output, aka the module tells you everything.
  • --quiet — quiet module output, aka the module says nothing at all. the silent treatment, but useful.
  • --ui — forces the GUI dialog to launch.

🦋 Parameters 🦋

  • input=name [required] — name of the input file you're importing. pass '-' and it reads from standard input instead, iconic.
  • output=name [required] — the name for your shiny new output 3D raster map.
  • null_value=string — the string that represents a NULL value data cell. use 'none' if there's no such value. Default: *
  • type=string — the data type used in the output raster3d map. Options: default, double, float. Default: default
  • precision=string — number of digits used as mantissa in the internal map storage. 0 -23 for float, 0 - 52 for double, max or default. Default: default
  • compression=string — the compression method used in the output raster3d map. Options: default, zip, none. Default: default
  • tiledimension=XxYxZ — the dimensions of the tiles used in the output raster3d map (XxYxZ, or default: 16x16x8). Default: default

💜 DESCRIPTION 💜

so what does r3.in.ascii actually do? it lets you create a (binary) GRASS 3D raster map layer out of a 3D ASCII raster input file. literally converting your text into a whole voxel moment. 🫶

the tiledimension parameter defines the dimension of the tiles used in the output file. the format is: XxYxZ

the nv parameter specifies which value to convert to NULL-value. if the specified value is none, no conversion is performed. Default is none.

🔥 NOTES 🔥

the data is automatically imported into the correct internal coordinate system, which is visualized in the following picture, independently from the specified ordering in the ASCII input file:

The volume coordinate system and tile layout of the imported voxel map

📦 Format 📦

the format of the 3D ASCII file:

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 option have been introduced in GRASS 7 in June 2011. the version option is self explaining. the order option specifies the row and depth order of the data in the input file. the supported row/depth ordering is documented in the r3.out.ascii manual page. the order of the data in the input file does not specify the data order in the generated output 3D raster map, which is in any case north -> south, west -> east, bottom -> top order. so dependent on the order information, the data is automatically imported into the correct internal coordinate system. ✨

the version and order options are not mandatory. in case no version and order option is specified, the default GRASS 6 ASCII format is assumed.

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.

🌈 EXAMPLES 🌈

4x3x2 sample. note: in case no specific ordering is specified in the input file, the upper-left (NW) corner of the bottom level comes first. the according order option is: nsbt for north -> south, bottom -> top ordering. this is identical with r.in.ascii for single level data. so the y coordinate is 0 at the northern edge.

north: 3.0
south: 0.0
east: 4.0
west: 0.0
top: 2.0
bottom: 0.0
rows: 3
cols: 4
levels: 2
w111x1,y1,z1  w211x2,y1,z1  w311x3,y1,z1  w411x4,y1,z1
w121x1,y2,z1  w221x2,y2,z1  w321x3,y2,z1  w421x4,y2,z1
w131x1,y3,z1  w231x2,y3,z1  w331x3,y3,z1  w431x4,y3,z1
w112x1,y1,z2  w212x2,y1,z2  w312x3,y1,z2  w412x4,y1,z2
w122x1,y2,z2  w222x2,y2,z2  w322x3,y2,z2  w422x4,y2,z2
w132x1,y3,z2  w232x2,y3,z2  w332x3,y3,z2  w432x4,y3,z2

note that unit tests for r3.in.ascii are implemented in the test.r3.out.ascii.sh script located in the r3.out.ascii directory.

🌟 EXAMPLES 🌟

please refer to the detailed examples in r3.out.ascii. 👑

👀 SEE ALSO 👀

r.in.ascii, r3.out.ascii, v.to.rast3, g.region

👑 AUTHORS 👑

Roman Waupotitsch, Michael Shapiro, Helena Mitasova, Bill Brown, Lubos Mitas, Jaro Hofierka, Sören Gebbert

💻 SOURCE CODE 💻

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

Accessed: Saturday Jan 17 05:41:14 2026

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

and that's the whole page bestie 💖 this was GRASS GIS 8.4.2, r3.in.ascii(1), and the manual was accessed Saturday Jan 17 05:41:14 2026. go import some voxels, you ate fr fr 🌸✨

📦 where this page comes from