BRDF

Module: sasktran.brdf

SASKTRAN support BRDF surfaces. A surface must be added to every Atmosphere object. Below are the BRDF classes currently supported by SASKTRAN.

Common BRDFs

Below is the documentation for the common BRDFs that SASKTRAN supports.

class sasktran.BRDF(name: str)

Bases: object

Class which implements a Bidirectional Reflectance Distribution Function. This is a light wrapper around the sasktranif ISKBrdf object. It is recommended to use the specialized BRDF classes rather than this one.

A BRDF is defined as the ratio of the radiance scattered from a surface into a given direction to the collimated power incident on a unit area of the surface. Much of the literature on BRDFs (Spurr 2002, Roujean 1992, Rahman 1993, Wanner 1995, Cox and Munk 1954, Kokhanovsky 2012) define reflectance functions through a quantity that is scaled up by pi compared to this definition.

Sasktran defines the relative azimuth angle such that 0 degrees corresponds to forward scattering. Much of the literature on BRDFs (Spurr 2002, Roujean 1992, Rahman 1993, Wanner 1995, Cox and Munk 1954, Hapke 2012) define it the opposite way.

Parameters:

name (str) – Name of the BRDF object to create

Examples

>>> from sasktran import BRDF
>>> brdf = BRDF('lambertian')
>>> brdf.skif_object().SetProperty('Albedo', 0.3)
True
>>> brdf.reflectance(340, 0, 0, 54372, 0.5, 0.5, 0)
0.0954929658551372
reflectance(wavel_nm: float, latitude: float, longitude: float, mjd: float, mu_in: float, mu_out: float, cos_dphi: float)

Calculates the value of the BRDF for a given wavelength, location, time and geometry.

Parameters:

  • wavel_nm (float) – Wavelength in nanometers.

  • latitude (float) – Latitude of surface location.

  • longitude (float) – Longitude of surface location.

  • mjd (float) – Modified Julian Date

  • mu_in (float) – Cosine of the incoming zenith angle. Must be between 0 and 1

  • mu_out (float) – Cosine of the outgoing zenith angle. Must be between 0 and 1

  • cos_dphi (float) – Cosine of the azimuth angle between incoming and outgoing directions. Must be between -1 (backscattering) and +1 (forward scattering).

skif_object(**kwargs)

Returns the internel SasktranIF object

class sasktran.Lambertian(albedo)

Bases: BRDF

Class which implements a Lambertian Bidirectional Reflectance Distribution Function.

Parameters:

albedo (float) – Ratio of incoming to outgoing radiance. The reflectance distribution is equal to albedo/pi

Examples

>>> from sasktran.brdf import Lambertian
>>> brdf = Lambertian(albedo=0.3)
>>> brdf.reflectance(340, 0, 0, 54372, 0.5, 0.5, 0)
0.0954929658551372
>>> brdf.albedo = 1
>>> brdf.reflectance(340, 0, 0, 54372, 0.5, 0.5, 0)
0.3183098861837907
class sasktran.Kokhanovsky(L: float = 3600000.0, M: float = 5.5e-08)

Bases: BRDF

Implementation of the snow BRDF from Kokhanovsky 2012. The parameters L and M are optional, the default values correspond to 1020 nm over greenland.

Equation 1 is implemented with the following changes:

  • the reflectance is divided by pi

Parameters:

  • L (float, optional) – Parameter approximately equal to 13 times the average snow grain optical diameter. Default 3.6e6

  • M (float, optional) – Parameter proportional to the mass concentration of pollutants in the snow. Default 5.5e-8

Examples

>>> from sasktran.brdf import Kokhanovsky
>>> brdf = Kokhanovsky()
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.25185744490707646

References

A. A. Kokhanovsky and F. M. Breon, “Validation of an Analytical Snow BRDF Model Using PARASOL Multi-Angular and Multispectral Observations,” IEEE Geoscience and Remote Sensing Letters, vol. 9, no. 5, pp. 928-932, Sept. 2012. doi: 10.1109/LGRS.2012.2185775 URL: http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=6166850&isnumber=6205680

class sasktran.Roujean(surface, spectral_region='vis')

Bases: BRDF

Implementation of the BRDF from Roujean 1992 for heterogenous surfaces. Pre-defined values are given for 11 different surfaces in the visible and near infrared bands.

Equation 10 is implemented with values of k0, k1, and k2 from Table 1, but with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

  • the reflectance is also divided by 100 (k0, k1, k2 are percentages)

Parameters:

  • surface (str) – One of the following: ‘plowed field’, ‘annual grass’, ‘hard wheat’, ‘steppe’, ‘corn’, ‘orchard grass’, ‘irrigated wheat’, ‘pineforest’, ‘deciduous forest’, ‘soybean’, or ‘grass lawn’

  • spectral_region (str, optional) – One of the following: ‘vis’ for the visible spectrum or ‘nir’ for the near-infrared spectrum. Default ‘vis’

