System Requirements

Dependencies	None
Platforms	Windows, Linux, macOS
GPU	Not required

Quick Start

from pyhelios import Context, LeafOptics
from pyhelios.types import vec3, vec2
 
with Context() as context:
    # Create leaf geometry
    uuid = context.addPatch(center=vec3(0, 0, 1), size=vec2(0.1, 0.1))
 
    # Use LeafOptics plugin
    with LeafOptics(context) as leafoptics:
        # Get properties from species library
        props = leafoptics.getPropertiesFromLibrary("sunflower")
 
        # Compute spectra and assign to geometry
        leafoptics.run([uuid], props, "sunflower")
 
        # Retrieve computed spectra
        wavelengths, reflectance, transmittance = leafoptics.getLeafSpectra(props)
        print(f"Spectral range: {wavelengths[0]}-{wavelengths[-1]} nm ({len(wavelengths)} points)")

Introduction

This plug-in computes leaf spectral reflectance and transmittance using the PROSPECT family of models. The implementation follows the PROSPECT–PRO formulation with eight absorbing constituents and a structural parameter \(N\) that represents the number of elementary layers in the leaf. Output spectra cover the range 400–2500 nm in 1 nm steps.

For each wavelength \(\lambda\) the absorption coefficient of a single layer is calculated as

\[ k(\lambda)=\frac{C_{ab}a_{ab}(\lambda)+C_{ar}a_{ar}(\lambda)+C_{an}a_{an}(\lambda)+C_{br}a_{br}(\lambda) +C_{w}a_{w}(\lambda)+C_{m}a_{m}(\lambda)+C_{p}a_{p}(\lambda)+C_{c}a_{c}(\lambda)}{N}, \]

where the \(C\) variables are the constituent masses per area and the \(a(\lambda)\) terms are the specific absorption coefficients loaded from the internal spectral library. Fresnel equations are used to compute surface reflectance and a radiative transfer solution gives the total leaf reflectance and transmittance.

LeafOptics Class Constructor

Constructors
LeafOptics

The constructor simply stores a pointer to the Helios context and loads the spectral library data required by the model.

LeafOpticsProperties Structure

The LeafOpticsProperties structure stores the biochemical inputs to the model.

Member	Units	Description	Default Value
numberlayers	unitless	Leaf structure parameter \(N\)	1.5
brownpigments	unitless	Mass of brown pigments	0
chlorophyllcontent	\(\mu\)g cm \(^{-2}\)	Total chlorophyll	30
carotenoidcontent	\(\mu\)g cm \(^{-2}\)	Total carotenoids	7
anthocyancontent	\(\mu\)g cm \(^{-2}\)	Anthocyanins	1
watermass	g cm \(^{-2}\)	Equivalent water thickness	0.015
drymass	g cm \(^{-2}\)	Dry matter mass	0.09
protein	g cm \(^{-2}\)	Protein mass	0
carbonconstituents	g cm \(^{-2}\)	Cellulose and other carbon compounds	0
V2Z	unitless, [0,1]	Violaxanthin↔zeaxanthin de-epoxidation state. Used by the radiation plugin's solar-induced fluorescence (SIF) pipeline; ignored by PROSPECT.	0
fqe	unitless	Intrinsic fluorescence quantum-efficiency scalar applied on top of the per-leaf Phi_F at SIF emission time. Ignored by PROSPECT.	1

SIF parameters (helios-core v1.3.72+): V2Z and fqe are inert for the pure reflectance/transmittance calculation. They are written to fluspect_biochem_<label> global data on every run() so the radiation plugin's SIF camera can look them up per primitive when building Fluspect-B emission kernels.

Integration with the Radiation SIF Pipeline

The radiation plugin includes a Fluspect-B / van der Tol pipeline for simulating solar-induced chlorophyll fluorescence (SIF) — see SIF camera in the radiation docs. LeafOptics is the canonical way to author the per-leaf biochemistry that pipeline needs.

What LeafOptics Writes for SIF

Every run(uuids, props, label) call emits one extra global-data entry and one extra primitive-data label, in addition to the reflectance and transmittance outputs:

Output	Type	Description
Global data `fluspect_biochem_<label>`	`std::vector<float>` (11 elements)	Fluspect-B biochemistry vector in fixed field order: `[Cab, Cca, Cw, Cdm, Cs, Cant, Cp, Cbc, N, V2Z, fqe]`.
Primitive data `fluspect_spectrum`	`string`	Stamped on every UUID — value is `"fluspect_biochem_<label>"`. The radiation plugin reads this per primitive to identify fluorescing leaves; primitives without it are silently treated as non-fluorescing (stems, soil, etc.).

