GRASS logo

NAME

i.hyper.atcorr - Atmospheric correction of hyperspectral 3D raster radiance imagery using the 6SV2.1 radiative transfer algorithm.

KEYWORDS

imagery, atmospheric correction, radiative transfer, 6SV, LUT, hyperspectral

SYNOPSIS

i.hyper.atcorr
i.hyper.atcorr --help
i.hyper.atcorr [-urawzpmPeD] [input=name] [output=name] [lut=string] [sza=float] [vza=float] [raa=float] [altitude=float] [atmosphere=string] [aerosol=string] [mie_r=float] [mie_sigma=float] [mie_mr=float] [mie_mi=float] [ozone=float] [brdf=string] [brdf_params=string] [aod=string] [h2o=string] [wl_min=float] [wl_max=float] [wl_step=float] [doy=integer] [aod_val=float] [h2o_val=float] [aod_map=name] [h2o_map=name] [smooth=float] [adj_psf=float] [pixel_size=float] [uncertainty=name] [oe_sigma_aod=float] [oe_sigma_h2o=float] [maiac_patch=integer] [quality=name] [dem=name] [slope=name] [aspect=name] [sun_azimuth=float] [view_zenith=name] [view_azimuth=name] [brdf_fiso=name] [brdf_fvol=name] [brdf_fgeo=name] [mcd43_fiso=string] [mcd43_fvol=string] [mcd43_fgeo=string] [mcd43_alpha=float] [dasf=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-u
Compute per-band reflectance uncertainty
Propagates instrument noise and AOD uncertainty through the inversion. Stores σ_rfl per pixel per band. Write to Raster3D with uncertainty= option.
-r
Apply surface prior MAP regularisation
After inverting all bands, blends retrieved reflectance with a 3-component Gaussian mixture surface prior (vegetation/soil/water) using diagonal MAP estimation. Requires loading the full cube into memory. Uses per-band model discrepancy as uncertainty floor (#6).
-a
Retrieve AOD from Dark Dense Vegetation (DDV)
Estimates per-pixel AOD at 550 nm from dark vegetated pixels (MODIS dark-target: 470/660/860/2130 nm bands). Updates aod_val= and provides a per-pixel AOD map. Requires input= with wavelength metadata.
-w
Retrieve column water vapour from 940 nm absorption
Estimates per-pixel WVC [g/cm²] from the 940 nm band depth (continuum interpolation: 865/940/1040 nm). Provides a per-pixel H2O map for correction. Requires input= with wavelength metadata.
-z
Retrieve O3 column from Chappuis absorption
Estimates scene-mean ozone [DU] from 600 nm band depth (continuum: 540/600/680 nm). Updates the ozone= value used in LUT computation. Requires input= with wavelength metadata.
-p
Retrieve per-pixel surface pressure from O₂-A band (760 nm)
Estimates per-pixel surface pressure [hPa] from the O₂-A band depth (continuum: 740/760/780 nm). Applies per-pixel Rayleigh scaling to R_atm, T_down, T_up. K_O2=0.25 calibrated to ~10 nm FWHM sensors. Requires input= with wavelength metadata.
-m
Compute pre-correction cloud / shadow / water / snow bitmask
Classifies each pixel using TOA reflectance thresholds (cloud: blue>0.25 AND NDVI<0.2; shadow: VIS+NIR<0.04; water: NIR<0.05; snow: NDSI>0.4). Output written to quality= map; the mask is diagnostic and is not used to filter atmospheric retrievals. Requires input= with wavelength metadata.
-P
Enable vector (Stokes I,Q,U) radiative transfer
Use sixs_ospol() instead of sixs_os() for the atmospheric RT. Propagates all three Stokes components simultaneously, improving the atmospheric path reflectance R_atm by 1–5% in blue bands (Rayleigh polarisation feedback). Approximately 3× slower than scalar RT. Built-in aerosol models use their full 6SV I/Q/U phase matrices; aerosol=custom is scalar only.
-e
Joint AOD + H₂O optimal-estimation retrieval
Per-pixel MAP grid-search inversion of AOD and column water vapour using spectral smoothness (VIS) and H₂O band-depth (NIR) constraints. Supersedes independent -a and -w retrievals when used together. Requires input= with wavelength metadata and a pre-computed LUT.
-D
Retrieve DASF (canopy angular structure) to dasf= raster
Accumulates per-pixel Directional Area Scattering Factor from corrected surface reflectance in the 710–790 nm NIR plateau. Output is written to the dasf= 2-D raster. Requires output= for per-pixel corrected BRF. Non-vegetation pixels (NDVI < 0.2) are masked to NaN.
--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:

input=name
Input radiance 3D raster map
TOA radiance per µm or per nm; wavelengths and units are read from hyperspectral metadata (nm, µm, or cm-1)
output=name
Output surface reflectance 3D raster map
Name for output 3D raster map
lut=string
Output LUT binary file
Binary LUT (*.lut) with R_atm, T_down, T_up, s_alb on an [AOD × H2O × wavelength] grid
sza=float
Solar zenith angle (0–89°, required if no metadata, overrides metadata)
vza=float
View zenith angle (0–60°, default: 0, overrides metadata)
raa=float
Relative azimuth angle (default: 0°, overrides metadata)
altitude=float
Observer altitude in km (<=0 ground, 0–100 aircraft, >=100 satellite; default: 1000; overrides metadata)
atmosphere=string
Standard atmosphere model (default: us62)
Options: us62, midsum, midwin, tropical, subsum, subwin
aerosol=string
Aerosol model (default: continental; use 'custom' with mie_r/mie_sigma/mie_mr/mie_mi)
Options: none, continental, maritime, urban, desert, custom
mie_r=float
Custom Mie: log-normal mode radius [µm] (AERONET fine-mode r_eff~0.10-0.15)
Default: 0.10
mie_sigma=float
Custom Mie: geometric standard deviation σ_g (typical 1.4-1.8)
Default: 1.50
mie_mr=float
Custom Mie: real refractive index at 550 nm (dust~1.55, carbon~1.75, marine~1.38)
Default: 1.45
mie_mi=float
Custom Mie: imaginary refractive index at 550 nm (absorbing 0.01-0.05, scattering <0.005)
Default: 0.005
ozone=float
Total ozone column in DU (default: 300, overrides metadata)
brdf=string
Surface BRDF model (default: lambertian)
Options: lambertian, rahman, roujean, hapke, ocean, walthall, minnaert, rosslimaignan
Default: lambertian
brdf_params=string
BRDF model parameters (comma-separated floats)
Up to 5 comma-separated floats for the chosen BRDF model:
lambertian: rho0
rahman: rho0, af, k
roujean: k0, k1, k2
hapke: om, af, s0, h
ocean: wspd_ms, azw_deg, sal_ppt, pcl_mgl
walthall: a, ap, b, c
minnaert: k, b
rosslimaignan: f_iso, f_vol, f_geo
aod=string
AOD at 550 nm grid (comma-separated)
Default: 0.0,0.05,0.1,0.2,0.4,0.8
h2o=string
Column water vapour grid in g/cm² (comma-separated)
Default: 0.5,1.0,1.5,2.0,3.5,5.0
wl_min=float
Minimum wavelength (nm, default: 400)
Default: 400
wl_max=float
Maximum wavelength (nm, default: 2500)
Default: 2500
wl_step=float
Wavelength step (nm, default: 10)
Default: 10
doy=integer
Day of year (1–366, default: 180, overrides metadata)
aod_val=float
Scene AOD at 550 nm (default: 0.1, overrides metadata)
h2o_val=float
Column water vapour g/cm² (default: 2.0, overrides metadata)
aod_map=name
Per-pixel AOD raster (overrides aod_val= where non-null)
2-D raster of AOD at 550 nm
h2o_map=name
Per-pixel water vapour raster (overrides h2o_val= where non-null)
2-D raster of column water vapour in g/cm²
smooth=float
Gaussian smoothing σ in pixels (default: 0 = disabled)
Spatially smooths aod_map= and h2o_map= before correction. 0 = disabled. Typical value: 2–5 pixels.
Default: 0
adj_psf=float
Adjacency PSF radius in km (default: 0 = disabled)
Environmental PSF radius for Vermote 1997 adjacency correction. Typical value: 0.5–2 km. 0 = disabled.
Default: 0
pixel_size=float
Pixel size in metres (default: 0 = auto-detect)
Default: 0
uncertainty=name
Output uncertainty 3D raster map (requires -u flag)
Name for output 3D raster map
oe_sigma_aod=float
OE prior uncertainty for log(AOD)
Controls how strongly the OE solution is pulled toward aod_val=. 0.5 = broad prior (±50% in log-AOD space); 0.2 = tight constraint.
Default: 0.5
oe_sigma_h2o=float
OE prior uncertainty for H₂O [g/cm²]
Controls H₂O prior strength. 1.0 = broad (±1 g/cm²); 0.5 = tight.
Default: 1.0
maiac_patch=integer
MAIAC patch size for AOD spatial regularization (pixels; 0=disabled)
After DDV retrieval (-a), divides the image into non-overlapping patches of this size and replaces each patch AOD with the patch median. Non-DDV patches are filled by inverse-distance weighting. Typical: 32 pixels for 30 m imagery; 16 for 5 m imagery.
Default: 0
quality=name
Output 2-D quality bitmask raster (requires -m flag)
Per-pixel quality bitmask: bit 0=cloud, bit 1=shadow, bit 2=water, bit 3=snow/ice. Written as integer raster.
dem=name
DEM raster for surface pressure retrieval
2-D elevation raster [m above sea level]. Scene-mean elevation → ISA pressure, overriding standard-atmosphere sea-level pressure in LUT computation.
slope=name
Terrain slope raster [degrees]
2-D raster of terrain slope in degrees. When combined with aspect=, enables per-pixel terrain illumination correction (Cosine model: direct irradiance scaled by cos_i/cos_sza, diffuse by the skyview factor).
aspect=name
Terrain aspect raster [degrees, CW from North]
2-D raster of terrain aspect in degrees clockwise from North. Must be provided together with slope=.
sun_azimuth=float
Solar azimuth °CW from N (default: 180, overrides metadata)
Used for terrain illumination (cos_incidence) and NBAR relative azimuth computation. Typically from r.sunmask or scene metadata.
view_zenith=name
Per-pixel view zenith angle raster [degrees]
2-D raster of per-pixel view zenith angles. Used for T_up Beer-Lambert path-length scaling in terrain correction. Falls back to scalar vza= when not provided.
view_azimuth=name
Per-pixel view azimuth angle raster [degrees, CW from North]
2-D raster of per-pixel view azimuth angles. Used to compute relative azimuth for NBAR normalization.
brdf_fiso=name
MCD43 f_iso kernel weight raster
Ross-Li isotropic kernel weight from MODIS MCD43A1. When all three kernel weights (brdf_fiso=, brdf_fvol=, brdf_fgeo=) are provided, output reflectance is NBAR-normalized to nadir view using standard MODIS Ross-Thick + Li-Sparse kernels.
brdf_fvol=name
MCD43 f_vol kernel weight raster
Ross-Thick volumetric kernel weight from MODIS MCD43A1.
brdf_fgeo=name
MCD43 f_geo kernel weight raster
Li-Sparse geometric kernel weight from MODIS MCD43A1.
mcd43_fiso=string
MCD43 f_iso at 7 MODIS bands (469,555,645,858,1240,1640,2130 nm)
Seven comma-separated f_iso kernel weights from MCD43A1 at the 7 MODIS bands. Used to disaggregate the isotropic kernel weight to the full hyperspectral range via piecewise-linear interpolation + Tikhonov smoothing (FlexBRDF).
mcd43_fvol=string
MCD43 f_vol at 7 MODIS bands
Seven comma-separated f_vol (RossThick volumetric) kernel weights.
mcd43_fgeo=string
MCD43 f_geo at 7 MODIS bands
Seven comma-separated f_geo (LiSparse geometric) kernel weights.
mcd43_alpha=float
Tikhonov smoothing strength for MCD43 disaggregation
Controls spectral smoothness of the disaggregated kernel weights. 0.0 = no smoothing (piecewise-linear only); ~0.1 = gentle smoothing (recommended). Larger values increase spectral smoothness.
Default: 0.10
dasf=name
Output 2-D DASF raster (requires -D flag)
Directional Area Scattering Factor: regresses per-pixel corrected BRF against PROSPECT-D leaf albedo over 710–790 nm. Output range [0.01, 1.0]; NaN for non-vegetation (NDVI < 0.2). Knyazikhin et al. (2013) PNAS 110, E185-E192.

Table of contents

DESCRIPTION

i.hyper.atcorr performs atmospheric correction of a hyperspectral 3D raster map. The input is calibrated top of atmosphere spectral radiance. The output is unitless bottom of atmosphere surface reflectance.

The module uses the 6SV2.1 radiative transfer model to compute a lookup table over aerosol optical depth (AOD) at 550 nm, column water vapour, and wavelength. It converts radiance to top of atmosphere reflectance using the acquisition day, solar zenith angle, and solar irradiance spectrum, then interpolates the lookup table to invert surface reflectance.

The lut option writes the table computed by the current invocation. It is output-only and is never read as correction input. A lookup table can be written without correcting a raster. Correction requires both input and output; lut may additionally save the table used by that correction.

Atmospheric conditions can be supplied as scene values with aod_val and h2o_val, or as raster maps with aod_map and h2o_map. Raster map values take precedence over scene values where they are not null. The atmospheric maps can be smoothed before correction.

The module can estimate selected atmospheric quantities from suitable input bands. It can also apply adjacency, terrain illumination, and surface anisotropy corrections. Optional outputs include reflectance uncertainty, a quality mask, and the directional area scattering factor (DASF).

OPTIONS

The aod and h2o options define the lookup table axes. The default H2O grid is 0.5,1.0,1.5,2.0,3.5,5.0 g/cm2. The scene fallback h2o_val defaults to 2.0 g/cm2. The wavelength axis is defined by wl_min, wl_max, and wl_step in nanometres. The axes should cover input wavelengths and expected atmospheric values.

The atmosphere can be represented by a standard profile selected with atmosphere. The aerosol model is selected with aerosol. aerosol=desert selects the complete background desert model (BDM), including its optical properties and phase matrices. When aerosol=custom is used, mie_r, mie_sigma, mie_mr, and mie_mi define a log-normal spherical Mie aerosol.

The altitude option is sensor altitude in kilometres. Values less than or equal to zero select ground mode. Values greater than zero and less than 100 select aircraft mode and use partial Rayleigh, aerosol, and gas columns between target and sensor. Values greater than or equal to 100 select satellite mode and use the full atmospheric column. The default is 1000 km.

Flag -P enables vector radiative transfer. The built-in aerosol choices none, continental, maritime, urban, and desert use the complete available polarization phase-matrix data. Combining -P with aerosol=custom is rejected because custom Mie polarization is unsupported. The vector solver propagates Stokes I, Q, and U internally so polarization feeds back into Stokes I. The module uses the resulting Stokes-I path reflectance but does not output Q or U.

Flags -a, -w, and -z estimate AOD, water vapour, and ozone from the input map. Flag -p estimates surface pressure from the oxygen A band. Flag -e performs a joint AOD and water vapour retrieval. These operations require wavelength metadata and suitable input bands. The dem option instead uses mean terrain elevation to set surface pressure for lookup table computation. Image-based retrievals remain dependent on scene content, metadata, model choices, and configured lookup table ranges; they are not a general standalone replacement for ancillary atmospheric information.

The slope and aspect raster maps enable terrain illumination correction and must be supplied together. The sun_azimuth option or supported scene metadata supplies solar azimuth. Per-pixel view geometry can be given with view_zenith for terrain path-length correction and with view_zenith and view_azimuth for BRDF normalization.

The brdf_fiso, brdf_fvol, and brdf_fgeo raster maps enable nadir BRDF adjusted reflectance normalization and must all be supplied. The mcd43_fiso, mcd43_fvol, and mcd43_fgeo options provide spectral MCD43 kernel weights and must also be supplied together. All MCD43 raster and comma-separated inputs must already have the product scale factor applied. The module does not apply a 0.001 scale factor.

Flag -u computes reflectance uncertainty, written when uncertainty is specified. Flag -m computes the bitmask written with quality. The quality mask is an output product only and is not applied to mask or null the corrected reflectance cube. Flag -D computes DASF and writes it with dasf. Flag -r applies surface prior regularisation and requires the complete reflectance cube to be held in memory.

The quality output is a 2-D integer raster whose category values describe the pre-correction scene classes. Each pixel's value may combine several classes (1 = cloud, 2 = shadow, 4 = water, 8 = snow/ice, summed). The mask is diagnostic only and is not applied to null or clip the reflectance cube. The module currently writes the map without a category table; assign labels with r.category if desired.

CategoryMeaning
0No class detected (clear)
1Cloud
2Shadow
3Cloud + Shadow
4Water
5Cloud + Water
6Shadow + Water
7Cloud + Shadow + Water
8Snow / ice
9Cloud + Snow / ice
10Shadow + Snow / ice
11Cloud + Shadow + Snow / ice
12Water + Snow / ice
13Cloud + Water + Snow / ice
14Shadow + Water + Snow / ice
15All classes

RADIATIVE TRANSFER

The lookup table stores four effective inversion coefficients at every grid point: gas-weighted atmospheric path reflectance R_atm, total downward transmittance T_down, gas-weighted total upward transmittance T_up, and atmospheric spherical albedo s_alb.

R_atm is not gas-free path reflectance. Its aerosol and multiple-scattering part and its Rayleigh part are weighted by their applicable gas transmittances. Similarly, the stored upward coefficient is T_up_sca * T_gas,total / T_gas,down, while the stored downward coefficient is T_down_sca * T_gas,down. Their product therefore includes total gas absorption over the complete Sun-surface-sensor path.

For a Lambertian surface, the inversion is

rho_toa = pi * L * d2 / (E0 * cos(sza))
y = (rho_toa - R_atm) / (T_down * T_up)
rho_boa = y / (1 + s_alb * y)

where L is radiance per micrometre, d2 is squared Earth-Sun distance, and E0 is solar spectral irradiance. The spherical-albedo denominator uses y, not the unknown rho_boa on its right-hand side.

Automatic libRadtran/reptran spectral response function correction is disabled and unsupported. Its gas parameterization cannot be multiplied into the current 6SV effective coefficients consistently. Support remains pending a mathematically consistent integration into R_atm, T_down, and T_up.

NOTES

Radiometric metadata may declare spectral radiance per nanometre or per micrometre. Per-nanometre values are multiplied by 1000; per-micrometre values are unchanged, giving internal W m-2 sr-1 um-1. Missing radiometric units produce a warning and are assumed to be per micrometre. Reflectance input and other unsupported radiometric units are rejected.

Band centre and FWHM metadata may use nm, um, or cm-1. Nanometres are divided by 1000 and micrometres are unchanged. Wavenumber centres are converted as wavelength_um = 10000 / wavenumber_cm-1; wavenumber FWHM is converted as fwhm_um = 10000 * fwhm_cm-1 / wavenumber_cm-1^2. Missing wavelength units default to nm. Unsupported unit strings are rejected. The module reads resolved metadata exclusively through i.hyper.metadata; input maps must provide valid hyperspectral metadata.

Output and uncertainty metadata are derived from the input in one atomic i.hyper.metadata operation. Each output receives a new dataset identifier, one source-to-output history entry, and its local radiometry and atmospheric correction settings. Failure to create valid output metadata aborts the module.

The module reads the following resolved input metadata. Product availability refers to metadata written by i.hyper.import; "when present" means that the field is conditional in the source product.

Use or optionResolved metadata keyUnits or valuesEnMAPPRISMATanagerModule fallback
Band centresbands.wavelengthnm, um (µm), or cm-1YesYesYesLUT wavelength grid, with warning
Band FWHMbands.fwhmSame unit as band centresYesYesYes0 (unavailable)
Wavelength unitswavelength_unitsnm, um, or cm-1YesYesYesnm
Radiometric quantityradiometric_quantityRadiance or reflectanceYesYesYesUnset
Radiometric unitsradiometric_unitsW m-2 sr-1 nm-1 or W m-2 sr-1 µm-1YesYesYesW m-2 sr-1 µm-1, with warning
szaextended_metadata.geometry.sun_zenith_degDegreesYesYesYesRequired
vzaextended_metadata.geometry.view_zenith_degDegreesYesYesYes0
raaextended_metadata.geometry.relative_azimuth_degDegreesYesYesYes0
sun_azimuthextended_metadata.geometry.sun_azimuth_degDegrees clockwise from northYesYesYes180
altitudeextended_metadata.geometry.sensor_altitude_mMetadata in m; option in kmWhen presentNoNo1000 km
doyextended_metadata.acquisition.day_of_yearDay index, 1-366YesYesYes180
aod_valextended_metadata.atmosphere.aod_550Unitless, at 550 nmWhen presentNoMap mean when present0.1
h2o_valextended_metadata.atmosphere.h2o_g_cm2g/cm2When presentNoMap mean when present2.0 g/cm2
ozoneextended_metadata.atmosphere.ozone_duDobson units (DU)When presentNoNo300 DU
atmosphereextended_metadata.atmosphere.atmosphere_modelus62, midsum, midwin, tropical, subsum, or subwinNoWhen presentNous62
aerosolextended_metadata.atmosphere.aerosol_modelnone, continental, maritime, urban, desert, or customNoNoNocontinental

For metadata-backed options, values are resolved in this order: command line option, input map metadata, module fallback. Lookup table axes, flags, files, and ancillary raster maps are not read from metadata.

The day-of-year range is 1 through 366, with a default of 180. It is used for Earth-Sun distance. The solar and view angles must describe the input acquisition geometry.

Values outside an AOD or water vapour lookup table axis are limited to its nearest boundary. A finer table increases computation and memory use. The default binary table, with 6 AOD points, 6 H2O points, and 211 wavelengths, is 122448 bytes (about 120 KiB). The format size is 20 + 4*(n_aod+n_h2o+n_wl) + 16*n_aod*n_h2o*n_wl bytes.

The 2D ancillary raster maps are read in the current computational region. Set the region to the horizontal extent and resolution of the input 3D raster before running the module. Null radiance cells remain null. Bands with round-trip transmittance below 0.10 are also written as null.

Final output reflectance is clipped to the interval from -0.01 to 1.5, retaining the module's established range after all optional processing.

The source-vendored libsixsv tree is compiled directly into the GRASS module by both supported build descriptions. A separately installed libsixsv shared library is not required. Building requires GRASS development libraries, a C11 compiler, the math library, and OpenMP support. libRadtran is not a supported module dependency while automatic SRF correction is disabled.

Surface prior regularisation, uncertainty calculation, DASF retrieval, and some image-based retrievals need arrays for the complete scene. Memory use therefore increases with the number of cells and bands.

EXAMPLES

Compute and write a lookup table without correcting a 3D raster:

i.hyper.atcorr lut=scene.lut \
    sza=35 vza=4 raa=95 \
    atmosphere=midsum aerosol=continental \
    aod=0.0,0.1,0.2,0.5 h2o=0.5,1.0,1.5,2.0,3.5,5.0 \
    wl_min=400 wl_max=2500 wl_step=10

Compute a table in memory, optionally save it, and correct a radiance cube using scene AOD and water vapour:

i.hyper.atcorr input=scene_radiance output=scene_reflectance \
    lut=scene_correction.lut sza=35 vza=4 raa=95 doy=180 \
    atmosphere=midsum aerosol=continental \
    aod_val=0.15 h2o_val=2.0

Use the BDM desert aerosol for a Saharan scene:

i.hyper.atcorr input=sahara_radiance output=sahara_reflectance \
    sza=28 vza=3 raa=110 doy=120 \
    atmosphere=tropical aerosol=desert \
    aod_val=0.35 h2o_val=1.0

Use atmospheric raster maps instead of scene values:

i.hyper.atcorr input=scene_radiance output=scene_reflectance \
    sza=35 vza=4 raa=95 doy=180 \
    atmosphere=midsum aerosol=continental \
    aod_map=aod_550 h2o_map=water_vapour smooth=2

SEE ALSO

i.atcorr, i.hyper.metadata, i.atcorr2, i.hyper.atcorr reference implementation

REFERENCES

AUTHORS

Yann Chemin, Seilio Douar EI
Tomaz Zagar and Alen Mangafic, Geodetic Institute of Slovenia

SOURCE CODE

Available at: i.hyper.atcorr source code (history)

Accessed: Sunday Nov 15 10:56:48 2026


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

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual