GRASS logo

NAME

i.variance.opencl - Computes local (moving window) variance and related texture measures for an imagery group or a 3D raster of any number of bands.

KEYWORDS

imagery, statistics, texture, variance, hyperspectral, parallel, OpenCL

SYNOPSIS

i.variance.opencl
i.variance.opencl --help
i.variance.opencl [-tg] [group=name] [subgroup=name] [input=name] output=basename [size=integer[,integer,...]] [method=string] [aggregate=string] [normalize=string] [units=string] [min_valid=float] [min_norm=float] [profile=string] [precision=string] [group_output=name] [memory=memory in MB] [nprocs=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-t
Three layer texture stack: the same as size=15,31,61
The window sizes the ERDAS Field Guide recommends for geologic and vegetation discrimination; also collects the three maps into an imagery group named after output=, unless group_output= gives another name
-g
Print global per-band statistics in shell script style
--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:

group=name
Name of input imagery group
subgroup=name
Name of input imagery subgroup
input=name
Name of input 3D raster map (band per depth)
output=basename [required]
Base name for output maps
size=integer[,integer,...]
Moving window size(s) in cells
Odd numbers only; one output map per size, e.g. size=15,31,61
Default: 3
method=string
Local measure to compute
Options: variance, stddev, cv, rvf, skewness, kurtosis, med, spherical, sam_mean
Default: variance
variance: Sample variance in the window (ERDAS variance)
stddev: Standard deviation (what the ERDAS Variance option outputs)
cv: Coefficient of variation, local sd / local mean
rvf: Relative variance factor, local variance / global variance
skewness: Skewness, 3rd order (ERDAS normalisation)
kurtosis: Kurtosis, 4th order (ERDAS normalisation)
med: Mean Euclidean distance to the window centre, all bands
spherical: Spherical (SAM) variance 1 - R/n, all bands
sam_mean: Mean SAM angle to the window centre, all bands
aggregate=string
How to collapse a per-band measure over bands
Default: trace for method=variance, stddev and rvf, none otherwise
Options: none, trace, det
normalize=string
Per-band pre-scaling for med, spherical and sam_mean
Options: none, band_stddev
Default: none
units=string
Output units for spherical and sam_mean measures
Options: ratio, degrees
Default: ratio
min_valid=float
Minimum percentage of valid cells in the window
Options: 0-100
Default: 50
min_norm=float
Spectra with a Euclidean norm below this are treated as null
Default: 1e-6
profile=string
Device profile the compute path is tuned for
cpu runs the exact double precision host reference path
Options: auto, cpu, igpu, dgpu, egpu
Default: auto
precision=string
Device storage precision for med, spherical and sam_mean
Options: fp32, fp16
Default: fp32
group_output=name
Name of an imagery group to create from the output maps
The maps are added in the order they are created, so the window sizes appear in the order given in size=
memory=memory in MB
Maximum memory to be used (in MB)
Cache size for raster rows
Default: 300
nprocs=integer
Number of threads for parallel computing
0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
Default: 0

Table of contents

DESCRIPTION

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.

Local measures

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.

Aggregation over bands

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.

Several window sizes in one call

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.

Device adaptation

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.

NOTES

Numerical treatment

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.

Comparison with r.neighbors

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.

Null cells and the region border

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:

Band scaling for the angular measures

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.

3D raster input

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.

Output names

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.

Memory and tiling

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.

How a 3D raster is read

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 patternper voxelone pass over 25.2 G voxels
tile aligned block, all depths0.036 us0.25 h
one band plane at a time0.167 us1.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.

Measured cost

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.

EXAMPLES

ERDAS style three layer variance image

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

Total local variance of a hyperspectral cube

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.

Spectral shape texture of the same cube

i.variance.opencl input=emit_cube output=sam_tex size=9 \
    method=spherical units=degrees precision=fp16

Local variance curve for the dominant object size

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.

Per band skewness and kurtosis

i.variance.opencl group=scene output=skew size=7 method=skewness \
    aggregate=none

Global statistics only, in shell style

i.variance.opencl group=scene output=dummy size=3 -g --q

Validating the OpenCL path against the host reference

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

REFERENCES

  • ERDAS Field Guide, Fifth Edition, Revised and Expanded. ERDAS Inc., Atlanta. Chapter 5, Enhancement: Texture, Radar Imagery Enhancement; Appendix A, Math Topics: Statistics.
  • Irons, J. R. and Petersen, G. W. (1981). Texture transforms of remote sensing data. Remote Sensing of Environment 11, 359-370.
  • Blom, R. G. et al. (1982). Multispectral and texture analysis.
  • Haralick, R. M. (1979). Statistical and structural approaches to texture. Proceedings of the IEEE 67(5), 786-804.
  • Woodcock, C. E. and Strahler, A. H. (1987). The factor of scale in remote sensing. Remote Sensing of Environment 21, 311-332.
  • Mardia, K. V. and Jupp, P. E. (2000). Directional Statistics. Wiley. Spherical variance and the mean resultant length.
  • Fisher, N. I., Lewis, T. and Embleton, B. J. J. (1987). Statistical Analysis of Spherical Data. Cambridge University Press.
  • Kruse, F. A. et al. (1993). The Spectral Image Processing System (SIPS). Remote Sensing of Environment 44, 145-163. Spectral angle mapper.
  • Lee, J. S. (1981). Speckle analysis and smoothing of synthetic aperture radar images. Computer Graphics and Image Processing 17, 24-32.

SEE ALSO

i.hyper.continuum, i.hyper.import, i.pca, r.neighbors, r.texture, r.univar, r3.what

AUTHORS

Yann Chemin

SOURCE CODE

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