r3.in.xyz(1grass)

r3.in.xyz 💖

okay bestie, welcome to the GRASS User's Manual entry for r3.in.xyz(1grass) — she's a 3D raster builder and she EATS point clouds for breakfast. Strap in 🎀

✨ NAME ✨

r3.in.xyz — bestie, this makes a 3D raster map out of an assemblage of many coordinates using univariate statistics. literally turns your messy pile of points into voxels. iconic behavior tbh 🦋

🔑 KEYWORDS 🔑

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

(iykyk — she's the LIDAR girlie 🌸)

📜 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 data file for extent then exit. no cap, she just peeks and dips 👀
• -g — In scan mode, print using shell script style
• -i — Ignore broken lines. messy input? we simply do not perceive it 💅
• --overwrite — Allow output files to overwrite existing files
• --help — Print usage summary
• --verbose — Verbose module output
• --quiet — Quiet module output
• --ui — Force launching GUI dialog

🎛️ Parameters

• input=name [required] — ASCII file containing input data
• output=name [required] — Name for output raster map
• method=string — Statistic to use for raster values
  • Options: n, min, max, range, sum, mean, stddev, variance, coeff_var, median, percentile, skewness, trimmean
  • Default: mean
• type=string — Storage type for resultant raster map
  • Options: float, double
  • Default: float
• separator=character — Field separator
  • Special characters: pipe, comma, space, tab, newline
  • Default: pipe
• x=integer — Column number of x coordinates in input file (first column is 1)
  • Default: 1
• y=integer — Column number of y coordinates in input file
  • Default: 2
• z=integer — Column number of z coordinates in input file
  • Default: 3
• value_column=integer — Column number of data values in input file
  • If not given or set to 0, the data points' z-values are used
  • Default: 0
• vrange=min,max — Filter range for value column data (min,max)
• vscale=float — Scaling factor to apply to 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 💜

okay so here's the tea ☕ r3.in.xyz imports sparse XYZ data from an ASCII file into a 3D raster map (aka voxels). the way she does it?? she runs the r.in.xyz module multiple times for different z-ranges and then assembles the slices with r.to.rast3. queen of delegation, honestly 👑

if you want the general parameter usage and tips, go read the r.in.xyz help page — she's the blueprint, fr fr.

the map gets created using the rows</>, columns</>, and depths</> set by current region settings. so bestie, PLEASE check and adjust those with the g.region module before you do the import. do not skip this step, I am begging 🙈

you've got two vibes to choose from:

• use the z-value as the data value for the voxel (e.g. with the 'n' statistic), or
• alternately, scan another column for the data values to bin into the voxels.

that alternate data column can be both filtered by range and have a scaling factor applied to it. versatility?? she has it 🌈

---

📝 NOTES 📝

• the 2D and 3D horizontal region resolutions must match. no wiggle room. see the EXAMPLES section below 👇
• unlike r.in.xyz, reading from stdin and z-scaling are not possible. filtering by z-range gets accomplished by setting the 3D region instead.
• to enable parallel processing support, set the workers= option to match the number of CPUs or CPU-cores available on your system. alternatively, the WORKERS environment variable can be set to the number of concurrent processes desired. girl loves 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. edge cases stay winning ✨
• the script is expected to be nearly as efficient as if it was fully written in C. she's fast AND cute, we love that for her 🚀

---

🌟 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

the same, but aggregate and store backscatter strength from column 5 into voxels instead of the z-value:

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 input. yeah. she does that. not our fault bestie, we just live here 😭

---

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

Latest change: Tuesday Oct 21 09:57:14 2025 in commit: fb0165c2d021b7700528aca09c224847be871729

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

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

---

and that's the whole page bestie, tysm for reading 🫶 this was the r3.in.xyz(1grass) manual straight out of the GRASS 8.5.0 world — go make some voxels, you're gonna slay 💖✨🌈