r3.in.xyz
Create a 3D raster map from an assemblage of many coordinates using univariate statistics
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] [--verbose] [--quiet] [--qq] [--ui]
Example:
r3.in.xyz input=name output=name
grass.script.run_command("r3.in.xyz", input, output, method="mean", type="float", separator="pipe", x=1, y=2, z=3, value_column=0, vrange=None, vscale=1.0, percent=100, pth=None, trim=None, workers=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("r3.in.xyz", input="name", output="name")
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
Allowed values: n, min, max, range, sum, mean, stddev, variance, coeff_var, median, percentile, skewness, trimmean
Default: mean
type=string
Storage type for resultant raster map
Allowed values: 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
Allowed values: 1-100
Default: 100
pth=integer
pth percentile of the values
Allowed values: 1-100
trim=float
Discard <trim> percent of the smallest and <trim> percent of the largest observations
Allowed values: 0-50
workers=integer
Number of parallel processes to launch
Allowed values: 1-256
Default: 1
-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
--qq
Very quiet module output
--ui
Force launching GUI dialog
input : str, required
ASCII file containing input data
Used as: input, file, name
output : str, required
Name for output raster map
Used as: output, 3d-raster, name
method : str, optional
Statistic to use for raster values
Allowed values: n, min, max, range, sum, mean, stddev, variance, coeff_var, median, percentile, skewness, trimmean
Default: mean
type : str, optional
Storage type for resultant raster map
Allowed values: float, double
Default: float
separator : str, optional
Field separator
Special characters: pipe, comma, space, tab, newline
Used as: input, separator, character
Default: pipe
x : int, optional
Column number of x coordinates in input file (first column is 1)
Default: 1
y : int, optional
Column number of y coordinates in input file
Default: 2
z : int, optional
Column number of z coordinates in input file
Default: 3
value_column : int, optional
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 : tuple[float, float] | list[float] | str, optional
Filter range for value column data (min,max)
Used as: min,max
vscale : float, optional
Scaling factor to apply to value column data
Default: 1.0
percent : int, optional
Percent of map to keep in memory
Allowed values: 1-100
Default: 100
pth : int, optional
pth percentile of the values
Allowed values: 1-100
trim : float, optional
Discard <trim> percent of the smallest and <trim> percent of the largest observations
Allowed values: 0-50
workers : int, optional
Number of parallel processes to launch
Allowed values: 1-256
Default: 1
flags : str, optional
Allowed values: s, g, i
s
Scan data file for extent then exit
g
In scan mode, print using shell script style
i
Ignore broken lines
overwrite: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
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: Friday Feb 07 19:16:09 2025 in commit a82a39f