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 411 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 absorbed radiation flux density for all primitives, summed over all bands.

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.

	addSIFCamera (self, str camera_label, List[str] emission_band_labels, position, lookat_or_direction, camera_properties=None, int antialiasing_samples=100)
	Add a solar-induced chlorophyll fluorescence (SIF) camera.

bool	isSIFCamera (self, str camera_label)
	Return True if the camera was registered via :meth:`addSIFCamera` (vs.

	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).

	writePrimitiveDataLabelMap (self, str camera, str primitive_data_label, str imagefile_base, str image_path="./", int frame=-1, float padvalue=float('nan'))
	Write a per-pixel primitive-data label map for a camera to a text file.

	writeObjectDataLabelMap (self, str camera, str object_data_label, str imagefile_base, str image_path="./", int frame=-1, float padvalue=float('nan'))
	Write a per-pixel object-data label map for a camera to a text file.

'np.ndarray'	getPrimitiveDataLabelMap (self, str camera, str primitive_data_label, float padvalue=float('nan'))
	Return a per-pixel primitive-data label map for a camera as a NumPy array.

'np.ndarray'	getObjectDataLabelMap (self, str camera, str object_data_label, float padvalue=float('nan'))
	Return a per-pixel object-data label map for a camera as a NumPy array.

	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.

	writeCameraImageDataEXR (self, str camera, band, str imagefile_base, str image_path="./", int frame=-1)
	Write camera pixel data to an EXR file with lossless float compression.

	writeDepthImageData (self, str camera_label, str imagefile_base, str image_path="./", int frame=-1)
	Write depth image data to an ASCII text file.

	writeDepthImageDataEXR (self, str camera_label, str imagefile_base, str image_path="./", int frame=-1)
	Write depth image data to an EXR file with lossless float compression.

	writeNormDepthImage (self, str camera_label, str imagefile_base, float max_depth, str image_path="./", int frame=-1)
	Write normalized depth image as grayscale JPEG.

str	getBackendName (self)
	Get the name of the active ray tracing backend.

Static Public Member Functions
bool	probeAnyGPUBackend ()
	Probe whether any compiled-in GPU backend is available on this system.

Public Attributes
	context = context

	radiation_model = None

Protected Member Functions
	_check_context_alive (self)
	Raise if the owning Context has been destroyed (see Context.check_context_alive).

	_check_camera_has_pixel_data (self, str camera, List[str] bands, str operation)
	Raise an actionable error if a camera/band has no rendered pixel data.

Protected Attributes
bool	_geometry_updated = False

Constructor & Destructor Documentation

◆ init()

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

Initialize RadiationModel with graceful plugin handling.

Parameters

context Helios Context instance

Exceptions

TypeError	If context is not a Context instance
RadiationModelError	If radiation plugin is not available

Definition at line 423 of file RadiationModel.py.

◆ del()

pyhelios.RadiationModel.RadiationModel.__del__ ( self )

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

Definition at line 546 of file RadiationModel.py.

Member Function Documentation

◆ enter()

pyhelios.RadiationModel.RadiationModel.__enter__ ( self )

Context manager entry.

Definition at line 531 of file RadiationModel.py.

◆ exit()

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

Context manager exit with proper cleanup.

Definition at line 535 of file RadiationModel.py.

◆ _check_camera_has_pixel_data()

pyhelios.RadiationModel.RadiationModel._check_camera_has_pixel_data	(		self,
		str	camera,
		List[str]	bands,
		str	operation )

protected

Raise an actionable error if a camera/band has no rendered pixel data.

   A camera's pixel data is populated only by ``runBand()``, and only for
   the bands passed to that call and for cameras that already existed when
   it ran. Requesting an image for an unrendered camera/band otherwise
   reaches the native layer as a bare ``invalid map<K, T> key`` from
   ``std::map::at`` -- see GitHub issue #4 and the upstream fix landing in
   helios-core v1.3.79. This preflight turns that into a message naming the
   camera, the band, and the call the user is missing.

   Kept after the upstream fix lands: it stays correct (merely redundant)
   against a fixed core, and users on earlier versions still need it.

