toolsrtm.canopy

Leaf-angle distributions (dladgen, campbell), volume-scattering geometry (volscatt), the SAIL scattering solutions (conservative and non-conservative), and the fourSAIL / fourSAIL2 canopy BRDF models. Direct port of ToolsRTM/R/dladgen.R, campbell.R, volscatt.R, Jfunc1-4.R, NonConservativeScatering.R, ConservativeScattering.R, foursail.R, foursail2.R.

fourSAIL canopy radiative transfer model and its supporting leaf-angle distribution / scattering-geometry helpers.

Direct, function-by-function port of:

  • ToolsRTM/R/volscatt.R

  • ToolsRTM/R/campbell.R

  • ToolsRTM/R/dladgen.R

  • ToolsRTM/R/dcum.R

  • ToolsRTM/R/Jfunc1.R, Jfunc2.R, Jfunc4.R

  • ToolsRTM/R/NonConservativeScatering.R

  • ToolsRTM/R/foursail.R (single-layer canopy; all 5 leaf models ToolsRTM itself supports – PROSPECT-D/-PRO, Liberty, Fluspect-B/-B-Cx – are wired in via _leaf_optics, matching R’s own dispatch)

References

Verhoef W & Bach H, 2007. Coupled soil-leaf-canopy and atmosphere radiative transfer modeling … Remote Sensing of Environment, 109:166-182. Verhoef, Jia, Xiao & Su, 2007. Unified optical-thermal four-stream radiative transfer theory for homogeneous vegetation canopies. IEEE TGRS 45:1808-1822.

toolsrtm.canopy.volscatt(tts, tto, psi, ttl)[source]

Volume scattering functions and interception coefficients for given solar zenith, viewing zenith, azimuth and (scalar) leaf inclination angle. Direct port of ToolsRTM::volscatt (scalar-ttl variant, called once per leaf-angle class inside foursail_core()).

Return type:

tuple(chi_s, chi_o, frho, ftau)

Parameters:

  • tts (float)

  • tto (float)

  • psi (float)

  • ttl (float)

toolsrtm.canopy.campbell(ala)[source]

Ellipsoidal leaf angle distribution (Campbell, 1986), parametrised by the average leaf inclination angle ala (degrees).

Direct port of ToolsRTM::campbell.

Parameters:

ala (float)

Return type:

LeafAngleDistribution

toolsrtm.canopy.dladgen(a, b)[source]

Bimodal (Verhoef) leaf angle distribution function, from parameters a (average leaf slope) and b (bimodality). Direct port of ToolsRTM::dladgen (a.k.a. SCOPEinR::leafangles).

Constraint: abs(a) + abs(b) < 1.

Parameters:

  • a (float)

  • b (float)

Return type:

LeafAngleDistribution

toolsrtm.canopy.dcum(a, b, t)[source]

Cumulative leaf inclination distribution value at angle t (deg).

Direct port of ToolsRTM::dcum.

Parameters:

  • a (float)

  • b (float)

  • t (float)

Return type:

float

toolsrtm.canopy.jfunc1(k, l, t)[source]

J1 function with avoidance of singularity problem. Port of ToolsRTM::Jfunc1 (k, t scalars; l array over wavelength).

Parameters:
Return type:

ndarray

toolsrtm.canopy.jfunc2(k, l, t)[source]

J2 function. Port of ToolsRTM::Jfunc2. k/l may be scalars or arrays (broadcastable); t a scalar.

Parameters:

  • k (float)

  • t (float)

toolsrtm.canopy.jfunc4(m, t)[source]

J4 function for treating (near) conservative scattering. Port of ToolsRTM::Jfunc4.

Parameters:
Return type:

ndarray

toolsrtm.canopy.non_conservative_scattering(m, lai, att, sigb, ks, ko, sf, sb, vf, vb, tss, too)[source]

Non-conservative scattering solution of the SAIL 4-stream equations.

