i.pca(1grass)

✨ i.pca — like, the GRASS manual page, but make it make sense ✨

okay bestie, buckle up, because this is i.pca from the GRASS User's Manual and it's lowkey iconic 💖 It does Principal components analysis (PCA) for image processing and honestly? it's giving main character energy.

keywords: imagery, transformation, PCA, principal components analysis 🦋

---

🌸 SYNOPSIS 🌸

no cap, here's literally how you call it:

i.pca
i.pca --help
i.pca [-nf] input=name[,name,...] output=basename  [rescale=min,max]
[percent=integer]   [--overwrite]  [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags 🎀

• -n — Normalize (center and scale) input maps. The default is just centering, bestie, so this is you asking for the extra glow-up. ✨
• -f — Output will be filtered input bands. It applies inverse PCA after the PCA. so it PCA's and then un-PCA's, and yes that's the whole point, iykyk 💅
• --overwrite — Allow output files to overwrite existing files. committing crimes against your old data, love that for you 🫶
• --help — Print usage summary.
• --verbose — Verbose module output. it will not stop yapping.
• --quiet — Quiet module output. it will stop yapping.
• --ui — Force launching GUI dialog. for when the terminal is not the vibe today 🎀

💜 Parameters 💜

• input=name[,name,...] — [required] Name of two or more input raster maps or imagery group. two. or more. minimum. fr fr.
• output=basename — [required] Name for output basename raster map(s). A numerical suffix will be added for each component map, so don't @ me about the .1 .2 situation, it's automatic.
• rescale=min,max — Rescaling range for output maps. For no rescaling use 0,0. Default: 0,255.
• percent=integer — Cumulative percent importance for filtering. Options: 50-99. Default: 99.

---

💅 DESCRIPTION 💅

i.pca is an image processing program based on the algorithm provided by Vali (1990), and what it does is process n (n >= 2) input raster map layers and produce n output raster map layers containing the principal components of the input data in decreasing order of variance ("contrast"). so the spiciest component comes first. periodt.

The output raster map layers are assigned names with .1, .2, ... .n suffixes. The numbers used as suffix correspond to percent importance, with .1 being the scores of the principal component with the highest importance. so .1 is the queen 👑

The current geographic region definition and raster mask settings are respected when reading the input raster map layers. like, it's not gonna go off-region on you. When the rescale option is used, the output files are rescaled to fit the min,max range.

The order of the input bands does not matter for the output maps (PC scores), but it does matter for the vectors (loadings), since each loading refers to a specific input band. so keep your bands in an order you can actually remember, bestie 😭

If the output is not rescaled (rescale=0,0), the output raster maps will be of type DCELL, otherwise the output raster maps will be of type CELL.

By default, the values of the input raster maps are centered for each map separately with x - mean. With -n, the input raster maps are normalized for each map separately with (x - mean) / stddev. Normalizing is highly recommended when the input raster maps have different units, e.g. represent different environmental parameters. she said highly recommended, so listen 🗣️

The -f flag, together with the percent option, can be used to remove noise from input bands. Input bands will be recalculated from a subset of the principal components (inverse PCA). The subset is selected by using only the most important (highest eigenvalue) principal components which explain together percent percent variance observed in the input bands. noise? gone. deleted. not invited to the party. 🧚

---

✨ NOTES ✨

Richards (1986) gives a good example of the application of principal components analysis (PCA) to a time series of LANDSAT images of a burned region in Australia. iconic reference, go read it 🦋

Eigenvalue and eigenvector information is stored in the output maps' history files. View with r.info. it's literally sitting right there, go look 👀

---

🌈 EXAMPLE 🌈

PCA calculation using Landsat7 imagery in the North Carolina sample dataset:

g.region raster=lsat7_2002_10 -p
i.pca in=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 \
    out=lsat7_2002_pca
r.info -h lsat7_2002_pca.1
   Eigen values, (vectors), and [percent importance]:
   PC1   4334.35 ( 0.2824, 0.3342, 0.5092,-0.0087, 0.5264, 0.5217) [83.04%]
   PC2    588.31 ( 0.2541, 0.1885, 0.2923,-0.7428,-0.5110,-0.0403) [11.27%]
   PC3    239.22 ( 0.3801, 0.3819, 0.2681, 0.6238,-0.4000,-0.2980) [ 4.58%]
   PC4     32.85 ( 0.1752,-0.0191,-0.4053, 0.1593,-0.4435, 0.7632) [ 0.63%]
   PC5     20.73 (-0.6170,-0.2514, 0.6059, 0.1734,-0.3235, 0.2330) [ 0.40%]
   PC6      4.08 (-0.5475, 0.8021,-0.2282,-0.0607,-0.0208, 0.0252) [ 0.08%]
d.mon wx0
d.rast lsat7_2002_pca.1
# ...
d.rast lsat7_2002_pca.6

In this example, the first two PCAs (PCA1 and PCA2) already explain 94.31% of the variance in the six input channels. two out of six carrying the entire squad, we love an overachiever 💅✨

Resulting PCA maps calculated from the Landsat7 imagery (NC, USA) 🗺️

---

👀 SEE ALSO 👀

Richards, John A., Remote Sensing Digital Image Analysis, Springer-Verlag, 1986.

Vali, Ali R., Personal communication, Space Research Center, University of Texas, Austin, 1990.

i.cca, g.gui.iclass, i.fft, i.ifft, m.eigensystem, r.covar, r.mapcalc

Principal Components Analysis article (GRASS Wiki)

---

💖 AUTHORS 💖

David Satnik, GIS Laboratory

Major modifications for GRASS 4.1 were made by Olga Waupotitsch and Michael Shapiro, U.S.Army Construction Engineering Research Laboratory

Rewritten for GRASS 6.x and major modifications by Brad Douglas

---

🎀 SOURCE CODE 🎀

Available at: i.pca source code (history)

Latest change: Thursday May 08 14:35:40 2025 in commit: 9528b1e38ba37992c1597a979dc3efbb07b74ec5

Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index

---

and that's the whole page bestie 🫶 this was GRASS 8.5.0 (© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual) and honestly? she ate. go run some PCA, you got this 💅🌸✨