PyHelios 0.1.11
Loading...
Searching...
No Matches
pyhelios.RadiationModel.RadiationModel Class Reference

High-level interface for radiation modeling and ray tracing. More...

Detailed Description

High-level interface for radiation modeling and ray tracing.

This class provides a user-friendly wrapper around the native Helios radiation plugin with automatic plugin availability checking and graceful error handling.

Definition at line 335 of file RadiationModel.py.

Public Member Functions

 __init__ (self, Context context)
 Initialize RadiationModel 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 GPU resources freed even without 'with' statement.
 
 get_native_ptr (self)
 Get native pointer for advanced operations.
 
 getNativePtr (self)
 Get native pointer for advanced operations.
 
 disableMessages (self)
 Disable RadiationModel status messages.
 
 enableMessages (self)
 Enable RadiationModel status messages.
 
 addRadiationBand (self, str band_label, float wavelength_min=None, float wavelength_max=None)
 Add radiation band with optional wavelength bounds.
 
 copyRadiationBand (self, str old_label, str new_label, float wavelength_min=None, float wavelength_max=None)
 Copy existing radiation band to new label, optionally with new wavelength range.
 
int addCollimatedRadiationSource (self, direction=None)
 Add collimated radiation source.
 
int addSphereRadiationSource (self, position, float radius)
 Add spherical radiation source.
 
int addSunSphereRadiationSource (self, float radius, float zenith, float azimuth, float position_scaling=1.0, float angular_width=0.53, float flux_scaling=1.0)
 Add sun sphere radiation source.
 
 setSourcePosition (self, int source_id, position)
 Set position of a radiation source.
 
int addRectangleRadiationSource (self, position, size, rotation)
 Add a rectangle (planar) radiation source.
 
int addDiskRadiationSource (self, position, float radius, rotation)
 Add a disk (circular planar) radiation source.
 
 setSourceSpectrum (self, source_id, spectrum)
 Set radiation spectrum for source(s).
 
 setSourceSpectrumIntegral (self, int source_id, float source_integral, float wavelength_min=None, float wavelength_max=None)
 Set source spectrum integral value.
 
float integrateSpectrum (self, object_spectrum, float wavelength_min=None, float wavelength_max=None, int source_id=None, camera_spectrum=None)
 Integrate spectrum with optional source/camera spectra and wavelength range.
 
float integrateSourceSpectrum (self, int source_id, float wavelength_min, float wavelength_max)
 Integrate source spectrum over wavelength range.
 
 scaleSpectrum (self, str existing_label, new_label_or_scale, float scale_factor=None)
 Scale spectrum in-place or to new label.
 
 scaleSpectrumRandomly (self, str existing_label, str new_label, float min_scale, float max_scale)
 Scale spectrum with random factor and store as new label.
 
 blendSpectra (self, str new_label, List[str] spectrum_labels, List[float] weights)
 Blend multiple spectra with specified weights.
 
 blendSpectraRandomly (self, str new_label, List[str] spectrum_labels)
 Blend multiple spectra with random weights.
 
 interpolateSpectrumFromPrimitiveData (self, List[int] primitive_uuids, List[str] spectra_labels, List[float] values, str primitive_data_query_label, str primitive_data_radprop_label)
 Interpolate spectral properties based on primitive data values.
 
 interpolateSpectrumFromObjectData (self, List[int] object_ids, List[str] spectra_labels, List[float] values, str object_data_query_label, str primitive_data_radprop_label)
 Interpolate spectral properties based on object data values.
 
 setDirectRayCount (self, str band_label, int ray_count)
 Set direct ray count for radiation band.
 
 setDiffuseRayCount (self, str band_label, int ray_count)
 Set diffuse ray count for radiation band.
 
 setDiffuseRadiationFlux (self, str label, float flux)
 Set diffuse radiation flux for band.
 
 setDiffuseRadiationExtinctionCoeff (self, str label, float K, peak_direction)
 Set diffuse radiation extinction coefficient with directional bias.
 
float getDiffuseFlux (self, str band_label)
 Get diffuse flux for band.
 
 setDiffuseSpectrum (self, band_label, str spectrum_label)
 Set diffuse spectrum from global data label.
 
 setDiffuseSpectrumIntegral (self, float spectrum_integral, float wavelength_min=None, float wavelength_max=None, str band_label=None)
 Set diffuse spectrum integral.
 
 setSourceFlux (self, source_id, str label, float flux)
 Set source flux for single source or multiple sources.
 
float getSourceFlux (self, int source_id, str label)
 Get source flux for band.
 
 updateGeometry (self, Optional[List[int]] uuids=None)
 Update geometry in radiation model.
 
 runBand (self, band_label)
 Run radiation simulation for single band or multiple bands.
 
List[float] getTotalAbsorbedFlux (self)
 Get total absorbed flux for all primitives.
 
bool doesBandExist (self, str label)
 Check if a radiation band exists.
 
 deleteRadiationSource (self, int source_id)
 Delete a radiation source.
 
 getSourcePosition (self, int source_id)
 Get position of a radiation source.
 
float getSkyEnergy (self)
 Get total sky energy.
 
float calculateGtheta (self, view_direction)
 Calculate G-function (geometry factor) for given view direction.
 
 optionalOutputPrimitiveData (self, str label)
 Enable optional primitive data output.
 
 enforcePeriodicBoundary (self, str boundary)
 Enforce periodic boundary conditions.
 
 setScatteringDepth (self, str label, int depth)
 Set scattering depth for radiation band.
 
 setMinScatterEnergy (self, str label, float energy)
 Set minimum scatter energy for radiation band.
 
 disableEmission (self, str label)
 Disable emission for radiation band.
 
 enableEmission (self, str label)
 Enable emission for radiation band.
 
 addRadiationCamera (self, str camera_label, List[str] band_labels, position, lookat_or_direction, camera_properties=None, int antialiasing_samples=100)
 Add a radiation camera to the simulation.
 
 setCameraPosition (self, str camera_label, position)
 Set camera position.
 
 getCameraPosition (self, str camera_label)
 Get camera position.
 
 setCameraLookat (self, str camera_label, lookat)
 Set camera lookat point.
 
 getCameraLookat (self, str camera_label)
 Get camera lookat point.
 
 setCameraOrientation (self, str camera_label, direction)
 Set camera orientation.
 
 getCameraOrientation (self, str camera_label)
 Get camera orientation.
 