Definition at line 503 of file RadiationModel.py.

◆ _check_context_alive()

pyhelios.RadiationModel.RadiationModel._check_context_alive ( self )

protected

Raise if the owning Context has been destroyed (see Context.check_context_alive).

Definition at line 485 of file RadiationModel.py.

◆ addCollimatedRadiationSource()

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

Add collimated radiation source.

Parameters

direction Optional direction vector. Can be tuple (x, y, z), vec3, or None for default direction.

Returns: Source ID

Definition at line 637 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

position	Center position as vec3 or list [x, y, z]
radius	Disk radius
rotation	Rotation 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 800 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_label	Name/label for the radiation band
wavelength_min	Optional minimum wavelength (nm)
wavelength_max	Optional maximum wavelength (nm)

Definition at line 584 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_label	Unique label string for the camera
band_labels	List of radiation band labels for the camera
position	Camera position as vec3 object
lookat_or_direction	Either: Lookat point as vec3 object SphericalCoord for viewing direction
camera_properties	CameraProperties instance or None for defaults
antialiasing_samples	Number of antialiasing samples (default: 100)

Exceptions

ValidationError	If parameters are invalid or have wrong types
RadiationModelError	If 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 1620 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_label	Label for the camera instance
library_camera_label	Label of camera in library (e.g., "Canon_20D", "iPhone11", "NikonD700")
position	Camera position as vec3 or (x, y, z) tuple
lookat	Lookat point as vec3 or (x, y, z) tuple
antialiasing_samples	Number of ray samples per pixel. Default: 1
band_labels	Optional custom band labels. If None, uses library defaults.

Exceptions

RadiationModelError	If operation fails
ValueError	If 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 2067 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

position	Center position as vec3 or list [x, y, z]
size	Rectangle dimensions as vec2 or list [width, height]
rotation	Rotation 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 769 of file RadiationModel.py.

◆ addSIFCamera()

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

Add a solar-induced chlorophyll fluorescence (SIF) camera.

   Each band in ``emission_band_labels`` must already exist (added via
   :meth:`addRadiationBand`); those bands are flagged internally as SIF-emitting and
   use the Fluspect-B leaf-fluorescence kernel for emission instead of Stefan-Boltzmann.
   Helios auto-creates internal radiation bands covering 400-750 nm at the resolution
   specified by ``camera_properties.excitation_bin_width_nm``.

Parameters

camera_label	Unique label for the camera.
emission_band_labels	List of pre-existing radiation band labels to drive with SIF emission.
position	Camera position as a `vec3`.
lookat_or_direction	Either a `vec3` lookat point or a `SphericalCoord` viewing direction.
camera_properties	:class:`SIFCameraProperties` instance. If `None` defaults are used (10 nm excitation bins, no excitation scattering).
antialiasing_samples	Antialiasing samples per pixel (>= 1, default 100).

Exceptions

RadiationModelError	If the underlying SIF camera cannot be added (e.g., an emission band was already bound to a different excitation bin width).
NotImplementedError	If running against helios-core older than v1.3.72.

Definition at line 1713 of file RadiationModel.py.

◆ addSphereRadiationSource()

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

Add spherical radiation source.

Parameters

position	Position of the source. Can be tuple (x, y, z) or vec3.
radius	Radius of the spherical source

Returns: Source ID

Definition at line 682 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

radius	Radius of the sun sphere
zenith	Zenith angle (degrees)
azimuth	Azimuth angle (degrees)
position_scaling	Position scaling factor
angular_width	Angular width of the sun (degrees)
flux_scaling	Flux scaling factor

Returns: Source ID

Definition at line 710 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_label	Camera label
red_band_label	Red band label
green_band_label	Green band label
blue_band_label	Blue band label
output_file_path	Output file path
print_quality_report	Whether to print quality report
algorithm	Color correction algorithm ("DIAGONAL_ONLY", "MATRIX_3X3_AUTO", "MATRIX_3X3_FORCE")
ccm_export_file_path	Path to export color correction matrix (optional)

Returns: Output filename string

Exceptions

RadiationModelError	If auto-calibration fails
TypeError	If parameters have incorrect types
ValueError	If algorithm is not valid

Definition at line 2698 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_label	New global data label for blended spectrum
spectrum_labels	List of spectrum labels to blend
weights	List 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 1025 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_label	New global data label for blended spectrum
spectrum_labels	List 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 1054 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.

   The G-function is computed from the geometry currently loaded in the radiation
   model. If updateGeometry() has not yet been called, this method calls it
   automatically (with a warning) so the query operates on the current context
   geometry. If the result is still undefined (no primitives / zero leaf area),
   a RuntimeError is raised rather than silently returning NaN.

Parameters

view_direction View direction as vec3 or list/tuple [x, y, z]

Returns: G-function value

Exceptions

RuntimeError If the context has no geometry (or zero total leaf area), so the G-function is undefined.

Example: >>> from pyhelios.types import vec3 >>> radiation.updateGeometry() >>> g_value = radiation.calculateGtheta(vec3(0, 0, 1)) >>> print(f"G-function: {g_value}")

Definition at line 1501 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_label	Existing band label to copy
new_label	New label for the copied band
wavelength_min	Optional minimum wavelength for new band (nm)
wavelength_max	Optional maximum wavelength for new band (nm)

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 615 of file RadiationModel.py.

◆ deleteRadiationSource()

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

Delete a radiation source.

Parameters

source_id ID of the radiation source to delete

Example: >>> source_id = radiation.addCollimatedRadiationSource() >>> radiation.deleteRadiationSource(source_id)

Definition at line 1426 of file RadiationModel.py.

◆ disableEmission()

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

Disable emission for radiation band.

Definition at line 1578 of file RadiationModel.py.

◆ disableMessages()

pyhelios.RadiationModel.RadiationModel.disableMessages ( self )

Disable RadiationModel status messages.

Definition at line 565 of file RadiationModel.py.

◆ doesBandExist()

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

Check if a radiation band exists.

Parameters

label Name/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 1409 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_labels Single camera label (str) or list of camera labels (List[str])

Exceptions

RadiationModelError	If operation fails
ValueError	If 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 2152 of file RadiationModel.py.

◆ enableEmission()

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

Enable emission for radiation band.

Definition at line 1585 of file RadiationModel.py.

◆ enableMessages()

pyhelios.RadiationModel.RadiationModel.enableMessages ( self )

Enable RadiationModel status messages.

Definition at line 571 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

boundary Boundary specification string (e.g., "xy", "xyz", "x", "y", "z")

Example: >>> radiation.enforcePeriodicBoundary("xy")

Definition at line 1554 of file RadiationModel.py.

◆ get_native_ptr()

pyhelios.RadiationModel.RadiationModel.get_native_ptr ( self )

Get native pointer for advanced operations.

Definition at line 556 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 1926 of file RadiationModel.py.

◆ getBackendName()

str pyhelios.RadiationModel.RadiationModel.getBackendName ( self )

Get the name of the active ray tracing backend.

Returns: Backend name string (e.g., "OptiX 8.1", "Vulkan Compute")

Definition at line 2896 of file RadiationModel.py.

◆ getCameraLookat()

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

Get camera lookat point.

Parameters

camera_label Camera label string

Returns: vec3 lookat point

Example: >>> lookat = radiation.getCameraLookat("cam1") >>> print(f"Camera looking at: {lookat}")

Definition at line 1864 of file RadiationModel.py.

◆ getCameraOrientation()

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

Get camera orientation.

Parameters

camera_label Camera label string

Returns: SphericalCoord orientation [radius, elevation, azimuth]

Example: >>> orientation = radiation.getCameraOrientation("cam1") >>> print(f"Camera orientation: {orientation}")

Definition at line 1907 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_label	Camera label
band_label	Band label

Returns: List of pixel values

Example: >>> pixels = radiation.getCameraPixelData("cam1", "red") >>> print(f"Mean pixel value: {sum(pixels)/len(pixels)}")

Definition at line 1993 of file RadiationModel.py.

◆ getCameraPosition()

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

Get camera position.

Parameters

camera_label Camera label string

Returns: vec3 position of the camera

Example: >>> position = radiation.getCameraPosition("cam1") >>> print(f"Camera at: {position}")

Definition at line 1823 of file RadiationModel.py.

◆ getDiffuseFlux()

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

Get diffuse flux for band.

Parameters

band_label Band label

Returns: Diffuse flux value

Example: >>> flux = radiation.getDiffuseFlux("SW")

Definition at line 1216 of file RadiationModel.py.

◆ getNativePtr()

pyhelios.RadiationModel.RadiationModel.getNativePtr ( self )

Get native pointer for advanced operations.

(Legacy naming for compatibility)

Definition at line 560 of file RadiationModel.py.

◆ getObjectDataLabelMap()

'np.ndarray' pyhelios.RadiationModel.RadiationModel.getObjectDataLabelMap	(		self,
		str	camera,
		str	object_data_label,
		float	padvalue = float('nan') )

Return a per-pixel object-data label map for a camera as a NumPy array.

   Convenience wrapper around :meth:`writeObjectDataLabelMap`; see
   :meth:`getPrimitiveDataLabelMap` for behaviour. The label map is written to a temporary
   file, loaded with ``numpy.loadtxt``, and returned as a 2D ``(height, width)`` array with
   ``padvalue`` (NaN by default) for background pixels. The file does not persist.

Parameters

camera	Camera label
object_data_label	Object data label to map (float/double/uint/int)
padvalue	Value used for empty/background pixels (default: NaN)

Returns: 2D NumPy array of shape (height, width) (row-major).

Exceptions

RadiationModelError	If the label map generation fails
TypeError	If parameters have incorrect types

Definition at line 2455 of file RadiationModel.py.

◆ getPluginInfo()

dict pyhelios.RadiationModel.RadiationModel.getPluginInfo ( self )

Get information about the radiation plugin.

Definition at line 2741 of file RadiationModel.py.

◆ getPrimitiveDataLabelMap()

'np.ndarray' pyhelios.RadiationModel.RadiationModel.getPrimitiveDataLabelMap	(		self,
		str	camera,
		str	primitive_data_label,
		float	padvalue = float('nan') )

Return a per-pixel primitive-data label map for a camera as a NumPy array.

   Convenience wrapper around :meth:`writePrimitiveDataLabelMap` for the common use case
   of per-pixel masking in Python: the label map is written to a temporary file, loaded
   with ``numpy.loadtxt``, and returned as a 2D array. The file does not persist.

Parameters

camera	Camera label
primitive_data_label	Primitive data label to map (float/double/uint/int)
padvalue	Value used for empty/background pixels (default: NaN)

Returns: 2D NumPy array of shape (height, width) (row-major) holding the primitive-data value at each pixel, with padvalue (NaN by default) where no labelled geometry was seen.

Exceptions

RadiationModelError	If the label map generation fails
TypeError	If parameters have incorrect types

Example: >>> labels = radiation.getPrimitiveDataLabelMap("main_cam", "leaf_id") >>> mask = labels == 3 # per-pixel mask for primitive label 3 >>> background = np.isnan(labels)

Definition at line 2418 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 1468 of file RadiationModel.py.

◆ getSourceFlux()

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

Get source flux for band.

Definition at line 1293 of file RadiationModel.py.

◆ getSourcePosition()

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

Get position of a radiation source.

Parameters

source_id ID 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 1448 of file RadiationModel.py.

◆ getTotalAbsorbedFlux()

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

Get absorbed radiation flux density for all primitives, summed over all bands.

   Returns one value per primitive, in the Context's primitive order (matching
   ``context.getAllUUIDs()``).

   Units are **W/m^2** (flux density), not watts. This is the sum of the
   ``radiation_flux_<band>`` primitive data over every band added to the model.
   Because it is a density, the value does not change when a primitive's size
changes a 1x1 m and a 2x2 m patch under the same collimated source both
   report the same number.

   To obtain absorbed power in watts, weight each primitive by its area::

       flux = radiation.getTotalAbsorbedFlux()
       power = sum(f * context.getPrimitiveArea(u)
                   for f, u in zip(flux, context.getAllUUIDs()))

   Summing the returned values directly (``sum(flux)``) adds flux densities of
   differently-sized surfaces and is not physically meaningful.

Returns: Absorbed flux density per primitive in W/m^2.

Definition at line 1385 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_id	Source ID
wavelength_min	Minimum wavelength
wavelength_max	Maximum wavelength

Returns: Integrated source spectrum value

Example: >>> par_flux = radiation.integrateSourceSpectrum(source_id, 400, 700)

Definition at line 935 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_spectrum	Object spectrum as list of (wavelength, value) tuples/vec2
wavelength_min	Optional minimum wavelength for integration range
wavelength_max	Optional maximum wavelength for integration range
source_id	Optional source ID for source spectrum weighting
camera_spectrum	Optional 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 912 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_ids	List of object IDs
spectra_labels	List of reference spectrum labels
values	List of data values corresponding to each spectrum
object_data_query_label	Object data label containing query values
primitive_data_radprop_label	Primitive 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 1135 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_uuids	List of primitive UUIDs to assign spectra
spectra_labels	List of reference spectrum labels
values	List of data values corresponding to each spectrum
primitive_data_query_label	Primitive data label containing query values
primitive_data_radprop_label	Primitive 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 1090 of file RadiationModel.py.

◆ isSIFCamera()

bool pyhelios.RadiationModel.RadiationModel.isSIFCamera	(		self,
		str	camera_label )

Return True if the camera was registered via :meth:addSIFCamera (vs.

addRadiationCamera).

Definition at line 1778 of file RadiationModel.py.

◆ optionalOutputPrimitiveData()

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

Enable optional primitive data output.

Parameters

label Name/label of the primitive data to output

Example: >>> radiation.optionalOutputPrimitiveData("temperature")

Definition at line 1535 of file RadiationModel.py.

◆ probeAnyGPUBackend()

bool pyhelios.RadiationModel.RadiationModel.probeAnyGPUBackend ( )

static

Probe whether any compiled-in GPU backend is available on this system.

   Probes backends in priority order (OptiX 8 -> OptiX 6 -> Vulkan) without
   constructing a full backend. Useful for checking GPU availability before
   creating a RadiationModel.

Returns: True if at least one GPU backend is available

Definition at line 2911 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
   - GPU 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_label Single band name (str) or list of band names for multi-band simulation

Definition at line 1343 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_label	Existing global data label
new_label_or_scale	Either new label string (if creating new) or scale factor (if in-place)
scale_factor	Scale 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 966 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_label	Existing global data label
new_label	New global data label for scaled spectrum
min_scale	Minimum scale factor
max_scale	Maximum scale factor

Example: >>> # Create random variation of leaf reflectance >>> radiation.scaleSpectrumRandomly("leaf_base", "leaf_variant", 0.8, 1.2)

Definition at line 992 of file RadiationModel.py.

◆ setCameraLookat()

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

Set camera lookat point.

Parameters

camera_label	Camera label string
lookat	Lookat point as vec3 or list [x, y, z]

Example: >>> radiation.setCameraLookat("cam1", [0, 0, 0])

Definition at line 1842 of file RadiationModel.py.

◆ setCameraOrientation()

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

Set camera orientation.

Parameters

camera_label	Camera label string
direction	View 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 1885 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_label	Camera label
band_label	Band label
pixel_data	List 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 2017 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_label	Camera label string
position	Camera 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 1801 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_label	Camera label
band_label	Band label
global_data	Global data label for spectral response curve

Example: >>> radiation.setCameraSpectralResponse("cam1", "red", "sensor_red_response")

Definition at line 1942 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_label	Camera label
camera_library_name	Standard camera name (e.g., "iPhone13", "NikonD850", "CanonEOS5D")

Example: >>> radiation.setCameraSpectralResponseFromLibrary("cam1", "iPhone13")

Definition at line 1966 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

label	Band label
K	Extinction coefficient
peak_direction	Peak 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 1194 of file RadiationModel.py.

◆ setDiffuseRadiationFlux()

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

Set diffuse radiation flux for band.

Definition at line 1173 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 1165 of file RadiationModel.py.

◆ setDiffuseSpectrum()

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

Set diffuse spectrum from global data label.

Parameters

band_label	Band label (string) or list of band labels
spectrum_label	Spectrum global data label

Example: >>> radiation.setDiffuseSpectrum("SW", "sky_spectrum") >>> radiation.setDiffuseSpectrum(["SW", "NIR"], "sky_spectrum")

Definition at line 1233 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_integral	Integral value
wavelength_min	Optional minimum wavelength
wavelength_max	Optional maximum wavelength
band_label	Optional 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 1260 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 1157 of file RadiationModel.py.

◆ setMinScatterEnergy()

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

Set minimum scatter energy for radiation band.

Definition at line 1572 of file RadiationModel.py.

◆ setScatteringDepth()

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

Set scattering depth for radiation band.

Definition at line 1565 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 1274 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_id	ID of the radiation source
position	New 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 737 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_id	Source ID (int) or list of source IDs
spectrum	Either: 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 836 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_id	Source ID
source_integral	Target integral value
wavelength_min	Optional minimum wavelength for integration range
wavelength_max	Optional 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 858 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_label	Label for the camera to update
camera_properties	CameraProperties instance with new parameters

Exceptions

RadiationModelError	If operation fails or camera doesn't exist
ValueError	If 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 2111 of file RadiationModel.py.

◆ updateGeometry()

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

Update geometry in radiation model.

Parameters

uuids Optional list of specific UUIDs to update. If None, updates all geometry.

Definition at line 1305 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

camera	Camera label
bands	List of band labels to include in the image
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to write (-1 for all frames)
flux_to_pixel_conversion	Conversion factor from flux to pixel values

Returns: Output filename string

Exceptions

RadiationModelError	If camera image writing fails
TypeError	If parameters have incorrect types

Definition at line 2182 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

camera	Camera label
band	Band label
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to write (-1 for all frames)

Exceptions

RadiationModelError	If camera image data writing fails
TypeError	If parameters have incorrect types

Definition at line 2267 of file RadiationModel.py.

◆ writeCameraImageDataEXR()

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

Write camera pixel data to an EXR file with lossless float compression.

   Preserves full floating-point precision unlike JPEG/PNG exports.

Parameters

camera	Camera label
band	Band label (str) for single-band, or list of band labels for multi-band
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to append to filename (-1 to omit)

Exceptions

RadiationModelError	If writing fails
TypeError	If parameters have incorrect types

Definition at line 2765 of file RadiationModel.py.

◆ writeDepthImageData()

pyhelios.RadiationModel.RadiationModel.writeDepthImageData	(		self,
		str	camera_label,
		str	imagefile_base,
		str	image_path = "./",
		int	frame = -1 )

Write depth image data to an ASCII text file.

Parameters

camera_label	Camera label
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to append to filename (-1 to omit)

Exceptions

RadiationModelError	If writing fails
TypeError	If parameters have incorrect types

Definition at line 2805 of file RadiationModel.py.

◆ writeDepthImageDataEXR()

pyhelios.RadiationModel.RadiationModel.writeDepthImageDataEXR	(		self,
		str	camera_label,
		str	imagefile_base,
		str	image_path = "./",
		int	frame = -1 )

Write depth image data to an EXR file with lossless float compression.

   Preserves full floating-point depth precision unlike ASCII or JPEG exports.

Parameters

camera_label	Camera label
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to append to filename (-1 to omit)

Exceptions

RadiationModelError	If writing fails
TypeError	If parameters have incorrect types

