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 433 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 or average a spectrum, optionally weighted by a source and/or camera spectrum.
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 the number of direct rays per primitive for a radiation band (default 100).
	setDiffuseRayCount (self, str band_label, int ray_count)
	Set the number of diffuse rays per primitive for a radiation band (default 1000).
	setDiffuseRadiationFlux (self, str label, float flux)
	Set the diffuse (ambient sky) radiation flux for a 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.
Union["np.ndarray", Dict[str, "np.ndarray"]]	getAbsorbedFlux (self, Union[str, List[str]] band_label, Optional[List[int]] uuids=None)
	Get per-band absorbed radiation flux density, aligned to UUIDs.
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 the radiative energy lost to the sky (deprecated).
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.
None	enableBelowHorizonDiffuseRadiation (self)
	Apply the diffuse (ambient) sky radiation to rays that leave the domain below the horizon.
None	disableBelowHorizonDiffuseRadiation (self)
	Restrict the diffuse (ambient) sky radiation to the upper hemisphere (the default).
None	enableScatteringRayReduction (self)
	Reduce the diffuse rays per primitive in later scattering iterations (on by default).
None	disableScatteringRayReduction (self)
	Launch the full diffuse ray count in every scattering iteration.
	setScatteringDepth (self, str label, int depth)
	Set the maximum number of scattering iterations for a band.
	setMinScatterEnergy (self, str label, float energy)
	Set the flux threshold that stops a band's scattering iterations early.
	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.
None	enableCameraFluxSmoothing (self, float crease_angle_degrees=30.0)
	Reconstruct camera images by interpolating outgoing flux across each facet.
None	disableCameraFluxSmoothing (self)
	Reconstruct camera images by holding the outgoing flux constant across each facet.
bool	isCameraFluxSmoothingEnabled (self)
	Return True if camera images are reconstructed by interpolating flux across each facet.
float	getCameraFluxSmoothingCreaseAngle (self)
	Return the crease angle in degrees used by camera flux smoothing.
	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.
None	enableCameraAtmosphere (self, str camera_label, str atmosphere_label)
	Convert a camera's images to the radiance reaching a sensor above the atmosphere.
None	disableCameraAtmosphere (self, str camera_label)
	Stop applying a sensor atmosphere to a camera's images.
	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.
None	applyCameraImageCorrections (self, str camera_label, str red_band_label, str green_band_label, str blue_band_label, float saturation_adjustment=1.0, float brightness_adjustment=1.0, float contrast_adjustment=1.0)
	Apply brightness, contrast, and saturation corrections to an RGB camera image.
None	applyCameraColorCorrectionMatrix (self, str camera_label, str red_band_label, str green_band_label, str blue_band_label, Union[str, os.PathLike] ccm_file_path)
	Apply a color correction matrix (CCM) from an XML file to an RGB camera image.
	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.
bool	gpuBackendsDisabledByEnvironment ()
	Check whether GPU backends are vetoed by the HELIOS_NO_GPU environment variable.

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).
	_warn_if_bounded_bands_with_camera_response (self, str camera_label, List[str] band_labels, str operation)
	Warn when bands have explicit wavelength bounds and the camera has a spectral response.
	_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.
	_check_image_was_written (self, str filename, str camera, List[str] bands, str image_path, str operation)
	Raise if the native layer reported a failed write via an empty filename.

Static Protected Member Functions
	_validate_rgb_camera_labels (camera_label, red_band_label, green_band_label, blue_band_label, function_name)

Protected Attributes
bool	_geometry_updated = False
bool	_geometry_subset = False
	_bounded_bands = set()

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

__del__()

pyhelios.RadiationModel.RadiationModel.__del__

(

self

)

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

Definition at line 649 of file RadiationModel.py.

Member Function Documentation

__enter__()

pyhelios.RadiationModel.RadiationModel.__enter__

(

self

)

Context manager entry.

Definition at line 634 of file RadiationModel.py.

__exit__()

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

Context manager exit with proper cleanup.

Definition at line 638 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. This preflight turns that into a
   message naming the camera, the band, and the call the user is missing.

   This check is load-bearing rather than merely cosmetic, and must not be
   removed on the grounds that helios-core v1.3.79 addressed the same case
   upstream. The upstream change makes the native call return an empty
   filename instead of throwing, so without this preflight an unrendered
   camera would look like a successful write that produced no file.
   :meth:`_check_image_was_written` is the backstop for the failure modes
   this preflight cannot see, such as an unwritable output directory.

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

_check_image_was_written()

pyhelios.RadiationModel.RadiationModel._check_image_was_written ( self, str filename, str camera, List[str] bands, str image_path, str operation )

protected