List[str] getAllCameraLabels (self)
 Get all camera labels.
 
 setCameraSpectralResponse (self, str camera_label, str band_label, str global_data)
 Set camera spectral response from global data.
 
 setCameraSpectralResponseFromLibrary (self, str camera_label, str camera_library_name)
 Set camera spectral response from standard camera library.
 
List[float] getCameraPixelData (self, str camera_label, str band_label)
 Get camera pixel data for specific band.
 
 setCameraPixelData (self, str camera_label, str band_label, List[float] pixel_data)
 Set camera pixel data for specific band.
 
 addRadiationCameraFromLibrary (self, str camera_label, str library_camera_label, position, lookat, int antialiasing_samples=1, Optional[List[str]] band_labels=None)
 Add radiation camera loading all properties from camera library.
 
 updateCameraParameters (self, str camera_label, CameraProperties camera_properties)
 Update camera parameters for an existing camera.
 
 enableCameraMetadata (self, camera_labels)
 Enable automatic JSON metadata file writing for camera(s).
 
str writeCameraImage (self, str camera, List[str] bands, str imagefile_base, str image_path="./", int frame=-1, float flux_to_pixel_conversion=1.0)
 Write camera image to file and return output filename.
 
str writeNormCameraImage (self, str camera, List[str] bands, str imagefile_base, str image_path="./", int frame=-1)
 Write normalized camera image to file and return output filename.
 
 writeCameraImageData (self, str camera, str band, str imagefile_base, str image_path="./", int frame=-1)
 Write camera image data to file (ASCII format).
 
 writeImageBoundingBoxes (self, str camera_label, primitive_data_labels=None, object_data_labels=None, object_class_ids=None, str image_file="", str classes_txt_file="classes.txt", str image_path="./")
 Write image bounding boxes for object detection training.
 
 writeImageSegmentationMasks (self, str camera_label, primitive_data_labels=None, object_data_labels=None, object_class_ids=None, str json_filename="", str image_file="", bool append_file=False)
 Write image segmentation masks in COCO JSON format.
 
str autoCalibrateCameraImage (self, str camera_label, str red_band_label, str green_band_label, str blue_band_label, str output_file_path, bool print_quality_report=False, str algorithm="MATRIX_3X3_AUTO", str ccm_export_file_path="")
 Auto-calibrate camera image with color correction and return output filename.
 
dict getPluginInfo (self)
 Get information about the radiation plugin.
 

Public Attributes

 context = context
 
 radiation_model = None
 

Constructor & Destructor Documentation

◆ __init__()

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

Initialize RadiationModel with graceful plugin handling.

Parameters
contextHelios Context instance
Exceptions
TypeErrorIf context is not a Context instance
RadiationModelErrorIf radiation plugin is not available

Definition at line 347 of file RadiationModel.py.

◆ __del__()

pyhelios.RadiationModel.RadiationModel.__del__ ( self)

Destructor to ensure GPU resources freed even without 'with' statement.

Definition at line 416 of file RadiationModel.py.

Member Function Documentation

◆ __enter__()

pyhelios.RadiationModel.RadiationModel.__enter__ ( self)

Context manager entry.

Definition at line 401 of file RadiationModel.py.

◆ __exit__()

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

Context manager exit with proper cleanup.

Definition at line 405 of file RadiationModel.py.

◆ addCollimatedRadiationSource()

int pyhelios.RadiationModel.RadiationModel.addCollimatedRadiationSource ( self,
direction = None )

Add collimated radiation source.

Parameters
directionOptional direction vector. Can be tuple (x, y, z), vec3, or None for default direction.
Returns
Source ID

Definition at line 502 of file RadiationModel.py.

◆ addDiskRadiationSource()

int pyhelios.RadiationModel.RadiationModel.addDiskRadiationSource ( self,
position,
float radius,
rotation )

Add a disk (circular planar) radiation source.

   Disk sources are useful for modeling circular light sources such as
   spotlights, circular LED arrays, or solar simulators.
Parameters
positionCenter position as vec3 or list [x, y, z]
radiusDisk radius
rotationRotation vector as vec3 or list [rx, ry, rz] (Euler angles in radians)
Returns
Source ID
Example
>>> from pyhelios.types import vec3 >>> source_id = radiation.addDiskRadiationSource( ... position=vec3(0, 0, 5), ... radius=1.5, ... rotation=vec3(0, 0, 0) ... ) >>> radiation.setSourceFlux(source_id, "PAR", 300.0)

Definition at line 656 of file RadiationModel.py.

◆ addRadiationBand()

pyhelios.RadiationModel.RadiationModel.addRadiationBand ( self,
str band_label,
float wavelength_min = None,
float wavelength_max = None )

Add radiation band with optional wavelength bounds.

Parameters
band_labelName/label for the radiation band
wavelength_minOptional minimum wavelength (μm)
wavelength_maxOptional maximum wavelength (μm)

Definition at line 452 of file RadiationModel.py.

◆ addRadiationCamera()

pyhelios.RadiationModel.RadiationModel.addRadiationCamera ( self,
str camera_label,
List[str] band_labels,
position,
lookat_or_direction,
camera_properties = None,
int antialiasing_samples = 100 )

Add a radiation camera to the simulation.

Parameters
camera_labelUnique label string for the camera
band_labelsList of radiation band labels for the camera
positionCamera position as vec3 object
lookat_or_directionEither:
  • Lookat point as vec3 object
  • SphericalCoord for viewing direction
camera_propertiesCameraProperties instance or None for defaults
antialiasing_samplesNumber of antialiasing samples (default: 100)
Exceptions
ValidationErrorIf parameters are invalid or have wrong types
RadiationModelErrorIf camera creation fails
Example
>>> from pyhelios import vec3, CameraProperties >>> # Create camera looking at origin from above >>> camera_props = CameraProperties(camera_resolution=(1024, 1024)) >>> radiation_model.addRadiationCamera("main_camera", ["red", "green", "blue"], ... position=vec3(0, 0, 5), lookat_or_direction=vec3(0, 0, 0), ... camera_properties=camera_props)

