## 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 data file for extent then exit
-g
  In scan mode, print using shell script style
-i
  Ignore broken lines
--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

r3.in.xyz imports sparse XYZ data from an ASCII file into a 3D raster map (voxels). It does this by running the r.in.xyz module multiple times for different z-ranges and then assembling the slices with r.to.rast3.

See the r.in.xyz help page for general parameter usage and tips.

The map is created using the rows, columns, and depths set by current region settings. Be sure to check and adjust these with the g.region module before performing the import.

You may either 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. This alternate data column can be both filtered by range and have a scaling factor applied to it.

## NOTES

The 2D and 3D horizontal region resolutions must match. See the EXAMPLES section below.

Unlike r.in.xyz, reading from stdin and z-scaling are not possible. Filtering by z-range is accomplished by setting the 3D region.

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.

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.

The script is expected to be nearly as efficient as if it was fully written in C.

## 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 in 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.

## 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