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

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

	__enter__ (self)
	Context manager entry.

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

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

	get_native_ptr (self)
	Get native pointer for advanced operations.

	getNativePtr (self)
	Get native pointer for advanced operations.

	disableMessages (self)
	Disable RadiationModel status messages.

	enableMessages (self)
	Enable RadiationModel status messages.

	addRadiationBand (self, str band_label, float wavelength_min=None, float wavelength_max=None)
	Add radiation band with optional wavelength bounds.

	copyRadiationBand (self, str old_label, str new_label, float wavelength_min=None, float wavelength_max=None)
	Copy existing radiation band to new label, optionally with new wavelength range.

int	addCollimatedRadiationSource (self, direction=None)
	Add collimated radiation source.

int	addSphereRadiationSource (self, position, float radius)
	Add spherical radiation source.

int	addSunSphereRadiationSource (self, float radius, float zenith, float azimuth, float position_scaling=1.0, float angular_width=0.53, float flux_scaling=1.0)
	Add sun sphere radiation source.

	setSourcePosition (self, int source_id, position)
	Set position of a radiation source.

int	addRectangleRadiationSource (self, position, size, rotation)
	Add a rectangle (planar) radiation source.

int	addDiskRadiationSource (self, position, float radius, rotation)
	Add a disk (circular planar) radiation source.

	setSourceSpectrum (self, source_id, spectrum)
	Set radiation spectrum for source(s).

	setSourceSpectrumIntegral (self, int source_id, float source_integral, float wavelength_min=None, float wavelength_max=None)
	Set source spectrum integral value.

float	integrateSpectrum (self, object_spectrum, float wavelength_min=None, float wavelength_max=None, int source_id=None, camera_spectrum=None)
	Integrate spectrum with optional source/camera spectra and wavelength range.

float	integrateSourceSpectrum (self, int source_id, float wavelength_min, float wavelength_max)
	Integrate source spectrum over wavelength range.

	scaleSpectrum (self, str existing_label, new_label_or_scale, float scale_factor=None)
	Scale spectrum in-place or to new label.

	scaleSpectrumRandomly (self, str existing_label, str new_label, float min_scale, float max_scale)
	Scale spectrum with random factor and store as new label.

	blendSpectra (self, str new_label, List[str] spectrum_labels, List[float] weights)
	Blend multiple spectra with specified weights.

	blendSpectraRandomly (self, str new_label, List[str] spectrum_labels)
	Blend multiple spectra with random weights.

	interpolateSpectrumFromPrimitiveData (self, List[int] primitive_uuids, List[str] spectra_labels, List[float] values, str primitive_data_query_label, str primitive_data_radprop_label)
	Interpolate spectral properties based on primitive data values.

	interpolateSpectrumFromObjectData (self, List[int] object_ids, List[str] spectra_labels, List[float] values, str object_data_query_label, str primitive_data_radprop_label)
	Interpolate spectral properties based on object data values.

	setDirectRayCount (self, str band_label, int ray_count)
	Set direct ray count for radiation band.

	setDiffuseRayCount (self, str band_label, int ray_count)
	Set diffuse ray count for radiation band.

	setDiffuseRadiationFlux (self, str label, float flux)
	Set diffuse radiation flux for band.

	setDiffuseRadiationExtinctionCoeff (self, str label, float K, peak_direction)
	Set diffuse radiation extinction coefficient with directional bias.

float	getDiffuseFlux (self, str band_label)
	Get diffuse flux for band.

	setDiffuseSpectrum (self, band_label, str spectrum_label)
	Set diffuse spectrum from global data label.

	setDiffuseSpectrumIntegral (self, float spectrum_integral, float wavelength_min=None, float wavelength_max=None, str band_label=None)
	Set diffuse spectrum integral.

	setSourceFlux (self, source_id, str label, float flux)
	Set source flux for single source or multiple sources.

float	getSourceFlux (self, int source_id, str label)
	Get source flux for band.

	updateGeometry (self, Optional[List[int]] uuids=None)
	Update geometry in radiation model.

	runBand (self, band_label)
	Run radiation simulation for single band or multiple bands.

List[float]	getTotalAbsorbedFlux (self)
	Get absorbed radiation flux density for all primitives, summed over all bands.

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 total sky energy.

