i.hyper.atcorr
Atmospheric correction of hyperspectral 3D raster radiance imagery using the 6SV2.1 radiative transfer algorithm.
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] [--verbose] [--quiet] [--qq] [--ui]
Example:
i.hyper.atcorr
grass.tools.Tools.i_hyper_atcorr(input=None, output=None, lut=None, sza=None, vza=None, raa=None, altitude=None, atmosphere=None, aerosol=None, mie_r=0.10, mie_sigma=1.50, mie_mr=1.45, mie_mi=0.005, ozone=None, brdf="lambertian", brdf_params=None, aod="0.0,0.05,0.1,0.2,0.4,0.8", h2o="0.5,1.0,1.5,2.0,3.5,5.0", wl_min=400, wl_max=2500, wl_step=10, doy=None, aod_val=None, h2o_val=None, aod_map=None, h2o_map=None, smooth=0, adj_psf=0, pixel_size=0, uncertainty=None, oe_sigma_aod=0.5, oe_sigma_h2o=1.0, maiac_patch=0, quality=None, dem=None, slope=None, aspect=None, sun_azimuth=None, view_zenith=None, view_azimuth=None, brdf_fiso=None, brdf_fvol=None, brdf_fgeo=None, mcd43_fiso=None, mcd43_fvol=None, mcd43_fgeo=None, mcd43_alpha=0.10, dasf=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.i_hyper_atcorr()
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.run_command("i.hyper.atcorr", input=None, output=None, lut=None, sza=None, vza=None, raa=None, altitude=None, atmosphere=None, aerosol=None, mie_r=0.10, mie_sigma=1.50, mie_mr=1.45, mie_mi=0.005, ozone=None, brdf="lambertian", brdf_params=None, aod="0.0,0.05,0.1,0.2,0.4,0.8", h2o="0.5,1.0,1.5,2.0,3.5,5.0", wl_min=400, wl_max=2500, wl_step=10, doy=None, aod_val=None, h2o_val=None, aod_map=None, h2o_map=None, smooth=0, adj_psf=0, pixel_size=0, uncertainty=None, oe_sigma_aod=0.5, oe_sigma_h2o=1.0, maiac_patch=0, quality=None, dem=None, slope=None, aspect=None, sun_azimuth=None, view_zenith=None, view_azimuth=None, brdf_fiso=None, brdf_fvol=None, brdf_fgeo=None, mcd43_fiso=None, mcd43_fvol=None, mcd43_fgeo=None, mcd43_alpha=0.10, dasf=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("i.hyper.atcorr")
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)
Allowed values: us62, midsum, midwin, tropical, subsum, subwin
aerosol=string
Aerosol model (default: continental; use 'custom' with mie_r/mie_sigma/mie_mr/mie_mi)
Allowed values: 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)
Allowed values: 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.
-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
--qq
Very quiet module output
--ui
Force launching GUI dialog
input : str, optional
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)
Used as: input, raster_3d, name
output : str, optional
Output surface reflectance 3D raster map
Name for output 3D raster map
Used as: output, raster_3d, name
lut : str, optional
Output LUT binary file
Binary LUT (*.lut) with R_atm, T_down, T_up, s_alb on an [AOD × H2O × wavelength] grid
Used as: output, file
sza : float, optional
Solar zenith angle (0–89°, required if no metadata, overrides metadata)
vza : float, optional
View zenith angle (0–60°, default: 0, overrides metadata)
raa : float, optional
Relative azimuth angle (default: 0°, overrides metadata)
altitude : float, optional
Observer altitude in km (<=0 ground, 0–100 aircraft, >=100 satellite; default: 1000; overrides metadata)
atmosphere : str, optional
Standard atmosphere model (default: us62)
Allowed values: us62, midsum, midwin, tropical, subsum, subwin
aerosol : str, optional
Aerosol model (default: continental; use 'custom' with mie_r/mie_sigma/mie_mr/mie_mi)
Allowed values: none, continental, maritime, urban, desert, custom
mie_r : float, optional
Custom Mie: log-normal mode radius [µm] (AERONET fine-mode r_eff~0.10-0.15)
Default: 0.10
mie_sigma : float, optional
Custom Mie: geometric standard deviation σ_g (typical 1.4-1.8)
Default: 1.50
mie_mr : float, optional
Custom Mie: real refractive index at 550 nm (dust~1.55, carbon~1.75, marine~1.38)
Default: 1.45
mie_mi : float, optional
Custom Mie: imaginary refractive index at 550 nm (absorbing 0.01-0.05, scattering <0.005)
Default: 0.005
ozone : float, optional
Total ozone column in DU (default: 300, overrides metadata)
brdf : str, optional
Surface BRDF model (default: lambertian)
Allowed values: lambertian, rahman, roujean, hapke, ocean, walthall, minnaert, rosslimaignan
Default: lambertian
brdf_params : str, optional
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 : str, optional
AOD at 550 nm grid (comma-separated)
Default: 0.0,0.05,0.1,0.2,0.4,0.8
h2o : str, optional
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, optional
Minimum wavelength (nm, default: 400)
Default: 400
wl_max : float, optional
Maximum wavelength (nm, default: 2500)
Default: 2500
wl_step : float, optional
Wavelength step (nm, default: 10)
Default: 10
doy : int, optional
Day of year (1–366, default: 180, overrides metadata)
aod_val : float, optional
Scene AOD at 550 nm (default: 0.1, overrides metadata)
h2o_val : float, optional
Column water vapour g/cm² (default: 2.0, overrides metadata)
aod_map : str | np.ndarray, optional
Per-pixel AOD raster (overrides aod_val= where non-null)
2-D raster of AOD at 550 nm
Used as: input, raster, name
h2o_map : str | np.ndarray, optional
Per-pixel water vapour raster (overrides h2o_val= where non-null)
2-D raster of column water vapour in g/cm²
Used as: input, raster, name
smooth : float, optional
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, optional
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, optional
Pixel size in metres (default: 0 = auto-detect)
Default: 0
uncertainty : str, optional
Output uncertainty 3D raster map (requires -u flag)
Name for output 3D raster map
Used as: output, raster_3d, name
oe_sigma_aod : float, optional
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, optional
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 : int, optional
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 : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
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.
Used as: output, raster, name
dem : str | np.ndarray, optional
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.
Used as: input, raster, name
slope : str | np.ndarray, optional
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).
Used as: input, raster, name
aspect : str | np.ndarray, optional
Terrain aspect raster [degrees, CW from North]
2-D raster of terrain aspect in degrees clockwise from North. Must be provided together with slope=.
Used as: input, raster, name
sun_azimuth : float, optional
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 : str | np.ndarray, optional
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.
Used as: input, raster, name
view_azimuth : str | np.ndarray, optional
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.
Used as: input, raster, name
brdf_fiso : str | np.ndarray, optional
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.
Used as: input, raster, name
brdf_fvol : str | np.ndarray, optional
MCD43 f_vol kernel weight raster
Ross-Thick volumetric kernel weight from MODIS MCD43A1.
Used as: input, raster, name
brdf_fgeo : str | np.ndarray, optional
MCD43 f_geo kernel weight raster
Li-Sparse geometric kernel weight from MODIS MCD43A1.
Used as: input, raster, name
mcd43_fiso : str, optional
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 : str, optional
MCD43 f_vol at 7 MODIS bands
Seven comma-separated f_vol (RossThick volumetric) kernel weights.
mcd43_fgeo : str, optional
MCD43 f_geo at 7 MODIS bands
Seven comma-separated f_geo (LiSparse geometric) kernel weights.
mcd43_alpha : float, optional
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 : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
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.
Used as: output, raster, name
flags : str, optional
Allowed values: u, r, a, w, z, p, m, P, e, D
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 : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.
Raises:
grass.tools.ToolError: When the tool ended with an error.
input : str, optional
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)
Used as: input, raster_3d, name
output : str, optional
Output surface reflectance 3D raster map
Name for output 3D raster map
Used as: output, raster_3d, name
lut : str, optional
Output LUT binary file
Binary LUT (*.lut) with R_atm, T_down, T_up, s_alb on an [AOD × H2O × wavelength] grid
Used as: output, file
sza : float, optional
Solar zenith angle (0–89°, required if no metadata, overrides metadata)
vza : float, optional
View zenith angle (0–60°, default: 0, overrides metadata)
raa : float, optional
Relative azimuth angle (default: 0°, overrides metadata)
altitude : float, optional
Observer altitude in km (<=0 ground, 0–100 aircraft, >=100 satellite; default: 1000; overrides metadata)
atmosphere : str, optional
Standard atmosphere model (default: us62)
Allowed values: us62, midsum, midwin, tropical, subsum, subwin
aerosol : str, optional
Aerosol model (default: continental; use 'custom' with mie_r/mie_sigma/mie_mr/mie_mi)
Allowed values: none, continental, maritime, urban, desert, custom
mie_r : float, optional
Custom Mie: log-normal mode radius [µm] (AERONET fine-mode r_eff~0.10-0.15)
Default: 0.10
mie_sigma : float, optional
Custom Mie: geometric standard deviation σ_g (typical 1.4-1.8)
Default: 1.50
mie_mr : float, optional
Custom Mie: real refractive index at 550 nm (dust~1.55, carbon~1.75, marine~1.38)
Default: 1.45
mie_mi : float, optional
Custom Mie: imaginary refractive index at 550 nm (absorbing 0.01-0.05, scattering <0.005)
Default: 0.005
ozone : float, optional
Total ozone column in DU (default: 300, overrides metadata)
brdf : str, optional
Surface BRDF model (default: lambertian)
Allowed values: lambertian, rahman, roujean, hapke, ocean, walthall, minnaert, rosslimaignan
Default: lambertian
brdf_params : str, optional
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 : str, optional
AOD at 550 nm grid (comma-separated)
Default: 0.0,0.05,0.1,0.2,0.4,0.8
h2o : str, optional
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, optional
Minimum wavelength (nm, default: 400)
Default: 400
wl_max : float, optional
Maximum wavelength (nm, default: 2500)
Default: 2500
wl_step : float, optional
Wavelength step (nm, default: 10)
Default: 10
doy : int, optional
Day of year (1–366, default: 180, overrides metadata)
aod_val : float, optional
Scene AOD at 550 nm (default: 0.1, overrides metadata)
h2o_val : float, optional
Column water vapour g/cm² (default: 2.0, overrides metadata)
aod_map : str, optional
Per-pixel AOD raster (overrides aod_val= where non-null)
2-D raster of AOD at 550 nm
Used as: input, raster, name
h2o_map : str, optional
Per-pixel water vapour raster (overrides h2o_val= where non-null)
2-D raster of column water vapour in g/cm²
Used as: input, raster, name
smooth : float, optional
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, optional
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, optional
Pixel size in metres (default: 0 = auto-detect)
Default: 0
uncertainty : str, optional
Output uncertainty 3D raster map (requires -u flag)
Name for output 3D raster map
Used as: output, raster_3d, name
oe_sigma_aod : float, optional
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, optional
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 : int, optional
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 : str, optional
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.
Used as: output, raster, name
dem : str, optional
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.
Used as: input, raster, name
slope : str, optional
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).
Used as: input, raster, name
aspect : str, optional
Terrain aspect raster [degrees, CW from North]
2-D raster of terrain aspect in degrees clockwise from North. Must be provided together with slope=.
Used as: input, raster, name
sun_azimuth : float, optional
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 : str, optional
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.
Used as: input, raster, name
view_azimuth : str, optional
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.
Used as: input, raster, name
brdf_fiso : str, optional
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.
Used as: input, raster, name
brdf_fvol : str, optional
MCD43 f_vol kernel weight raster
Ross-Thick volumetric kernel weight from MODIS MCD43A1.
Used as: input, raster, name
brdf_fgeo : str, optional
MCD43 f_geo kernel weight raster
Li-Sparse geometric kernel weight from MODIS MCD43A1.
Used as: input, raster, name
mcd43_fiso : str, optional
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 : str, optional
MCD43 f_vol at 7 MODIS bands
Seven comma-separated f_vol (RossThick volumetric) kernel weights.
mcd43_fgeo : str, optional
MCD43 f_geo at 7 MODIS bands
Seven comma-separated f_geo (LiSparse geometric) kernel weights.
mcd43_alpha : float, optional
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 : str, optional
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.
Used as: output, raster, name
flags : str, optional
Allowed values: u, r, a, w, z, p, m, P, e, D
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 : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
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.
| Category | Meaning |
|---|---|
| 0 | No class detected (clear) |
| 1 | Cloud |
| 2 | Shadow |
| 3 | Cloud + Shadow |
| 4 | Water |
| 5 | Cloud + Water |
| 6 | Shadow + Water |
| 7 | Cloud + Shadow + Water |
| 8 | Snow / ice |
| 9 | Cloud + Snow / ice |
| 10 | Shadow + Snow / ice |
| 11 | Cloud + Shadow + Snow / ice |
| 12 | Water + Snow / ice |
| 13 | Cloud + Water + Snow / ice |
| 14 | Shadow + Water + Snow / ice |
| 15 | All 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 option | Resolved metadata key | Units or values | EnMAP | PRISMA | Tanager | Module fallback |
|---|---|---|---|---|---|---|
| Band centres | bands.wavelength |
nm, um (µm), or cm-1 |
Yes | Yes | Yes | LUT wavelength grid, with warning |
| Band FWHM | bands.fwhm |
Same unit as band centres | Yes | Yes | Yes | 0 (unavailable) |
| Wavelength units | wavelength_units |
nm, um, or cm-1 |
Yes | Yes | Yes | nm |
| Radiometric quantity | radiometric_quantity |
Radiance or reflectance | Yes | Yes | Yes | Unset |
| Radiometric units | radiometric_units |
W m-2 sr-1 nm-1 or W m-2 sr-1 µm-1 | Yes | Yes | Yes | W m-2 sr-1 µm-1, with warning |
| sza | extended_metadata.geometry.sun_zenith_deg |
Degrees | Yes | Yes | Yes | Required |
| vza | extended_metadata.geometry.view_zenith_deg |
Degrees | Yes | Yes | Yes | 0 |
| raa | extended_metadata.geometry.relative_azimuth_deg |
Degrees | Yes | Yes | Yes | 0 |
| sun_azimuth | extended_metadata.geometry.sun_azimuth_deg |
Degrees clockwise from north | Yes | Yes | Yes | 180 |
| altitude | extended_metadata.geometry.sensor_altitude_m |
Metadata in m; option in km | When present | No | No | 1000 km |
| doy | extended_metadata.acquisition.day_of_year |
Day index, 1-366 | Yes | Yes | Yes | 180 |
| aod_val | extended_metadata.atmosphere.aod_550 |
Unitless, at 550 nm | When present | No | Map mean when present | 0.1 |
| h2o_val | extended_metadata.atmosphere.h2o_g_cm2 |
g/cm2 | When present | No | Map mean when present | 2.0 g/cm2 |
| ozone | extended_metadata.atmosphere.ozone_du |
Dobson units (DU) | When present | No | No | 300 DU |
| atmosphere | extended_metadata.atmosphere.atmosphere_model |
us62, midsum, midwin, tropical, subsum, or subwin |
No | When present | No | us62 |
| aerosol | extended_metadata.atmosphere.aerosol_model |
none, continental, maritime, urban, desert, or custom |
No | No | No | continental |
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
- Vermote, E.F., Tanre, D., Deuze, J.L., Herman, M. and Morcrette, J.J. (1997). Second simulation of the satellite signal in the solar spectrum, 6S: An overview. IEEE Transactions on Geoscience and Remote Sensing, 35(3), 675-686.
- Kotchenova, S.Y., Vermote, E.F., Matarrese, R. and Klemm, F.J. (2006). Validation of a vector version of the 6S radiative transfer code for atmospheric correction of satellite data. Applied Optics, 45(26), 6762-6774.
- Thompson, D.R. et al. (2018). Optimal estimation for imaging spectrometer atmospheric correction. Remote Sensing of Environment, 216, 355-373.
AUTHORS
Yann Chemin, Seilio Douar EI; Tomaž Žagar and Alen Mangafić, Geodetic Institute of Slovenia
SOURCE CODE
Available at: i.hyper.atcorr source code
(history)
Latest change: Wednesday Sep 16 14:49:52 2026 in commit 9b0a4cb