Skip to content

Index

source package isofit.surface

Classes

  • BaseSurface — A model of the surface.

  • GlintModelSurface — A model of the surface based on a collection of multivariate Gaussians, extended with two surface glint terms (sun + sky glint).

  • LUTSurface — A model of the surface based on an N-dimensional lookup table indexed by one or more state vector elements. We calculate the reflectance by multilinear interpolation. This is good for surfaces like aquatic ecosystems or snow that can be described with just a few degrees of freedom.

  • MultiComponentSurface — A model of the surface based on a collection of multivariate Gaussians, with one or more equiprobable components and full covariance matrices.

  • ThermalSurface — A model of the surface based on a Mixture of a hot Black Body and Multicomponent cold surfaces.

Functions

  • Surface — Reads an ISOFIT full config and initializes the desired Surface model

source class BaseSurface(full_config: Config)

A model of the surface.

Surface models are stored as MATLAB '.mat' format files.

Methods

  • resample_reflectance — Make sure model wavelengths align with the wavelength file.

  • xa — Mean of prior state vector distribution calculated at state x.

  • Sa — Covariance of prior state vector distribution calculated at state x.

  • Sb — Uncertainty due to unmodeled variables.

  • fit_params — Given a directional reflectance estimate and one or more emissive parameters, fit a state vector.

  • calc_lamb — Calculate a Lambertian surface reflectance for this state vector.

  • calc_rfl — Calculate the directed reflectance (specifically the HRDF) for this state vector.

  • drfl_dsurface — Partial derivative of reflectance with respect to state vector, calculated at x_surface. In the case that there are no free paramters our convention is to return the vector of zeros.

  • drfl_dsurfaceb — Partial derivative of reflectance with respect to unmodeled variables, calculated at x_surface. In the case that there are no free paramters our convention is to return the vector of zeros.

  • calc_Ls — Emission of surface, as a radiance.

  • dLs_dsurface — Partial derivative of surface emission with respect to state vector, calculated at x_surface. In the case that there are no free paramters our convention is to return the vector of zeros.

  • summarize — Summary of state vector.

source method BaseSurface.resample_reflectance()

Make sure model wavelengths align with the wavelength file.

source method BaseSurface.xa(x_surface, geom)

Mean of prior state vector distribution calculated at state x.

source method BaseSurface.Sa(x_surface, geom)

Covariance of prior state vector distribution calculated at state x.

source method BaseSurface.Sb()

Uncertainty due to unmodeled variables.

source method BaseSurface.fit_params(rfl_meas, geom, *args)

Given a directional reflectance estimate and one or more emissive parameters, fit a state vector.

source method BaseSurface.calc_lamb(x_surface, geom)

Calculate a Lambertian surface reflectance for this state vector.

source method BaseSurface.calc_rfl(x_surface, geom)

Calculate the directed reflectance (specifically the HRDF) for this state vector.

source method BaseSurface.drfl_dsurface(x_surface, geom)

Partial derivative of reflectance with respect to state vector, calculated at x_surface. In the case that there are no free paramters our convention is to return the vector of zeros.

source method BaseSurface.drfl_dsurfaceb(x_surface, geom)

Partial derivative of reflectance with respect to unmodeled variables, calculated at x_surface. In the case that there are no free paramters our convention is to return the vector of zeros.

source method BaseSurface.calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

source method BaseSurface.dLs_dsurface(x_surface, geom)

Partial derivative of surface emission with respect to state vector, calculated at x_surface. In the case that there are no free paramters our convention is to return the vector of zeros.

source method BaseSurface.summarize(x_surface, geom)

Summary of state vector.

source class GlintModelSurface(full_config: Config)

Bases : MultiComponentSurface

A model of the surface based on a collection of multivariate Gaussians, extended with two surface glint terms (sun + sky glint).

Methods

  • xa — Mean of prior distribution, calculated at state x.

  • Sa — Covariance of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function.

  • fit_params — Given a reflectance estimate and one or more emissive parameters, fit a state vector.

  • calc_rfl — Direct and diffuse Reflectance (includes sun and sky glint).

  • drfl_dsurface — Partial derivative of reflectance with respect to state vector, calculated at x_surface.

  • drdn_dglint — Derivative of radiance with respect to the direct and diffuse glint terms

  • drdn_dsurface — Derivative of radiance with respect to full surface vector

  • analytical_model — Linearization of the glint terms to use in AOE inner loop. Function will fetch the linearization of the rho terms and add the matrix components for the direct glint term. Currently we set the diffuse glint scaling term to constant value, which makes the AOE inner loop inversion possible.

  • summarize — Summary of state vector.

  • fresnel_rf — Calculates reflectance factor of sky radiance based on the Fresnel equation for unpolarized light as a function of view zenith angle (vza).

