High-level interface for PROSPECT leaf optical model. More...

Detailed Description

High-level interface for PROSPECT leaf optical model.

This class provides a user-friendly wrapper around the native Helios LeafOptics plugin for computing spectral reflectance and transmittance of plant leaves based on their biochemical properties.

The PROSPECT model computes spectral optical properties for wavelengths from 400 nm to 2500 nm at 1 nm resolution (2101 data points).

System requirements:

Cross-platform support (Windows, Linux, macOS)
No GPU required
Requires spectral_data assets (~475KB XML file)
LeafOptics plugin compiled into PyHelios

Example: >>> from pyhelios import Context, LeafOptics, LeafOpticsProperties >>> >>> with Context() as context: ... with LeafOptics(context) as leafoptics: ... # Get properties for a known species ... props = leafoptics.getPropertiesFromLibrary("sunflower") ... print(f"Sunflower chlorophyll: {props.chlorophyllcontent} ug/cm^2") ... ... # Compute spectra ... wavelengths, reflectance, transmittance = leafoptics.getLeafSpectra(props) ... print(f"Spectral range: {wavelengths[0]}-{wavelengths[-1]} nm") ... ... # Apply to geometry ... leaf_uuid = context.addPatch(center=[0, 0, 1], size=[0.1, 0.1]) ... leafoptics.run([leaf_uuid], props, "sunflower_leaf")

Definition at line 223 of file LeafOptics.py.

Public Member Functions
	__init__ (self, Context context)
	Initialize LeafOptics with graceful plugin handling.

	__enter__ (self)
	Context manager entry.

	__exit__ (self, exc_type, exc_value, traceback)
	Context manager exit with proper cleanup.

	__del__ (self)
	Destructor to ensure C++ resources freed even without 'with' statement.

None	run (self, List[int] UUIDs, LeafOpticsProperties leafproperties, str label)
	Run the LeafOptics model to generate spectra and assign to primitives.

None	runNoUUIDs (self, LeafOpticsProperties leafproperties, str label)
	Run the LeafOptics model without assigning to primitives.

Tuple[List[float], List[float], List[float]]	getLeafSpectra (self, LeafOpticsProperties leafproperties)
	Compute leaf reflectance and transmittance spectra.

None	setProperties (self, List[int] UUIDs, LeafOpticsProperties leafproperties)
	Set leaf optical properties for primitives as Context primitive data.

None	getPropertiesFromSpectrum (self, List[int] UUIDs)
	Get PROSPECT parameters from reflectivity spectrum for primitives.

LeafOpticsProperties	getPropertiesFromLibrary (self, str species)
	Get leaf optical properties from the built-in species library.

None	disableMessages (self)
	Disable command-line output messages from LeafOptics.

None	enableMessages (self)
	Enable command-line output messages from LeafOptics.

None	optionalOutputPrimitiveData (self, str label)
	Selectively output specific biochemical properties as primitive data.

Static Public Member Functions
List[str]	getAvailableSpecies ()
	Get list of available species in the built-in library.

bool	isAvailable ()
	Check if LeafOptics plugin is available in the current build.

Public Attributes
	context = context

Protected Attributes
	_leafoptics_ptr = None

Constructor & Destructor Documentation

◆ init()

pyhelios.LeafOptics.LeafOptics.__init__	(		self,
		Context	context )

Initialize LeafOptics with graceful plugin handling.

Parameters

context Helios Context instance

Exceptions

TypeError	If context is not a Context instance
LeafOpticsError	If LeafOptics plugin is not available or spectral data missing

Definition at line 235 of file LeafOptics.py.

◆ del()

pyhelios.LeafOptics.LeafOptics.__del__ ( self )

Destructor to ensure C++ resources freed even without 'with' statement.

Definition at line 305 of file LeafOptics.py.

Member Function Documentation

◆ enter()

pyhelios.LeafOptics.LeafOptics.__enter__ ( self )

Context manager entry.

Definition at line 290 of file LeafOptics.py.

◆ exit()

pyhelios.LeafOptics.LeafOptics.__exit__	(	self,
		exc_type,
		exc_value,
		traceback )