Definition at line 1383 of file RadiationModel.py.

◆ addRadiationCameraFromLibrary()

pyhelios.RadiationModel.RadiationModel.addRadiationCameraFromLibrary ( self,
str camera_label,
str library_camera_label,
position,
lookat,
int antialiasing_samples = 1,
Optional[List[str]] band_labels = None )

Add radiation camera loading all properties from camera library.

   Loads camera intrinsic parameters (resolution, FOV, sensor size) and spectral
   response data from the camera library XML file. This is the recommended way to
   create realistic cameras with proper spectral responses.
Parameters
camera_labelLabel for the camera instance
library_camera_labelLabel of camera in library (e.g., "Canon_20D", "iPhone11", "NikonD700")
positionCamera position as vec3 or (x, y, z) tuple
lookatLookat point as vec3 or (x, y, z) tuple
antialiasing_samplesNumber of ray samples per pixel. Default: 1
band_labelsOptional custom band labels. If None, uses library defaults.
Exceptions
RadiationModelErrorIf operation fails
ValueErrorIf parameters are invalid
Note
Available cameras in plugins/radiation/camera_library/camera_library.xml include:
  • Canon_20D, Nikon_D700, Nikon_D50
  • iPhone11, iPhone12ProMAX
  • Additional cameras available in library
Example
>>> radiation.addRadiationCameraFromLibrary( ... camera_label="cam1", ... library_camera_label="iPhone11", ... position=(0, -5, 1), ... lookat=(0, 0, 0.5), ... antialiasing_samples=10 ... )

Definition at line 1715 of file RadiationModel.py.

◆ addRectangleRadiationSource()

int pyhelios.RadiationModel.RadiationModel.addRectangleRadiationSource ( self,
position,
size,
rotation )

Add a rectangle (planar) radiation source.

   Rectangle sources are ideal for modeling artificial lighting such as
   LED panels, grow lights, or window light sources.
Parameters
positionCenter position as vec3 or list [x, y, z]
sizeRectangle dimensions as vec2 or list [width, height]
rotationRotation vector as vec3 or list [rx, ry, rz] (Euler angles in radians)
Returns
Source ID
Example
>>> from pyhelios.types import vec3, vec2 >>> source_id = radiation.addRectangleRadiationSource( ... position=vec3(0, 0, 5), ... size=vec2(2, 1), ... rotation=vec3(0, 0, 0) ... ) >>> radiation.setSourceFlux(source_id, "PAR", 500.0)

Definition at line 629 of file RadiationModel.py.

◆ addSphereRadiationSource()

int pyhelios.RadiationModel.RadiationModel.addSphereRadiationSource ( self,
position,
float radius )

Add spherical radiation source.

Parameters
positionPosition of the source. Can be tuple (x, y, z) or vec3.
radiusRadius of the spherical source
Returns
Source ID

Definition at line 545 of file RadiationModel.py.

◆ addSunSphereRadiationSource()

int pyhelios.RadiationModel.RadiationModel.addSunSphereRadiationSource ( self,
float radius,
float zenith,
float azimuth,
float position_scaling = 1.0,
float angular_width = 0.53,
float flux_scaling = 1.0 )

Add sun sphere radiation source.

Parameters
radiusRadius of the sun sphere
zenithZenith angle (degrees)
azimuthAzimuth angle (degrees)
position_scalingPosition scaling factor
angular_widthAngular width of the sun (degrees)
flux_scalingFlux scaling factor
Returns
Source ID

Definition at line 573 of file RadiationModel.py.

◆ autoCalibrateCameraImage()

str pyhelios.RadiationModel.RadiationModel.autoCalibrateCameraImage ( self,
str camera_label,
str red_band_label,
str green_band_label,
str blue_band_label,
str output_file_path,
bool print_quality_report = False,
str algorithm = "MATRIX_3X3_AUTO",
str ccm_export_file_path = "" )

Auto-calibrate camera image with color correction and return output filename.

Parameters
camera_labelCamera label
red_band_labelRed band label
green_band_labelGreen band label
blue_band_labelBlue band label
output_file_pathOutput file path
print_quality_reportWhether to print quality report
algorithmColor correction algorithm ("DIAGONAL_ONLY", "MATRIX_3X3_AUTO", "MATRIX_3X3_FORCE")
ccm_export_file_pathPath to export color correction matrix (optional)
Returns
Output filename string
Exceptions
RadiationModelErrorIf auto-calibration fails
TypeErrorIf parameters have incorrect types
ValueErrorIf algorithm is not valid

Definition at line 2146 of file RadiationModel.py.

◆ blendSpectra()

pyhelios.RadiationModel.RadiationModel.blendSpectra ( self,
str new_label,
List[str] spectrum_labels,
List[float] weights )

Blend multiple spectra with specified weights.

   Creates weighted combination of spectra, useful for mixing material properties
   or creating composite light sources.
Parameters
new_labelNew global data label for blended spectrum
spectrum_labelsList of spectrum labels to blend
weightsList of weights (must sum to reasonable values, same length as labels)
Example
>>> # Mix two leaf types (70% type A, 30% type B) >>> radiation.blendSpectra("mixed_leaf", ... ["leaf_type_a", "leaf_type_b"], ... [0.7, 0.3] ... )

Definition at line 872 of file RadiationModel.py.

◆ blendSpectraRandomly()

pyhelios.RadiationModel.RadiationModel.blendSpectraRandomly ( self,
str new_label,
List[str] spectrum_labels )

Blend multiple spectra with random weights.

   Creates random combinations of spectra, useful for generating diverse
   material properties in stochastic simulations.
Parameters
new_labelNew global data label for blended spectrum
spectrum_labelsList of spectrum labels to blend
Example
>>> # Create random mixture of leaf spectra >>> radiation.blendSpectraRandomly("random_leaf", ... ["young_leaf", "mature_leaf", "senescent_leaf"] ... )

Definition at line 900 of file RadiationModel.py.

◆ calculateGtheta()

float pyhelios.RadiationModel.RadiationModel.calculateGtheta ( self,
view_direction )

Calculate G-function (geometry factor) for given view direction.

   The G-function describes the geometric relationship between leaf area
   distribution and viewing direction, important for canopy radiation modeling.
Parameters
view_directionView direction as vec3 or list/tuple [x, y, z]
Returns
G-function value
Example
>>> from pyhelios.types import vec3 >>> g_value = radiation.calculateGtheta(vec3(0, 0, 1)) >>> print(f"G-function: {g_value}")

Definition at line 1290 of file RadiationModel.py.

◆ copyRadiationBand()

pyhelios.RadiationModel.RadiationModel.copyRadiationBand ( self,
str old_label,
str new_label,
float wavelength_min = None,
float wavelength_max = None )

Copy existing radiation band to new label, optionally with new wavelength range.

Parameters
old_labelExisting band label to copy
new_labelNew label for the copied band
wavelength_minOptional minimum wavelength for new band (μm)
wavelength_maxOptional maximum wavelength for new band (μm)
Example
>>> # Copy band with same wavelength range >>> radiation.copyRadiationBand("SW", "SW_copy") >>> >>> # Copy band with different wavelength range >>> radiation.copyRadiationBand("full_spectrum", "PAR", 400, 700)

Definition at line 481 of file RadiationModel.py.

◆ deleteRadiationSource()

pyhelios.RadiationModel.RadiationModel.deleteRadiationSource ( self,
int source_id )

Delete a radiation source.

Parameters
source_idID of the radiation source to delete
Example
>>> source_id = radiation.addCollimatedRadiationSource() >>> radiation.deleteRadiationSource(source_id)

Definition at line 1229 of file RadiationModel.py.

◆ disableEmission()

pyhelios.RadiationModel.RadiationModel.disableEmission ( self,
str label )

Disable emission for radiation band.

Definition at line 1343 of file RadiationModel.py.

◆ disableMessages()

pyhelios.RadiationModel.RadiationModel.disableMessages ( self)

Disable RadiationModel status messages.

Definition at line 435 of file RadiationModel.py.

◆ doesBandExist()

bool pyhelios.RadiationModel.RadiationModel.doesBandExist ( self,
str label )

Check if a radiation band exists.

Parameters
labelName/label of the radiation band to check
Returns
True if band exists, False otherwise
Example
>>> radiation.addRadiationBand("SW") >>> radiation.doesBandExist("SW") True >>> radiation.doesBandExist("nonexistent") False

Definition at line 1213 of file RadiationModel.py.

◆ enableCameraMetadata()

pyhelios.RadiationModel.RadiationModel.enableCameraMetadata ( self,
camera_labels )

Enable automatic JSON metadata file writing for camera(s).

   When enabled, writeCameraImage() automatically creates a JSON metadata file
   alongside the image containing comprehensive camera and scene information.
Parameters
camera_labelsSingle camera label (str) or list of camera labels (List[str])
Exceptions
RadiationModelErrorIf operation fails
ValueErrorIf parameters are invalid
Note
Metadata includes:
  • Camera properties (model, lens, sensor specs)
  • Geographic location (latitude, longitude)
  • Acquisition settings (date, time, exposure, white balance)
  • Agronomic data (plant species, heights, phenology stages)
Example
>>> # Enable for single camera >>> radiation.enableCameraMetadata("cam1") >>> >>> # Enable for multiple cameras >>> radiation.enableCameraMetadata(["cam1", "cam2", "cam3"])

Definition at line 1796 of file RadiationModel.py.

◆ enableEmission()

pyhelios.RadiationModel.RadiationModel.enableEmission ( self,
str label )

Enable emission for radiation band.

Definition at line 1349 of file RadiationModel.py.

◆ enableMessages()

pyhelios.RadiationModel.RadiationModel.enableMessages ( self)

Enable RadiationModel status messages.

Definition at line 440 of file RadiationModel.py.

◆ enforcePeriodicBoundary()

pyhelios.RadiationModel.RadiationModel.enforcePeriodicBoundary ( self,
str boundary )

Enforce periodic boundary conditions.

   Periodic boundaries are useful for large-scale simulations to reduce
   edge effects by wrapping radiation at domain boundaries.
Parameters
boundaryBoundary specification string (e.g., "xy", "xyz", "x", "y", "z")
Example
>>> radiation.enforcePeriodicBoundary("xy")

Definition at line 1322 of file RadiationModel.py.

◆ get_native_ptr()

pyhelios.RadiationModel.RadiationModel.get_native_ptr ( self)

Get native pointer for advanced operations.

Definition at line 426 of file RadiationModel.py.

◆ getAllCameraLabels()

List[str] pyhelios.RadiationModel.RadiationModel.getAllCameraLabels ( self)

Get all camera labels.

Returns
List of all camera label strings
Example
>>> cameras = radiation.getAllCameraLabels() >>> print(f"Available cameras: {cameras}")

Definition at line 1579 of file RadiationModel.py.

◆ getCameraLookat()

pyhelios.RadiationModel.RadiationModel.getCameraLookat ( self,
str camera_label )

Get camera lookat point.

Parameters
camera_labelCamera label string
Returns
vec3 lookat point
Example
>>> lookat = radiation.getCameraLookat("cam1") >>> print(f"Camera looking at: {lookat}")

Definition at line 1521 of file RadiationModel.py.

◆ getCameraOrientation()

pyhelios.RadiationModel.RadiationModel.getCameraOrientation ( self,
str camera_label )

Get camera orientation.

Parameters
camera_labelCamera label string
Returns
SphericalCoord orientation [radius, elevation, azimuth]
Example
>>> orientation = radiation.getCameraOrientation("cam1") >>> print(f"Camera orientation: {orientation}")

Definition at line 1561 of file RadiationModel.py.

◆ getCameraPixelData()

List[float] pyhelios.RadiationModel.RadiationModel.getCameraPixelData ( self,
str camera_label,
str band_label )

Get camera pixel data for specific band.

   Retrieves raw pixel values for programmatic access and analysis.
Parameters
camera_labelCamera label
band_labelBand label
Returns
List of pixel values
Example
>>> pixels = radiation.getCameraPixelData("cam1", "red") >>> print(f"Mean pixel value: {sum(pixels)/len(pixels)}")

Definition at line 1643 of file RadiationModel.py.

◆ getCameraPosition()

pyhelios.RadiationModel.RadiationModel.getCameraPosition ( self,
str camera_label )

Get camera position.

Parameters
camera_labelCamera label string
Returns
vec3 position of the camera
Example
>>> position = radiation.getCameraPosition("cam1") >>> print(f"Camera at: {position}")

Definition at line 1483 of file RadiationModel.py.

◆ getDiffuseFlux()

float pyhelios.RadiationModel.RadiationModel.getDiffuseFlux ( self,
str band_label )

Get diffuse flux for band.

Parameters
band_labelBand label
Returns
Diffuse flux value
Example
>>> flux = radiation.getDiffuseFlux("SW")

Definition at line 1054 of file RadiationModel.py.

◆ getNativePtr()

pyhelios.RadiationModel.RadiationModel.getNativePtr ( self)

Get native pointer for advanced operations.

(Legacy naming for compatibility)

Definition at line 430 of file RadiationModel.py.

◆ getPluginInfo()

dict pyhelios.RadiationModel.RadiationModel.getPluginInfo ( self)

Get information about the radiation plugin.

Definition at line 2188 of file RadiationModel.py.

◆ getSkyEnergy()

float pyhelios.RadiationModel.RadiationModel.getSkyEnergy ( self)

Get total sky energy.

Returns
Total sky energy value
Example
>>> energy = radiation.getSkyEnergy() >>> print(f"Sky energy: {energy}")

Definition at line 1269 of file RadiationModel.py.

◆ getSourceFlux()

float pyhelios.RadiationModel.RadiationModel.getSourceFlux ( self,
int source_id,
str label )

Get source flux for band.

Definition at line 1126 of file RadiationModel.py.

◆ getSourcePosition()

pyhelios.RadiationModel.RadiationModel.getSourcePosition ( self,
int source_id )

Get position of a radiation source.

Parameters
source_idID of the radiation source
Returns
vec3 position of the source
Example
>>> source_id = radiation.addCollimatedRadiationSource() >>> position = radiation.getSourcePosition(source_id) >>> print(f"Source at: {position}")

Definition at line 1250 of file RadiationModel.py.

◆ getTotalAbsorbedFlux()

List[float] pyhelios.RadiationModel.RadiationModel.getTotalAbsorbedFlux ( self)

Get total absorbed flux for all primitives.

Definition at line 1190 of file RadiationModel.py.

◆ integrateSourceSpectrum()

float pyhelios.RadiationModel.RadiationModel.integrateSourceSpectrum ( self,
int source_id,
float wavelength_min,
float wavelength_max )

Integrate source spectrum over wavelength range.

Parameters
source_idSource ID
wavelength_minMinimum wavelength
wavelength_maxMaximum wavelength
Returns
Integrated source spectrum value
Example
>>> par_flux = radiation.integrateSourceSpectrum(source_id, 400, 700)

Definition at line 785 of file RadiationModel.py.

◆ integrateSpectrum()

float pyhelios.RadiationModel.RadiationModel.integrateSpectrum ( self,
object_spectrum,
float wavelength_min = None,
float wavelength_max = None,
int source_id = None,
camera_spectrum = None )

Integrate spectrum with optional source/camera spectra and wavelength range.

   This unified method handles multiple integration scenarios:
   - Basic: Total spectrum integration
   - Range: Integration over wavelength range
   - Source: Integration weighted by source spectrum
   - Camera: Integration weighted by camera spectral response
   - Full: Integration with both source and camera spectra
Parameters
object_spectrumObject spectrum as list of (wavelength, value) tuples/vec2
wavelength_minOptional minimum wavelength for integration range
wavelength_maxOptional maximum wavelength for integration range
source_idOptional source ID for source spectrum weighting
camera_spectrumOptional camera spectrum for camera response weighting
Returns
Integrated value
Example
>>> leaf_reflectance = [(400, 0.1), (500, 0.4), (600, 0.6), (700, 0.5)] >>> >>> # Total integration >>> total = radiation.integrateSpectrum(leaf_reflectance) >>> >>> # PAR range (400-700nm) >>> par = radiation.integrateSpectrum(leaf_reflectance, 400, 700) >>> >>> # With source spectrum >>> source_weighted = radiation.integrateSpectrum( ... leaf_reflectance, 400, 700, source_id=sun_source ... ) >>> >>> # With camera response >>> camera_response = [(400, 0.2), (550, 1.0), (700, 0.3)] >>> camera_weighted = radiation.integrateSpectrum( ... leaf_reflectance, camera_spectrum=camera_response ... )

Definition at line 763 of file RadiationModel.py.

◆ interpolateSpectrumFromObjectData()

pyhelios.RadiationModel.RadiationModel.interpolateSpectrumFromObjectData ( self,
List[int] object_ids,
List[str] spectra_labels,
List[float] values,
str object_data_query_label,
str primitive_data_radprop_label )

Interpolate spectral properties based on object data values.

   Automatically assigns spectra to object primitives by interpolating between
   reference spectra based on continuous object-level data values.
Parameters
object_idsList of object IDs
spectra_labelsList of reference spectrum labels
valuesList of data values corresponding to each spectrum
object_data_query_labelObject data label containing query values
primitive_data_radprop_labelPrimitive data label to store assigned spectra
Example
>>> # Assign tree reflectance based on health index >>> tree_ids = [tree1_id, tree2_id, tree3_id] >>> radiation.interpolateSpectrumFromObjectData( ... object_ids=tree_ids, ... spectra_labels=["healthy_tree", "stressed_tree", "diseased_tree"], ... values=[1.0, 0.5, 0.0], # Health index ... object_data_query_label="health_index", ... primitive_data_radprop_label="reflectance" ... )

Definition at line 979 of file RadiationModel.py.

◆ interpolateSpectrumFromPrimitiveData()

pyhelios.RadiationModel.RadiationModel.interpolateSpectrumFromPrimitiveData ( self,
List[int] primitive_uuids,
List[str] spectra_labels,
List[float] values,
str primitive_data_query_label,
str primitive_data_radprop_label )

Interpolate spectral properties based on primitive data values.

   Automatically assigns spectra to primitives by interpolating between
   reference spectra based on continuous data values (e.g., age, moisture, etc.).
Parameters
primitive_uuidsList of primitive UUIDs to assign spectra
spectra_labelsList of reference spectrum labels
valuesList of data values corresponding to each spectrum
primitive_data_query_labelPrimitive data label containing query values
primitive_data_radprop_labelPrimitive data label to store assigned spectra
Example
>>> # Assign leaf reflectance based on age >>> leaf_patches = context.getAllUUIDs("patch") >>> radiation.interpolateSpectrumFromPrimitiveData( ... primitive_uuids=leaf_patches, ... spectra_labels=["young_leaf", "mature_leaf", "old_leaf"], ... values=[0.0, 50.0, 100.0], # Days since emergence ... primitive_data_query_label="leaf_age", ... primitive_data_radprop_label="reflectance" ... )

Definition at line 935 of file RadiationModel.py.

◆ optionalOutputPrimitiveData()

pyhelios.RadiationModel.RadiationModel.optionalOutputPrimitiveData ( self,
str label )

Enable optional primitive data output.

Parameters
labelName/label of the primitive data to output
Example
>>> radiation.optionalOutputPrimitiveData("temperature")

Definition at line 1304 of file RadiationModel.py.

◆ runBand()

pyhelios.RadiationModel.RadiationModel.runBand ( self,
band_label )

Run radiation simulation for single band or multiple bands.

PERFORMANCE When simulating multiple radiation bands, it is HIGHLY RECOMMENDED
   to run all bands in a single call (e.g., runBand(["PAR", "NIR", "SW"])) rather than
   sequential single-band calls. This provides significant computational efficiency gains
   because:

   - GPU ray tracing setup is done once for all bands
   - Scene geometry acceleration structures are reused
   - OptiX kernel launches are batched together
   - Memory transfers between CPU/GPU are minimized
Example

EFFICIENT - Single call for multiple bands

radiation.runBand(["PAR", "NIR", "SW"])

INEFFICIENT - Sequential single-band calls

radiation.runBand("PAR") radiation.runBand("NIR") radiation.runBand("SW")

Parameters
band_labelSingle band name (str) or list of band names for multi-band simulation

Definition at line 1172 of file RadiationModel.py.

◆ scaleSpectrum()

pyhelios.RadiationModel.RadiationModel.scaleSpectrum ( self,
str existing_label,
new_label_or_scale,
float scale_factor = None )

Scale spectrum in-place or to new label.

   Useful for adjusting spectrum intensities or creating variations of
   existing spectra for sensitivity analysis.

   Supports two call patterns:
   - scaleSpectrum("label", scale) -> scales in-place
   - scaleSpectrum("existing", "new", scale) -> creates new scaled spectrum
Parameters
existing_labelExisting global data label
new_label_or_scaleEither new label string (if creating new) or scale factor (if in-place)
scale_factorScale factor (required only if new_label_or_scale is a string)
Example
>>> # In-place scaling >>> radiation.scaleSpectrum("leaf_reflectance", 1.2) >>> >>> # Create new scaled spectrum >>> radiation.scaleSpectrum("leaf_reflectance", "scaled_leaf", 1.5)

Definition at line 815 of file RadiationModel.py.

◆ scaleSpectrumRandomly()

pyhelios.RadiationModel.RadiationModel.scaleSpectrumRandomly ( self,
str existing_label,
str new_label,
float min_scale,
float max_scale )

Scale spectrum with random factor and store as new label.

   Useful for creating stochastic variations in spectral properties for
   Monte Carlo simulations or uncertainty quantification.
Parameters
existing_labelExisting global data label
new_labelNew global data label for scaled spectrum
min_scaleMinimum scale factor
max_scaleMaximum scale factor
Example
>>> # Create random variation of leaf reflectance >>> radiation.scaleSpectrumRandomly("leaf_base", "leaf_variant", 0.8, 1.2)

Definition at line 840 of file RadiationModel.py.

◆ setCameraLookat()

pyhelios.RadiationModel.RadiationModel.setCameraLookat ( self,
str camera_label,
lookat )

Set camera lookat point.

Parameters
camera_labelCamera label string
lookatLookat point as vec3 or list [x, y, z]
Example
>>> radiation.setCameraLookat("cam1", [0, 0, 0])

Definition at line 1501 of file RadiationModel.py.

◆ setCameraOrientation()

pyhelios.RadiationModel.RadiationModel.setCameraOrientation ( self,
str camera_label,
direction )

Set camera orientation.

Parameters
camera_labelCamera label string
directionView direction as vec3, SphericalCoord, or list [x, y, z]
Example
>>> radiation.setCameraOrientation("cam1", [0, 0, 1]) >>> from pyhelios.types import SphericalCoord >>> radiation.setCameraOrientation("cam1", SphericalCoord(1.0, 45.0, 90.0))

Definition at line 1541 of file RadiationModel.py.

◆ setCameraPixelData()

pyhelios.RadiationModel.RadiationModel.setCameraPixelData ( self,
str camera_label,
str band_label,
List[float] pixel_data )

Set camera pixel data for specific band.

   Allows programmatic modification of pixel values.
Parameters
camera_labelCamera label
band_labelBand label
pixel_dataList of pixel values
Example
>>> pixels = radiation.getCameraPixelData("cam1", "red") >>> modified_pixels = [p * 1.2 for p in pixels] # Brighten by 20% >>> radiation.setCameraPixelData("cam1", "red", modified_pixels)

Definition at line 1666 of file RadiationModel.py.

◆ setCameraPosition()

pyhelios.RadiationModel.RadiationModel.setCameraPosition ( self,
str camera_label,
position )

Set camera position.

   Allows dynamic camera repositioning during simulation, useful for
   time-series captures or multi-view imaging.
Parameters
camera_labelCamera label string
positionCamera position as vec3 or list [x, y, z]
Example
>>> radiation.setCameraPosition("cam1", [0, 0, 10]) >>> from pyhelios.types import vec3 >>> radiation.setCameraPosition("cam1", vec3(5, 5, 10))

Definition at line 1463 of file RadiationModel.py.

◆ setCameraSpectralResponse()

pyhelios.RadiationModel.RadiationModel.setCameraSpectralResponse ( self,
str camera_label,
str band_label,
str global_data )