Raise if the native layer reported a failed write via an empty filename.

   helios-core v1.3.79 changed ``writeCameraImage``/``writeNormCameraImage`` to
   return an empty string on failure rather than throwing, so no exception and no
   error code reaches Python. Returning that empty string to the caller -- or
   logging it as "written to: " -- would present a write that produced no file as
   a success, which the fail-fast policy forbids.

   :meth:`_check_camera_has_pixel_data` already rejects the unrendered-camera and
   unrendered-band cases before the native call, so by the time an empty filename
   gets here the likeliest cause is an output directory that does not exist or
   cannot be written.

Definition at line 620 of file RadiationModel.py.

_validate_rgb_camera_labels()

pyhelios.RadiationModel.RadiationModel._validate_rgb_camera_labels ( camera_label, red_band_label, green_band_label, blue_band_label, function_name )

staticprotected

Definition at line 2712 of file RadiationModel.py.

_warn_if_bounded_bands_with_camera_response()

pyhelios.RadiationModel.RadiationModel._warn_if_bounded_bands_with_camera_response ( self, str camera_label, List[str] band_labels, str operation )

protected

Warn when bands have explicit wavelength bounds and the camera has a spectral response.

The two combined silently produce wrong colors. Helios computes camera pixels by integrating surface reflectance against the camera's spectral response curve, but computes SCATTERED flux by integrating over the band's wavelength bounds instead. When bounds are absent Helios deliberately falls back to the camera-weighted average for scattering, so both paths agree; setting bounds breaks that agreement.

With scattering enabled most camera-visible light is scattered, so the image carries band-limited color the camera never expected. Low-chroma natural surfaces are hit hardest: a measured soil spectrum whose true red/green ratio is 1.2 renders at 2.6 – brown soil comes out pink – while saturated colorboard-style spectra survive and look fine, which makes the problem easy to miss.

Nothing errors and no output looks obviously broken, so this is a warning at the point the camera is created rather than a failure.

Definition at line 542 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 769 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 932 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). Must not be negative; a band may start at 0 nm.
wavelength_max	Optional maximum wavelength (nm). Must exceed wavelength_min by at least 1 nm.

Note

Wavelength bounds change how the band is treated. Surface reflectivity_spectrum/transmissivity_spectrum data are only applied in a band that has bounds. An emission-enabled band with bounds emits only the part of the Planck spectrum inside them (e.g. about 38% of sigma*T^4 for 8000-14000 nm at 300 K), whereas a band without bounds emits the full broadband epsilon*sigma*T^4; any diffuse flux given to a bounded emission band should likewise be the in-band value.

Definition at line 698 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 2084 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 2899 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 901 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``.

   Leaves fluoresce only if they carry ``fluspect_spectrum`` primitive data (authored by
   :class:`LeafOptics`). Every such leaf must also carry ``electron_transport_ratio``
   (the relative light saturation Ja/Je written by the Farquhar or C4 photosynthesis
   model when that optional output is requested) when a SIF band is run; otherwise
   :meth:`runBand` raises an error.

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 2185 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 814 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 842 of file RadiationModel.py.

applyCameraColorCorrectionMatrix()

None pyhelios.RadiationModel.RadiationModel.applyCameraColorCorrectionMatrix	(		self,
		str	camera_label,
		str	red_band_label,
		str	green_band_label,
		str	blue_band_label,
		Union[str, os.PathLike]	ccm_file_path )

Apply a color correction matrix (CCM) from an XML file to an RGB camera image.

   Each pixel's ``(r, g, b)`` is replaced in place by ``M @ (r, g, b)`` for a 3x3 matrix,
   or ``M[:, :3] @ (r, g, b) + M[:, 3]`` for a matrix with a fourth, affine offset column
   (3 rows of 4 values, labelled ``matrix_type="4x3"`` in the file).
   Values are not clamped. The matrix file is the XML format written by
   :meth:`autoCalibrateCameraImage` through its ``ccm_export_file_path`` argument::

       <helios>
         <ColorCorrectionMatrix camera_label="cam" matrix_type="3x3">
           <row>1.0 0.0 0.0</row>
           <row>0.0 1.0 0.0</row>
           <row>0.0 0.0 1.0</row>
         </ColorCorrectionMatrix>
       </helios>

   Each ``<row>`` must be on its own line. Apply it after :meth:`runBand` and before
   :meth:`applyCameraImageCorrections` and :meth:`writeCameraImage`. The change to the
   stored pixel data is permanent, so applying the matrix twice applies it twice.

Parameters

camera_label	Label of an existing camera.
red_band_label	Band holding the red channel.
green_band_label	Band holding the green channel.
blue_band_label	Band holding the blue channel.
ccm_file_path	Path to the color correction matrix XML file.

Exceptions