Context manager exit with proper cleanup.

Definition at line 294 of file LeafOptics.py.

◆ disableMessages()

None pyhelios.LeafOptics.LeafOptics.disableMessages ( self )

Disable command-line output messages from LeafOptics.

Definition at line 516 of file LeafOptics.py.

◆ enableMessages()

None pyhelios.LeafOptics.LeafOptics.enableMessages ( self )

Enable command-line output messages from LeafOptics.

Definition at line 523 of file LeafOptics.py.

◆ getAvailableSpecies()

List[str] pyhelios.LeafOptics.LeafOptics.getAvailableSpecies ( )

static

Get list of available species in the built-in library.

Returns: List of species names that can be used with getPropertiesFromLibrary()

Definition at line 582 of file LeafOptics.py.

◆ getLeafSpectra()

Tuple[List[float], List[float], List[float]] pyhelios.LeafOptics.LeafOptics.getLeafSpectra	(		self,
		LeafOpticsProperties	leafproperties )

Compute leaf reflectance and transmittance spectra.

   This method computes spectral properties without creating global data entries
   or assigning to primitives.

Parameters

leafproperties LeafOpticsProperties with biochemical parameters

Returns

Tuple of (wavelengths, reflectivities, transmissivities):

wavelengths: List of wavelengths in nm (400-2500 at 1nm resolution, 2101 points)
reflectivities: List of reflectance values (0-1) at each wavelength
transmissivities: List of transmittance values (0-1) at each wavelength

Exceptions

ValueError	If parameters are invalid
LeafOpticsError	If computation fails

Example: >>> props = LeafOpticsProperties(chlorophyllcontent=40.0) >>> wavelengths, refl, trans = leafoptics.getLeafSpectra(props) >>> # Find reflectance at 550 nm (green peak) >>> idx_550 = wavelengths.index(550.0) >>> print(f"Reflectance at 550 nm: {refl[idx_550]:.3f}")

Definition at line 409 of file LeafOptics.py.

◆ getPropertiesFromLibrary()

LeafOpticsProperties pyhelios.LeafOptics.LeafOptics.getPropertiesFromLibrary	(		self,
		str	species )

Get leaf optical properties from the built-in species library.

   The library contains PROSPECT-D parameters fitted from the LOPEX93 dataset
   for common plant species.

Parameters

species Name of the species (case-insensitive). Available species: "default", "garden_lettuce", "alfalfa", "corn", "sunflower", "english_walnut", "rice", "soybean", "wine_grape", "tomato", "common_bean", "cowpea"

Returns: LeafOpticsProperties populated with the species-specific parameters

Exceptions

ValueError If species name is empty

Note: If species is not found, default properties are used and a warning is issued.

Example: >>> props = leafoptics.getPropertiesFromLibrary("sunflower") >>> print(f"Chlorophyll: {props.chlorophyllcontent} ug/cm^2")

Definition at line 502 of file LeafOptics.py.

◆ getPropertiesFromSpectrum()

None pyhelios.LeafOptics.LeafOptics.getPropertiesFromSpectrum	(		self,
		List[int]	UUIDs )

Get PROSPECT parameters from reflectivity spectrum for primitives.

   This method retrieves the "reflectivity_spectrum" primitive data for each
   primitive and checks if it matches a spectrum generated by this LeafOptics
   instance. If a match is found, the corresponding PROSPECT model parameters
   are assigned as primitive data.

Parameters

UUIDs List of primitive UUIDs to query

Note: Primitives without matching spectra are silently skipped.

Definition at line 465 of file LeafOptics.py.

◆ isAvailable()

bool pyhelios.LeafOptics.LeafOptics.isAvailable ( )

static

Check if LeafOptics plugin is available in the current build.

Returns: True if LeafOptics is available, False otherwise

Definition at line 592 of file LeafOptics.py.

◆ optionalOutputPrimitiveData()

None pyhelios.LeafOptics.LeafOptics.optionalOutputPrimitiveData	(		self,
		str	label )

Selectively output specific biochemical properties as primitive data.

   By default, LeafOptics writes all biochemical properties to primitive data.
   Use this method to specify only the properties you need for improved performance.

