r3.in.xyz(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 r3.in.xyz 💖

okay bestie, welcome to the GRASS GIS User's Manual page for r3.in.xyz — she's a 3D raster queen and she's about to eat 💅

✨ NAME ✨

r3.in.xyz — create a 3D raster map from an assemblage of many coordinates using univariate statistics 🦋

🌈 KEYWORDS 🌈

raster3d, import, voxel, LIDAR, statistics, conversion, aggregation, binning

🎀 SYNOPSIS 🎀

r3.in.xyz
r3.in.xyz --help
r3.in.xyz [-sgi] input=name output=name  [method=string]   [type=string]
[separator=character]   [x=integer]   [y=integer]   [z=integer]
[value_column=integer]   [vrange=min,max]   [vscale=float]
[percent=integer]   [pth=integer]   [trim=float]   [workers=integer]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🚩 Flags

  • -s — scan the data file for its extent, then dip out (exit) 👋
  • -g — when you're in scan mode, print everything shell-script style 🐚
  • -i — ignore broken lines, no cap, we move on 🙈
  • --overwrite — let output files overwrite existing files, chaotic but iconic 💀
  • --help — print the usage summary 🫶
  • --verbose — verbose module output, she's chatty ✨
  • --quiet — quiet module output, she's mysterious 🤫
  • --ui — force launching the GUI dialog 🖥️

🧚 Parameters

  • input=name [required] — the ASCII file containing your input data 📄
  • output=name [required] — name for the output raster map 💾
  • method=string — which statistic to use for the raster values
    • Options: n, min, max, range, sum, mean, stddev, variance, coeff_var, median, percentile, skewness, trimmean
    • Default: mean
  • type=string — storage type for the resultant raster map
    • Options: float, double
    • Default: float
  • separator=character — the field separator
    • Special characters: pipe, comma, space, tab, newline
    • Default: pipe
  • x=integer — column number of the x coordinates in the input file (first column is 1)
    • Default: 1
  • y=integer — column number of the y coordinates in the input file
    • Default: 2
  • z=integer — column number of the z coordinates in the input file
    • Default: 3
  • value_column=integer — column number of the data values in the input file
    • If it's not given or it's set to 0, the data points' z-values get used instead
    • Default: 0
  • vrange=min,max — filter range for the value column data (min,max)
  • vscale=float — scaling factor to apply to the value column data
    • Default: 1.0
  • percent=integer — percent of map to keep in memory
    • Options: 1-100
    • Default: 100
  • pth=integer — pth percentile of the values
    • Options: 1-100
  • trim=float — discard <trim> percent of the smallest and <trim> percent of the largest observations
    • Options: 0-50
  • workers=integer — number of parallel processes to launch
    • Options: 1-256
    • Default: 1

💫 DESCRIPTION 💫

So r3.in.xyz imports sparse XYZ data from an ASCII file and turns it into a 3D raster map (aka voxels, we love a voxel moment 🧊). The way she does it: she runs the r.in.xyz module multiple times for different z-ranges, then assembles all those slices together with r.to.rast3. It's giving assembly line but make it cute.

For the general parameter usage and all the tips, go read the r.in.xyz help page, bestie, it's the blueprint fr fr.

The map gets created using the rows, columns, and depths that are set by your current region settings. So please, I'm begging you 🥺 — check and adjust those with the g.region module before you do the import. Do not skip this step. This is the vibe check.

Now, you've got options (as you should 💅). You can either use the z-value as the data value for the voxel (like with the 'n' statistic), or you can scan a whole different column for the data values you want to bin into the voxels. That alternate data column? She can be filtered by range and have a scaling factor applied to her. Versatile icon.

📝 NOTES 📝

  • The 2D and 3D horizontal region resolutions must match. No exceptions, no negotiating. Peep the EXAMPLES section below for the receipts 👀
  • Unlike r.in.xyz, reading from stdin and z-scaling are not possible. Not a thing. Can't happen. Filtering by z-range is accomplished by setting the 3D region instead.
  • Want parallel processing support? Set the workers= option to match the number of CPUs or CPU-cores available on your system. Alternatively, you can set the WORKERS environment variable to the number of concurrent processes you want. Either way, she's multitasking 💪
  • Points falling exactly on a vertical bound will belong to the depth band below them — except for points exactly on the top bound, which will belong to the top-most slice. Yes this is specific, yes it matters.
  • The script is expected to be nearly as efficient as if it was fully written in C. She's built different, and that's on periodt. 🔥

🌸 EXAMPLE 🌸

Using the Serpent Mound dataset. (see the GRASS LiDAR wiki page 🐍)

#scan dataset for extent:
r3.in.xyz -s in=Serpent_Mound_Model_LAS_Data.txt out=dummy \
   x=1 y=2 z=3 separator=space
# set the 2D and 3D regions:
g.region n=4323641.57 s=4320942.61 w=289020.90 e=290106.02 res=1 -a
g.region b=166 t=216 res3=1 tbres=5 -3 -p
r3.in.xyz in=Serpent_Mound_Model_LAS_Data.txt out=serpent3D \
   method=mean x=1 y=2 z=3 separator=space type=float

Same energy, but this time we aggregate and store the backscatter strength from column 5 into the voxels instead of the z-value. Look at her go 🌟

r3.in.xyz in=Serpent_Mound_Model_LAS_Data.txt out=serpent3D.bakscat \
   method=mean x=1 y=2 z=3 val=5 separator=space type=float

💀 KNOWN ISSUES 💀

r.to.rast3 always creates a double output map regardless of the input. Yeah. She does what she wants. Not our problem, but now it's yours too 🫠

👑 SEE ALSO 👑

g.region, r.in.xyz, r.to.rast3

💜 AUTHOR 💜

Hamish Bowman Dunedin, New Zealand 🌿

🔥 SOURCE CODE 🔥

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

Accessed: Saturday Jan 17 05:41:52 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 — GRASS 8.4.2, page r3.in.xyz(1), accessed Saturday Jan 17 05:41:52 2026, © 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual. go import something gorgeous 🦋💖✨

📦 where this page comes from