ValueError	If a label is not a non-empty string or the path is empty
FileNotFoundError	If ccm_file_path does not exist
RadiationModelError	If the camera or a band does not exist, the camera has no pixel data for a band, or the file holds no valid 3x3 or 4x3 matrix

Example

>>> radiation.autoCalibrateCameraImage("cam", "red", "green", "blue", "calibrated.jpeg", ... ccm_export_file_path="cam_ccm.xml") >>> # Later, apply the same correction to a new render of that camera >>> radiation.runBand(["red", "green", "blue"]) >>> radiation.applyCameraColorCorrectionMatrix("cam", "red", "green", "blue", "cam_ccm.xml") >>> radiation.writeCameraImage("cam", ["red", "green", "blue"], "corrected")

Definition at line 2837 of file RadiationModel.py.

applyCameraImageCorrections()

None pyhelios.RadiationModel.RadiationModel.applyCameraImageCorrections	(		self,
		str	camera_label,
		str	red_band_label,
		str	green_band_label,
		str	blue_band_label,
		float	saturation_adjustment = 1.0,
		float	brightness_adjustment = 1.0,
		float	contrast_adjustment = 1.0 )

Apply brightness, contrast, and saturation corrections to an RGB camera image.

   Modifies the camera's stored pixel data for the three bands in place, in this order:

   1. Lens flare, if lens flare is enabled for the camera.
   2. Brightness and contrast, in linear space:
      ``v = 0.5 + (v * brightness_adjustment - 0.5) * contrast_adjustment``.
   3. Saturation: each channel is moved away from (or toward) the pixel's luminance,
      ``v = L + saturation_adjustment * (v - L)``.

   Values are not clamped. A factor of exactly 1.0 skips its step, so calling with all
   defaults changes nothing (apart from lens flare, when enabled).

   Call it after :meth:`runBand` has rendered the camera (or after
   :meth:`setCameraPixelData`) and before :meth:`writeCameraImage`. Auto exposure and
   white balance are not applied here: they are applied during rendering according to
   the camera's ``exposure`` and ``white_balance`` :class:`CameraProperties`. sRGB gamma
   compression is applied by :meth:`writeCameraImage` when it writes a 3-band image. If
   you also apply a color correction matrix, apply it first with
   :meth:`applyCameraColorCorrectionMatrix`.

   The corrections change the stored pixel data permanently, so calling this twice
   compounds them. The factors are recorded in the camera metadata when metadata export
   is enabled with :meth:`enableCameraMetadata`.

Parameters

camera_label	Label of an existing camera.
red_band_label	Band holding the red channel.
green_band_label	Band holding the green channel.
blue_band_label	Band holding the blue channel.
saturation_adjustment	Saturation factor; 0 gives grayscale, >1 more saturated. Default 1.0 (no change).
brightness_adjustment	Multiplier applied to every channel. Default 1.0 (no change).
contrast_adjustment	Contrast factor about a midpoint of 0.5. Default 1.0 (no change).

Exceptions

ValueError	If a label is not a non-empty string, or an adjustment is not a finite, non-negative number
RadiationModelError	If the camera does not exist or has no pixel data for one of the bands (e.g. it has not been rendered)

Example

>>> radiation.runBand(["red", "green", "blue"]) >>> radiation.applyCameraImageCorrections("cam", "red", "green", "blue", ... saturation_adjustment=1.2, ... brightness_adjustment=1.1, ... contrast_adjustment=1.05) >>> radiation.writeCameraImage("cam", ["red", "green", "blue"], "corrected")

Definition at line 2770 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 3550 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 1181 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 1210 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 no geometry has been built yet, this method builds 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.

   A subset built by ``updateGeometry(uuids)`` is never widened by this method: the
   G-function is reported over the subset the caller selected.

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 1853 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). Must not be negative.
wavelength_max	Optional maximum wavelength for new band (nm). Must exceed wavelength_min by at least 1 nm. Passing 0 for both bounds creates a band without wavelength bounds; omitting both keeps the bounds of the copied band.

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) >>> >>> # Copy band, dropping its wavelength bounds >>> radiation.copyRadiationBand("PAR", "PAR_unbounded", 0, 0)

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

disableBelowHorizonDiffuseRadiation()

None pyhelios.RadiationModel.RadiationModel.disableBelowHorizonDiffuseRadiation

(

self

)

Restrict the diffuse (ambient) sky radiation to the upper hemisphere (the default).

   See :meth:`enableBelowHorizonDiffuseRadiation`.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.92

Definition at line 1958 of file RadiationModel.py.

disableCameraAtmosphere()

None pyhelios.RadiationModel.RadiationModel.disableCameraAtmosphere	(		self,
		str	camera_label )

Stop applying a sensor atmosphere to a camera's images.

   Images rendered by later :meth:`runBand` calls record the radiance leaving the
   scene again. Calling this for a camera with no atmosphere enabled does nothing.

Parameters

camera_label

Label of an existing camera.

Exceptions

ValueError	If camera_label is not a non-empty string
RadiationModelError	If the camera does not exist
RuntimeError	If the native library predates helios-core v1.3.90

Definition at line 2624 of file RadiationModel.py.

disableCameraFluxSmoothing()

None pyhelios.RadiationModel.RadiationModel.disableCameraFluxSmoothing

(

self

)

Reconstruct camera images by holding the outgoing flux constant across each facet.

   This is the default. Each pixel reports the outgoing flux of the primitive behind it.

Exceptions

RadiationModelError	If the call fails
RuntimeError	If the native library predates helios-core v1.3.84

Note

If geometry has already been built, this re-uploads it and rebuilds the acceleration structure.

Definition at line 2327 of file RadiationModel.py.

disableEmission()

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

Disable emission for radiation band.

Definition at line 2042 of file RadiationModel.py.

disableMessages()

pyhelios.RadiationModel.RadiationModel.disableMessages

(

self

)

Disable RadiationModel status messages.

Definition at line 668 of file RadiationModel.py.

disableScatteringRayReduction()

None pyhelios.RadiationModel.RadiationModel.disableScatteringRayReduction

(

self

)

Launch the full diffuse ray count in every scattering iteration.

   See :meth:`enableScatteringRayReduction`.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.92

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

enableBelowHorizonDiffuseRadiation()

None pyhelios.RadiationModel.RadiationModel.enableBelowHorizonDiffuseRadiation

(

self

)

Apply the diffuse (ambient) sky radiation to rays that leave the domain below the horizon.

   By default the diffuse sky fills only the upper hemisphere, so a ray that leaves all
   geometry heading downward (past the edge of a finite ground, or from the underside of an
   isolated object) receives no ambient radiation. This restores the behavior of
   helios-core before 1.3.92, in which the sky filled the full sphere and such rays received
   the same ambient radiation as rays leaving upward. It applies to all bands and to camera
   rays.

Note

To avoid dark domain edges from a finite ground, use :meth:enforcePeriodicBoundary rather than this method.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.92

Example

>>> radiation.enableBelowHorizonDiffuseRadiation()

Definition at line 1945 of file RadiationModel.py.

enableCameraAtmosphere()

None pyhelios.RadiationModel.RadiationModel.enableCameraAtmosphere	(		self,
		str	camera_label,
		str	atmosphere_label )

Convert a camera's images to the radiance reaching a sensor above the atmosphere.

   Use this to simulate satellite imagery. After each camera ray trace, the radiance of
   every pixel in a reflective band becomes ``L_path + T_dir_up * L_pixel + L_adj``: the
   path radiance, the surface-leaving radiance attenuated by the upward direct
   transmittance, and the adjacency radiance, each combined over the band with the
   camera's spectral response. These spectra are computed by
   :meth:`SolarPosition.calculateSensorAtmosphereSpectra`.

   Emission (thermal) bands are converted with the thermal atmosphere computed by
   :meth:`SolarPosition.calculateSensorThermalAtmosphere` under the same label. Each
   pixel's in-band radiance gives a brightness temperature; the Planck spectrum at that
   temperature is transmitted through the atmosphere wavelength by wavelength and
   integrated over the band with the camera's spectral response, and the upwelling
   atmospheric radiance is added.

Parameters

camera_label	Label of an existing camera.
atmosphere_label	Label prefix passed to :meth:SolarPosition.calculateSensorAtmosphereSpectra (reflective bands) and :meth:SolarPosition.calculateSensorThermalAtmosphere (emission bands).

Exceptions

ValueError	If either label is not a non-empty string
RadiationModelError	If the camera does not exist
RuntimeError	If the native library predates helios-core v1.3.90

Note

The atmosphere spectra are read when :meth:runBand is next called, not here, so problems with them are raised by runBand(). It raises if:

• the spectra do not exist in Context global data, or were not computed for the direction from the camera's look-at point toward its position (to within 1 degree);
• any pixel sees the sky rather than the scene;
• a reflective band lies outside the wavelength range of the atmosphere spectra (300-2600 nm at the default 1 nm resolution);
• an emission band has no wavelength bounds, has bounds outside 5502-15326 nm, or a pixel's brightness temperature lies outside 150-400 K.

The spectra describe the camera's central viewing direction, so give the camera a narrow field of view. The camera does not need to be at orbital altitude.

Illuminate the scene with the <label>_direct_irradiance and <label>_diffuse_irradiance spectra stored by :meth:SolarPosition.calculateSensorAtmosphereSpectra, so that the illumination and the view path share one atmosphere.

Use CameraProperties(exposure="manual", white_balance="off") to obtain radiance values; any other setting rescales the images after the atmosphere is

Exceptions

applied.

Example

>>> solar.calculateSensorAtmosphereSpectra("satellite_atmosphere", vec3(0, 0, 1)) >>> radiation.addRadiationCamera("satellite", ["red"], position=vec3(0, 0, 50), ... lookat_or_direction=vec3(0, 0, 0), ... camera_properties=properties) >>> radiation.enableCameraAtmosphere("satellite", "satellite_atmosphere") >>> radiation.runBand("red")

Definition at line 2595 of file RadiationModel.py.

enableCameraFluxSmoothing()

None pyhelios.RadiationModel.RadiationModel.enableCameraFluxSmoothing	(		self,
		float	crease_angle_degrees = 30.0 )

Reconstruct camera images by interpolating outgoing flux across each facet.

   Averages each primitive's outgoing flux onto the mesh vertices it shares with its
   neighbours and interpolates it back across the facet, so a coarsely tessellated
   curved surface reads as a curve rather than as a set of flat panels. This applies
   to Tube, Sphere, Cone, Polymesh, Tile and AdaptiveTile objects. A Box, a Disk, and
   any primitive belonging to no object are left alone, since their faces are genuinely
   flat. A polymesh must carry the face table that :meth:`Context.loadOBJ` and
   :meth:`Context.loadPLY` retain; one assembled from loose primitives by
   :meth:`Context.addPolymeshObject` has no topology and is left alone.

   Smoothing is off by default and should be enabled deliberately: it changes what the
   camera reports. A pixel no longer carries the outgoing flux of the primitive behind
   it, but a blend of that primitive's value with its neighbours', so pixel values no
   longer correspond exactly to the ``radiation_flux_*`` primitive data. The radiation
   solve, those primitive data values, and the pixel-label and depth images are all
   unchanged.

Parameters

crease_angle_degrees

Angle between adjacent facet normals above which a shared edge is treated as a hard crease, so flux is not averaged across it. Applies to polymesh objects only; the curved object types are smooth by construction and are never creased. Must be between 0 and 180 degrees. Defaults to 30.

Exceptions

RadiationModelError	If the crease angle is out of range or the call fails
RuntimeError	If the native library predates helios-core v1.3.84

Note

If geometry has already been built, this re-uploads it and rebuilds the acceleration structure, which is not cheap. Prefer calling it before :meth:updateGeometry.

Example

>>> with RadiationModel(context) as radiation: ... radiation.enableCameraFluxSmoothing(crease_angle_degrees=45.0) ... radiation.updateGeometry()

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

enableEmission()

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

Enable emission for radiation band.

Definition at line 2049 of file RadiationModel.py.

enableMessages()

pyhelios.RadiationModel.RadiationModel.enableMessages

(

self

)

Enable RadiationModel status messages.

Definition at line 674 of file RadiationModel.py.

enableScatteringRayReduction()

None pyhelios.RadiationModel.RadiationModel.enableScatteringRayReduction

(

self

)

Reduce the diffuse rays per primitive in later scattering iterations (on by default).

   Each scattering iteration launches less energy than the one before, so later iterations
   contribute less to the noise in the absorbed flux. With this on, iteration ``s`` uses
   ``N * E_s / E_0`` rays per primitive, where ``N`` is the diffuse ray count, ``E_s`` the
   energy launched in iteration ``s`` and ``E_0`` that of the first scattering iteration,
   with a minimum of 16. This makes strongly scattering bands faster, at the cost of
   somewhat noisier scattered flux -- most for deeply shaded primitives and camera images,
   whose light comes mostly from scattering.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.92

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

get_native_ptr()

pyhelios.RadiationModel.RadiationModel.get_native_ptr

(

self

)

Get native pointer for advanced operations.

Definition at line 659 of file RadiationModel.py.

getAbsorbedFlux()

Union["np.ndarray", Dict[str, "np.ndarray"]] pyhelios.RadiationModel.RadiationModel.getAbsorbedFlux	(		self,
		Union[str, List[str]]	band_label,
		Optional[List[int]]	uuids = None )

Get per-band absorbed radiation flux density, aligned to UUIDs.

   ``runBand()`` stores each band's result as ``radiation_flux_<band>``
primitive   the **total** absorbed flux density for that band, i.e.
   direct plus diffuse plus scattered contributions. This method reads that
   data back keyed by UUID, so element ``i`` of the result always belongs to
   ``uuids[i]``.

   Prefer this over :meth:`getTotalAbsorbedFlux`, which sums over every band
   (double-counting overlapping bands such as PAR/NIR/SW) and whose ordering
   does not correspond to ``context.getAllUUIDs()``.

Parameters

band_label	Band name, or a list of band names to fetch at once.
uuids	Primitives to query, defaulting to context.getAllUUIDs(). Results follow this list's order.

Returns

For a single band, a float32 array of absorbed flux density per primitive in W/m^2. For a list of bands, a dict mapping each band label to that array.

Exceptions

RadiationModelError

If a band does not exist, or if ``runBand()`` has not been run for it.

Example

>>> radiation.runBand(["PAR", "NIR", "SW"]) >>> uuids = context.getAllUUIDs() >>> par = radiation.getAbsorbedFlux("PAR") # W/m^2, PAR only >>> par_watts = par * context.getPrimitiveArea(uuids) >>> all_bands = radiation.getAbsorbedFlux(["PAR", "NIR", "SW"]) >>> all_bands["SW"][0] # doctest: +SKIP

Definition at line 1671 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 2505 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 3748 of file RadiationModel.py.

getCameraFluxSmoothingCreaseAngle()

float pyhelios.RadiationModel.RadiationModel.getCameraFluxSmoothingCreaseAngle

(

self

)

Return the crease angle in degrees used by camera flux smoothing.

   This is the value last passed to :meth:`enableCameraFluxSmoothing`, or 30.0 if it
   has never been called.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.84

Definition at line 2359 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 2443 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 2486 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 2676 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 2402 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 1403 of file RadiationModel.py.

getNativePtr()

pyhelios.RadiationModel.RadiationModel.getNativePtr

(

self

)

Get native pointer for advanced operations.

(Legacy naming for compatibility)

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

getPluginInfo()

dict pyhelios.RadiationModel.RadiationModel.getPluginInfo

(

self

)

Get information about the radiation plugin.

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

getSkyEnergy()

float pyhelios.RadiationModel.RadiationModel.getSkyEnergy

(

self

)

Get the radiative energy lost to the sky (deprecated).

   .. deprecated::
       No ray-tracing backend computes the energy lost to the sky, so this always returned
       0. As of helios-core 1.3.92 it raises, and it will be removed in helios-core v2.0.

Exceptions

HeliosRuntimeError

Always, from the native library

Definition at line 1813 of file RadiationModel.py.

getSourceFlux()

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

Get source flux for band.

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

getTotalAbsorbedFlux()

List[float] pyhelios.RadiationModel.RadiationModel.getTotalAbsorbedFlux

(

self

)

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

   .. warning::
      **The returned values cannot be matched to UUIDs by position.** They are
      ordered by the radiation model's internal primitive ordering (grouped by
      parent object, built during :meth:`updateGeometry`), which is *not* the
      order of ``context.getAllUUIDs()`` -- that iterates an unordered map and
      returns a hash order. Pairing the two by index silently attributes flux
      to the wrong primitive. Use :meth:`getAbsorbedFlux` instead, which is
      keyed by UUID.

   .. warning::
      This sums the ``radiation_flux_<band>`` primitive data over **every**
      band registered in the model. For overlapping bands -- e.g. PAR, NIR
      and SW, where SW already spans the other two -- the sum double-counts
      and is not a physically meaningful quantity. Use
      :meth:`getAbsorbedFlux` to get a single band's flux.

   Units are **W/m^2** (flux density), not watts. 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.

   Summing the returned values directly (``sum(flux)``) adds flux densities of
   differently-sized surfaces and is not physically meaningful. To obtain
   absorbed power in watts, weight each primitive by its area -- via
   :meth:`getAbsorbedFlux`, so that flux and area refer to the same primitive::

       uuids = context.getAllUUIDs()
       flux = radiation.getAbsorbedFlux("SW")
       power = float((flux * context.getPrimitiveArea(uuids)).sum(dtype="float64"))

Returns

Absorbed flux density per primitive in W/m^2, summed over all bands.

       :meth:`getAbsorbedFlux`: band-specific, UUID-aligned absorbed flux.

Definition at line 1630 of file RadiationModel.py.

gpuBackendsDisabledByEnvironment()

bool pyhelios.RadiationModel.RadiationModel.gpuBackendsDisabledByEnvironment ( )

static

Check whether GPU backends are vetoed by the HELIOS_NO_GPU environment variable.

   True when ``HELIOS_NO_GPU`` is set to any value other than ``"0"``. The veto
   makes a GPU-equipped machine behave exactly like one with no compatible
hardware    :meth:`probeAnyGPUBackend` returns False and constructing a
   RadiationModel with the automatic backend fails. Requesting a backend by name
   bypasses the veto.

   Use this to tell an intentional veto apart from missing hardware when
   reporting why the GPU path is unavailable.

Note

The environment is read once and cached for the process lifetime, so changing HELIOS_NO_GPU after the first call has no effect.

Returns

True if GPU backend probing is disabled by the environment

Exceptions

RuntimeError

If the native library predates helios-core v1.3.79