Examples

>>> from sasktran.brdf import Roujean
>>> brdf = Roujean(surface='corn', spectral_region='nir')
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.09605247619742084

References

Roujean, J.-L., M. Leroy, and P.-Y. Deschamps (1992), A bidirectional reflectance model of the Earth’s surface for the correction of remote sensing data, J. Geophys. Res., 97(D18), 20455–20468, doi:10.1029/92JD01411.

class sasktran.CoxMunk(wind_speed: float = 5.0, water_index: float = 1.334)

Bases: BRDF

Implementation of the water BRDF based on Cox and Munk 1954 and Spurr 2002.

Equation A.18 from Spurr is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Parameters:

  • wind_speed (float, optional) – Wind speed in m/s. Default 5.0

  • water_index (float, optional) – Index of refraction of water. Default 1.334

Examples

>>> import sasktran as sk
>>> brdf = sk.CoxMunk(wind_speed=5.0, water_index=1.334)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 1)
0.21213348733518164

References

Cox C, Munk W. The measurement of the roughness of the sea surface from photographs of the Sun glitter. J Opt Soc Ann 1954; 44:838–50.

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

class sasktran.Rahman(rho0: float, theta: float, k: float)

Bases: BRDF

Implementation of the Semiempirical Rahman BRDF based on Rahman 1993 and Spurr 2002.

Equation 2 from Rahman is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Parameters:

  • rho0 (float) – Empirical parameter related to the overall intensity of reflection (not proportional to single-scatter albedo)

  • theta (float) – Empirical parameter that controls the relative amount of backward (-1<=theta<=0) or forward (0<=theta<=1) scattering

  • k (float) – Emprical parameter that indicates the level of anisotropy of the surface

Examples

>>> import sasktran as sk
>>> brdf = sk.Rahman(rho0=0.1, theta=-0.5, k=1.5)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.01505098240847888

References

Rahman H, Pinty B, Verstraete M. Coupled surface atmosphere reflectance (CSAR) model: 2. Semi-empirical surface model usable with NOAA AVHRR data. J Geophys Res 1993; 98:20,791–801.

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

class sasktran.Hapke(omega: float, delta: float, b0: float)

Bases: BRDF

Implementation of a vegetation BRDF based on Hapke 2012 and Spurr 2002.

Equation A.10 of Spurr is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Parameters:

  • omega (float) – Single scatter albedo

  • delta (float) – Angular width at half maximum of the hotspot / opposition peak

  • b0 (float) – Amplitude of the hotspot / opposition peak

Examples

>>> import sasktran as sk
>>> brdf = sk.Hapke(omega=0.6, delta=0.06, b0=1.0)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.0814968276380363

References

Hapke B. Theory of reflectance and emittance spectroscopy. Cambridge: Cambridge University Press, 2012.

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

class sasktran.MODIS(f_iso, f_vol, f_geo)

Bases: BRDF

Implementation of the Ross-thick Li-sparse-reciprocal BRDF used in MODIS’ Albedo/BRDF product. It is a linear combination of an isotropic (Lambertian) term, a volume scatterer (Ross-thick kernel) and a geometric scatterer (Li-sparse-reciprocal kernel).

Parameters:

  • f_iso (float) – Weight of the isotropic (Lambertian) kernel

  • f_vol (float) – Weight of the volume (Ross-thick) kernel

  • f_geo (float) – Weight of the geometric (Li-sparse-reciprocal) kernel

Examples

>>> import sasktran as sk
>>> brdf = sk.MODIS(f_iso=0.2, f_vol=0.2, f_geo=0.1)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.031577469878097834

References

A. H. Strahler, J. P. Muller, “MODIS BRDF/Albedo Product: Algorithm Theoretical Basis Document Version 5.0,” April 1999. URL: https://lpdaac.usgs.gov/sites/default/files/public/product_documentation/atbd_mod09_v5.pdf

Kernel-Based BRDFs

Below is the documentation for the kernel-based BRDFs that SASKTRAN supports.

class sasktran.LinearCombination

Bases: BRDF

Implements a BRDF that is a linear combination of an arbitrary number of kernels.

Examples

>>> import sasktran as sk
>>> brdf = sk.LinearCombination()

>>> kernel1 = sk.Lambertian(albedo=1.0)
>>> kernel2 = sk.RossThickKernel()
>>> kernel3 = sk.LiSparseReciprocalKernel(crown_shape=1.0, relative_height=2.0)

>>> brdf.kernels = [kernel1, kernel2, kernel3]
>>> brdf.kernel_weights = [0.2, 0.2, 0.1]

