i.variance.opencl computes local (moving window) variance and related texture measures for an imagery group of any number of bands, or for a hyperspectral 3D raster such as the cubes produced by i.hyper.import. It follows the definitions published in the ERDAS Field Guide for variance, skewness, kurtosis and mean Euclidean distance, and adds a spherical (SAM) variance designed for cubes with many bands.
Three of the four ERDAS texture measures are per band: variance, skewness and kurtosis each consume one band at a time. Only mean Euclidean distance is written for a multispectral image. The aggregate option says what to do with the per band results of a group with more than one band, and method=spherical and method=sam_mean are multivariate by construction.
method=variance is the ERDAS variance, the sample variance of the cells in the window:
variance = sum((x_ij - M)^2) / (n - 1), M = sum(x_ij) / n
with n the number of non-null cells in the window. method=stddev is its square root. Note that the ERDAS IMAGINE Variance option in fact outputs the standard deviation, so method=stddev is what reproduces ERDAS output; method=variance is what the published formula states.
method=cv is the coefficient of variation, the local standard deviation over the local mean. It is the scene derived sigma the ERDAS Sigma and Lee speckle filters take as input. The Field Guide writes this quantity as VARIANCE/MEAN while calling it a standard deviation; this module uses the standard definition, sd/mean.
method=rvf is the relative variance factor, the local variance divided by the global variance of the same band over the computational region. It is dimensionless and comparable between bands and between scenes. Running it at a series of window sizes traces the local variance curve of Woodcock and Strahler (1987), whose peak indicates the dominant object size in the scene.
method=skewness and method=kurtosis are the 3rd and 4th order measures with the ERDAS normalisation:
skewness = sum((x_ij - M)^3) / ((n - 1) * V^1.5) kurtosis = sum((x_ij - M)^4) / ((n - 1) * V^2)
where V is the variance above. The kurtosis is therefore not the excess kurtosis, and a normal distribution gives roughly 3, not 0.
method=med is the ERDAS mean Euclidean distance, the only ERDAS measure that consumes every band at once:
med = sum_ij sqrt(sum_lambda (x_c,lambda - x_ij,lambda)^2) / (n - 1)
with x_c the centre cell of the window. With a single band it reduces to the mean absolute deviation from the centre cell, which is still a usable texture measure.
method=spherical is a variance in the spectral angle metric. Every spectrum is reduced to a unit vector u = x / ||x||; with R the length of the resultant sum(u) over the window,
S = 1 - R / n
which is exactly the mean of (1 - cos theta) over the window, theta being the SAM angle between a cell and the resultant direction. It is therefore the angular analogue of the ERDAS variance, with 1 - cos theta in place of the squared deviation and the resultant direction in place of M. Because R needs only the per band sums of the unit vectors, the cost is O(bands) per cell and independent of the window size, against O(window^2 x bands) for med and sam_mean. Three properties make it the measure of choice for a cube with hundreds of bands:
With units=degrees the output is the root mean square SAM angle sqrt(2S) in degrees, which is faithful up to about 20 degrees of dispersion.
method=sam_mean is the mean SAM angle between the window centre spectrum and its neighbours, the direct angular counterpart of med. It is the expensive, exact form; spherical is the one that scales.
aggregate=none writes one output map per band. aggregate=trace, the default for variance, stddev and rvf, writes one map whatever the band count: the trace of the local covariance matrix, that is the sum over bands of the per band local variance. It is the correct multivariate scalar for "how textured is this cell", it costs the same as the per band pass, and it is the recommended setting for hyperspectral data. For stddev the trace is reported as its square root, and for rvf as the trace of the local covariance divided by the trace of the global covariance.
aggregate=det is the generalized variance, the determinant of the local covariance matrix. It needs p(p+1)/2 cross products per window and is limited to 16 bands; above about 8 bands the determinant usually underflows to zero, so reduce the bands first with i.pca or a subgroup. It always runs on the host.
aggregate=trace and aggregate=det are undefined for cv, skewness and kurtosis: a sum of coefficients of variation or of skewnesses is not a meaningful quantity, so the module refuses the combination instead of inventing one. The angular measures reject aggregate altogether, being already multivariate.
size takes a list. The ERDAS Field Guide recommends a three layer variance image at 15, 31 and 61 cells displayed as RGB for geologic or vegetation discrimination (after Blom et al. 1982), which is one call:
i.variance.opencl group=scene output=var size=15,31,61
Every size is computed from the same pass over the data, so the three maps cost little more than one.
The -t flag is that recipe as a shortcut: it sets size=15,31,61 and,
unless group_output gives another name, collects the three maps into an
imagery group named after output. So the shortest useful invocation of
this module, and the quickest way to see what it does on a new scene, is
i.variance.opencl group=scene output=tex -t
which writes tex.15, tex.31, tex.61 and the group tex, ready for
r.composite, i.pca or a classifier. -t and size are mutually
exclusive.
group_output works on its own as well, with any number of sizes and
with per band output, and is the operational form: it saves naming the
maps again in the next step of a pipeline. The maps are added in the order
they are created, which is the order of size for an aggregated run, and
one pass per band with the sizes inside it for aggregate=none. An imagery
group holds 2D raster maps, so asking for one alongside a 3D raster output
is a fatal error rather than a silently empty group.
Every output name, the group included, is checked before the statistics pass. On a large cube that pass is minutes of reading, and a name clash should not cost that.
The module queries the OpenCL devices at start-up and derives a profile from the device type, unified memory, global memory, maximum allocation and compute unit count. profile=auto prefers a discrete GPU, then an integrated one, and never selects a CPU OpenCL device, because the host reference path beats GPU shaped kernels on a CPU runtime. The chosen device and the reason are printed with --verbose. A forced profile that cannot run is a fatal error, not a silent fallback.
precision=fp16 stores the band data as half for med, spherical
and sam_mean, halving the traffic of the memory bound pass; arithmetic
stays single precision through vload_half, and no cl_khr_fp16 extension
is needed. Half precision keeps about 5e-4 relative on each band value,
which propagates to roughly 5e-4 absolute on the spherical variance and
0.03 degrees on an angle. That is negligible for a cube with real spectral
dispersion, but it is an absolute floor: on a nearly collinear set of
spectra, where the spherical variance itself is of order 1e-3, it dominates.
Compare against precision=fp32 before trusting it on a given data set.
It is refused for the moment measures, where the accumulators, not the
input, set the precision.
Setting I_VARIANCE_OPENCL_PROFILE=1 prints per kernel call counts and
times, and the achieved transfer bandwidth, timed with clFinish and the
wall clock because event timestamps are wrong on some drivers.
I_VARIANCE_OPENCL_KERNELS=/path/to/kernels.cl loads the kernels from a
file instead of the copy compiled into the binary.
The moment measures standardise every band by its global mean and standard
deviation, computed in one streaming pass before the window pass. This is
not cosmetic: the raw sum(x^2) - sum(x)^2/n of DN sized values loses most
of its significant digits to cancellation in single precision. The
standardised form keeps every sum of order n, and the variance is scaled
back to data units at the end. It also makes rvf fall out directly, and
it is why a constant band is a fatal error rather than a zero map.
Window sums are separable: a horizontal pass that sums w cells per output cell feeds a vertical pass that slides over the rows at O(1) per cell. The cost is therefore independent of the window height, which is what makes a 61 x 61 window affordable. The host path uses exact summed area tables in double precision instead.
r.neighbors method=variance divides the sum of squared deviations by
n, the population variance, and rounds the result to the nearest integer.
This module divides by n - 1, the sample variance, as the ERDAS formula
states, so its output is larger by a factor n / (n - 1): 9/8 for a 3 x 3
window. Border cells differ further, because r.neighbors and this module
handle the region edge differently.
A null cell contributes nothing, not even to the count, so n is the
number of valid cells in the window and the n - 1 denominator follows it.
Cells outside the computational region are treated exactly like null cells,
so a window on the border simply sees fewer cells. min_valid sets the
percentage of the window that must be valid, below which the output cell is
null; the default is 50.
The multivariate measures are stricter about what counts: a cell contributes only if every band is non-null there, because an angle or a distance computed over a different band subset is not comparable with its neighbours. A spectrum whose Euclidean norm falls below min_norm has no direction and is treated the same way.
Whether a cell gets an output of its own when its own value is null depends on how the measure is defined, and the two cases differ:
The direction of a spectrum is still dominated by its high magnitude bands, so spherical and sam_mean are not automatically band equitable. For shape only texture, feed continuum removed input (i.hyper.continuum) or set normalize=band_stddev, which divides each band by its global standard deviation before the angle is formed.
Radiance can be negative after atmospheric correction. The angle is still defined but can exceed 90 degrees and stops being easy to interpret; the module keeps such values rather than clamping them.
The cube is read in its own cell grid with bulk block reads, which bypass window resampling. The computational 3D region may be any sub-box of the map, which is the usual way to work on a scene of a few gigavoxels, but it has to be that grid restricted to whole cells: the resolution must equal the map's in all three axes, every edge must fall on the map's cell boundaries, and the box must lie inside the map. Each of those is checked before anything is read and refused with the reason named, rather than resampled or approximated. The 2D region must also be the 3D region cell for cell, since the output rasters are written on it. Depths are the bands: depth 1 is the first band.
Note that the global per band statistics of the moment measures are taken over the computational region, so variance, stddev, cv, skewness and kurtosis on a sub-box are standardised by that box's own mean and standard deviation. The standardisation cancels in the result to within single precision — measured at 0.007 % mean and 0.2 % worst case relative difference against the same cells of a whole-map run — but rvf is by definition relative to the region's global variance and will differ between a sub-box and the whole map.
With aggregate=none and a 3D input, the output is one 3D raster per window size with the same depths as the input. With any aggregation, or with an angular measure, the output is one 2D raster per window size. Window sizes apply within each band; spatio-spectral windows with a depth of their own are not implemented.
| input and settings | output maps |
|---|---|
| one size, aggregated | <output> |
| several sizes, aggregated | <output>.<size> |
| one size, per band, group | <output>.<band> |
| several sizes, per band, group | <output>.<size>.<band> |
| per band, 3D input | one 3D raster, as the aggregated rows |
Band numbers are 1 based and follow the order of the group or subgroup. Every output name is checked for a clash before any computation starts.
The region is processed in tiles with a halo of half the largest window. The moment measures stream one band at a time and get a full width tile; the angular measures and the generalized variance need the whole spectrum resident and get a smaller tile. memory bounds both the tile and the output row buffers. A tile that would exceed the device maximum allocation is a fatal error naming the figure, so that memory can be lowered.
memory is worth raising on a large cube, because it sets how much of the
halo is wasted. On the 7284 x 8471 x 408 cube below, memory=300 leaves
room for 8 output rows per tile against a halo of 22, so 2.8 cells are read
for every cell computed; memory=2000 gives 58 rows against 72, which is
1.24. The tile itself is then 997 MB, well inside the 4 GiB maximum
allocation this Iris Xe reports.
A 3D raster is stored as compressed tiles spanning several depths at once (31 x 26 x 10 voxels on the cube below). The tile is therefore the unit of reading and of decompression, and the cost of a pass is the number of tiles it touches, not the number of voxels it uses. Both passes of this module — the global statistics and the window pass — consequently read tile aligned spatial blocks over the whole depth range and consume each tile once, rather than taking one band plane at a time, which would decompress every tile once per depth it holds. Measured on that cube:
| read pattern | per voxel | one pass over 25.2 G voxels |
|---|---|---|
| tile aligned block, all depths | 0.036 us | 0.25 h |
| one band plane at a time | 0.167 us | 1.2 h |
The z axis inside a tile is already contiguous, which is also the layout every per pixel spectral measure wants, so the two concerns agree.
Kernel time on 480000 cells (600 x 800) with 60 bands, Intel Iris Xe Graphics through the Intel compute runtime, on mains power. Kernel time only; the wall clock of a whole run at this size is a few seconds and is dominated by the GRASS raster reads, not by the compute.
| method | 15 x 15 | 31 x 31 | 61 x 61 |
|---|---|---|---|
spherical |
0.052 s | 0.072 s | 0.147 s |
variance with aggregate=trace |
0.152 s | ||
sam_mean |
0.376 s | 1.962 s | 9.93 s |
med |
9.69 s |
The vertical sliding pass is flat at 0.017 to 0.019 s across all three window sizes, which is the O(1) in the window height; the horizontal pass grows linearly with the window width. The brute force angle loop grows with the window area, so at 61 x 61 the closed form spherical variance is about 68 times faster than the same quantity measured cell by cell, and the gap widens with the window.
Asking for three window sizes in one call costs little: 15, 31 and 61 together took 3.60 s of wall clock against 3.17 s for 15 alone.
precision=fp16 is not currently a win at this scale. It halves the transferred bytes as intended, 71.1 MB against 134.2 MB, and the kernels get about 14 percent faster, but the host side conversion to half sits inside the upload and costs more than the transfer saves (0.088 s against 0.038 s here). It is worth measuring on a slow link, where the halved payload matters, and not worth it on an integrated GPU. Measure before choosing it.
g.region raster=band1 -p
i.group group=scene input=band1,band2,band3
i.variance.opencl group=scene output=tex size=15,31,61 method=stddev
r.composite red=tex.15 green=tex.31 blue=tex.61 output=tex.rgb
g.region raster_3d=emit_cube -p3
i.variance.opencl input=emit_cube output=tex size=9 method=variance
One output raster: the trace of the local covariance matrix over all bands, the default aggregation.
i.variance.opencl input=emit_cube output=sam_tex size=9 \
method=spherical units=degrees precision=fp16
for s in 3 5 9 15 23 31 45 61 ; do
i.variance.opencl group=scene output=rvf method=rvf size=$s
echo -n "$s "
r.univar -g map=rvf | grep '^mean='
done
The window size at which the mean relative variance factor peaks is the scale of the dominant objects in the scene.
i.variance.opencl group=scene output=skew size=7 method=skewness \
aggregate=none
i.variance.opencl group=scene output=dummy size=3 -g --q
i.variance.opencl group=scene output=gpu size=9 profile=auto
i.variance.opencl group=scene output=cpu size=9 profile=cpu
r.mapcalc "diff = abs(gpu - cpu)"
r.univar map=diff
i.hyper.continuum, i.hyper.import, i.pca, r.neighbors, r.texture, r.univar, r3.what
Yann Chemin
Available at: i.variance.opencl source code (history)
Accessed: Sunday Nov 15 10:57:24 2026
Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index
© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual