Helper Classes in the BRDF Workflow

Helper Classes in the BRDF Workflow#

In addition to the core classes such as BRDFMeasurements and BRDFParameters, the BRDF framework provides several helper classes that support retrieval, correction, and visualisation tasks. These classes simplify common operations such as:

  • fitting BRDF model parameters to measured reflectances

  • correcting BRF/HCRF measurements to new viewing geometries

  • generating diagnostic and comparison plots for data analysis

The following helper classes are available:

  • BRDFFitting — performs BRDF parameter retrieval using measurable reflectances, uncertainties, and optional priors.

  • BRDFCorrections — corrects measured BRF/HCRF values to new angular configurations using a parameterised BRDF model.

  • Plotter — produces visualisations including spectral plots, polar reflectance grids, time-series plots and error-correlation matrices.

Each class integrates seamlessly with the main BRDF data structures, enabling a complete end-to-end workflow

BRDFFitting#

A fitting object is created from a BRDFMeasurements dataset:

from pydirectional import BRDFFitting
fitter = BRDFFitting(BRDFmeas)

Performing a Fit#

Fits are performed using fit_model():

results = fitter.fit_model(
    forward_model="RPV",
    retrieval_method="LM",
    initial_guess=[0.1, 0.3, 1.5],
)

Inputs include:

  • forward_model - BRDF model name (e.g. "RTLS", "RPV")

  • retrieval_method - curepy retrieval method (e.g. Markov Chain Monte Carlo)

  • initial_guess - starting point for optimisation

Optional inputs:

  • prior_shape - shape of prior distribution

  • prior_params - prior parameters

  • prior_correlation - correlation matrix for prior

  • retrieval_kwargs - method-specific options

  • return_as_BRDFparam_object - return result as BRDFParameters

The returned object is either a RetrievalResult (curepy object) or, if requested, a full BRDFParameters dataset for downstream BRDF evaluation.

BRDFCorrections#

A corrections object is constructed using a BRDFParameters instance:

from pydirectional import BRDFCorrections
corrections = BRDFCorrections(BRDFparams)

Correcting Individual Measurements#

To correct standalone reflectance arrays:

corrected = corrections.correct_BRF(
    input_reflectances=refl,
    input_angles=input_angles,
    corrected_angles=new_angles,
)

Angles must be provided as:

[solar_zenith, viewing_zenith, relative_azimuth]

Both BRF and HCRF correction routines follow the same structure.

Correcting a Full Measurement Dataset#

To correct an entire BRDFMeasurements object:

corrected_meas = corrections.correct_measurements(
    BRDFmeasurements=BRDFmeas,
    corrected_angles=new_angles,
)

This:

  • computes BRF/HCRF at original and new angles

  • applies multiplicative correction

  • updates angle variables in the dataset

BRDFPlotting#

Create a plotter instance:

from pydirectional import Plotter
p = Plotter(path="figures/", plot_format="png")

Types of Plot#

To generate a spectral plot:

p.plot_spectral(
    "spectral.png",
    wavelength=wl,
    var=params,
    y_axis_label="Parameter Value",
)

For subplot integration:

p.plot_spectral_ax(ax, wl, params, "Parameter", label="k")

To create binned polar grids:

p.plot_polar_reflectance_grid(
    "polar_grid.png",
    sza, vza, saa, vaa,
    refl,
    wavelength=550,
)

Standard deviation polar grids:

p.plot_polar_reflectance_grid_std(...)

To create timeseries plots:

p.plot_timeseries(
    "timeseries.png",
    times=datetimes,
    var=refl,
    y_axis_label="Reflectance",
)

To plot error-correlation matrices:

p.plot_err_corr_matrix(
    "corr_matrix.png",
    err_corr_matrix,
)