Example

>>> if not RadiationModel.probeAnyGPUBackend(): ... if RadiationModel.gpuBackendsDisabledByEnvironment(): ... print("GPU disabled via HELIOS_NO_GPU") ... else: ... print("No compatible GPU found")

Definition at line 3812 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.

   The spectrum is linearly interpolated to the wavelength bounds, so a bound
   falling between tabulated points contributes only the part of its segment
   inside the 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 1091 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 or average a spectrum, optionally weighted by a source and/or camera spectrum.

   What is returned depends on which optional arguments are given:

   - Neither ``source_id`` nor ``camera_spectrum``: the integral of the spectrum, over
     all tabulated wavelengths or between ``wavelength_min`` and ``wavelength_max``.
   - ``source_id`` (with both wavelength bounds): the source-weighted average
     ``int(S*f) / int(S)`` between the bounds, where ``S`` is the source spectrum and
     ``f`` the object spectrum.
   - ``camera_spectrum``: the camera-response-weighted average ``int(f*C) / int(C)``
     over the wavelengths at which the camera response ``C`` is tabulated.
   - ``source_id`` and ``camera_spectrum``: ``int(S*f*C) / int(S)`` over the
     wavelengths at which both the source spectrum and the camera response are
     tabulated. The wavelength bounds are not used.

   In the weighted forms every spectrum is zero outside the wavelengths at which it is
   tabulated, so a source weights only the part of the interval its spectrum covers.

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. The spectrum is linearly interpolated to the bounds, so a bound falling between tabulated points contributes only the part of its segment inside the range.
source_id	Optional source ID for source spectrum weighting. The source must have a spectrum (see :meth:setSourceSpectrum). Requires wavelength_min and wavelength_max unless camera_spectrum is also given.
camera_spectrum	Optional camera spectrum for camera response weighting

Returns

Integral or weighted average, as described above

Exceptions

HeliosRuntimeError

If there is nothing to weight by: the source spectrum has no energy between the bounds (or where the camera response is tabulated), or the camera response is zero everywhere.

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 1064 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 1291 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 1246 of file RadiationModel.py.

isCameraFluxSmoothingEnabled()

bool pyhelios.RadiationModel.RadiationModel.isCameraFluxSmoothingEnabled

(

self

)

Return True if camera images are reconstructed by interpolating flux across each facet.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.84

Definition at line 2344 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 2252 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 1898 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 False when ``HELIOS_NO_GPU`` is set to anything other than ``"0"``,
   whatever hardware is actually present -- see
   :meth:`gpuBackendsDisabledByEnvironment` to distinguish an environment veto
   from genuinely absent hardware.

Note

The probe runs at most once per process and the result is cached (helios-core v1.3.79+), so repeated calls are cheap and never re-enter the GPU driver. A driver that becomes usable after the first probe is not picked up until the process restarts.

Returns

True if at least one GPU backend is available

Example

>>> if RadiationModel.probeAnyGPUBackend(): ... with RadiationModel(context) as radiation: ... radiation.addRadiationBand("SW")

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

Note

Geometry and radiative properties are updated automatically as needed (helios-core v1.3.79+), so an explicit :meth:updateGeometry call is not required first. A subset build from updateGeometry(uuids) is preserved: it is never rebuilt automatically, since that would discard the subset.

Bands run together share one ray launch, so the direct and diffuse ray counts used are the largest values set for any band in the call (see :meth:setDirectRayCount and :meth:setDiffuseRayCount); bands with lower counts receive more rays than requested. Run bands in separate calls to give each its own ray count.

Definition at line 1569 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 1122 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 1148 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 2421 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 2464 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 2700 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 2380 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 2521 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 2649 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 1381 of file RadiationModel.py.

setDiffuseRadiationFlux()

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

Set the diffuse (ambient sky) radiation flux for a band.

   The flux is that incident on a horizontal surface above all geometry in the domain.

Parameters

label	Band label
flux	Diffuse radiative flux (W/m²)

Note

The diffuse sky fills the upper hemisphere only (helios-core 1.3.92+): rays that leave all geometry heading below the horizon – past the edge of a finite ground, or from the underside of an isolated object – receive no diffuse radiation. Use :meth:enforcePeriodicBoundary to remove domain edge effects, or :meth:enableBelowHorizonDiffuseRadiation to restore the previous full-sphere sky.

Definition at line 1360 of file RadiationModel.py.

setDiffuseRayCount()

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

Set the number of diffuse rays per primitive for a radiation band (default 1000).

   The diffuse ray count is also used for the scattering iterations.

Note

Bands run together in one :meth:runBand call share a single ray launch, which uses the largest diffuse ray count set for any of them. To trace bands with different ray counts, run them in separate runBand() calls.

