GRASS logo

NAME - Create a 3D raster map from an assemblage of many coordinates using univariate statistics


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

SYNOPSIS --help [-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]


Scan data file for extent then exit
In scan mode, print using shell script style
Ignore broken lines
Allow output files to overwrite existing files
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


input=name [required]
ASCII file containing input data
output=name [required]
Name for output raster map
Statistic to use for raster values
Options: n, min, max, range, sum, mean, stddev, variance, coeff_var, median, percentile, skewness, trimmean
Default: mean
Storage type for resultant raster map
Options: float, double
Default: float
Field separator
Special characters: pipe, comma, space, tab, newline
Default: pipe
Column number of x coordinates in input file (first column is 1)
Default: 1
Column number of y coordinates in input file
Default: 2
Column number of z coordinates in input file
Default: 3
Column number of data values in input file
If not given or set to 0, the data points' z-values are used
Default: 0
Filter range for value column data (min,max)
Scaling factor to apply to value column data
Default: 1.0
Percent of map to keep in memory
Options: 1-100
Default: 100
pth percentile of the values
Options: 1-100
Discard <trim> percent of the smallest and <trim> percent of the largest observations
Options: 0-50
Number of parallel processes to launch
Options: 1-256
Default: 1

Table of contents

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

See the 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.


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

Unlike, 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.


Using the Serpent Mound dataset. (see the GRASS LiDAR wiki page)
  #scan dataset for extent: -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 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: 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 always creates a double output map regardless of input.




Hamish Bowman
Dunedin, New Zealand


Available at: source code (history)

Latest change: Thursday Feb 03 11:10:06 2022 in commit: 547ff44e6aecfb4c9cbf6a4717fc14e521bec0be

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

© 2003-2024 GRASS Development Team, GRASS GIS 8.3.3dev Reference Manual