Definition at line 2835 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_label	Camera label
primitive_data_labels	Single primitive data label (str) or list of primitive data labels
object_data_labels	Single object data label (str) or list of object data labels
object_class_ids	Single class ID (int) or list of class IDs (must match data labels)
image_file	Image filename
classes_txt_file	Classes definition file (default: "classes.txt")
image_path	Image output path (default: current directory)

Exceptions

RadiationModelError	If bounding box writing fails
TypeError	If parameters have incorrect types
ValueError	If both primitive and object data labels are provided, or neither

Definition at line 2490 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_label	Camera label
primitive_data_labels	Single primitive data label (str) or list of primitive data labels
object_data_labels	Single object data label (str) or list of object data labels
object_class_ids	Single class ID (int) or list of class IDs (must match data labels)
json_filename	JSON output filename
image_file	Image filename
append_file	Whether to append to existing JSON file

Exceptions

RadiationModelError	If segmentation mask writing fails
TypeError	If parameters have incorrect types
ValueError	If both primitive and object data labels are provided, or neither

Definition at line 2594 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

camera	Camera label
bands	List of band labels to include in the image
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to write (-1 for all frames)

Returns: Output filename string

Exceptions

RadiationModelError	If normalized camera image writing fails
TypeError	If parameters have incorrect types

Definition at line 2228 of file RadiationModel.py.

◆ writeNormDepthImage()

pyhelios.RadiationModel.RadiationModel.writeNormDepthImage	(		self,
		str	camera_label,
		str	imagefile_base,
		float	max_depth,
		str	image_path = "./",
		int	frame = -1 )

Write normalized depth image as grayscale JPEG.

   Depth values are normalized to the range [0, max_depth] for visualization.

Parameters

camera_label	Camera label
imagefile_base	Base filename for output
max_depth	Maximum depth value for normalization (e.g., sky depth)
image_path	Output directory path (default: current directory)
frame	Frame number to append to filename (-1 to omit)

Exceptions

RadiationModelError	If writing fails
TypeError	If parameters have incorrect types
ValueError	If max_depth is not positive

Definition at line 2867 of file RadiationModel.py.

◆ writeObjectDataLabelMap()

pyhelios.RadiationModel.RadiationModel.writeObjectDataLabelMap	(		self,
		str	camera,
		str	object_data_label,
		str	imagefile_base,
		str	image_path = "./",
		int	frame = -1,
		float	padvalue = float('nan') )

Write a per-pixel object-data label map for a camera to a text file.

   Identical to :meth:`writePrimitiveDataLabelMap` but maps the value of an object-data
   label (compound-object data) rather than primitive data. The object data must be of
   type float, double, uint, or int. The radiation model must have been run
   (``updateGeometry`` + ``runBand``) so that per-pixel labels exist.

Output  ``{camera}_{imagefile_base}.txt`` when ``frame < 0`` (default), or
   ``{camera}_{imagefile_base}_{frame:05d}.txt`` when ``frame >= 0``.

Parameters

camera	Camera label
object_data_label	Object data label to map (float/double/uint/int)
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to write (-1 to omit the frame suffix)
padvalue	Value written for empty/background pixels (default: NaN)

Exceptions

RadiationModelError	If the label map writing fails
TypeError	If parameters have incorrect types

Definition at line 2368 of file RadiationModel.py.

◆ writePrimitiveDataLabelMap()

pyhelios.RadiationModel.RadiationModel.writePrimitiveDataLabelMap	(		self,
		str	camera,
		str	primitive_data_label,
		str	imagefile_base,
		str	image_path = "./",
		int	frame = -1,
		float	padvalue = float('nan') )

Write a per-pixel primitive-data label map for a camera to a text file.

   For each camera pixel, writes the value of ``primitive_data_label`` on the primitive
   seen at that pixel. Pixels that hit no geometry (or a primitive lacking the data) are
   written as ``padvalue`` (NaN by default). The primitive data must be of type
   float, double, uint, or int. The radiation model must have been run
   (``updateGeometry`` + ``runBand``) so that per-pixel primitive labels exist.

   The output file is written row-by-row (one line per image row), so it loads directly
   into a 2D ``(height, width)`` array. See :meth:`getPrimitiveDataLabelMap` for a
   convenience that returns a NumPy array instead of a file on disk.

