isofit.surface ============== .. py:module:: isofit.surface Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/isofit/surface/surface/index /autoapi/isofit/surface/surface_glint_model/index /autoapi/isofit/surface/surface_lut/index /autoapi/isofit/surface/surface_multicomp/index /autoapi/isofit/surface/surface_thermal/index Classes ------- .. autoapisummary:: isofit.surface.BaseSurface isofit.surface.GlintModelSurface isofit.surface.LUTSurface isofit.surface.MultiComponentSurface isofit.surface.ThermalSurface Functions --------- .. autoapisummary:: isofit.surface.Surface Package Contents ---------------- .. py:class:: BaseSurface(full_config: Config) A model of the surface. Surface models are stored as MATLAB '.mat' format files. .. py:attribute:: model_dict :value: None .. py:attribute:: statevec_names :value: [] .. py:attribute:: idx_surface .. py:attribute:: bounds .. py:attribute:: scale .. py:attribute:: init .. py:attribute:: bvec :value: [] .. py:attribute:: bval .. py:attribute:: idx_lamb .. py:attribute:: emissive :value: False .. py:attribute:: wl :value: None .. py:attribute:: fwhm :value: None .. py:method:: resample_reflectance() Make sure model wavelengths align with the wavelength file. .. py:method:: xa(x_surface, geom) Mean of prior state vector distribution calculated at state x. .. py:method:: Sa(x_surface, geom) Covariance of prior state vector distribution calculated at state x. .. py:method:: Sb() Uncertainty due to unmodeled variables. .. py:method:: fit_params(rfl_meas, geom, *args) Given a directional reflectance estimate and one or more emissive parameters, fit a state vector. .. py:method:: calc_lamb(x_surface, geom) Calculate a Lambertian surface reflectance for this state vector. .. py:method:: calc_rfl(x_surface, geom) Calculate the directed reflectance (specifically the HRDF) for this state vector. .. py:method:: 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. .. py:method:: 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. .. py:method:: calc_Ls(x_surface, geom) Emission of surface, as a radiance. .. py:method:: 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. .. py:method:: summarize(x_surface, geom) Summary of state vector. .. py:class:: GlintModelSurface(full_config: Config) Bases: :py:obj:`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). .. py:attribute:: glint_ind .. py:attribute:: sky_glint_ind .. py:attribute:: sun_glint_ind .. py:attribute:: n_state .. py:attribute:: idx_surface .. py:attribute:: analytical_iv_idx .. py:attribute:: sun_glint_sigma .. py:attribute:: sky_glint_sigma .. py:method:: xa(x_surface, geom) Mean of prior distribution, calculated at state x. .. py:method:: 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. .. py:method:: fit_params(rfl_meas, geom, *args) Given a reflectance estimate and one or more emissive parameters, fit a state vector. .. py:method:: 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. .. py:method:: drfl_dsurface(x_surface, geom) Partial derivative of reflectance with respect to state vector, calculated at x_surface. .. py:method:: drdn_dglint(L_tot, L_down_dir, s_alb, rho_dif_dir) Derivative of radiance with respect to the direct and diffuse glint terms .. py:method:: 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 .. py:method:: 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. .. py:method:: summarize(x_surface, geom) Summary of state vector. .. py:method:: fresnel_rf(vza) :staticmethod: Calculates reflectance factor of sky radiance based on the Fresnel equation for unpolarized light as a function of view zenith angle (vza). .. py:class:: LUTSurface(full_config: Config) Bases: :py:obj:`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 .. py:attribute:: lut_grid .. py:attribute:: lut_names .. py:attribute:: statevec_names .. py:attribute:: data .. py:attribute:: wl .. py:attribute:: n_wl .. py:attribute:: bounds .. py:attribute:: scale .. py:attribute:: init .. py:attribute:: mean .. py:attribute:: sigma .. py:attribute:: n_state .. py:attribute:: n_lut .. py:attribute:: idx_lut .. py:attribute:: idx_lamb .. py:attribute:: itp .. py:attribute:: analytical_iv_idx .. py:method:: xa(x_surface, geom) Mean of prior distribution. .. py:method:: Sa(x_surface, geom) Covariance of prior distribution, calculated at state x. .. py:method:: Sb() Uncertainty due to unmodeled variables. .. py:method:: fit_params(rfl_meas, geom, *args) Given a reflectance estimate, fit a state vector. .. py:method:: 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. .. py:method:: calc_lamb(x_surface, geom) Lambertian reflectance. Be sure to incorporate BRDF-related LUT dimensions such as solar and view zenith. .. py:method:: drfl_dsurface(x_surface, geom) Partial derivative of reflectance with respect to state vector, calculated at x_surface. .. py:method:: 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. .. py:method:: drdn_drfl(L_tot, s_alb, rho_dif_dir) Partial derivative of radiance with respect to surface reflectance .. py:method:: calc_Ls(x_surface, geom) Emission of surface, as a radiance. .. py:method:: dLs_dsurface(x_surface, geom) Partial derivative of surface emission with respect to state vector, calculated at x_surface. .. py:method:: drdn_dLs(t_total_up) Partial derivative of radiance with respect to surface emission .. py:method:: 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 .. py:method:: 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. .. py:method:: summarize(x_surface, geom) Summary of state vector. .. py:class:: MultiComponentSurface(full_config: Config) Bases: :py:obj:`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. .. py:attribute:: components .. py:attribute:: n_comp .. py:attribute:: wl .. py:attribute:: n_wl .. py:attribute:: normalize .. py:attribute:: selection_metric .. py:attribute:: select_on_init .. py:attribute:: refwl .. py:attribute:: idx_ref .. py:attribute:: statevec_names .. py:attribute:: idx_surface .. py:attribute:: analytical_iv_idx .. py:attribute:: bounds .. py:attribute:: scale .. py:attribute:: init .. py:attribute:: idx_lamb .. py:attribute:: n_state .. py:attribute:: full_glint :value: False .. py:method:: 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. .. py:method:: 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. .. py:method:: 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. .. py:method:: fit_params(rfl_meas, geom, *args) Given a reflectance estimate, fit a state vector. .. py:method:: 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. .. py:method:: calc_lamb(x_surface, geom) Lambertian reflectance. .. py:method:: drfl_dsurface(x_surface, geom) Partial derivative of reflectance with respect to state vector, calculated at x_surface. .. py:method:: dlamb_dsurface(x_surface, geom) Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface. .. py:method:: drdn_drfl(L_tot, s_alb, rho_dif_dir) Partial derivative of radiance with respect to surface reflectance .. py:method:: calc_Ls(x_surface, geom) Emission of surface, as a radiance. .. py:method:: dLs_dsurface(x_surface, geom) Partial derivative of surface emission with respect to state vector, calculated at x_surface. .. py:method:: drdn_dLs(t_total_up) Partial derivative of radiance with respect to surface emission .. py:method:: 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 .. py:method:: 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 .. py:method:: summarize(x_surface, geom) Summary of state vector. .. py:class:: ThermalSurface(full_config: Config) Bases: :py:obj:`isofit.surface.surface_multicomp.MultiComponentSurface` A model of the surface based on a Mixture of a hot Black Body and Multicomponent cold surfaces. .. py:attribute:: idx_surface .. py:attribute:: surf_temp_ind .. py:attribute:: emissive :value: True .. py:attribute:: n_state .. py:attribute:: emissivity_for_surface_T_init .. py:attribute:: surface_T_prior_sigma_degK .. py:method:: 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. .. py:method:: Sa(x_surface, geom) Covariance of prior distribution, calculated at state x. .. py:method:: fit_params(rfl_meas, geom, *args) Given a reflectance estimate, find the surface reflectance .. py:method:: dlamb_dsurface(x_surface, geom) Partial derivative of Lambertian reflectance with respect to state vector, calculated at x_surface. .. py:method:: calc_Ls(x_surface, geom) Emission of surface, as a radiance. .. py:method:: dLs_dsurface(x_surface, geom) Partial derivative of surface emission with respect to state vector, calculated at x_surface. .. py:method:: 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 .. py:method:: summarize(x_surface, geom) Summary of state vector. .. py:function:: Surface(config) Reads an ISOFIT full config and initializes the desired Surface model :param config: The full_config to determine the surface category from and to pass along to the Surface model's initialization :type config: isofit.configs.Config :rtype: Surface Model