source method GlintModelSurface.xa(x_surface, geom)

Mean of prior distribution, calculated at state x.

source method GlintModelSurface.Sa(x_surface, geom)

Covariance of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function.

source method GlintModelSurface.fit_params(rfl_meas, geom, *args)

Given a reflectance estimate and one or more emissive parameters, fit a state vector.

source method GlintModelSurface.calc_rfl(x_surface, geom)

Direct and diffuse Reflectance (includes sun and sky glint).

Inputs

x_surface : np.ndarray Surface portion of the statevector element geom : Geometry Isofit geometry object

Outputs

rho_dir_dir : np.ndarray Reflectance quantity for downward direct photon paths rho_dif_dir : np.ndarray Reflectance quantity for downward diffuse photon paths

NOTE

Here, we treat direct and diffuse photon path reflectance differently. The sun and sky glint magnitudes are statevector elements that interact with the two reflectance quantities independently.

source method GlintModelSurface.drfl_dsurface(x_surface, geom)

Partial derivative of reflectance with respect to state vector, calculated at x_surface.

source method GlintModelSurface.drdn_dglint(L_tot, drdn_dgdd, s_alb, rho_dif_dir)

Derivative of radiance with respect to the direct and diffuse glint terms

source method GlintModelSurface.drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

Derivative of radiance with respect to full surface vector