>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.031577469878097834
add_kernel(kernel: BRDF)

Add a BRDF kernel to the linear combination.

Parameters:

kernel (sk.BRDF) – The BRDF kernel to add.

property kernel_weights

List of kernel weights. If the number of weights given does not match the number of kernels present, the given weights will not be set.

property kernels

Full list of BRDF kernels.

remove_kernel(index: int = -1)

Remove the BRDF kernel at the position given by index. Accepts negative indices as Python does.

Parameters:

index (int) – Position of the kernel to remove. Invalid indices will remove nothing and produce a warning. Default -1

class sasktran.RoujeanKernel

Bases: BRDF

Implements the Roujean kernel from Roujean 1992 and Spurr 2002. This kernel is part of the above Roujean BRDF. It is recommended to use kernels as part of a LinearCombination and not as standalone BRDFs.

Equation 2 from Roujean is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Examples

>>> import sasktran as sk
>>> brdf = sk.RoujeanKernel()
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
-0.4471903004981418

References

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

Roujean, J.-L., M. Leroy, and P.-Y. Deschamps (1992), A bidirectional reflectance model of the Earth’s surface for the correction of remote sensing data, J. Geophys. Res., 97(D18), 20455–20468, doi:10.1029/92JD01411.

class sasktran.LiKernel(name: str, crown_shape: float, relative_height: float)

Bases: BRDF

Base class for Li kernels from Wanner 1995 and Spurr 2002. It is recommended to use derived classes (LiSparseKernel, LiDenseKernel or LiSparseReciprocalKernel) instead of this class. It is also recommended to use kernels as part of a LinearCombination and not as standalone BRDFs.

Tree crowns are modelled as spheroids of height 2b and width 2r, with centers a height of h above the ground.

Parameters:

  • crown_shape (float) – The ratio b/r describing the shape of the crown.

  • relative_height (float) – The ratio h/b describing the height of the crown above the ground.

Examples

>>> import sasktran as sk
>>> brdf = sk.LiKernel('li_sparse_kernel', crown_shape=1.0, relative_height=2.0)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
-0.8753521870054244

References

W. Wanner and A. H. Strahler, “On the derivation of kernels for kernel-driven modes of bidirectional reflectance,” Journal of Geophysical Research, vol. 100, no. d10, pp. 21077-21089, Oct. 20, 1995. doi: 10.1029/95JD02371 URL: http://onlinelibrary.wiley.com/doi/10.1029/95JD02371/abstract

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

class sasktran.LiSparseKernel(crown_shape: float = 1.0, relative_height: float = 2.0)

Bases: LiKernel

The Li-sparse kernel models sparse canopy where mutual shadowing can be ignored. It is recommended to use kernels as part of a LinearCombination and not as standalone BRDFs.

Equation 32 from Wanner is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Parameters:

  • crown_shape (float, optional) – See sk.LiSparse - Default 1.0

  • relative_height (float, optional) – See sk.LiSparse - Default 2.0

Examples

>>> import sasktran as sk
>>> brdf = sk.LiSparseKernel(crown_shape=1.0, relative_height=2.0)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
-0.8753521870054244

References

W. Wanner and A. H. Strahler, “On the derivation of kernels for kernel-driven modes of bidirectional reflectance,” Journal of Geophysical Research, vol. 100, no. d10, pp. 21077-21089, Oct. 20, 1995. doi: 10.1029/95JD02371 URL: http://onlinelibrary.wiley.com/doi/10.1029/95JD02371/abstract

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

class sasktran.LiSparseReciprocalKernel(crown_shape=1.0, relative_height=2.0)

Bases: LiKernel

The Li-sparse-reciprocal kernel is a variation on the Li-sparse kernel which allows the incident/viewing angles to be swapped without changing the BRDF’s value (reciprocal) - See the MODIS Albedo/BRDF ATBD. It is recommended to use kernels as part of a LinearCombination and not as standalone BRDFs.

Equation 39 from Strahler is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Parameters:

  • crown_shape (float, optional) – See sk.LiSparse - Default 1.0

  • relative_height (float, optional) – See sk.LiSparse - Default 2.0

Examples

>>> import sasktran as sk
>>> brdf = sk.LiSparseReciprocalKernel(crown_shape=1.0, relative_height=2.0)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
-0.477464829275686

References

A. H. Strahler, J. P. Muller, “MODIS BRDF/Albedo Product: Algorithm Theoretical Basis Document Version 5.0,” April 1999. URL: https://lpdaac.usgs.gov/sites/default/files/public/product_documentation/atbd_mod09_v5.pdf

class sasktran.LiDenseKernel(crown_shape=2.5, relative_height=2.0)

Bases: LiKernel