The biochemistry vector is keyed by label, so leaves sharing a spectrum label share a single Fluspect-B kernel in the radiation plugin's per-label kernel cache. This is automatic — no extra API to enable.

Field Mapping (LeafOpticsProperties → Fluspect-B)

`LeafOpticsProperties` Member	Fluspect-B Field	Notes
`chlorophyllcontent`	C_ab	Drives the dominant red-edge absorption that emits at 685 nm.
`carotenoidcontent`	C_ca	Combined with V2Z controls absorption in the 400–550 nm excitation range.
`watermass`	C_w	Equivalent water thickness (cm).
`drymass`	C_dm	PROSPECT-D dry matter (g/cm²). Set to 0 in PROSPECT-PRO mode.
`brownpigments`	C_s	Senescence/brown-pigment content.
`anthocyancontent`	C_ant
`protein`	C_p	PROSPECT-PRO only.
`carbonconstituents`	C_bc	PROSPECT-PRO only.
`numberlayers`	N	Mesophyll layer parameter.
`V2Z`	V2Z	SIF-only field; ignored by PROSPECT.
`fqe`	f_qe	SIF-only field; ignored by PROSPECT.

Minimal SIF Wiring Example

from pyhelios import Context, LeafOptics
from pyhelios.LeafOptics import LeafOpticsProperties
from pyhelios.types import vec3, vec2
 
with Context() as context:
    leaf_uuids = [context.addPatch(center=vec3(0, 0, 1), size=vec2(0.1, 0.1))]
    with LeafOptics(context) as leafoptics:
        props = LeafOpticsProperties()
        props.chlorophyllcontent = 40.0   # Cab, ug/cm^2
        props.carotenoidcontent  = 10.0   # Cca, ug/cm^2
        props.numberlayers       = 1.5
        props.watermass          = 0.009  # cm
        props.drymass            = 0.012  # g/cm^2
        props.V2Z                = 0.0    # dark-adapted; SIF-only
        props.fqe                = 1.0    # no calibration scalar; SIF-only
        leafoptics.run(leaf_uuids, props, "myleaf")
 
# Now the radiation plugin's SIF pipeline can find every leaf in leaf_uuids via the
# "fluspect_spectrum" primitive data and look up its biochemistry from the
# "fluspect_biochem_myleaf" global data — no further wiring required.

Note: the reverse path getPropertiesFromSpectrum() does not currently populate V2Z or fqe as primitive data — those fields are SIF-only and are read by the radiation plugin directly from the fluspect_biochem_* global-data vector.

Using the LeafOptics Plug-in

The model can be run to produce global spectra and, optionally, assign those spectra and optical properties to a set of primitives.

from pyhelios import Context, LeafOptics
from pyhelios.LeafOptics import LeafOpticsProperties
from pyhelios.types import vec3, vec2
 
with Context() as context:
    with LeafOptics(context) as leafoptics:
        # Set custom properties
        props = LeafOpticsProperties()
        props.chlorophyllcontent = 40.0
        props.watermass = 0.02
 
        # Create leaf geometry
        leafIDs = [context.addPatch(center=vec3(0, 0, 1), size=vec2(0.1, 0.1))]
 
        # Run the model
        leafoptics.run(leafIDs, props, "example")

This command creates global data labeled "leaf_reflectivity_example" and "leaf_transmissivity_example" containing the computed spectra. The spectra labels are also stored as primitive data for the specified UUIDs together with the biochemical property values.

Using the Built-in Species Library

The LeafOptics class includes a built-in species library that provides pre-configured optical properties for common plant species. This simplifies model usage by eliminating the need to manually specify biochemical parameters.

Basic Usage

Use the getPropertiesFromLibrary() method to return a LeafOpticsProperties structure with species-specific values:

from pyhelios import Context, LeafOptics
from pyhelios.types import vec3, vec2
 
with Context() as context:
    with LeafOptics(context) as leafoptics:
        # Get properties from library
        props = leafoptics.getPropertiesFromLibrary("default")
 
        # Create leaf geometry
        leafIDs = [context.addPatch(center=vec3(0, 0, 1), size=vec2(0.1, 0.1))]
 
        # Run the model
        leafoptics.run(leafIDs, props, "example")

The method returns a LeafOpticsProperties structure with the nine PROSPECT biochemistry parameters populated (numberlayers, chlorophyllcontent, carotenoidcontent, anthocyancontent, brownpigments, watermass, drymass, protein, carbonconstituents). The optional Fluspect-B SIF fields (V2Z, fqe) keep their dataclass defaults (0.0 and 1.0); set them on the returned object if you intend to use the radiation plugin's SIF camera.