Set camera spectral response from global data.

Parameters
camera_labelCamera label
band_labelBand label
global_dataGlobal data label for spectral response curve
Example
>>> radiation.setCameraSpectralResponse("cam1", "red", "sensor_red_response")

Definition at line 1594 of file RadiationModel.py.

◆ setCameraSpectralResponseFromLibrary()

pyhelios.RadiationModel.RadiationModel.setCameraSpectralResponseFromLibrary ( self,
str camera_label,
str camera_library_name )

Set camera spectral response from standard camera library.

   Uses pre-defined spectral response curves for common cameras.
Parameters
camera_labelCamera label
camera_library_nameStandard camera name (e.g., "iPhone13", "NikonD850", "CanonEOS5D")
Example
>>> radiation.setCameraSpectralResponseFromLibrary("cam1", "iPhone13")

Definition at line 1617 of file RadiationModel.py.

◆ setDiffuseRadiationExtinctionCoeff()

pyhelios.RadiationModel.RadiationModel.setDiffuseRadiationExtinctionCoeff ( self,
str label,
float K,
peak_direction )

Set diffuse radiation extinction coefficient with directional bias.

   Models directionally-biased diffuse radiation (e.g., sky radiation with zenith peak).
Parameters
labelBand label
KExtinction coefficient
peak_directionPeak direction as vec3, SphericalCoord, or list [x, y, z]
Example
>>> from pyhelios.types import vec3 >>> radiation.setDiffuseRadiationExtinctionCoeff("SW", 0.5, vec3(0, 0, 1))

Definition at line 1034 of file RadiationModel.py.

◆ setDiffuseRadiationFlux()

pyhelios.RadiationModel.RadiationModel.setDiffuseRadiationFlux ( self,
str label,
float flux )

Set diffuse radiation flux for band.

Definition at line 1014 of file RadiationModel.py.

◆ setDiffuseRayCount()

pyhelios.RadiationModel.RadiationModel.setDiffuseRayCount ( self,
str band_label,
int ray_count )

Set diffuse ray count for radiation band.

Definition at line 1007 of file RadiationModel.py.

◆ setDiffuseSpectrum()

pyhelios.RadiationModel.RadiationModel.setDiffuseSpectrum ( self,
band_label,
str spectrum_label )

Set diffuse spectrum from global data label.

Parameters
band_labelBand label (string) or list of band labels
spectrum_labelSpectrum global data label
Example
>>> radiation.setDiffuseSpectrum("SW", "sky_spectrum") >>> radiation.setDiffuseSpectrum(["SW", "NIR"], "sky_spectrum")

Definition at line 1070 of file RadiationModel.py.

◆ setDiffuseSpectrumIntegral()

pyhelios.RadiationModel.RadiationModel.setDiffuseSpectrumIntegral ( self,
float spectrum_integral,
float wavelength_min = None,
float wavelength_max = None,
str band_label = None )

Set diffuse spectrum integral.

Parameters
spectrum_integralIntegral value
wavelength_minOptional minimum wavelength
wavelength_maxOptional maximum wavelength
band_labelOptional specific band label (None for all bands)
Example
>>> radiation.setDiffuseSpectrumIntegral(1000.0) # All bands >>> radiation.setDiffuseSpectrumIntegral(500.0, 400, 700, band_label="PAR") # Specific band

Definition at line 1096 of file RadiationModel.py.

◆ setDirectRayCount()

pyhelios.RadiationModel.RadiationModel.setDirectRayCount ( self,
str band_label,
int ray_count )

Set direct ray count for radiation band.

Definition at line 1000 of file RadiationModel.py.

◆ setMinScatterEnergy()

pyhelios.RadiationModel.RadiationModel.setMinScatterEnergy ( self,
str label,
float energy )

Set minimum scatter energy for radiation band.

Definition at line 1338 of file RadiationModel.py.

◆ setScatteringDepth()

pyhelios.RadiationModel.RadiationModel.setScatteringDepth ( self,
str label,
int depth )

Set scattering depth for radiation band.

Definition at line 1332 of file RadiationModel.py.

◆ setSourceFlux()

pyhelios.RadiationModel.RadiationModel.setSourceFlux ( self,
source_id,
str label,
float flux )

Set source flux for single source or multiple sources.

Definition at line 1109 of file RadiationModel.py.

◆ setSourcePosition()

pyhelios.RadiationModel.RadiationModel.setSourcePosition ( self,
int source_id,
position )

Set position of a radiation source.

   Allows dynamic repositioning of radiation sources during simulation,
   useful for time-series modeling or moving light sources.
Parameters
source_idID of the radiation source
positionNew position as vec3, SphericalCoord, or list/tuple [x, y, z]
Example
>>> source_id = radiation.addCollimatedRadiationSource() >>> radiation.setSourcePosition(source_id, [10, 20, 30]) >>> from pyhelios.types import vec3 >>> radiation.setSourcePosition(source_id, vec3(15, 25, 35))

Definition at line 599 of file RadiationModel.py.

◆ setSourceSpectrum()

pyhelios.RadiationModel.RadiationModel.setSourceSpectrum ( self,
source_id,
spectrum )

Set radiation spectrum for source(s).

   Spectral distributions define how radiation intensity varies with wavelength,
   essential for realistic modeling of different light sources (sunlight, LEDs, etc.).
Parameters
source_idSource ID (int) or list of source IDs
spectrumEither:
  • Spectrum data as list of (wavelength, value) tuples
  • Global data label string
Example
>>> # Define custom LED spectrum >>> led_spectrum = [ ... (400, 0.0), (450, 0.3), (500, 0.8), ... (550, 0.5), (600, 0.2), (700, 0.0) ... ] >>> radiation.setSourceSpectrum(source_id, led_spectrum) >>> >>> # Use predefined spectrum from global data >>> radiation.setSourceSpectrum(source_id, "D65_illuminant") >>> >>> # Apply same spectrum to multiple sources >>> radiation.setSourceSpectrum([src1, src2, src3], led_spectrum)

Definition at line 689 of file RadiationModel.py.

◆ setSourceSpectrumIntegral()