source method GlintModelSurface.analytical_model(background, L_tot, geom, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

Linearization of the glint terms to use in AOE inner loop. Function will fetch the linearization of the rho terms and add the matrix components for the direct glint term. Currently we set the diffuse glint scaling term to constant value, which makes the AOE inner loop inversion possible.

source method GlintModelSurface.summarize(x_surface, geom)

Summary of state vector.

source staticmethod GlintModelSurface.fresnel_rf(vza)

Calculates reflectance factor of sky radiance based on the Fresnel equation for unpolarized light as a function of view zenith angle (vza).

source class LUTSurface(full_config: Config)

Bases : Surface

A model of the surface based on an N-dimensional lookup table indexed by one or more state vector elements. We calculate the reflectance by multilinear interpolation. This is good for surfaces like aquatic ecosystems or snow that can be described with just a few degrees of freedom.

The lookup table must be precalculated based on the wavelengths of the instrument. It is stored with other metadata in a matlab- format file. For an n-dimensional lookup table, it contains the following fields: - grids: an object array containing n lists of gridpoints - data: an n+1 dimensional array containing the reflectances for each gridpoint - bounds: a list of n [min,max] tuples representing the bounds for all state vector elements - statevec_names: an array of n strings representing state vector element names - mean: an array of n prior mean values, one for each state vector element - sigma: an array of n prior standard deviations, one for each state vector element - scale: an array of n scale values, one for each state vector element

.

Methods

  • xa — Mean of prior distribution.

  • Sa — Covariance of prior distribution, calculated at state x.

  • Sb — Uncertainty due to unmodeled variables.

  • fit_params — Given a reflectance estimate, fit a state vector.

  • calc_rfl — Non-Lambertian reflectance.

  • calc_lamb — Lambertian reflectance. Be sure to incorporate BRDF-related LUT dimensions such as solar and view zenith.

  • drfl_dsurface — Partial derivative of reflectance with respect to state vector, calculated at x_surface.

  • dlamb_dsurface — Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface. We calculate the reflectance with multilinear interpolation so the finite difference derivative is exact.

  • drdn_drfl — Partial derivative of radiance with respect to surface reflectance

  • calc_Ls — Emission of surface, as a radiance.

  • dLs_dsurface — Partial derivative of surface emission with respect to state vector, calculated at x_surface.

  • drdn_dLs — Partial derivative of radiance with respect to surface emission

  • drdn_dsurface — Derivative of radiance with respect to full surface vector

  • analytical_model — Linearization of the surface reflectance terms to use in the AOE inner loop (see Susiluoto, 2025). We set the quadratic spherical albedo term to a constant background, which simplifies the linearization background - s * rho_bg

  • summarize — Summary of state vector.

source method LUTSurface.xa(x_surface, geom)

Mean of prior distribution.

source method LUTSurface.Sa(x_surface, geom)

Covariance of prior distribution, calculated at state x.

source method LUTSurface.Sb()

Uncertainty due to unmodeled variables.

source method LUTSurface.fit_params(rfl_meas, geom, *args)

Given a reflectance estimate, fit a state vector.

source method LUTSurface.calc_rfl(x_surface, geom)

Non-Lambertian reflectance.

Inputs

x_surface : np.ndarray Surface portion of the statevector element geom : Geometry Isofit geometry object

Outputs

rho_dir_dir : np.ndarray Reflectance quantity for downward direct photon paths rho_dif_dir : np.ndarray Reflectance quantity for downward diffuse photon paths

NOTE

We do not handle direct and diffuse photon path reflectance quantities differently for the multicomponent surface model. This is why we return the same quantity for both outputs.

source method LUTSurface.calc_lamb(x_surface, geom)

Lambertian reflectance. Be sure to incorporate BRDF-related LUT dimensions such as solar and view zenith.

source method LUTSurface.drfl_dsurface(x_surface, geom)

Partial derivative of reflectance with respect to state vector, calculated at x_surface.

source method LUTSurface.dlamb_dsurface(x_surface, geom)

Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface. We calculate the reflectance with multilinear interpolation so the finite difference derivative is exact.

source method LUTSurface.drdn_drfl(L_tot, s_alb, rho_dif_dir)

Partial derivative of radiance with respect to surface reflectance

source method LUTSurface.calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

source method LUTSurface.dLs_dsurface(x_surface, geom)

Partial derivative of surface emission with respect to state vector, calculated at x_surface.

source method LUTSurface.drdn_dLs(t_total_up)

Partial derivative of radiance with respect to surface emission

source method LUTSurface.drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

Derivative of radiance with respect to full surface vector

source method LUTSurface.analytical_model(background, L_tot, geom, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

Linearization of the surface reflectance terms to use in the AOE inner loop (see Susiluoto, 2025). We set the quadratic spherical albedo term to a constant background, which simplifies the linearization background - s * rho_bg

NOTE FOR SURFACE_LUT

This assumes that the only surface statevector terms are surface reflectance terms. Any additional surface state elements have to be explicitely handled in this function. How they are handled is dependent on the nature of the surface rfl model. The n-columns of H is equal to the number of statevector elements. Here, set to the number of wavelengths.

source method LUTSurface.summarize(x_surface, geom)

Summary of state vector.

source class MultiComponentSurface(full_config: Config)

Bases : Surface

A model of the surface based on a collection of multivariate Gaussians, with one or more equiprobable components and full covariance matrices.

To evaluate the probability of a new spectrum, we calculate the distance to each component cluster.

.

Methods

  • component — We pick a surface model component using a distance metric.

  • xa — Mean of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function. This always uses the Lambertian (non-specular) version of the surface reflectance.

  • Sa — Covariance of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function.

  • fit_params — Given a reflectance estimate, fit a state vector.

  • calc_rfl — Non-Lambertian reflectance.

  • calc_lamb — Lambertian reflectance.

  • drfl_dsurface — Partial derivative of reflectance with respect to state vector, calculated at x_surface.

  • dlamb_dsurface — Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface.

  • drdn_drfl — Partial derivative of radiance with respect to surface reflectance

  • calc_Ls — Emission of surface, as a radiance.

  • dLs_dsurface — Partial derivative of surface emission with respect to state vector, calculated at x_surface.

  • drdn_dLs — Partial derivative of radiance with respect to surface emission

  • drdn_dsurface — Derivative of radiance with respect to full surface vector

  • analytical_model — Linearization of the surface reflectance terms to use in the AOE inner loop (see Susiluoto, 2025). We set the quadratic spherical albedo term to a constant background, which simplifies the linearization background = s * rho_bg

  • summarize — Summary of state vector.

  • euclidean_distance

  • spectral_angle_distance

  • spectral_gradient_angle

source method MultiComponentSurface.component(x, geom)

We pick a surface model component using a distance metric.

This always uses the Lambertian (non-specular) version of the surface reflectance. If the forward model initialize via heuristic (i.e. algebraic inversion), the component is only calculated once based on that first solution. That state is preserved in the geometry object.

Raises

  • ValueError

source method MultiComponentSurface.xa(x_surface, geom)

Mean of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function. This always uses the Lambertian (non-specular) version of the surface reflectance.

source method MultiComponentSurface.Sa(x_surface, geom)

Covariance of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function.

source method MultiComponentSurface.fit_params(rfl_meas, geom, *args)

Given a reflectance estimate, fit a state vector.

Raises

  • ValueError

source method MultiComponentSurface.calc_rfl(x_surface, geom)

Non-Lambertian reflectance.

Inputs

x_surface : np.ndarray Surface portion of the statevector element geom : Geometry Isofit geometry object

Outputs

rho_dir_dir : np.ndarray Reflectance quantity for downward direct photon paths rho_dif_dir : np.ndarray Reflectance quantity for downward diffuse photon paths

NOTE

We do not handle direct and diffuse photon path reflectance quantities differently for the multicomponent surface model. This is why we return the same quantity for both outputs.

source method MultiComponentSurface.calc_lamb(x_surface, geom)

Lambertian reflectance.

source method MultiComponentSurface.drfl_dsurface(x_surface, geom)

Partial derivative of reflectance with respect to state vector, calculated at x_surface.

source method MultiComponentSurface.dlamb_dsurface(x_surface, geom)

Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface.

source method MultiComponentSurface.drdn_drfl(L_tot, s_alb, rho_dif_dir)

Partial derivative of radiance with respect to surface reflectance

source method MultiComponentSurface.calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

source method MultiComponentSurface.dLs_dsurface(x_surface, geom)

Partial derivative of surface emission with respect to state vector, calculated at x_surface.

source method MultiComponentSurface.drdn_dLs(t_total_up)

Partial derivative of radiance with respect to surface emission

source method MultiComponentSurface.drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

Derivative of radiance with respect to full surface vector

source method MultiComponentSurface.analytical_model(background, L_tot, geom, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

Linearization of the surface reflectance terms to use in the AOE inner loop (see Susiluoto, 2025). We set the quadratic spherical albedo term to a constant background, which simplifies the linearization background = s * rho_bg

source method MultiComponentSurface.summarize(x_surface, geom)

Summary of state vector.

source staticmethod MultiComponentSurface.euclidean_distance(lamb_ref, mus)

source staticmethod MultiComponentSurface.spectral_angle_distance(lamb_ref, mus)

source method MultiComponentSurface.spectral_gradient_angle(lamb_ref, mus)

source class ThermalSurface(full_config: Config)

Bases : MultiComponentSurface

A model of the surface based on a Mixture of a hot Black Body and Multicomponent cold surfaces.

.

Methods

  • xa — Mean of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function.

  • Sa — Covariance of prior distribution, calculated at state x.

  • fit_params — Given a reflectance estimate, find the surface reflectance

  • dlamb_dsurface — Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface.

  • calc_Ls — Emission of surface, as a radiance.

  • dLs_dsurface — Partial derivative of surface emission with respect to state vector, calculated at x_surface.

  • drdn_dsurface — Derivative of radiance with respect to full surface vector

  • summarize — Summary of state vector.

source method ThermalSurface.xa(x_surface, geom)

Mean of prior distribution, calculated at state x. We find the covariance in a normalized space (normalizing by z) and then un- normalize the result for the calling function.

source method ThermalSurface.Sa(x_surface, geom)

Covariance of prior distribution, calculated at state x.

source method ThermalSurface.fit_params(rfl_meas, geom, *args)

Given a reflectance estimate, find the surface reflectance

source method ThermalSurface.dlamb_dsurface(x_surface, geom)

Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface.

source method ThermalSurface.calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

source method ThermalSurface.dLs_dsurface(x_surface, geom)

Partial derivative of surface emission with respect to state vector, calculated at x_surface.

source method ThermalSurface.drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

Derivative of radiance with respect to full surface vector

source method ThermalSurface.summarize(x_surface, geom)

Summary of state vector.

source Surface(config)

Reads an ISOFIT full config and initializes the desired Surface model

Parameters

  • config : isofit.configs.Config — The full_config to determine the surface category from and to pass along to the Surface model's initialization

Returns

  • Surface Model

Raises

  • ValueError