r.texture(1grass)

💅 r.texture — the GRASS manual, but make it make sense

okay bestie, gather round, because we're talking about r.texture from the GRASS User's Manual and honestly? it's giving texture in the most literal way possible. 🎀

NAME ✨

r.texture — Generate images with textural features from a raster map.

---

🌈 KEYWORDS 🌈

raster, algebra, statistics, texture, parallel

---

🦋 SYNOPSIS 🦋

r.texture
r.texture --help
r.texture [-san] input=name output=basename  [nprocs=integer]
[size=value]   [distance=value]   [method=string[,string,...]]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags

• -s — Separate output for each angle (0, 45, 90, 135). And the angles are counterclockwise starting from east, so 0 is East to West, and 45 is North-East to South-West. iykyk, angles have opinions.
• -a — Calculate all textural measurements. every single one. slay.
• -n — Allow NULL cells in a moving window. this one also means it will avoid cropping along edges of the current region, which is lowkey a whole bonus.
• --overwrite — Allow output files to overwrite existing files. (yes, it will absolutely eat your old file. consent first, bestie.)
• --help — Print usage summary.
• --verbose — Verbose module output.
• --quiet — Quiet module output.
• --ui — Force launching GUI dialog.

💖 Parameters

• input=name [required] — Name of input raster map.
• output=basename [required] — Name for output basename raster map(s).
• nprocs=integer — Number of threads for parallel computing. Here's the lore: 0 = use OpenMP default; >0 = use nprocs; <0 = use MAX-nprocs. Default: 0
• size=value — The size of moving window (odd and >= 3). Default: 3
• distance=value — The distance between two samples (>= 1). and no cap: the distance must be smaller than the size of the moving window. Default: 1
• method=string[,string,...] — Textural measurement method. Options: asm, contrast, corr, var, idm, sa, sv, se, entr, dv, de, moc1, moc2

---

✨ DESCRIPTION ✨

so r.texture creates raster maps with textural features from a raster map layer you specify. it figures out those textural features based on spatial dependence matrices at 0, 45, 90, and 135 degrees. four angles, four vibes, one module. 👑

Now, because texture has scale (a thing can be bumpy up close and smooth from far away, the way your life looks different from different distances 💀), r.texture lets you define the size of the moving window and the distance at which pixel grey values get compared. By default the module averages the results over all 4 orientations, but you can absolutely request the texture variables in 4 different orientations instead — that's the -s flag. 🫶

important angle lore: angles are defined in degrees of east and they increase counterclockwise, so 0 is East - West, 45 is North-East - South-West, 90 is North - South, and 135 is North-West - South-East. write that down. ✍️

You can either choose one or several texture measures (descriptions further down, bestie, keep reading) using the method parameter, or you can just request the creation of maps for all available methods with -a. no thoughts, all methods.

Now the technical tea ☕: r.texture assumes grey levels ranging from 0 to 255 as input. If the input map range is outside of this range, the input is automatically rescaled to 0 to 255. Not a suggestion, that's just what happens.

And because we want texture to actually pop instead of drowning in noise, it's recommended that you recode the data using equal-probability quantization. This reduces noise in the input data (which generally reinforces the textural features 💅) and also speeds up processing. Quantization rules for r.recode can be generated with r.quantile -r using e.g. 16 or 32 quantiles — peep the example below.

---

