isofit.surface

Submodules

• isofit.surface.surface
• isofit.surface.surface_glint_model
• isofit.surface.surface_lut
• isofit.surface.surface_multicomp
• isofit.surface.surface_thermal

Classes

BaseSurface	A model of the surface.
GlintModelSurface	A model of the surface based on a collection of multivariate
LUTSurface	A model of the surface based on an N-dimensional lookup table
MultiComponentSurface	A model of the surface based on a collection of multivariate
ThermalSurface	A model of the surface based on a Mixture of a hot Black Body and

Functions

Surface(config)

Reads an ISOFIT full config and initializes the desired Surface model

Package Contents

class BaseSurface(full_config: Config)

A model of the surface.

Surface models are stored as MATLAB ‘.mat’ format files.

model_dict = None

statevec_names = []

idx_surface

bounds

scale

init

bvec = []

bval

idx_lamb

emissive = False

wl = None

fwhm = None

resample_reflectance()

Make sure model wavelengths align with the wavelength file.

xa(x_surface, geom)

Mean of prior state vector distribution calculated at state x.

Sa(x_surface, geom)

Covariance of prior state vector distribution calculated at state x.

Sb()

Uncertainty due to unmodeled variables.

fit_params(rfl_meas, geom, *args)

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

calc_lamb(x_surface, geom)

Calculate a Lambertian surface reflectance for this state vector.

calc_rfl(x_surface, geom)

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

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.

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.

calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

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.

summarize(x_surface, geom)

Summary of state vector.

class GlintModelSurface(full_config: Config)

Bases: isofit.surface.surface_multicomp.MultiComponentSurface

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

glint_ind

sky_glint_ind

sun_glint_ind

n_state

idx_surface

analytical_iv_idx

sun_glint_sigma

sky_glint_sigma

xa(x_surface, geom)

Mean of prior distribution, calculated at state x.

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.

fit_params(rfl_meas, geom, *args)

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

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

geomGeometry

Isofit geometry object

Outputs: rho_dir_dir : np.ndarray

Reflectance quantity for downward direct photon paths

rho_dif_dirnp.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.

drfl_dsurface(x_surface, geom)

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

drdn_dglint(L_tot, L_down_dir, s_alb, rho_dif_dir)

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

drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_down_dir)

Derivative of radiance with respect to full surface vector

analytical_model(background, L_down_dir, L_down_dif, 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.

summarize(x_surface, geom)

Summary of state vector.

static 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).

class LUTSurface(full_config: Config)

Bases: isofit.surface.surface.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

lut_grid

lut_names

statevec_names

data

wl

n_wl

bounds

scale

init

mean

sigma

n_state

n_lut

idx_lut

idx_lamb

itp

analytical_iv_idx

xa(x_surface, geom)

Mean of prior distribution.

Sa(x_surface, geom)

Covariance of prior distribution, calculated at state x.

Sb()

Uncertainty due to unmodeled variables.

fit_params(rfl_meas, geom, *args)

Given a reflectance estimate, fit a state vector.

calc_rfl(x_surface, geom)

Non-Lambertian reflectance.

Inputs: x_surface : np.ndarray

Surface portion of the statevector element

geomGeometry

Isofit geometry object

Outputs: rho_dir_dir : np.ndarray

Reflectance quantity for downward direct photon paths

rho_dif_dirnp.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.

calc_lamb(x_surface, geom)

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

drfl_dsurface(x_surface, geom)

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

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.

drdn_drfl(L_tot, s_alb, rho_dif_dir)

Partial derivative of radiance with respect to surface reflectance

calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

dLs_dsurface(x_surface, geom)

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

drdn_dLs(t_total_up)

Partial derivative of radiance with respect to surface emission

drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_down_dir)

Derivative of radiance with respect to full surface vector

analytical_model(background, L_down_dir, L_down_dif, 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.

summarize(x_surface, geom)

Summary of state vector.

class MultiComponentSurface(full_config: Config)

Bases: isofit.surface.surface.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 Mahalanobis distance to each component cluster, and use that as our Multivariate Gaussian surface model.

components

n_comp

wl

n_wl

normalize

selection_metric

select_on_init

refwl

idx_ref

statevec_names

idx_surface

analytical_iv_idx

bounds

scale

init

idx_lamb

n_state

full_glint = False

component(x, geom)

We pick a surface model component using the Mahalanobis distance.

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.

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.

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.

fit_params(rfl_meas, geom, *args)

Given a reflectance estimate, fit a state vector.

calc_rfl(x_surface, geom)

Non-Lambertian reflectance.

Inputs: x_surface : np.ndarray

Surface portion of the statevector element

geomGeometry

Isofit geometry object

Outputs: rho_dir_dir : np.ndarray

Reflectance quantity for downward direct photon paths

rho_dif_dirnp.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.

calc_lamb(x_surface, geom)

Lambertian reflectance.

drfl_dsurface(x_surface, geom)

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

dlamb_dsurface(x_surface, geom)

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

drdn_drfl(L_tot, s_alb, rho_dif_dir)

Partial derivative of radiance with respect to surface reflectance

calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

dLs_dsurface(x_surface, geom)

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

drdn_dLs(t_total_up)

Partial derivative of radiance with respect to surface emission

drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_down_dir)

Derivative of radiance with respect to full surface vector

analytical_model(background, L_down_dir, L_down_dif, 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

summarize(x_surface, geom)

Summary of state vector.

class ThermalSurface(full_config: Config)

Bases: isofit.surface.surface_multicomp.MultiComponentSurface

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

idx_surface

surf_temp_ind

emissive = True

n_state

emissivity_for_surface_T_init

surface_T_prior_sigma_degK

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.

Sa(x_surface, geom)

Covariance of prior distribution, calculated at state x.

fit_params(rfl_meas, geom, *args)

Given a reflectance estimate, find the surface reflectance

dlamb_dsurface(x_surface, geom)

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

calc_Ls(x_surface, geom)

Emission of surface, as a radiance.

dLs_dsurface(x_surface, geom)

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

drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_down_dir)

Derivative of radiance with respect to full surface vector

summarize(x_surface, geom)

Summary of state vector.

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

Return type:

Surface Model