Parameters

label

Biochemical property to output. Valid values:

"chlorophyll": Chlorophyll content
"carotenoid": Carotenoid content
"anthocyanin": Anthocyanin content
"brown": Brown pigment content
"water": Water content
"drymass": Dry mass content
"protein": Protein content
"cellulose": Cellulose content

Exceptions

ValueError	If label is empty or invalid
LeafOpticsError	If operation fails

Note: Added in helios-core v1.3.59 for performance optimization when only specific biochemical properties are needed for analysis.

Example: >>> with LeafOptics(context) as leaf: ... # Only output chlorophyll and water content ... leaf.optionalOutputPrimitiveData("chlorophyll") ... leaf.optionalOutputPrimitiveData("water") ... leaf.run(uuids, properties, "leaf_spectra")

Definition at line 561 of file LeafOptics.py.

◆ run()

None pyhelios.LeafOptics.LeafOptics.run	(		self,
		List[int]	UUIDs,
		LeafOpticsProperties	leafproperties,
		str	label )

Run the LeafOptics model to generate spectra and assign to primitives.

   This method computes reflectance and transmittance spectra based on the given
   leaf properties, creates global data entries, and assigns them to the specified
   primitives.

Parameters

UUIDs	List of primitive UUIDs to assign spectra to
leafproperties	LeafOpticsProperties with biochemical parameters
label	Label for the spectra (appended to "leaf_reflectivity_" and "leaf_transmissivity_")

Exceptions

ValueError	If parameters are invalid
LeafOpticsError	If computation fails

Example: >>> props = LeafOpticsProperties(chlorophyllcontent=40.0, watermass=0.02) >>> leafoptics.run([leaf_uuid], props, "my_leaf") >>> # Creates: "leaf_reflectivity_my_leaf" and "leaf_transmissivity_my_leaf"

Definition at line 335 of file LeafOptics.py.

◆ runNoUUIDs()

None pyhelios.LeafOptics.LeafOptics.runNoUUIDs	(		self,
		LeafOpticsProperties	leafproperties,
		str	label )

Run the LeafOptics model without assigning to primitives.

   This method computes reflectance and transmittance spectra based on the given
   leaf properties and creates global data entries, but does not assign them to
   any primitives.

Parameters

leafproperties	LeafOpticsProperties with biochemical parameters
label	Label for the spectra (appended to "leaf_reflectivity_" and "leaf_transmissivity_")

Exceptions

ValueError	If parameters are invalid
LeafOpticsError	If computation fails

Definition at line 368 of file LeafOptics.py.

◆ setProperties()

None pyhelios.LeafOptics.LeafOptics.setProperties	(		self,
		List[int]	UUIDs,
		LeafOpticsProperties	leafproperties )

Set leaf optical properties for primitives as Context primitive data.

   This assigns the biochemical properties as primitive data using labels:
   "chlorophyll", "carotenoid", "anthocyanin", "brown", "water", "drymass"
   (or "protein" + "cellulose" in PROSPECT-PRO mode).

Parameters

UUIDs	List of primitive UUIDs
leafproperties	LeafOpticsProperties with biochemical parameters

Exceptions

ValueError	If parameters are invalid
LeafOpticsError	If operation fails

Definition at line 436 of file LeafOptics.py.

Member Data Documentation

◆ _leafoptics_ptr

pyhelios.LeafOptics.LeafOptics._leafoptics_ptr = None

protected

Definition at line 243 of file LeafOptics.py.

◆ context

pyhelios.LeafOptics.LeafOptics.context = context

Definition at line 242 of file LeafOptics.py.

The documentation for this class was generated from the following file:

pyhelios/LeafOptics.py

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ disableMessages()

◆ enableMessages()

◆ getAvailableSpecies()

◆ getLeafSpectra()

◆ getPropertiesFromLibrary()

◆ getPropertiesFromSpectrum()

◆ isAvailable()

◆ optionalOutputPrimitiveData()

◆ run()

◆ runNoUUIDs()

◆ setProperties()

Member Data Documentation

◆ _leafoptics_ptr

◆ context

◆ init()

◆ del()

◆ enter()

◆ exit()