Output  ``{camera}_{imagefile_base}.txt`` when ``frame < 0`` (default), or
   ``{camera}_{imagefile_base}_{frame:05d}.txt`` when ``frame >= 0``.

Parameters

camera	Camera label
primitive_data_label	Primitive data label to map (float/double/uint/int)
imagefile_base	Base filename for output
image_path	Output directory path (default: current directory)
frame	Frame number to write (-1 to omit the frame suffix)
padvalue	Value written for empty/background pixels (default: NaN)

Exceptions

RadiationModelError	If the label map writing fails
TypeError	If parameters have incorrect types

Example: >>> radiation.writePrimitiveDataLabelMap( ... camera="main_cam", primitive_data_label="leaf_id", ... imagefile_base="leaf_labels", image_path="./output")

Definition at line 2321 of file RadiationModel.py.

Member Data Documentation

◆ _geometry_updated

bool pyhelios.RadiationModel.RadiationModel._geometry_updated = False

protected

Definition at line 434 of file RadiationModel.py.

◆ context

pyhelios.RadiationModel.RadiationModel.context = context

Definition at line 428 of file RadiationModel.py.

◆ radiation_model

pyhelios.RadiationModel.RadiationModel.radiation_model = None

Definition at line 429 of file RadiationModel.py.

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

pyhelios/RadiationModel.py

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ _check_camera_has_pixel_data()

◆ _check_context_alive()

◆ addCollimatedRadiationSource()

◆ addDiskRadiationSource()

◆ addRadiationBand()

◆ addRadiationCamera()

◆ addRadiationCameraFromLibrary()

◆ addRectangleRadiationSource()

◆ addSIFCamera()

◆ addSphereRadiationSource()

◆ addSunSphereRadiationSource()

◆ autoCalibrateCameraImage()

◆ blendSpectra()

◆ blendSpectraRandomly()

◆ calculateGtheta()

◆ copyRadiationBand()

◆ deleteRadiationSource()

◆ disableEmission()

◆ disableMessages()

◆ doesBandExist()

◆ enableCameraMetadata()

◆ enableEmission()

◆ enableMessages()

◆ enforcePeriodicBoundary()

◆ get_native_ptr()

◆ getAllCameraLabels()

◆ getBackendName()

◆ getCameraLookat()

◆ getCameraOrientation()

◆ getCameraPixelData()

◆ getCameraPosition()

◆ getDiffuseFlux()

◆ getNativePtr()

◆ getObjectDataLabelMap()

◆ getPluginInfo()

◆ getPrimitiveDataLabelMap()

◆ getSkyEnergy()

◆ getSourceFlux()

◆ getSourcePosition()

◆ getTotalAbsorbedFlux()

◆ integrateSourceSpectrum()

◆ integrateSpectrum()

◆ interpolateSpectrumFromObjectData()

◆ interpolateSpectrumFromPrimitiveData()

◆ isSIFCamera()

◆ optionalOutputPrimitiveData()

◆ probeAnyGPUBackend()

◆ runBand()

EFFICIENT - Single call for multiple bands

INEFFICIENT - Sequential single-band calls

◆ scaleSpectrum()

◆ scaleSpectrumRandomly()

◆ setCameraLookat()

◆ setCameraOrientation()

◆ setCameraPixelData()

◆ setCameraPosition()

◆ setCameraSpectralResponse()

◆ setCameraSpectralResponseFromLibrary()

◆ setDiffuseRadiationExtinctionCoeff()

◆ setDiffuseRadiationFlux()

◆ setDiffuseRayCount()

◆ setDiffuseSpectrum()

◆ setDiffuseSpectrumIntegral()

◆ setDirectRayCount()

◆ setMinScatterEnergy()

◆ setScatteringDepth()

◆ setSourceFlux()

◆ setSourcePosition()

◆ init()

◆ del()

◆ enter()

◆ exit()