Direct port of ToolsRTM::NonConservativeScattering. All spectral quantities (m, att, sigb, sf, sb, vf, vb) are arrays over wavelength; lai, ks, ko, tss, too are scalars.

Return type:

dict with keys tdd, rdd, tsd, rsd, tdo, rdo, rsod (arrays over wavelength).

toolsrtm.canopy.conservative_scattering(m, lai, att, sigb, ks, ko, sf, sb, vf, vb, tss, too)[source]

Near/complete conservative scattering solution (m close to 0), used by foursail2/INFORM for wavelengths where non_conservative_scattering’s general exponential-decay formulation is numerically unstable.

Direct port of ToolsRTM::ConservativeScattering. Same argument/return shape as non_conservative_scattering().

toolsrtm.canopy.scattering(m, lai, att, sigb, ks, ko, sf, sb, vf, vb, tss, too)[source]

Dispatch per-wavelength between conservative_scattering() (m <= 0.01) and non_conservative_scattering() (m > 0.01), matching foursail2.R/inform.R’s f_ConS/f_Non_ConS index split – computed for every wavelength with both formulations, then selected with np.where (simpler and equally correct vs. subsetting arrays and reassembling, since both branches are vectorised already). plain foursail() never needs this: it always uses the non-conservative formulation unconditionally, matching ToolsRTM::foursail.R itself.

class toolsrtm.canopy.LeafAngleDistribution(lidf: 'np.ndarray', litab: 'np.ndarray')[source]

Bases: object

Parameters:
lidf: ndarray
litab: ndarray
class toolsrtm.canopy.FourSAILResult(rdot: 'np.ndarray', rsot: 'np.ndarray', rddt: 'np.ndarray', rsdt: 'np.ndarray')[source]

Bases: object

Parameters:
rdot: ndarray
rsot: ndarray
rddt: ndarray
rsdt: ndarray
toolsrtm.canopy.foursail_core(rho, tau, rsoil, LIDFa, LIDFb, TypeLidf, lai, hotspot, tts, tto, psi)[source]

fourSAIL canopy bidirectional reflectance, given precomputed leaf reflectance/transmittance spectra rho/tau and soil reflectance rsoil (all same length, over wavelength).

This is the model-agnostic core of ToolsRTM::foursail (the part after leaf-model dispatch): sections 1.2 onward of the R function.

Parameters:

  • rho (array_like) – Leaf hemispherical reflectance / transmittance spectra.

  • tau (array_like) – Leaf hemispherical reflectance / transmittance spectra.

  • rsoil (array_like) – Soil reflectance spectrum, same length as rho/tau.

  • LIDFa (float) – Leaf inclination distribution parameters (see dladgen(), campbell()).

  • LIDFb (float) – Leaf inclination distribution parameters (see dladgen(), campbell()).

  • TypeLidf ({1, 2}) – 1: use dladgen() (LIDFa, LIDFb shape parameters); 2: use campbell() (LIDFa = average leaf angle).

  • lai (float) – Leaf area index. If negative, canopy is bare soil (LAI=0 case).

  • hotspot (float) – Hot-spot size parameter.

  • tts (float) – Solar zenith, viewing zenith, relative azimuth (degrees).

  • tto (float) – Solar zenith, viewing zenith, relative azimuth (degrees).

  • psi (float) – Solar zenith, viewing zenith, relative azimuth (degrees).

Returns:

rdot, rsot, rddt, rsdt spectra.

Return type:

FourSAILResult

toolsrtm.canopy.foursail(inputLUT, rsoil, leaf_model='PROSPECT-PRO', spectrum_all=True)[source]

fourSAIL simulation for a single set of input parameters, dispatching to a leaf model exactly as ToolsRTM::foursail does – all 5 leaf models ToolsRTM itself supports are ported and wired in here.

