Helper Classes in the BRDF Workflow
===================================

In addition to the core classes such as :class:`BRDFMeasurements` and
:class:`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:

* :class:`BRDFFitting` — performs BRDF parameter retrieval using measurable
  reflectances, uncertainties, and optional priors.
* :class:`BRDFCorrections` — corrects measured BRF/HCRF values to new angular
  configurations using a parameterised BRDF model.
* :class:`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 :class:`BRDFMeasurements` dataset::

    from pydirectional import BRDFFitting
    fitter = BRDFFitting(BRDFmeas)

Performing a Fit
^^^^^^^^^^^^^^^^

Fits are performed using :meth:`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 :class:`BRDFParameters`

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

BRDFCorrections
---------------

A corrections object is constructed using a :class:`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 :class:`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,
    )