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

	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)
	Copy existing radiation band to new label.

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.

	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.

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

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

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

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

List[float]	getTotalAbsorbedFlux (self)
	Get total absorbed flux for all primitives.

	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.

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

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

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

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

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

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

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

Public Attributes
	context = context

	radiation_model = None

Constructor & Destructor Documentation

◆ init()

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

Initialize RadiationModel with graceful plugin handling.

Parameters

context Helios Context instance

Exceptions

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

Definition at line 183 of file RadiationModel.py.

Member Function Documentation

◆ enter()

pyhelios.RadiationModel.RadiationModel.__enter__ ( self )

Context manager entry.

Definition at line 237 of file RadiationModel.py.

◆ exit()

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

Context manager exit with proper cleanup.

Definition at line 241 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 311 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 (μm)
wavelength_max	Optional maximum wavelength (μm)

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

Examples

>>> 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 559 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 354 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 382 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 963 of file RadiationModel.py.

◆ copyRadiationBand()

pyhelios.RadiationModel.RadiationModel.copyRadiationBand	(		self,
		str	old_label,
		str	new_label )

Copy existing radiation band to new label.

Parameters

old_label	Existing band label to copy
new_label	New label for the copied band

Definition at line 296 of file RadiationModel.py.

◆ disableEmission()

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

Disable emission for radiation band.

Definition at line 517 of file RadiationModel.py.

◆ disableMessages()

pyhelios.RadiationModel.RadiationModel.disableMessages ( self )

Disable RadiationModel status messages.

Definition at line 259 of file RadiationModel.py.

◆ enableEmission()

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

Enable emission for radiation band.

Definition at line 523 of file RadiationModel.py.

◆ enableMessages()

pyhelios.RadiationModel.RadiationModel.enableMessages ( self )

Enable RadiationModel status messages.

Definition at line 264 of file RadiationModel.py.

◆ get_native_ptr()

pyhelios.RadiationModel.RadiationModel.get_native_ptr ( self )

Get native pointer for advanced operations.

Definition at line 250 of file RadiationModel.py.

◆ getNativePtr()

pyhelios.RadiationModel.RadiationModel.getNativePtr ( self )

Get native pointer for advanced operations.

(Legacy naming for compatibility)

Definition at line 254 of file RadiationModel.py.

◆ getPluginInfo()

dict pyhelios.RadiationModel.RadiationModel.getPluginInfo ( self )

Get information about the radiation plugin.

Definition at line 1005 of file RadiationModel.py.

◆ getSourceFlux()

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

Get source flux for band.

Definition at line 431 of file RadiationModel.py.

◆ getTotalAbsorbedFlux()

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

Get total absorbed flux for all primitives.

Definition at line 497 of file RadiationModel.py.

◆ runBand()

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

Run radiation simulation for single band or multiple bands.

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

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

Examples

# EFFICIENT - Single call for multiple bands
radiation.runBand(["PAR", "NIR", "SW"])
 
# INEFFICIENT - Sequential single-band calls
radiation.runBand("PAR")
radiation.runBand("NIR")
radiation.runBand("SW")

Parameters

band_label Single band name (str) or list of band names for multi-band simulation

Definition at line 479 of file RadiationModel.py.

◆ setDiffuseRadiationFlux()

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

Set diffuse radiation flux for band.

Definition at line 407 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 400 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 393 of file RadiationModel.py.

◆ setMinScatterEnergy()

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

Set minimum scatter energy for radiation band.

Definition at line 512 of file RadiationModel.py.

◆ setScatteringDepth()

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

Set scattering depth for radiation band.

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

◆ updateGeometry()

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

Update geometry in radiation model.

Parameters

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

Definition at line 442 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 642 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 723 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 763 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 863 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 686 of file RadiationModel.py.

Member Data Documentation

◆ context

pyhelios.RadiationModel.RadiationModel.context = context

Definition at line 188 of file RadiationModel.py.

◆ radiation_model

pyhelios.RadiationModel.RadiationModel.radiation_model = None

Definition at line 189 of file RadiationModel.py.

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

pyhelios/RadiationModel.py

Detailed Description

Public Member Functions

Public Attributes

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ addCollimatedRadiationSource()

◆ addRadiationBand()

◆ addRadiationCamera()

◆ addSphereRadiationSource()

◆ addSunSphereRadiationSource()

◆ autoCalibrateCameraImage()

◆ copyRadiationBand()

◆ disableEmission()

◆ disableMessages()

◆ enableEmission()

◆ enableMessages()

◆ get_native_ptr()

◆ getNativePtr()

◆ getPluginInfo()

◆ getSourceFlux()

◆ getTotalAbsorbedFlux()

◆ runBand()

◆ setDiffuseRadiationFlux()

◆ setDiffuseRayCount()

◆ setDirectRayCount()

◆ setMinScatterEnergy()

◆ setScatteringDepth()

◆ setSourceFlux()

◆ updateGeometry()

◆ writeCameraImage()

◆ writeCameraImageData()

◆ writeImageBoundingBoxes()

◆ writeImageSegmentationMasks()

◆ writeNormCameraImage()

Member Data Documentation

◆ context

◆ radiation_model

◆ init()

◆ enter()

◆ exit()