Parameters:

  • inputLUT (dict) – Scalar input parameters. Must contain the fourSAIL geometry/canopy keys (LIDFa, LIDFb, TypeLidf, LAI, hspot, tts, tto, psi) plus the leaf-model parameters: for PROSPECT-D/-PRO, N, Cab, Car, Anth, Cbrown, EWT, LMA, alpha (PRO also Prot, CBC); for Liberty, cell.d, inter.c, baseline.abs, leaf.thick, albino.abs, Cab, EWT, lign.cell, Nitrogen; for Fluspect-B/-B-Cx, Cab, Car, EWT, LMA, Cs, N, fqe, Cx (Cx also Prot, CBC, Anth). See toolsrtm.liberty.liberty()/toolsrtm.fluspect.fluspect_b()/ toolsrtm.fluspect.fluspect_cx() for parameter meanings.

  • rsoil (array_like) – Soil reflectance spectrum, 400-2500 nm (2101 values) if spectrum_all else 400-2400 nm (2001 values). Always truncated to 2001 for the Fluspect leaf models regardless of spectrum_all (see _leaf_optics()).

  • leaf_model ({'PROSPECT-PRO', 'PROSPECT-D', 'Liberty', 'Fluspect-B', 'Fluspect-B-Cx'})

  • spectrum_all (bool) – True: full 400-2500 nm PROSPECT range (2101 pts). False: truncate to 400-2400 nm (2001 pts), as used inside SCOPE-style pipelines.

Return type:

FourSAILResult

class toolsrtm.canopy.FourSAIL2Result(rdot: 'np.ndarray', rsot: 'np.ndarray', rddt: 'np.ndarray', rsdt: 'np.ndarray', alfast: 'np.ndarray', alfadt: 'np.ndarray')[source]

Bases: object

Parameters:
rdot: ndarray
rsot: ndarray
rddt: ndarray
rsdt: ndarray
alfast: ndarray
alfadt: ndarray
toolsrtm.canopy.foursail2_core(rho_green, tau_green, rho_brown, tau_brown, rsoil, LIDFa, LIDFb, TypeLidf, lai, hotspot, tts, tto, psi, fraction_brown, diss, Cv, Zeta)[source]

Two-layer (green over brown/senescent) canopy bidirectional reflectance, given precomputed leaf optics for each layer.

Direct port of ToolsRTM::foursail2’s model-agnostic core (the part after leaf-model dispatch) – non-Lambertian soil is not supported here either, matching the R version’s own documented limitation.

Parameters:

  • rho_green (ndarray)

  • tau_green (ndarray)

  • rho_brown (ndarray)

  • tau_brown (ndarray)

  • rsoil (ndarray)

  • LIDFa (float)

  • LIDFb (float)

  • TypeLidf (Literal[1, 2])

  • lai (float)

  • hotspot (float)

  • tts (float)

  • tto (float)

  • psi (float)

  • fraction_brown (float)

  • diss (float)

  • Cv (float)

  • Zeta (float)

Return type:

FourSAIL2Result

toolsrtm.canopy.foursail2(inputLUT, rsoil, leaf_model='PROSPECT-PRO', spectrum_all=True)[source]

foursail2 (two-layer green/brown canopy) for a single set of input parameters, dispatching to a leaf model exactly as ToolsRTM::foursail2’s get.foursail2.leafopt does – all 5 leaf models are wired in (see foursail() for the full parameter list per leaf model). Green-vegetation leaf optics come from inputLUT itself (matching ToolsRTM::foursail2’s default FieldObserv=NULL behaviour); brown-vegetation leaf optics use the illustrative default senescent spectrum (_BROWN_LEAF_DEFAULT_*) the R function also falls back to when no field-observed LUT_GB is supplied.

Extra inputLUT keys beyond plain foursail(): fraction_brown (0-1), diss (layer dissociation factor), Cv (vertical crown cover fraction), Zeta (tree shape factor, crown diameter / height).

Parameters:

  • inputLUT (dict)

  • rsoil (ndarray)

  • leaf_model (Literal['PROSPECT-PRO', 'PROSPECT-D', 'Liberty', 'Fluspect-B', 'Fluspect-B-Cx'])

  • spectrum_all (bool)

Return type:

FourSAIL2Result