Definition at line 1337 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 1420 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 1447 of file RadiationModel.py.

setDirectRayCount()

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

Set the number of direct rays per primitive for a radiation band (default 100).

Note

Bands run together in one :meth:runBand call share a single ray launch, which uses the largest direct ray count set for any of them. To trace bands with different ray counts, run them in separate runBand() calls.

Definition at line 1320 of file RadiationModel.py.

setMinScatterEnergy()

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

Set the flux threshold that stops a band's scattering iterations early.

   Scattering iterations for the band stop once no primitive has more than ``energy`` flux
   left to scatter. The energy still in flight when they stop is accounted for as described
   in :meth:`setScatteringDepth`.

Parameters

label	Band label
energy	Flux threshold, in the units of the band's flux (W/m² for a shortwave band). The default of 0 never stops early, so the band runs to its scattering depth.

Exceptions

ValueError

If ``energy`` is negative or not a number

Definition at line 2036 of file RadiationModel.py.

setScatteringDepth()

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

Set the maximum number of scattering iterations for a band.

Parameters

label	Band label
depth	Maximum number of scattering iterations (0 turns scattering off)

Note

The energy that would still be scattered after the last iteration is not dropped: the remaining iterations are summed as a geometric series, each primitive receiving its absorption in the last iteration times q/(1-q), where q is the ratio of the energy launched in the last two iterations. A depth of 3 to 5 is therefore usually enough for absorbed fluxes, even for strongly scattering bands.

Radiation camera images are not extrapolated: they include only the scattering iterations that were traced, so images of strongly scattering bands need a higher

Parameters

depth.

Definition at line 2015 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 1461 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 869 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 968 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 990 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.

Warning

Changing camera_resolution discards the camera's existing image data. The per-pixel buffers are sized to the resolution the camera was rendered at, so helios-core v1.3.79+ clears them rather than reinterpret them at the new size. The camera must be re-rendered with :meth:runBand before its image can be written again; :meth:writeCameraImage will otherwise report that the camera has no rendered pixel data. Changing any other parameter leaves existing image data intact.

Example

>>> props = CameraProperties( ... camera_resolution=(1920, 1080), ... HFOV=35.0, ... lens_focal_length=0.085 # 85mm lens ... ) >>> radiation.updateCameraParameters("cam1", props) >>> # Resolution changed, so re-render before writing an image. >>> radiation.runBand(["red", "green", "blue"]) >>> radiation.writeCameraImage("cam1", ["red", "green", "blue"], "out")

Definition at line 2959 of file RadiationModel.py.

updateGeometry()

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

Update geometry in radiation model.

   The two call forms differ in more than scope, as of helios-core v1.3.79:

   - ``updateGeometry()`` (no argument) is **optional**. :meth:`runBand` builds
     the geometry itself before tracing and rebuilds it whenever primitives have
     been added to or deleted from the Context, or moved, rotated, scaled,
     reshaped or re-textured (helios-core v1.3.92+), since the last build. Call it
     explicitly only to control when the cost of the build is paid. Setting
     primitive data does not trigger a rebuild, so it is still required after
     changing ``twosided_flag`` or ``invisibility_flag`` on existing primitives.
   - ``updateGeometry(uuids)`` restricts the model to a subset of Context
     primitives, and that subset is **never** rebuilt automatically -- doing so
     would silently discard the subset you asked for. You must call it again
     yourself after modifying Context geometry.

Parameters

uuids

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

Note

Passing uuids latches the model into subset mode natively. Calling updateGeometry() with no argument afterwards clears that latch and returns the model to tracking the full Context.

Exceptions

HeliosRuntimeError

If the scene contains voxels, which no ray-tracing backend supports, or a triangle whose texture has a transparency channel but which has no texture (u,v) coordinates (e.g. one textured with setPrimitiveTextureFile()).

Definition at line 1516 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 3030 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 3119 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 3617 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 3657 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 3687 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 3342 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 3446 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 3078 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 3719 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 3220 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 3173 of file RadiationModel.py.

Member Data Documentation

_bounded_bands

pyhelios.RadiationModel.RadiationModel._bounded_bands = set()

protected

Definition at line 509 of file RadiationModel.py.

_geometry_subset

bool pyhelios.RadiationModel.RadiationModel._geometry_subset = False

protected

Definition at line 461 of file RadiationModel.py.

_geometry_updated

bool pyhelios.RadiationModel.RadiationModel._geometry_updated = False

protected

Definition at line 457 of file RadiationModel.py.

context

pyhelios.RadiationModel.RadiationModel.context = context

Definition at line 450 of file RadiationModel.py.

radiation_model

pyhelios.RadiationModel.RadiationModel.radiation_model = None

Definition at line 451 of file RadiationModel.py.

---

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

• pyhelios/RadiationModel.py