The Li-dense kernel models dense canopy where mutual shadowing cannot be ignored. It is recommended to use kernels as part of a LinearCombination and not as standalone BRDFs.

Equation 47 from Wanner is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Parameters:

  • crown_shape (float, optional) – See sk.LiSparse - Default 2.5

  • relative_height (float, optional) – See sk.LiSparse - Default 2.0

Examples

>>> import sasktran as sk
>>> brdf = sk.LiDenseKernel(crown_shape=2.5, relative_height=2.0)
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
-0.46940635114445084

References

W. Wanner and A. H. Strahler, “On the derivation of kernels for kernel-driven modes of bidirectional reflectance,” Journal of Geophysical Research, vol. 100, no. d10, pp. 21077-21089, Oct. 20, 1995. doi: 10.1029/95JD02371 URL: http://onlinelibrary.wiley.com/doi/10.1029/95JD02371/abstract

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

class sasktran.RossThinKernel

Bases: BRDF

The Ross-thin kernel models canopies with a small leaf area index (LAI) - see Wanner 1995 and Spurr 2002. It is recommended to use kernels as part of a LinearCombination and not as standalone BRDFs.

Equation 13 from Wanner is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Examples

>>> import sasktran as sk
>>> brdf = sk.RossThinKernel()
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.8132395113781661

References

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

W. Wanner and A. H. Strahler, “On the derivation of kernels for kernel-driven modles of bidirectional reflectance,” Journal of Geophysical Research, vol. 100, no. d10, pp. 21077-21089, Oct. 20, 1995. doi: 10.1029/95JD02371 URL: http://onlinelibrary.wiley.com/doi/10.1029/95JD02371/abstract

class sasktran.RossThickKernel

Bases: BRDF

The Ross-thick kernel models canopies with a large leaf area index (LAI) - see Wanner 1995 and Spurr 2002. It is recommended to use kernels as part of a LinearCombination and not as standalone BRDFs.

Equation 7 from Wanner is implemented with the following changes:

  • cos(phi) is replaced with -cos(phi)

  • the reflectance is divided by pi

Examples

>>> import sasktran as sk
>>> brdf = sk.RossThickKernel()
>>> brdf.reflectance(1050, 0, 0, 54372, 0.5, 0.5, 0)
0.07830987784454152

References

Robert J. D. Spurr, “A new approach to the retrieval of surface properties from earthshine measurements,” Journal of Quantitative Spectroscopy & Radiative Transfer, vol. 83, pp. 15-46, Oct. 9, 2002. doi:10.1016/S0022-4073(02)00283-2 url: http://www.sciencedirect.com/science/article/pii/S0022407302002832

W. Wanner and A. H. Strahler, “On the derivation of kernels for kernel-driven modles of bidirectional reflectance,” Journal of Geophysical Research, vol. 100, no. d10, pp. 21077-21089, Oct. 20, 1995. doi: 10.1029/95JD02371 URL: http://onlinelibrary.wiley.com/doi/10.1029/95JD02371/abstract

Two-Dimensional BRDFs

SASKTRAN is capable of modelling surfaces where the BRDF varies across the surface of the Earth. These are BRDFs that have two-dimensional variation across the surface

class sasktran.LatLonBRDF(longitudes: array, latitudes: array, brdfs: ndarray)

Bases: BRDF

A custom BRDF that is constructed as the combination of other BRDF’s on a uniform latitude/longitude grid.

Parameters:

  • longitudes (np.array) – Longitude grid that the BRDF is specified on in degrees. Longitudes must be specified from 0 to 360 and not from -180 to 180.

  • latitudes (np.array) – Latitude grid that the BRDF is specified on in degrees

  • brdfs (np.ndarray) – 2-D Array of dimension (len(longitudes), len(latitudes)) of sk.BRDF objects

Examples

>>> import sasktran as sk
>>> latitudes = [-10, 10]
>>> longitudes = [40, 60]
>>> brdfs = np.empty((len(longitudes), len(latitudes)), dtype=object)
>>> brdfs[0, 0] = sk.Lambertian(0.1)
>>> brdfs[0, 1] = sk.Lambertian(0.5)
>>> brdfs[1, 0] = sk.Lambertian(0.8)
>>> brdfs[1, 1] = sk.Lambertian(1.0)
>>> brdf = sk.LatLonBRDF(longitudes, latitudes, brdfs)
>>> brdf.reflectance(wavel_nm=750, latitude=0, longitude=50, mjd=54372, mu_in=0, mu_out=0, cos_dphi=0)
0.1909859317102744

See Also

Atmosphere

An object that describes the atmospheric constituents, and surface type to the engine. Atmospheric constituents are defined by a list of Species, and surfaces are defined by a given BRDF.