Available Species

The library contains PROSPECT-D parameters fitted to LOPEX93 spectral library samples using the fit_prospect_visrobust.py script with robust optimization. All species use PROSPECT-D mode (drymass > 0, protein = 0, carbonconstituents = 0).

Species Label	Scientific Name	N	Cab (µg/cm²)	Car (µg/cm²)	Ant (µg/cm²)	Cbrown	Cw (g/cm²)	Cm (g/cm²)	R²	Source
"default"	-	1.50	30.0	7.00	1.00	0.000	0.0150	0.0900	-	Original Helios defaults
"garden_lettuce"	Lactuca sativa L.	2.01	30.3	6.99	1.36	0.107	0.0282	0.0053	0.993	LOPEX93 sample 0021
"alfalfa"	Medicago sativa L.	2.01	43.6	10.3	1.34	0.000	0.0190	0.0047	0.994	LOPEX93 sample 0036
"corn"	Zea mays L.	1.59	22.9	3.97	0.00	0.727	0.0150	0.0044	0.975	LOPEX93 sample 0041
"sunflower"	Helianthus annuus L.	1.76	54.1	12.9	1.75	0.011	0.0186	0.0064	0.995	LOPEX93 sample 0081
"english_walnut"	Juglans regia L.	1.56	55.9	12.5	1.74	0.000	0.0128	0.0058	0.994	LOPEX93 sample 0091
"rice"	Oryza sativa L.	1.67	37.2	10.0	0.00	0.028	0.0101	0.0048	0.998	LOPEX93 sample 0106
"soybean"	Glycine max L.	1.54	46.4	12.1	0.65	0.000	0.0101	0.0029	0.997	LOPEX93 sample 0116
"wine_grape"	Vitis vinifera L.	1.43	50.9	12.5	1.44	0.080	0.0109	0.0060	0.997	LOPEX93 sample 0276
"tomato"	Lycopersicum esculentum	1.40	48.3	11.6	1.45	0.000	0.0156	0.0026	0.997	LOPEX93 sample 0316

Notes:

Species names are case-insensitive (e.g., "corn" and "CORN" are equivalent).
R² values computed as 1 - (RMSE² / variance), indicating goodness-of-fit to measured spectra.
All parameters were fitted without affine calibration using visible-robust optimization.
LOPEX93 dataset: Hosgood B. et al. (1994), Leaf Optical Properties Experiment 93 (LOPEX93), EUR 16095 EN.

Error Handling

If an unknown species name is provided, the method:

Issues a warning message (if messages are enabled)
Populates the properties structure with default values
Does not throw an error

This ensures that code continues to run even if a species name is misspelled or not yet in the library.

Extending the Species Library

To add new species to the library, edit the species library data in the Helios C++ source code at plugins/leafoptics/src/LeafOptics.cpp. The library supports both PROSPECT-D mode (using drymass) and PROSPECT-PRO mode (using protein and carbonconstituents). Contact the PyHelios developers to request new species additions.

Retrieving PROSPECT Parameters from Spectra

The LeafOptics class maintains an internal mapping between spectrum labels and the PROSPECT parameters used to generate them. This allows users to retrieve the original model parameters from primitives that have been assigned LeafOptics-generated spectra.

Basic Usage

The getPropertiesFromSpectrum() method queries primitives for their "reflectivity_spectrum" primitive data and, if it matches a spectrum generated by the LeafOptics instance, assigns the corresponding PROSPECT parameters as primitive data:

from pyhelios import Context, LeafOptics
from pyhelios.LeafOptics import LeafOpticsProperties
from pyhelios.types import vec3, vec2
 
with Context() as context:
    with LeafOptics(context) as leafoptics:
        # Generate spectra for different leaf types
        healthy_leaf = LeafOpticsProperties()
        healthy_leaf.chlorophyllcontent = 45.0
        healthy_leaf.carotenoidcontent = 12.0
 
        stressed_leaf = LeafOpticsProperties()
        stressed_leaf.chlorophyllcontent = 20.0
        stressed_leaf.brownpigments = 0.3
 
        # Create primitives
        healthy_IDs = [context.addPatch(center=vec3(0, 0, 1), size=vec2(0.1, 0.1))]
        stressed_IDs = [context.addPatch(center=vec3(0, 0, 2), size=vec2(0.1, 0.1))]
 
        # Run model for each leaf type
        leafoptics.run(healthy_IDs, healthy_leaf, "healthy")
        leafoptics.run(stressed_IDs, stressed_leaf, "stressed")
 
        # Later, retrieve parameters from primitives based on their assigned spectra
        all_leaves = healthy_IDs + stressed_IDs
        leafoptics.getPropertiesFromSpectrum(all_leaves)
 
        # Each primitive now has parameter data matching its assigned spectrum
        chl = context.getPrimitiveData(healthy_IDs[0], "chlorophyll")
        # chl[0] = 45.0 (from healthy_leaf parameters)
 
        chl = context.getPrimitiveData(stressed_IDs[0], "chlorophyll")
        # chl[0] = 20.0 (from stressed_leaf parameters)