float	calculateGtheta (self, view_direction)
	Calculate G-function (geometry factor) for given view direction.

	optionalOutputPrimitiveData (self, str label)
	Enable optional primitive data output.

	enforcePeriodicBoundary (self, str boundary)
	Enforce periodic boundary conditions.

	setScatteringDepth (self, str label, int depth)
	Set scattering depth for radiation band.

	setMinScatterEnergy (self, str label, float energy)
	Set minimum scatter energy for radiation band.

	disableEmission (self, str label)
	Disable emission for radiation band.

	enableEmission (self, str label)
	Enable emission for radiation band.

	addRadiationCamera (self, str camera_label, List[str] band_labels, position, lookat_or_direction, camera_properties=None, int antialiasing_samples=100)
	Add a radiation camera to the simulation.

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

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

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.

	setCameraSpectralResponseFromLibrary (self, str camera_label, str camera_library_name)
	Set camera spectral response from standard camera library.

List[float]	getCameraPixelData (self, str camera_label, str band_label)
	Get camera pixel data for specific band.

	setCameraPixelData (self, str camera_label, str band_label, List[float] pixel_data)
	Set camera pixel data for specific band.

	addRadiationCameraFromLibrary (self, str camera_label, str library_camera_label, position, lookat, int antialiasing_samples=1, Optional[List[str]] band_labels=None)
	Add radiation camera loading all properties from camera library.

	updateCameraParameters (self, str camera_label, CameraProperties camera_properties)
	Update camera parameters for an existing camera.

	enableCameraMetadata (self, camera_labels)
	Enable automatic JSON metadata file writing for camera(s).

str	writeCameraImage (self, str camera, List[str] bands, str imagefile_base, str image_path="./", int frame=-1, float flux_to_pixel_conversion=1.0)
	Write camera image to file and return output filename.

str	writeNormCameraImage (self, str camera, List[str] bands, str imagefile_base, str image_path="./", int frame=-1)
	Write normalized camera image to file and return output filename.

	writeCameraImageData (self, str camera, str band, str imagefile_base, str image_path="./", int frame=-1)
	Write camera image data to file (ASCII format).

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

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

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

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

	writeImageBoundingBoxes (self, str camera_label, primitive_data_labels=None, object_data_labels=None, object_class_ids=None, str image_file="", str classes_txt_file="classes.txt", str image_path="./")
	Write image bounding boxes for object detection training.

	writeImageSegmentationMasks (self, str camera_label, primitive_data_labels=None, object_data_labels=None, object_class_ids=None, str json_filename="", str image_file="", bool append_file=False)
	Write image segmentation masks in COCO JSON format.

str	autoCalibrateCameraImage (self, str camera_label, str red_band_label, str green_band_label, str blue_band_label, str output_file_path, bool print_quality_report=False, str algorithm="MATRIX_3X3_AUTO", str ccm_export_file_path="")
	Auto-calibrate camera image with color correction and return output filename.

dict	getPluginInfo (self)
	Get information about the radiation plugin.

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

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

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

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

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

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

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.

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

◆ del()

pyhelios.RadiationModel.RadiationModel.__del__ ( self )

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

Definition at line 645 of file RadiationModel.py.

Member Function Documentation

◆ enter()

pyhelios.RadiationModel.RadiationModel.__enter__ ( self )

Context manager entry.

Definition at line 630 of file RadiationModel.py.

◆ exit()

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

Context manager exit with proper cleanup.

Definition at line 634 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 574 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 513 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 616 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 538 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 744 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 907 of file RadiationModel.py.

◆ addRadiationBand()

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

Add radiation band with optional wavelength bounds.

Parameters

band_label	Name/label for the radiation band
wavelength_min	Optional minimum wavelength (nm)
wavelength_max	Optional maximum wavelength (nm)

Definition at line 683 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 1885 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 2443 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 876 of file RadiationModel.py.

◆ addSIFCamera()

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

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

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

Parameters

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

Exceptions

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

Definition at line 1980 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 789 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 817 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 3106 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 1132 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 1161 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 1755 of file RadiationModel.py.

◆ copyRadiationBand()

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

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

Parameters

old_label	Existing band label to copy
new_label	New label for the copied band
wavelength_min	Optional minimum wavelength for new band (nm)
wavelength_max	Optional maximum wavelength for new band (nm)

Example: >>> # Copy band with same wavelength range >>> radiation.copyRadiationBand("SW", "SW_copy") >>> >>> # Copy band with different wavelength range >>> radiation.copyRadiationBand("full_spectrum", "PAR", 400, 700)

Definition at line 716 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 1677 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 2122 of file RadiationModel.py.

◆ disableEmission()

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

Disable emission for radiation band.

Definition at line 1843 of file RadiationModel.py.

◆ disableMessages()

pyhelios.RadiationModel.RadiationModel.disableMessages ( self )

Disable RadiationModel status messages.

Definition at line 664 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 1660 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 2094 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 2544 of file RadiationModel.py.

◆ enableEmission()

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

Enable emission for radiation band.

Definition at line 1850 of file RadiationModel.py.

◆ enableMessages()

pyhelios.RadiationModel.RadiationModel.enableMessages ( self )

Enable RadiationModel status messages.

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

◆ get_native_ptr()

pyhelios.RadiationModel.RadiationModel.get_native_ptr ( self )

Get native pointer for advanced operations.

Definition at line 655 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 1577 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 2300 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 3304 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 2154 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 2238 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 2281 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 2369 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 2197 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 1323 of file RadiationModel.py.

◆ getNativePtr()

pyhelios.RadiationModel.RadiationModel.getNativePtr ( self )

Get native pointer for advanced operations.

(Legacy naming for compatibility)

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

◆ getPluginInfo()

dict pyhelios.RadiationModel.RadiationModel.getPluginInfo ( self )

Get information about the radiation plugin.

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

◆ getSkyEnergy()

float pyhelios.RadiationModel.RadiationModel.getSkyEnergy ( self )

Get total sky energy.

Returns: Total sky energy value

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

Definition at line 1719 of file RadiationModel.py.

◆ getSourceFlux()

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

Get source flux for band.

Definition at line 1400 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 1699 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 1536 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 3374 of file RadiationModel.py.

◆ integrateSourceSpectrum()

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

Integrate source spectrum over wavelength range.

Parameters

source_id	Source ID
wavelength_min	Minimum wavelength
wavelength_max	Maximum wavelength

Returns: Integrated source spectrum value

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

Definition at line 1042 of file RadiationModel.py.

◆ integrateSpectrum()

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

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

   This unified method handles multiple integration scenarios:
   - Basic: Total spectrum integration
   - Range: Integration over wavelength range
   - Source: Integration weighted by source spectrum
   - Camera: Integration weighted by camera spectral response
   - Full: Integration with both source and camera spectra

Parameters

object_spectrum	Object spectrum as list of (wavelength, value) tuples/vec2
wavelength_min	Optional minimum wavelength for integration range
wavelength_max	Optional maximum wavelength for integration range
source_id	Optional source ID for source spectrum weighting
camera_spectrum	Optional camera spectrum for camera response weighting

Returns: Integrated value

Example: >>> leaf_reflectance = [(400, 0.1), (500, 0.4), (600, 0.6), (700, 0.5)] >>> >>> # Total integration >>> total = radiation.integrateSpectrum(leaf_reflectance) >>> >>> # PAR range (400-700nm) >>> par = radiation.integrateSpectrum(leaf_reflectance, 400, 700) >>> >>> # With source spectrum >>> source_weighted = radiation.integrateSpectrum( ... leaf_reflectance, 400, 700, source_id=sun_source ... ) >>> >>> # With camera response >>> camera_response = [(400, 0.2), (550, 1.0), (700, 0.3)] >>> camera_weighted = radiation.integrateSpectrum( ... leaf_reflectance, camera_spectrum=camera_response ... )

Definition at line 1019 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 1242 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 1197 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 2139 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 2047 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 1800 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.

   This is the PyHelios equivalent of the native
   ``RadiationModel::isGPUBackendAvailable()``, which as of helios-core v1.3.79
   is a pure delegate to the same underlying probe.

   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. The flip side is that a driver which becomes usable after the first probe is not picked up until the process restarts, so a test that enables a device and re-probes in the same process still sees the cached answer.

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

Definition at line 1475 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 1073 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 1099 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 2216 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 2259 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 2393 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 2175 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 2316 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 2342 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 1301 of file RadiationModel.py.

◆ setDiffuseRadiationFlux()

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

Set diffuse radiation flux for band.

Definition at line 1280 of file RadiationModel.py.

◆ setDiffuseRayCount()

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

Set diffuse ray count for radiation band.

Definition at line 1272 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 1340 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 1367 of file RadiationModel.py.

◆ setDirectRayCount()

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

Set direct ray count for radiation band.

Definition at line 1264 of file RadiationModel.py.

◆ setMinScatterEnergy()

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

Set minimum scatter energy for radiation band.

Definition at line 1837 of file RadiationModel.py.

◆ setScatteringDepth()

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

Set scattering depth for radiation band.

Definition at line 1830 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 1381 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 844 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 943 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 965 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 2503 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 since the last build. Call it
     explicitly only to control when the cost of the build is paid.
   - ``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.

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

Note: helios-core v1.3.79+ reports a failed write by returning an empty filename rather than raising. PyHelios converts that into a RadiationModelError so a write that produced no file can never be mistaken for a success.

Definition at line 2580 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 2675 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 3173 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 3213 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 3243 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 2898 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 3002 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

Note: helios-core v1.3.79+ reports a failed write by returning an empty filename rather than raising. PyHelios converts that into a RadiationModelError so a write that produced no file can never be mistaken for a success.

Definition at line 2634 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 3275 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 2776 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 2729 of file RadiationModel.py.

Member Data Documentation

◆ _bounded_bands

pyhelios.RadiationModel.RadiationModel._bounded_bands = set()

protected

Definition at line 505 of file RadiationModel.py.

◆ _geometry_subset

bool pyhelios.RadiationModel.RadiationModel._geometry_subset = False

protected

Definition at line 457 of file RadiationModel.py.

◆ _geometry_updated

bool pyhelios.RadiationModel.RadiationModel._geometry_updated = False

protected

Definition at line 453 of file RadiationModel.py.

◆ context

pyhelios.RadiationModel.RadiationModel.context = context

Definition at line 446 of file RadiationModel.py.

◆ radiation_model

pyhelios.RadiationModel.RadiationModel.radiation_model = None

Definition at line 447 of file RadiationModel.py.

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

pyhelios/RadiationModel.py

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ _check_camera_has_pixel_data()

◆ _check_context_alive()

◆ _check_image_was_written()

◆ _warn_if_bounded_bands_with_camera_response()

◆ addCollimatedRadiationSource()

◆ addDiskRadiationSource()

◆ addRadiationBand()

◆ addRadiationCamera()

◆ addRadiationCameraFromLibrary()

◆ addRectangleRadiationSource()

◆ addSIFCamera()

◆ addSphereRadiationSource()

◆ addSunSphereRadiationSource()

◆ autoCalibrateCameraImage()

◆ blendSpectra()

◆ blendSpectraRandomly()

◆ calculateGtheta()

◆ copyRadiationBand()

◆ deleteRadiationSource()

◆ disableCameraFluxSmoothing()

◆ disableEmission()

◆ disableMessages()

◆ doesBandExist()

◆ enableCameraFluxSmoothing()

◆ enableCameraMetadata()

◆ enableEmission()

◆ enableMessages()

◆ enforcePeriodicBoundary()

◆ get_native_ptr()

◆ getAbsorbedFlux()

◆ getAllCameraLabels()

◆ getBackendName()

◆ getCameraFluxSmoothingCreaseAngle()

◆ getCameraLookat()

◆ getCameraOrientation()

◆ getCameraPixelData()

◆ getCameraPosition()

◆ getDiffuseFlux()

◆ getNativePtr()

◆ getObjectDataLabelMap()

◆ getPluginInfo()

◆ getPrimitiveDataLabelMap()

◆ getSkyEnergy()

◆ getSourceFlux()

◆ getSourcePosition()

◆ getTotalAbsorbedFlux()

◆ gpuBackendsDisabledByEnvironment()

◆ integrateSourceSpectrum()

◆ integrateSpectrum()

◆ interpolateSpectrumFromObjectData()

◆ interpolateSpectrumFromPrimitiveData()

◆ isCameraFluxSmoothingEnabled()

◆ isSIFCamera()

◆ optionalOutputPrimitiveData()

◆ probeAnyGPUBackend()

◆ runBand()

EFFICIENT - Single call for multiple bands

INEFFICIENT - Sequential single-band calls

◆ scaleSpectrum()

◆ scaleSpectrumRandomly()

◆ setCameraLookat()

◆ setCameraOrientation()

◆ setCameraPixelData()

◆ setCameraPosition()

◆ setCameraSpectralResponse()

◆ setCameraSpectralResponseFromLibrary()

◆ setDiffuseRadiationExtinctionCoeff()

◆ setDiffuseRadiationFlux()

◆ init()

◆ del()

◆ enter()

◆ exit()