pyhelios.RadiationModel.RadiationModel.setSourceSpectrumIntegral ( self,
int source_id,
float source_integral,
float wavelength_min = None,
float wavelength_max = None )

Set source spectrum integral value.

   Normalizes the spectrum so that its integral equals the specified value,
   useful for calibrating source intensity.
Parameters
source_idSource ID
source_integralTarget integral value
wavelength_minOptional minimum wavelength for integration range
wavelength_maxOptional maximum wavelength for integration range
Example
>>> radiation.setSourceSpectrumIntegral(source_id, 1000.0) >>> radiation.setSourceSpectrumIntegral(source_id, 500.0, 400, 700) # PAR range

Definition at line 710 of file RadiationModel.py.

◆ updateCameraParameters()

pyhelios.RadiationModel.RadiationModel.updateCameraParameters ( self,
str camera_label,
CameraProperties camera_properties )

Update camera parameters for an existing camera.

   Allows modification of camera properties after creation while preserving
   position, lookat direction, and spectral band configuration.
Parameters
camera_labelLabel for the camera to update
camera_propertiesCameraProperties instance with new parameters
Exceptions
RadiationModelErrorIf operation fails or camera doesn't exist
ValueErrorIf parameters are invalid
Note
FOV_aspect_ratio is automatically recalculated from camera_resolution. Camera position and lookat are preserved.
Example
>>> props = CameraProperties( ... camera_resolution=(1920, 1080), ... HFOV=35.0, ... lens_focal_length=0.085 # 85mm lens ... ) >>> radiation.updateCameraParameters("cam1", props)

Definition at line 1756 of file RadiationModel.py.

◆ updateGeometry()

pyhelios.RadiationModel.RadiationModel.updateGeometry ( self,
Optional[List[int]] uuids = None )

Update geometry in radiation model.

Parameters
uuidsOptional list of specific UUIDs to update. If None, updates all geometry.

Definition at line 1137 of file RadiationModel.py.

◆ writeCameraImage()

str pyhelios.RadiationModel.RadiationModel.writeCameraImage ( self,
str camera,
List[str] bands,
str imagefile_base,
str image_path = "./",
int frame = -1,
float flux_to_pixel_conversion = 1.0 )

Write camera image to file and return output filename.

Parameters
cameraCamera label
bandsList of band labels to include in the image
imagefile_baseBase filename for output
image_pathOutput directory path (default: current directory)
frameFrame number to write (-1 for all frames)
flux_to_pixel_conversionConversion factor from flux to pixel values
Returns
Output filename string
Exceptions
RadiationModelErrorIf camera image writing fails
TypeErrorIf parameters have incorrect types

Definition at line 1825 of file RadiationModel.py.

◆ writeCameraImageData()

pyhelios.RadiationModel.RadiationModel.writeCameraImageData ( self,
str camera,
str band,
str imagefile_base,
str image_path = "./",
int frame = -1 )

Write camera image data to file (ASCII format).

Parameters
cameraCamera label
bandBand label
imagefile_baseBase filename for output
image_pathOutput directory path (default: current directory)
frameFrame number to write (-1 for all frames)
Exceptions
RadiationModelErrorIf camera image data writing fails
TypeErrorIf parameters have incorrect types

Definition at line 1906 of file RadiationModel.py.

◆ writeImageBoundingBoxes()

pyhelios.RadiationModel.RadiationModel.writeImageBoundingBoxes ( self,
str camera_label,
primitive_data_labels = None,
object_data_labels = None,
object_class_ids = None,
str image_file = "",
str classes_txt_file = "classes.txt",
str image_path = "./" )

Write image bounding boxes for object detection training.

   Supports both single and multiple data labels. Either provide primitive_data_labels
   or object_data_labels, not both.
Parameters
camera_labelCamera label
primitive_data_labelsSingle primitive data label (str) or list of primitive data labels
object_data_labelsSingle object data label (str) or list of object data labels
object_class_idsSingle class ID (int) or list of class IDs (must match data labels)
image_fileImage filename
classes_txt_fileClasses definition file (default: "classes.txt")
image_pathImage output path (default: current directory)
Exceptions
RadiationModelErrorIf bounding box writing fails
TypeErrorIf parameters have incorrect types
ValueErrorIf both primitive and object data labels are provided, or neither

Definition at line 1946 of file RadiationModel.py.

◆ writeImageSegmentationMasks()

pyhelios.RadiationModel.RadiationModel.writeImageSegmentationMasks ( self,
str camera_label,
primitive_data_labels = None,
object_data_labels = None,
object_class_ids = None,
str json_filename = "",
str image_file = "",
bool append_file = False )

Write image segmentation masks in COCO JSON format.

   Supports both single and multiple data labels. Either provide primitive_data_labels
   or object_data_labels, not both.
Parameters
camera_labelCamera label
primitive_data_labelsSingle primitive data label (str) or list of primitive data labels
object_data_labelsSingle object data label (str) or list of object data labels
object_class_idsSingle class ID (int) or list of class IDs (must match data labels)
json_filenameJSON output filename
image_fileImage filename
append_fileWhether to append to existing JSON file
Exceptions
RadiationModelErrorIf segmentation mask writing fails
TypeErrorIf parameters have incorrect types
ValueErrorIf both primitive and object data labels are provided, or neither

Definition at line 2046 of file RadiationModel.py.

◆ writeNormCameraImage()

str pyhelios.RadiationModel.RadiationModel.writeNormCameraImage ( self,
str camera,
List[str] bands,
str imagefile_base,
str image_path = "./",
int frame = -1 )

Write normalized camera image to file and return output filename.

Parameters
cameraCamera label
bandsList of band labels to include in the image
imagefile_baseBase filename for output
image_pathOutput directory path (default: current directory)
frameFrame number to write (-1 for all frames)
Returns
Output filename string
Exceptions
RadiationModelErrorIf normalized camera image writing fails
TypeErrorIf parameters have incorrect types

Definition at line 1869 of file RadiationModel.py.

Member Data Documentation

◆ context

pyhelios.RadiationModel.RadiationModel.context = context

Definition at line 352 of file RadiationModel.py.

◆ radiation_model

pyhelios.RadiationModel.RadiationModel.radiation_model = None

Definition at line 353 of file RadiationModel.py.


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