Method Behavior

For each UUID passed to getPropertiesFromSpectrum():

The method queries the primitive data "reflectivity_spectrum"
If the spectrum label starts with "leaf_reflectivity_", it extracts the user-provided label
If that label matches a spectrum generated by this LeafOptics instance, the corresponding parameters are assigned as primitive data
Primitives without matching spectra are silently skipped (no error is thrown)

Assigned Primitive Data Labels

The method assigns primitive data using the same labels as setProperties():

Primitive Data Label	Parameter	Condition
"chlorophyll"	chlorophyllcontent	Always
"carotenoid"	carotenoidcontent	Always
"anthocyanin"	anthocyancontent	Always
"brown"	brownpigments	If brownpigments > 0
"water"	watermass	Always
"drymass"	drymass	If drymass > 0 (PROSPECT-D mode)
"protein"	protein	If drymass = 0 (PROSPECT-PRO mode)
"cellulose"	carbonconstituents	If drymass = 0 (PROSPECT-PRO mode)

Important Notes

The parameter mapping is stored per LeafOptics instance. If you create a new LeafOptics object, it will not have access to spectra generated by a previous instance.
Only spectra generated using the run() methods are tracked. Manually created global data with "leaf_reflectivity_" prefixes will not match.
The method always overwrites existing primitive data for the parameters listed above.
Both overloads are available: pass a list of UUIDs for multiple primitives or a single UUID for one primitive.

Optional Output Primitive Data

By default, the LeafOptics plug-in writes all leaf constituent concentrations to primitive data. To selectively output only specific properties for improved performance, call optionalOutputPrimitiveData() with the desired labels before calling run().

from pyhelios import Context, LeafOptics
from pyhelios.LeafOptics import LeafOpticsProperties
from pyhelios.types import vec3, vec2
 
with Context() as context:
    with LeafOptics(context) as leafoptics:
        # Enable selective output for better performance
        leafoptics.optionalOutputPrimitiveData("chlorophyll")
        leafoptics.optionalOutputPrimitiveData("carotenoid")
 
        # Run model
        props = LeafOpticsProperties()
        leafIDs = [context.addPatch(center=vec3(0, 0, 1), size=vec2(0.1, 0.1))]
        leafoptics.run(leafIDs, props, "example")

Primitive Data Label	Units	Data Type	Description
chlorophyll	\(\mu\)g cm \(^{-2}\)	float	Total chlorophyll content
carotenoid	\(\mu\)g cm \(^{-2}\)	float	Total carotenoid content
anthocyanin	\(\mu\)g cm \(^{-2}\)	float	Anthocyanin content
brown	unitless	float	Brown pigment content (only written if value > 0)
water	g cm \(^{-2}\)	float	Equivalent water thickness
drymass	g cm \(^{-2}\)	float	Dry matter mass (PROSPECT-D mode only, when drymass > 0)
protein	g cm \(^{-2}\)	float	Protein mass (PROSPECT-PRO mode only, when drymass = 0)
cellulose	g cm \(^{-2}\)	float	Cellulose and carbon compounds (PROSPECT-PRO mode only, when drymass = 0)

*/

Dependencies	None
Python Import	`from pyhelios import LeafOptics`
Main Class	LeafOptics

Table of Contents

System Requirements

Quick Start

Introduction

LeafOptics Class Constructor

LeafOpticsProperties Structure

Integration with the Radiation SIF Pipeline

What LeafOptics Writes for SIF

Field Mapping (LeafOpticsProperties → Fluspect-B)

Minimal SIF Wiring Example

Using the LeafOptics Plug-in

Using the Built-in Species Library

Basic Usage

Available Species

Error Handling

Extending the Species Library

Retrieving PROSPECT Parameters from Spectra

Basic Usage

Method Behavior

Assigned Primitive Data Labels

Important Notes

Optional Output Primitive Data