(part 1 done, more coming — don't go anywhere bestie 🦋)

🎀 NOTES 🎀

okay bestie, sit down, grab a snack, because this is the part where it gets good. 🍓

Texture is a feature of specific land cover classes in satellite imagery. It's particularly useful in situations where the spectral differences between classes are small, but the classes are still distinguishable by their organisation on the ground — and it's usually the natural-vs-human-made thing, yk? like cultivated fields vs meadows or golf courses, palm tree plantations vs natural rain forest. but texture can also be a natural phenomenon: dune fields, different canopies because of different tree species. 🌸

The usefulness and the actual use of texture is highly dependent on the resolution of the satellite imagery and on the scale of the human intervention (or the phenomenon that created the texture) — and yeah there's a whole discussion of scale dependency further down, we'll get there. The user should observe the phenomenon visually in order to determine an adequate setting of the size parameter. like, look at it with your eyes first, bestie. 👀

The output of r.texture can constitute very useful additional variables as input for image classification or image segmentation (object recognition). It can be used in supervised classification algorithms such as i.maxlik or i.smap, or for the identification of objects in i.segment, and/or for the characterization of these objects — so, for example, as one of the raster inputs of the i.segment.stats addon. slay. 💅

In general, several variables constitute texture: differences in grey level values, coarseness as scale of grey level differences, presence or lack of directionality and regular patterns. A texture can be characterized by tone (grey level intensity properties) and structure (spatial relationships). And since textures are highly scale dependent, hierarchical textures may occur. it's giving layers on layers. ✨

r.texture uses the common texture model based on the so-called grey level co-occurrence matrix as described by Haralick et al (1973). This matrix is a two-dimensional histogram of grey levels for a pair of pixels which are separated by a fixed spatial relationship. The matrix approximates the joint probability distribution of a pair of pixels. Several texture measures are directly computed from the Grey Level Co-occurrence Matrix (GLCM). The provided measures can be categorized under first-order and second-order statistics, with each playing a unique role in texture analysis. First-order statistics consider the distribution of individual pixel values without regard to spatial relationships, while second-order statistics — particularly those derived from the Grey Level Co-occurrence Matrix (GLCM) — consider the spatial relationship of pixels. besties, they're not the same thing and that matters. 🫶

The following part offers brief explanations of the Haralick et al texture measures (after Jensen 1996).

🌱 First-order statistics in the spatial domain 🌱

• Sum Average (SA) — Sum Average measures the average gray level intensity of the sum of pixel pairs within the moving window. It reflects the average intensity of pixel pairs at specific distances and orientations, highlighting the overall brightness level within the area.
• Entropy (ENT) — This measure analyses the randomness. It is high when the values of the moving window have similar values. It is low when the values are close to either 0 or 1 (i.e. when the pixels in the local window are uniform).
• Difference Entropy (DE) — This metric quantifies the randomness or unpredictability in the distribution of differences between the grey levels of pixel pairs. It is a measure of the entropy of the pixel-pair difference histogram, capturing texture granularity.
• Sum Entropy (SE) — Similar to Difference Entropy, Sum Entropy measures the randomness or unpredictability, but in the context of the sum of the grey levels of pixel pairs. It evaluates the entropy of the pixel-pair sum distribution, providing insight into the complexity of texture in terms of intensity variation.
• Variance (VAR) — A measure of gray tone variance within the moving window (second-order moment about the mean).
• Difference Variance (DV) — This is a measure of the variance or spread of the differences in grey levels between pairs of pixels within the moving window. It quantifies the contrast variability between pixels, indicating texture smoothness or roughness.
• Sum Variance (SV) — In contrast to Difference Variance, Sum Variance measures the variance of the sum of grey levels of pixel pairs. It assesses the variability in the intensity levels of pairs of pixels, contributing to an understanding of texture brightness or intensity variation.

💡 heads up: the measures mean, kurtosis, range, skewness, and standard deviation are available in r.neighbors. not here. different tool, different vibe.

👑 Second-order statistics in the spatial domain 👑

The second-order statistics texture model is based on the so-called grey level co-occurrence matrices (GLCM; after Haralick 1979).

• Angular Second Moment (ASM, also called Uniformity) — This is a measure of local homogeneity and the opposite of Entropy. High values of ASM occur when the pixels in the moving window are very similar.
  • Note: The square root of the ASM is sometimes used as a texture measure, and is called Energy.
• Inverse Difference Moment (IDM, also called Homogeneity) — This measure relates inversely to the contrast measure. It is a direct measure of the local homogeneity of a digital image. Low values are associated with low homogeneity and vice versa.
• Contrast (CON) — This measure analyses the image contrast (locally gray-level variations) as the linear dependency of grey levels of neighboring pixels (similarity). Typically high, when the scale of local texture is larger than the distance.
• Correlation (COR) — This measure analyses the linear dependency of grey levels of neighboring pixels. Typically high, when the scale of local texture is larger than the distance.
• Information Measures of Correlation (MOC) — These measures evaluate the complexity of the texture in terms of the mutual dependence between the grey levels of pixel pairs. They quantify how one pixel value informs or correlates with another, offering insight into pattern predictability and structure regularity.
• Maximal Correlation Coefficient (MCC) — This statistic measures the highest correlation between any two features of the texture, providing a single value that summarizes the degree of linear dependency between grey levels in the texture. It's often used to assess the overall correlation in the image, indicating how predictable the texture patterns are from one pixel to the next.

---

okay so the computational region? 💖 It should be set to the input map with g.region raster=<input map>, or aligned to the input map with g.region align=<input map> if only a subregion should be analyzed. get that region right or your numbers are gonna be a mess, no cap.

⚠️ Note that the output of r.texture will always be smaller than the current region, because only cells for which there are no null cells and for which all cells of the moving window are within the current region will contain a value. So the output will thus appear cropped at the margins. that's not a bug bestie that's just the geometry. 😭

🚨 and very importantly: the input raster map cannot have more than 255 categories. that's the ceiling. periodt.

⚡ Performance ⚡

To enable parallel processing, the user can specify the number of threads to be used with the nprocs parameter (default 1). Figures below show benchmark results running on Intel® Core™ i9-10940X CPU @ 3.30GHz. See benchmark scripts in the source code for more details. 🔥

• Figure 1: Benchmark shows execution time for different number of cells (1M, 2M, 4M, and 8M) and the fixed size of window (3×3).
• Figure 2: Benchmark shows efficiency for different numbers of cells (1M, 2M, 4M, and 8M) and the fixed size of window (3×3).
• Figure 3: Benchmark shows execution time for different sizes of windows (3×3, 9×9, 15×15, and 27×27) and the fixed number of cells (1M).
• Figure 4: Benchmark shows efficiency for different sizes of windows (3×3, 9×9, 15×15, and 27×27) and the fixed number of cells (1M).

go off, nprocs. 👑

---

🌈 EXAMPLE 🌈

Calculation of Angular Second Moment of B/W orthophoto (North Carolina data set):

g.region raster=ortho_2001_t792_1m -p
# set grey level color table 0% black 100% white
r.colors ortho_2001_t792_1m color=grey
# extract grey levels
r.mapcalc "ortho_2001_t792_1m.greylevel = ortho_2001_t792_1m"
# texture analysis
r.texture ortho_2001_t792_1m.greylevel output=ortho_texture method=asm -s
# display
g.region n=221461 s=221094 w=638279 e=638694
d.shade color=ortho_texture_ASM_0 shade=ortho_2001_t792_1m

This calculates four maps (requested texture at four orientations): ortho_texture_ASM_0, ortho_texture_ASM_45, ortho_texture_ASM_90, ortho_texture_ASM_135. four directions, one tmp era of output. 💅

Reducing the number of gray levels (equal-probability quantizing):

g.region -p raster=ortho_2001_t792_1m
# enter as one line or with \
r.quantile input=ortho_2001_t792_1m quantiles=16 -r | r.recode \
           input=ortho_2001_t792_1m output=ortho_2001_t792_1m_q16 rules=-

The recoded raster map can then be used as input for r.texture as before. 🦋

Second example: analysis of IDM (homogeneity) on a simple raster with North-South line pattern.

# import raster
r.in.ascii in=- output=lines << EOF
north: 9
south: 0
east: 9
west: 0
rows: 9
cols: 9
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
0 0 0 1 0 0 0 1 0
EOF
# adjust region to raster
g.region raster=lines
# calculate IDM (homogeneity) in all directions
r.texture -s lines method=idm output=text_lines

The following image shows the original map, the result in East-West direction and the result in North-South direction, showing how texture can depend on direction, with texture perfectly homogeneous (value=1) in the North-South direction, but quite heterogeneous in East-West direction — except for those areas where there are three columns of equal values (as size=3). The overlaid grid highlights that the texture measures output maps are cropped at the margins. 🌸

IDM textures according to direction

✨ REFERENCES ✨

okay so the lore of where this algorithm actually came from 💖 The algorithm was implemented after Haralick et al., 1973 and 1979.

The original code was taken by permission from pgmtexture, part of PBMPLUS (Copyright 1991, Jef Poskanser and Texas Agricultural Experiment Station, employer for hire of James Darrell McCauley). Manual page of pgmtexture. Over the years, the source code of r.texture was further improved. glow-up of the century fr fr 👑

• Haralick, R.M., K. Shanmugam, and I. Dinstein (1973). Textural features for image classification. IEEE Transactions on Systems, Man, and Cybernetics, SMC-3(6):610-621.
• Bouman, C. A., Shapiro, M. (1994). A Multiscale Random Field Model for Bayesian Image Segmentation, IEEE Trans. on Image Processing, vol. 3, no. 2.
• Jensen, J.R. (1996). Introductory digital image processing. Prentice Hall. ISBN 0-13-205840-5
• Haralick, R. (May 1979). Statistical and structural approaches to texture, Proceedings of the IEEE, vol. 67, No.5, pp. 786-804
• Hall-Beyer, M. (2007). The GLCM Tutorial Home Page (Grey-Level Co-occurrence Matrix texture measurements). University of Calgary, Canada

---

🌈 SEE ALSO

the whole friend group, no cap 💅

i.maxlik, i.gensig, i.smap, i.gensigset, i.segment.stats, i.pca, r.neighbors, r.rescale

---

👑 AUTHORS

give it up for the devs, they ate 🫶

G. Antoniol - RCOST (Research Centre on Software Technology - Viale Traiano - 82100 Benevento) C. Basco - RCOST (Research Centre on Software Technology - Viale Traiano - 82100 Benevento) M. Ceccarelli - Facolta di Scienze, Universita del Sannio, Benevento Markus Metz (correction and optimization of the initial version) Moritz Lennert (documentation)

---

🧚 SOURCE CODE

Available at: r.texture source code (history)

Latest change: Friday Jun 13 01:23:55 2025 in commit: 110ff3393c6ad8028dadae27ba776d469e03e6d8

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

---

and that's the whole page bestie, you made it to the end 🎀 this was GRASS 8.5.0, page r.texture(1grass) — go texture something gorgeous, ily, bye 💖✨🦋