Central simulation environment for PyHelios that manages 3D primitives and their data. More...

Detailed Description

Central simulation environment for PyHelios that manages 3D primitives and their data.

The Context class provides methods for:

Creating geometric primitives (patches, triangles)
Creating compound geometry (tiles, spheres, tubes, boxes)
Loading 3D models from files (PLY, OBJ, XML)
Managing primitive data (flexible key-value storage)
Querying primitive properties and collections
Batch operations on multiple primitives

Key features:

UUID-based primitive tracking
Comprehensive primitive data system with auto-type detection
Efficient array-based data retrieval via getPrimitiveDataArray()
Cross-platform compatibility with mock mode support
Context manager protocol for resource cleanup

Example: >>> with Context() as context: ... # Create primitives ... patch_uuid = context.addPatch(center=vec3(0, 0, 0)) ... triangle_uuid = context.addTriangle(vec3(0,0,0), vec3(1,0,0), vec3(0.5,1,0)) ... ... # Set primitive data ... context.setPrimitiveDataFloat(patch_uuid, "temperature", 25.5) ... context.setPrimitiveDataFloat(triangle_uuid, "temperature", 30.2) ... ... # Get data efficiently as NumPy array ... temps = context.getPrimitiveDataArray([patch_uuid, triangle_uuid], "temperature") ... print(temps) # [25.5 30.2]

Definition at line 78 of file Context.py.

Public Member Functions
	__init__ (self)

	__enter__ (self)

	__exit__ (self, exc_type, exc_value, traceback)

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

	getNativePtr (self)

	markGeometryClean (self)

	markGeometryDirty (self)

bool	isGeometryDirty (self)

	seedRandomGenerator (self, int seed)
	Seed the random number generator for reproducible stochastic results.

int	addPatch (self, vec3 center=vec3(0, 0, 0), vec2 size=vec2(1, 1), Optional[SphericalCoord] rotation=None, Optional[RGBcolor] color=None)

int	addTriangle (self, vec3 vertex0, vec3 vertex1, vec3 vertex2, Optional[RGBcolor] color=None)
	Add a triangle primitive to the context.

int	addTriangleTextured (self, vec3 vertex0, vec3 vertex1, vec3 vertex2, str texture_file, vec2 uv0, vec2 uv1, vec2 uv2)
	Add a textured triangle primitive to the context.

	getPrimitiveType (self, uuid)
	Get the type of a primitive or multiple primitives.

	getPrimitiveArea (self, uuid)
	Get the area of a primitive or multiple primitives.

	getPrimitiveNormal (self, uuid)
	Get the normal vector of a primitive or multiple primitives.

	getPrimitiveVertices (self, uuid)
	Get vertices of a primitive or multiple primitives.

	getPrimitiveColor (self, uuid)
	Get the color of a primitive or multiple primitives.

int	getPrimitiveCount (self)

List[int]	getAllUUIDs (self)

int	getObjectCount (self)

List[int]	getAllObjectIDs (self)

PrimitiveInfo	getPrimitiveInfo (self, int uuid)
	Get physical properties and geometry information for a single primitive.

List[PrimitiveInfo]	getAllPrimitiveInfo (self)
	Get physical properties and geometry information for all primitives in the context.

List[PrimitiveInfo]	getPrimitivesInfoForObject (self, int object_id)
	Get physical properties and geometry information for all primitives belonging to a specific object.

List[int]	addTile (self, vec3 center=vec3(0, 0, 0), vec2 size=vec2(1, 1), Optional[SphericalCoord] rotation=None, int2 subdiv=int2(1, 1), Optional[RGBcolor] color=None)
	Add a subdivided patch (tile) to the context.

List[int]	addSphere (self, vec3 center=vec3(0, 0, 0), float radius=1.0, int ndivs=10, Optional[RGBcolor] color=None)
	Add a sphere to the context.

List[int]	addTube (self, List[vec3] nodes, Union[float, List[float]] radii, int ndivs=6, Optional[Union[RGBcolor, List[RGBcolor]]] colors=None)
	Add a tube (pipe/cylinder) to the context.

List[int]	addBox (self, vec3 center=vec3(0, 0, 0), vec3 size=vec3(1, 1, 1), int3 subdiv=int3(1, 1, 1), Optional[RGBcolor] color=None)
	Add a rectangular box to the context.

List[int]	addDisk (self, vec3 center=vec3(0, 0, 0), vec2 size=vec2(1, 1), Union[int, int2] ndivs=20, Optional[SphericalCoord] rotation=None, Optional[Union[RGBcolor, RGBAcolor]] color=None)
	Add a disk (circular or elliptical surface) to the context.

List[int]	addCone (self, vec3 node0, vec3 node1, float radius0, float radius1, int ndivs=20, Optional[RGBcolor] color=None)
	Add a cone (or cylinder/frustum) to the context.

int	addSphereObject (self, vec3 center=vec3(0, 0, 0), Union[float, vec3] radius=1.0, int ndivs=20, Optional[RGBcolor] color=None, Optional[str] texturefile=None)
	Add a spherical or ellipsoidal compound object to the context.

int	addTileObject (self, vec3 center=vec3(0, 0, 0), vec2 size=vec2(1, 1), SphericalCoord rotation=SphericalCoord(1, 0, 0), int2 subdiv=int2(1, 1), Optional[RGBcolor] color=None, Optional[str] texturefile=None, Optional[int2] texture_repeat=None)
	Add a tiled patch (subdivided patch) as a compound object to the context.

int	addBoxObject (self, vec3 center=vec3(0, 0, 0), vec3 size=vec3(1, 1, 1), int3 subdiv=int3(1, 1, 1), Optional[RGBcolor] color=None, Optional[str] texturefile=None, bool reverse_normals=False)
	Add a rectangular box (prism) as a compound object to the context.

int	addConeObject (self, vec3 node0, vec3 node1, float radius0, float radius1, int ndivs=20, Optional[RGBcolor] color=None, Optional[str] texturefile=None)
	Add a cone/cylinder/frustum as a compound object to the context.

int	addDiskObject (self, vec3 center=vec3(0, 0, 0), vec2 size=vec2(1, 1), Union[int, int2] ndivs=20, Optional[SphericalCoord] rotation=None, Optional[Union[RGBcolor, RGBAcolor]] color=None, Optional[str] texturefile=None)
	Add a disk as a compound object to the context.

int	addTubeObject (self, int ndivs, List[vec3] nodes, List[float] radii, Optional[List[RGBcolor]] colors=None, Optional[str] texturefile=None, Optional[List[float]] texture_uv=None)
	Add a tube as a compound object to the context.

Union[int, List[int]]	copyPrimitive (self, Union[int, List[int]] UUID)
	Copy one or more primitives.

None	copyPrimitiveData (self, int sourceUUID, int destinationUUID)
	Copy all primitive data from source to destination primitive.

Union[int, List[int]]	copyObject (self, Union[int, List[int]] ObjID)
	Copy one or more compound objects.

None	copyObjectData (self, int source_objID, int destination_objID)
	Copy all object data from source to destination compound object.

None	translatePrimitive (self, Union[int, List[int]] UUID, vec3 shift)
	Translate one or more primitives by a shift vector.

None	translateObject (self, Union[int, List[int]] ObjID, vec3 shift)
	Translate one or more compound objects by a shift vector.

None	rotatePrimitive (self, Union[int, List[int]] UUID, float angle, Union[str, vec3] axis, Optional[vec3] origin=None)
	Rotate one or more primitives.

None	rotateObject (self, Union[int, List[int]] ObjID, float angle, Union[str, vec3] axis, Optional[vec3] origin=None, bool about_origin=False)
	Rotate one or more objects.

None	scalePrimitive (self, Union[int, List[int]] UUID, vec3 scale, Optional[vec3] point=None)
	Scale one or more primitives.

None	scaleObject (self, Union[int, List[int]] ObjID, vec3 scale, Optional[vec3] point=None, bool about_center=False, bool about_origin=False)
	Scale one or more objects.

None	scaleConeObjectLength (self, int ObjID, float scale_factor)
	Scale the length of a Cone object by scaling the distance between its two nodes.

None	scaleConeObjectGirth (self, int ObjID, float scale_factor)
	Scale the girth of a Cone object by scaling the radii at both nodes.

List[int]	loadPLY (self, str filename, Optional[vec3] origin=None, Optional[float] height=None, Optional[SphericalCoord] rotation=None, Optional[RGBcolor] color=None, str upaxis="YUP", bool silent=False)
	Load geometry from a PLY (Stanford Polygon) file.

List[int]	loadOBJ (self, str filename, Optional[vec3] origin=None, Optional[float] height=None, Optional[vec3] scale=None, Optional[SphericalCoord] rotation=None, Optional[RGBcolor] color=None, str upaxis="YUP", bool silent=False)
	Load geometry from an OBJ (Wavefront) file.

List[int]	loadXML (self, str filename, bool quiet=False)
	Load geometry from a Helios XML file.

None	writePLY (self, str filename, Optional[List[int]] UUIDs=None)
	Write geometry to a PLY (Stanford Polygon) file.

None	writeOBJ (self, str filename, Optional[List[int]] UUIDs=None, Optional[List[str]] primitive_data_fields=None, bool write_normals=False, bool silent=False)
	Write geometry to an OBJ (Wavefront) file.

None	writePrimitiveData (self, str filename, List[str] column_labels, Optional[List[int]] UUIDs=None, bool print_header=False)
	Write primitive data to an ASCII text file.

List[int]	addTrianglesFromArrays (self, np.ndarray vertices, np.ndarray faces, Optional[np.ndarray] colors=None)
	Add triangles from NumPy arrays (compatible with trimesh, Open3D format).

List[int]	addTrianglesFromArraysTextured (self, np.ndarray vertices, np.ndarray faces, np.ndarray uv_coords, Union[str, List[str]] texture_files, Optional[np.ndarray] material_ids=None)
	Add textured triangles from NumPy arrays with support for multiple textures.

None	setPrimitiveDataInt (self, uuids_or_uuid, str label, int value)
	Set primitive data as signed 32-bit integer for one or multiple primitives.

None	setPrimitiveDataUInt (self, uuids_or_uuid, str label, int value)
	Set primitive data as unsigned 32-bit integer for one or multiple primitives.

None	setPrimitiveDataFloat (self, uuids_or_uuid, str label, float value)
	Set primitive data as 32-bit float for one or multiple primitives.

None	setPrimitiveDataDouble (self, uuids_or_uuid, str label, float value)
	Set primitive data as 64-bit double for one or multiple primitives.

None	setPrimitiveDataString (self, uuids_or_uuid, str label, str value)
	Set primitive data as string for one or multiple primitives.

None	setPrimitiveDataVec2 (self, uuids_or_uuid, str label, x_or_vec, float y=None)
	Set primitive data as vec2 for one or multiple primitives.

None	setPrimitiveDataVec3 (self, uuids_or_uuid, str label, x_or_vec, float y=None, float z=None)
	Set primitive data as vec3 for one or multiple primitives.

None	setPrimitiveDataVec4 (self, uuids_or_uuid, str label, x_or_vec, float y=None, float z=None, float w=None)
	Set primitive data as vec4 for one or multiple primitives.

None	setPrimitiveDataInt2 (self, uuids_or_uuid, str label, x_or_vec, int y=None)
	Set primitive data as int2 for one or multiple primitives.

None	setPrimitiveDataInt3 (self, uuids_or_uuid, str label, x_or_vec, int y=None, int z=None)
	Set primitive data as int3 for one or multiple primitives.

None	setPrimitiveDataInt4 (self, uuids_or_uuid, str label, x_or_vec, int y=None, int z=None, int w=None)
	Set primitive data as int4 for one or multiple primitives.

	getPrimitiveData (self, int uuid, str label, type data_type=None)
	Get primitive data for a specific primitive.

bool	doesPrimitiveDataExist (self, int uuid, str label)
	Check if primitive data exists for a specific primitive and label.

float	getPrimitiveDataFloat (self, int uuid, str label)
	Convenience method to get float primitive data.

int	getPrimitiveDataType (self, int uuid, str label)
	Get the Helios data type of primitive data.

int	getPrimitiveDataSize (self, int uuid, str label)
	Get the size/length of primitive data (for vector data).

np.ndarray	getPrimitiveDataArray (self, List[int] uuids, str label)
	Get primitive data values for multiple primitives as a NumPy array.

	colorPrimitiveByDataPseudocolor (self, List[int] uuids, str primitive_data, str colormap="hot", int ncolors=10, Optional[float] max_val=None, Optional[float] min_val=None)
	Color primitives based on primitive data values using pseudocolor mapping.

	setTime (self, int hour, int minute=0, int second=0)
	Set the simulation time.

	setDate (self, int year, int month, int day)
	Set the simulation date.

	setDateJulian (self, int julian_day, int year)
	Set the simulation date using Julian day number.

	getTime (self)
	Get the current simulation time.

	getDate (self)
	Get the current simulation date.

	addTimeseriesData (self, str label, float value, 'Date' date, 'Time' time)
	Add a data point to a timeseries variable.

	setCurrentTimeseriesPoint (self, str label, int index)
	Set the Context date and time from a timeseries data point index.

float	queryTimeseriesData (self, str label, 'Date' date=None, 'Time' time=None, int index=None)
	Query a timeseries data value.

'Time'	queryTimeseriesTime (self, str label, int index)
	Get the Time associated with a timeseries data point.

'Date'	queryTimeseriesDate (self, str label, int index)
	Get the Date associated with a timeseries data point.

int	getTimeseriesLength (self, str label)
	Get the number of data points in a timeseries variable.

bool	doesTimeseriesVariableExist (self, str label)
	Check whether a timeseries variable exists.

List[str]	listTimeseriesVariables (self)
	List all existing timeseries variables.

	loadTabularTimeseriesData (self, str data_file, List[str] column_labels, str delimiter=",", str date_string_format="YYYYMMDD", int headerlines=0)
	Load tabular timeseries data from a text file.

None	deletePrimitive (self, Union[int, List[int]] uuids_or_uuid)
	Delete one or more primitives from the context.

None	deleteObject (self, Union[int, List[int]] objIDs_or_objID)
	Delete one or more compound objects from the context.

List[str]	get_available_plugins (self)
	Get list of available plugins for this PyHelios instance.

bool	is_plugin_available (self, str plugin_name)
	Check if a specific plugin is available.

dict	get_plugin_capabilities (self)
	Get detailed information about available plugin capabilities.

	print_plugin_status (self)
	Print detailed plugin status information.

List[str]	get_missing_plugins (self, List[str] requested_plugins)
	Get list of requested plugins that are not available.

	addMaterial (self, str material_label)
	Create a new material for sharing visual properties across primitives.

bool	doesMaterialExist (self, str material_label)
	Check if a material with the given label exists.

List[str]	listMaterials (self)
	Get list of all material labels in the context.

	deleteMaterial (self, str material_label)
	Delete a material from the context.

	getMaterialColor (self, str material_label)
	Get the RGBA color of a material.

	setMaterialColor (self, str material_label, color)
	Set the RGBA color of a material.

str	getMaterialTexture (self, str material_label)
	Get the texture file path for a material.

	setMaterialTexture (self, str material_label, str texture_file)
	Set the texture file for a material.

bool	isMaterialTextureColorOverridden (self, str material_label)
	Check if material texture color is overridden by material color.

	setMaterialTextureColorOverride (self, str material_label, bool override)
	Set whether material color overrides texture color.

int	getMaterialTwosidedFlag (self, str material_label)
	Get the two-sided rendering flag for a material (0 = one-sided, 1 = two-sided).

	setMaterialTwosidedFlag (self, str material_label, int twosided_flag)
	Set the two-sided rendering flag for a material (0 = one-sided, 1 = two-sided).

	assignMaterialToPrimitive (self, uuid, str material_label)
	Assign a material to primitive(s).

	assignMaterialToObject (self, objID, str material_label)
	Assign a material to all primitives in compound object(s).

	getPrimitiveMaterialLabel (self, uuid)
	Get the material label assigned to a primitive or multiple primitives.

int	getPrimitiveTwosidedFlag (self, int uuid, int default_value=1)
	Get two-sided rendering flag for a primitive.

List[int]	getPrimitivesUsingMaterial (self, str material_label)
	Get all primitive UUIDs that use a specific material.

	getPrimitiveTextureFile (self, uuid)
	Get the texture file path of a primitive or multiple primitives.

None	setPrimitiveTextureFile (self, int uuid, str texture_file)
	Set the texture file path of a primitive.

int2	getPrimitiveTextureSize (self, int uuid)
	Get the texture size (width, height) of a primitive.

	getPrimitiveTextureUV (self, uuid)
	Get the texture UV coordinates of a primitive or multiple primitives.

bool	primitiveTextureHasTransparencyChannel (self, int uuid)
	Check if primitive texture has a transparency channel.

	getPrimitiveSolidFraction (self, uuid)
	Get the solid fraction of a primitive or multiple primitives.

None	overridePrimitiveTextureColor (self, int uuid)
	Override texture color with constant RGB color for a primitive.

None	usePrimitiveTextureColor (self, int uuid)
	Use texture map color instead of constant RGB for a primitive.

bool	isPrimitiveTextureColorOverridden (self, int uuid)
	Check if primitive texture color is overridden.

'np.ndarray'	getAllPrimitiveNormals (self)
	Get normals for all primitives.

'np.ndarray'	getAllPrimitiveColors (self)
	Get colors for all primitives.

'np.ndarray'	getAllPrimitiveAreas (self)
	Get areas for all primitives.

'np.ndarray'	getAllPrimitiveTypes (self)
	Get types for all primitives.

'np.ndarray'	getAllPrimitiveSolidFractions (self)
	Get solid fractions for all primitives.

	getAllPrimitiveVertices (self)
	Get vertices for all primitives.

List[str]	getAllPrimitiveTextureFiles (self)
	Get texture files for all primitives.

List[str]	getAllPrimitiveMaterialLabels (self)
	Get material labels for all primitives.

Public Attributes
	context = None

Protected Member Functions
	_check_context_available (self)
	Helper method to check if context is available with detailed error messages.

	_validate_uuid (self, int uuid)
	Validate that a UUID exists in this context.

str	_validate_file_path (self, str filename, List[str] expected_extensions=None)
	Validate and normalize file path for security.

str	_validate_output_file_path (self, str filename, List[str] expected_extensions=None)
	Validate and normalize output file path for security.

Protected Attributes
	_plugin_registry = get_plugin_registry()

str	_lifecycle_state = 'initializing'

Constructor & Destructor Documentation

◆ init()

pyhelios.Context.Context.__init__ ( self )

Definition at line 80 of file Context.py.

◆ del()

pyhelios.Context.Context.__del__ ( self )

Destructor to ensure C++ resources freed even without 'with' statement.

Definition at line 295 of file Context.py.

Member Function Documentation

◆ enter()

pyhelios.Context.Context.__enter__ ( self )

Definition at line 285 of file Context.py.

◆ exit()

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

Definition at line 288 of file Context.py.

◆ _check_context_available()

pyhelios.Context.Context._check_context_available ( self )

protected

Helper method to check if context is available with detailed error messages.

Definition at line 133 of file Context.py.

◆ _validate_file_path()

str pyhelios.Context.Context._validate_file_path	(		self,
		str	filename,
		List[str]	expected_extensions = None )

protected

Validate and normalize file path for security.

Parameters

filename	File path to validate
expected_extensions	List of allowed file extensions (e.g., ['.ply', '.obj'])

Returns: Normalized absolute path

Exceptions

ValueError	If path is invalid or potentially dangerous
FileNotFoundError	If file does not exist

Definition at line 212 of file Context.py.

◆ _validate_output_file_path()

str pyhelios.Context.Context._validate_output_file_path	(		self,
		str	filename,
		List[str]	expected_extensions = None )

protected

Validate and normalize output file path for security.

Parameters

filename	Output file path to validate
expected_extensions	List of allowed file extensions (e.g., ['.ply', '.obj'])

Returns: Normalized absolute path

Exceptions

ValueError	If path is invalid or potentially dangerous
PermissionError	If output directory is not writable

Definition at line 255 of file Context.py.

◆ _validate_uuid()

pyhelios.Context.Context._validate_uuid	(		self,
		int	uuid )

protected

Validate that a UUID exists in this context.

Parameters

uuid	The UUID to validate

Exceptions

RuntimeError If UUID is invalid or doesn't exist in context

Definition at line 177 of file Context.py.

◆ addBox()

List[int] pyhelios.Context.Context.addBox	(		self,
		vec3	center = vec3(0, 0, 0),
		vec3	size = vec3(1, 1, 1),
		int3	subdiv = int3(1, 1, 1),
		Optional[RGBcolor]	color = None )

Add a rectangular box to the context.

   The box is subdivided into patches on each face based on the specified
   subdivisions.

Parameters

center	3D coordinates of box center (default: origin)
size	Width, height, and depth of the box (default: 1x1x1)
subdiv	Number of subdivisions in x, y, and z directions (default: 1x1x1) Higher values create more detailed surfaces
color	Color of the box (default: white)

Returns: List of UUIDs for all patches created on the box faces

Example: >>> context = Context() >>> # Create a blue box subdivided for detail >>> box_uuids = context.addBox( ... center=vec3(0, 0, 2), ... size=vec3(2, 1, 0.5), ... subdiv=int3(4, 2, 1), ... color=RGBcolor(0, 0, 1) ... ) >>> print(f"Created box with {len(box_uuids)} patches")

Definition at line 851 of file Context.py.

◆ addBoxObject()

int pyhelios.Context.Context.addBoxObject	(		self,
		vec3	center = vec3(0, 0, 0),
		vec3	size = vec3(1, 1, 1),
		int3	subdiv = int3(1, 1, 1),
		Optional[RGBcolor]	color = None,
		Optional[str]	texturefile = None,
		bool	reverse_normals = False )

Add a rectangular box (prism) as a compound object to the context.

Parameters

center	Center position (default: origin)
size	Size in x, y, z directions (default: 1x1x1)
subdiv	Subdivisions in x, y, z (default: 1x1x1)
color	Optional RGB color
texturefile	Optional texture file path
reverse_normals	Reverse normal directions (default: False)

Returns: Object ID of the created compound object

Definition at line 1279 of file Context.py.

◆ addCone()

List[int] pyhelios.Context.Context.addCone	(		self,
		vec3	node0,
		vec3	node1,
		float	radius0,
		float	radius1,
		int	ndivs = 20,
		Optional[RGBcolor]	color = None )

Add a cone (or cylinder/frustum) to the context.

   A cone is a 3D shape connecting two circular cross-sections with
   potentially different radii. When radii are equal, creates a cylinder.
   When one radius is zero, creates a true cone.

Parameters

node0	3D coordinates of the base center
node1	3D coordinates of the apex center
radius0	Radius at base (node0). Use 0 for pointed end.
radius1	Radius at apex (node1). Use 0 for pointed end.
ndivs	Number of radial divisions for tessellation (default: 20)
color	Color of the cone (default: white)

Returns: List of UUIDs for all triangles created in the cone

Example: >>> context = Context() >>> # Create a cylinder (equal radii) >>> cylinder_uuids = context.addCone( ... node0=vec3(0, 0, 0), ... node1=vec3(0, 0, 2), ... radius0=0.5, ... radius1=0.5, ... ndivs=20 ... ) >>> >>> # Create a true cone (one radius = 0) >>> cone_uuids = context.addCone( ... node0=vec3(1, 0, 0), ... node1=vec3(1, 0, 1.5), ... radius0=0.5, ... radius1=0.0, ... ndivs=24, ... color=RGBcolor(1, 0, 0) ... ) >>> >>> # Create a frustum (different radii) >>> frustum_uuids = context.addCone( ... node0=vec3(2, 0, 0), ... node1=vec3(2, 0, 1), ... radius0=0.8, ... radius1=0.4, ... ndivs=16 ... )

Definition at line 1056 of file Context.py.

◆ addConeObject()

int pyhelios.Context.Context.addConeObject	(		self,
		vec3	node0,
		vec3	node1,
		float	radius0,
		float	radius1,
		int	ndivs = 20,
		Optional[RGBcolor]	color = None,
		Optional[str]	texturefile = None )

Add a cone/cylinder/frustum as a compound object to the context.

Parameters

node0	Base position
node1	Top position
radius0	Radius at base
radius1	Radius at top
ndivs	Number of radial divisions (default: 20)
color	Optional RGB color
texturefile	Optional texture file path

Returns: Object ID of the created compound object

Definition at line 1323 of file Context.py.

◆ addDisk()

List[int] pyhelios.Context.Context.addDisk	(		self,
		vec3	center = vec3(0, 0, 0),
		vec2	size = vec2(1, 1),
		Union[int, int2]	ndivs = 20,
		Optional[SphericalCoord]	rotation = None,
		Optional[Union[RGBcolor, RGBAcolor]]	color = None )

Add a disk (circular or elliptical surface) to the context.

   A disk is a flat circular or elliptical surface tessellated into
   triangular faces. Supports both uniform radial subdivisions and
   separate radial/azimuthal subdivisions for finer control.

Parameters

center	3D coordinates of disk center (default: origin)
size	Semi-major and semi-minor radii of the disk (default: 1x1 circle)
ndivs	Number of radial divisions (int) or [radial, azimuthal] divisions (int2) (default: 20). Higher values create smoother circles but more triangles.
rotation	Orientation of the disk (default: horizontal, normal = +z)
color	Color of the disk (default: white). Can be RGBcolor or RGBAcolor for transparency.

Returns: List of UUIDs for all triangles created in the disk

Example: >>> context = Context() >>> # Create a red disk at (0, 0, 1) with radius 0.5 >>> disk_uuids = context.addDisk( ... center=vec3(0, 0, 1), ... size=vec2(0.5, 0.5), ... ndivs=30, ... color=RGBcolor(1, 0, 0) ... ) >>> print(f"Created disk with {len(disk_uuids)} triangles") >>> >>> # Create a semi-transparent blue elliptical disk >>> disk_uuids = context.addDisk( ... center=vec3(0, 0, 2), ... size=vec2(1.0, 0.5), ... ndivs=40, ... rotation=SphericalCoord(1, 0.5, 0), ... color=RGBAcolor(0, 0, 1, 0.5) ... ) >>> >>> # Create disk with polar/radial subdivisions for finer control >>> disk_uuids = context.addDisk( ... center=vec3(0, 0, 3), ... size=vec2(1, 1), ... ndivs=int2(10, 20), # 10 radial, 20 azimuthal divisions ... color=RGBcolor(0, 1, 0) ... )

Definition at line 927 of file Context.py.

◆ addDiskObject()

int pyhelios.Context.Context.addDiskObject	(		self,
		vec3	center = vec3(0, 0, 0),
		vec2	size = vec2(1, 1),
		Union[int, int2]	ndivs = 20,
		Optional[SphericalCoord]	rotation = None,
		Optional[Union[RGBcolor, RGBAcolor]]	color = None,
		Optional[str]	texturefile = None )

Add a disk as a compound object to the context.

Parameters

center	Center position (default: origin)
size	Semi-major and semi-minor radii (default: 1x1)
ndivs	int (uniform) or int2 (polar/radial subdivisions) (default: 20)
rotation	Optional spherical rotation
color	Optional RGB or RGBA color
texturefile	Optional texture file path

Returns: Object ID of the created compound object

Definition at line 1361 of file Context.py.

◆ addMaterial()

pyhelios.Context.Context.addMaterial	(		self,
		str	material_label )

Create a new material for sharing visual properties across primitives.

   Materials enable efficient memory usage by allowing multiple primitives to
   share rendering properties. Changes to a material affect all primitives using it.

Parameters

material_label Unique label for the material

Exceptions

RuntimeError If material label already exists

Example: >>> context.addMaterial("wood_oak") >>> context.setMaterialColor("wood_oak", (0.6, 0.4, 0.2, 1.0)) >>> context.assignMaterialToPrimitive(uuid, "wood_oak")

Definition at line 3407 of file Context.py.

◆ addPatch()

int pyhelios.Context.Context.addPatch	(		self,
		vec3	center = vec3(0, 0, 0),
		vec2	size = vec2(1, 1),
		Optional[SphericalCoord]	rotation = None,
		Optional[RGBcolor]	color = None )

Definition at line 337 of file Context.py.

◆ addSphere()

List[int] pyhelios.Context.Context.addSphere	(		self,
		vec3	center = vec3(0, 0, 0),
		float	radius = 1.0,
		int	ndivs = 10,
		Optional[RGBcolor]	color = None )

Add a sphere to the context.

   The sphere is tessellated into triangular faces based on the specified
   number of divisions.

Parameters

center	3D coordinates of sphere center (default: origin)
radius	Radius of the sphere (default: 1.0)
ndivs	Number of divisions for tessellation (default: 10) Higher values create smoother spheres but more triangles
color	Color of the sphere (default: white)

Returns: List of UUIDs for all triangles created in the sphere

Example: >>> context = Context() >>> # Create a red sphere at (1, 2, 3) with radius 0.5 >>> sphere_uuids = context.addSphere( ... center=vec3(1, 2, 3), ... radius=0.5, ... ndivs=20, ... color=RGBcolor(1, 0, 0) ... ) >>> print(f"Created sphere with {len(sphere_uuids)} triangles")

Definition at line 712 of file Context.py.

◆ addSphereObject()

int pyhelios.Context.Context.addSphereObject	(		self,
		vec3	center = vec3(0, 0, 0),
		Union[float, vec3]	radius = 1.0,
		int	ndivs = 20,
		Optional[RGBcolor]	color = None,
		Optional[str]	texturefile = None )

Add a spherical or ellipsoidal compound object to the context.

   Creates a sphere or ellipsoid as a compound object with a trackable object ID.
   Primitives within the object are registered as children of the object.

Parameters

center	Center position of sphere/ellipsoid (default: origin)
radius	Radius as float (sphere) or vec3 (ellipsoid) (default: 1.0)
ndivs	Number of tessellation divisions (default: 20)
color	Optional RGB color
texturefile	Optional texture image file path

Returns: Object ID of the created compound object

Exceptions

ValueError	If parameters are invalid
NotImplementedError	If object-returning functions unavailable

Examples: >>> # Create a basic sphere at origin >>> obj_id = ctx.addSphereObject()

: >>> # Create a colored sphere >>> obj_id = ctx.addSphereObject( ... center=vec3(0, 0, 5), ... radius=2.0, ... color=RGBcolor(1, 0, 0) ... )

: >>> # Create an ellipsoid (stretched sphere) >>> obj_id = ctx.addSphereObject( ... center=vec3(10, 0, 0), ... radius=vec3(2, 1, 1), # Elongated in x-direction ... ndivs=30 ... )

Definition at line 1126 of file Context.py.

◆ addTile()

List[int] pyhelios.Context.Context.addTile	(		self,
		vec3	center = vec3(0, 0, 0),
		vec2	size = vec2(1, 1),
		Optional[SphericalCoord]	rotation = None,
		int2	subdiv = int2(1, 1),
		Optional[RGBcolor]	color = None )

Add a subdivided patch (tile) to the context.

   A tile is a patch subdivided into a regular grid of smaller patches,
   useful for creating detailed surfaces or terrain.

Parameters

center	3D coordinates of tile center (default: origin)
size	Width and height of the tile (default: 1x1)
rotation	Orientation of the tile (default: no rotation)
subdiv	Number of subdivisions in x and y directions (default: 1x1)
color	Color of the tile (default: white)

Returns: List of UUIDs for all patches created in the tile

Example: >>> context = Context() >>> # Create a 2x2 meter tile subdivided into 4x4 patches >>> tile_uuids = context.addTile( ... center=vec3(0, 0, 1), ... size=vec2(2, 2), ... subdiv=int2(4, 4), ... color=RGBcolor(0.5, 0.8, 0.2) ... ) >>> print(f"Created {len(tile_uuids)} patches")

Definition at line 644 of file Context.py.

◆ addTileObject()

int pyhelios.Context.Context.addTileObject	(		self,
		vec3	center = vec3(0, 0, 0),
		vec2	size = vec2(1, 1),
		SphericalCoord	rotation = SphericalCoord(1, 0, 0),
		int2	subdiv = int2(1, 1),
		Optional[RGBcolor]	color = None,
		Optional[str]	texturefile = None,
		Optional[int2]	texture_repeat = None )

Add a tiled patch (subdivided patch) as a compound object to the context.

   Creates a rectangular patch subdivided into a grid of smaller patches,
   registered as a compound object with a trackable object ID.

Parameters

center	Center position of tile (default: origin)
size	Size in x and y directions (default: 1x1)
rotation	Spherical rotation (default: no rotation)
subdiv	Number of subdivisions in x and y (default: 1x1)
color	Optional RGB color
texturefile	Optional texture image file path
texture_repeat	Optional texture repetitions in x and y

Returns: Object ID of the created compound object

Exceptions

ValueError	If parameters are invalid
NotImplementedError	If object-returning functions unavailable

Examples: >>> # Create a basic 2x2 tile >>> obj_id = ctx.addTileObject( ... center=vec3(0, 0, 0), ... size=vec2(10, 10), ... subdiv=int2(2, 2) ... )

: >>> # Create a colored tile with rotation >>> obj_id = ctx.addTileObject( ... center=vec3(5, 0, 0), ... size=vec2(10, 5), ... rotation=SphericalCoord(1, 0, 45), ... subdiv=int2(4, 2), ... color=RGBcolor(0, 1, 0) ... )

Definition at line 1216 of file Context.py.

◆ addTimeseriesData()

pyhelios.Context.Context.addTimeseriesData	(		self,
		str	label,
		float	value,
		'Date'	date,
		'Time'	time )

Add a data point to a timeseries variable.

Parameters

label	Name of the timeseries variable (e.g., "temperature")
value	Value of the data point

Date: Date of the data point

Parameters

time	Time of the data point

Exceptions

ValueError	If label is empty, or date/time are wrong types
NotImplementedError	If timeseries functions not available

Example: >>> from pyhelios.types import Date, Time >>> context.addTimeseriesData("temperature", 25.3, Date(2024, 6, 15), Time(12, 0, 0))

Definition at line 2990 of file Context.py.

◆ addTriangle()

int pyhelios.Context.Context.addTriangle	(		self,
		vec3	vertex0,
		vec3	vertex1,
		vec3	vertex2,
		Optional[RGBcolor]	color = None )

Add a triangle primitive to the context.

Parameters

vertex0	First vertex of the triangle
vertex1	Second vertex of the triangle
vertex2	Third vertex of the triangle
color	Optional triangle color (defaults to white)

Returns: UUID of the created triangle primitive

Definition at line 357 of file Context.py.

◆ addTrianglesFromArrays()

List[int] pyhelios.Context.Context.addTrianglesFromArrays	(		self,
		np.ndarray	vertices,
		np.ndarray	faces,
		Optional[np.ndarray]	colors = None )

Add triangles from NumPy arrays (compatible with trimesh, Open3D format).

Parameters

vertices	NumPy array of shape (N, 3) containing vertex coordinates as float32/float64
faces	NumPy array of shape (M, 3) containing triangle vertex indices as int32/int64
colors	Optional NumPy array of shape (N, 3) or (M, 3) containing RGB colors as float32/float64 If shape (N, 3): per-vertex colors If shape (M, 3): per-triangle colors

Returns: List of UUIDs for the added triangles

Exceptions

ValueError If array dimensions are invalid

Definition at line 2233 of file Context.py.

◆ addTrianglesFromArraysTextured()

List[int] pyhelios.Context.Context.addTrianglesFromArraysTextured	(		self,
		np.ndarray	vertices,
		np.ndarray	faces,
		np.ndarray	uv_coords,
		Union[str, List[str]]	texture_files,
		Optional[np.ndarray]	material_ids = None )

Add textured triangles from NumPy arrays with support for multiple textures.

   This method supports both single-texture and multi-texture workflows:
   - Single texture: Pass a single texture file string, all faces use the same texture
   - Multiple textures: Pass a list of texture files and material_ids array specifying which texture each face uses

Parameters

vertices	NumPy array of shape (N, 3) containing vertex coordinates as float32/float64
faces	NumPy array of shape (M, 3) containing triangle vertex indices as int32/int64
uv_coords	NumPy array of shape (N, 2) containing UV texture coordinates as float32/float64
texture_files	Single texture file path (str) or list of texture file paths (List[str])
material_ids	Optional NumPy array of shape (M,) containing material ID for each face. If None and texture_files is a list, all faces use texture 0. If None and texture_files is a string, this parameter is ignored.

Returns: List of UUIDs for the added textured triangles

Exceptions

ValueError If array dimensions are invalid or material IDs are out of range

Example

Single texture usage (backward compatible)

>>> uuids = context.addTrianglesFromArraysTextured(vertices, faces, uvs, "texture.png")

Multi-texture usage (Open3D style)

>>> texture_files = ["wood.png", "metal.png", "glass.png"] >>> material_ids = np.array([0, 0, 1, 1, 2, 2]) # 6 faces using different textures >>> uuids = context.addTrianglesFromArraysTextured(vertices, faces, uvs, texture_files, material_ids)

Definition at line 2324 of file Context.py.

◆ addTriangleTextured()

int pyhelios.Context.Context.addTriangleTextured	(		self,
		vec3	vertex0,
		vec3	vertex1,
		vec3	vertex2,
		str	texture_file,
		vec2	uv0,
		vec2	uv1,
		vec2	uv2 )

Add a textured triangle primitive to the context.

   Creates a triangle with texture mapping. The texture image is mapped to the triangle
   surface using UV coordinates, where (0,0) represents the top-left corner of the image
   and (1,1) represents the bottom-right corner.

Parameters

vertex0	First vertex of the triangle
vertex1	Second vertex of the triangle
vertex2	Third vertex of the triangle
texture_file	Path to texture image file (supports PNG, JPG, JPEG, TGA, BMP)
uv0	UV texture coordinates for first vertex
uv1	UV texture coordinates for second vertex
uv2	UV texture coordinates for third vertex

Returns: UUID of the created textured triangle primitive

Exceptions

ValueError	If texture file path is invalid
FileNotFoundError	If texture file doesn't exist
RuntimeError	If context is in mock mode

Example: >>> context = Context() >>> # Create a textured triangle >>> vertex0 = vec3(0, 0, 0) >>> vertex1 = vec3(1, 0, 0) >>> vertex2 = vec3(0.5, 1, 0) >>> uv0 = vec2(0, 0) # Bottom-left of texture >>> uv1 = vec2(1, 0) # Bottom-right of texture >>> uv2 = vec2(0.5, 1) # Top-center of texture >>> uuid = context.addTriangleTextured(vertex0, vertex1, vertex2, ... "texture.png", uv0, uv1, uv2)

Definition at line 399 of file Context.py.

◆ addTube()

List[int] pyhelios.Context.Context.addTube	(		self,
		List[vec3]	nodes,
		Union[float, List[float]]	radii,
		int	ndivs = 6,
		Optional[Union[RGBcolor, List[RGBcolor]]]	colors = None )

Add a tube (pipe/cylinder) to the context.

   The tube is defined by a series of nodes (path) with radius at each node.
   It's tessellated into triangular faces based on the number of radial divisions.

Parameters

nodes	List of 3D points defining the tube path (at least 2 nodes)
radii	Radius at each node. Can be: Single float: constant radius for all nodes List of floats: radius for each node (must match nodes length)
ndivs	Number of radial divisions (default: 6) Higher values create smoother tubes but more triangles
colors	Colors at each node. Can be: None: white tube Single RGBcolor: constant color for all nodes List of RGBcolor: color for each node (must match nodes length)

Returns: List of UUIDs for all triangles created in the tube

Example: >>> context = Context() >>> # Create a curved tube with varying radius >>> nodes = [vec3(0, 0, 0), vec3(1, 0, 0), vec3(2, 1, 0)] >>> radii = [0.1, 0.2, 0.1] >>> colors = [RGBcolor(1, 0, 0), RGBcolor(0, 1, 0), RGBcolor(0, 0, 1)] >>> tube_uuids = context.addTube(nodes, radii, ndivs=8, colors=colors) >>> print(f"Created tube with {len(tube_uuids)} triangles")

Definition at line 772 of file Context.py.

◆ addTubeObject()

int pyhelios.Context.Context.addTubeObject	(		self,
		int	ndivs,
		List[vec3]	nodes,
		List[float]	radii,
		Optional[List[RGBcolor]]	colors = None,
		Optional[str]	texturefile = None,
		Optional[List[float]]	texture_uv = None )

Add a tube as a compound object to the context.

Parameters

ndivs	Number of radial subdivisions
nodes	List of vec3 positions defining tube segments
radii	List of radii at each node
colors	Optional list of RGB colors for each segment
texturefile	Optional texture file path
texture_uv	Optional UV coordinates for texture mapping

Returns: Object ID of the created compound object

Definition at line 1407 of file Context.py.

◆ assignMaterialToObject()

pyhelios.Context.Context.assignMaterialToObject	(		self,
			objID,
		str	material_label )

Assign a material to all primitives in compound object(s).

Parameters

objID	Single object ID (int) or list of object IDs (List[int])
material_label	Label of the material to assign

Exceptions

RuntimeError If object or material doesn't exist

Example: >>> tree_id = wpt.buildTree(WPTType.LEMON) >>> context.assignMaterialToObject(tree_id, "tree_bark") >>> context.assignMaterialToObject([id1, id2], "grass")

Definition at line 3556 of file Context.py.

◆ assignMaterialToPrimitive()

pyhelios.Context.Context.assignMaterialToPrimitive	(		self,
			uuid,
		str	material_label )

Assign a material to primitive(s).

Parameters

uuid	Single UUID (int) or list of UUIDs (List[int])
material_label	Label of the material to assign

Exceptions

RuntimeError If primitive or material doesn't exist

Example: >>> context.assignMaterialToPrimitive(uuid, "wood_oak") >>> context.assignMaterialToPrimitive([uuid1, uuid2, uuid3], "wood_oak")

Definition at line 3535 of file Context.py.

◆ colorPrimitiveByDataPseudocolor()

pyhelios.Context.Context.colorPrimitiveByDataPseudocolor	(		self,
		List[int]	uuids,
		str	primitive_data,
		str	colormap = "hot",
		int	ncolors = 10,
		Optional[float]	max_val = None,
		Optional[float]	min_val = None )

Color primitives based on primitive data values using pseudocolor mapping.

   This method applies a pseudocolor mapping to primitives based on the values
   of specified primitive data. The primitive colors are updated to reflect the
   data values using a color map.

Parameters

uuids	List of primitive UUIDs to color
primitive_data	Name of primitive data to use for coloring (e.g., "radiation_flux_SW")
colormap	Color map name - options include "hot", "cool", "parula", "rainbow", "gray", "lava"
ncolors	Number of discrete colors in color map (default: 10)
max_val	Maximum value for color scale (auto-determined if None)
min_val	Minimum value for color scale (auto-determined if None)

Definition at line 2872 of file Context.py.

◆ copyObject()

Union[int, List[int]] pyhelios.Context.Context.copyObject	(		self,
		Union[int, List[int]]	ObjID )

Copy one or more compound objects.

   Creates a duplicate of the specified compound object(s) with all
   associated primitives and data. The copy is placed at the same location
   as the original.

Parameters

ObjID Single object ID or list of object IDs to copy

Returns: Single object ID of copied object (if ObjID is int) or List of object IDs of copied objects (if ObjID is list)

Example: >>> context = Context() >>> original_obj = context.addTile(center=vec3(0, 0, 0), size=vec2(2, 2)) >>> # Copy single object >>> copied_obj = context.copyObject(original_obj) >>> # Copy multiple objects >>> copied_objs = context.copyObject([obj1, obj2, obj3])

Definition at line 1530 of file Context.py.

◆ copyObjectData()

None pyhelios.Context.Context.copyObjectData	(		self,
		int	source_objID,
		int	destination_objID )

Copy all object data from source to destination compound object.

   Copies all associated data (object data fields) from the source
   compound object to the destination object. Both objects must already exist.

Parameters

source_objID	Object ID of the source compound object
destination_objID	Object ID of the destination compound object

Example: >>> context = Context() >>> source_obj = context.addTile(center=vec3(0, 0, 0), size=vec2(2, 2)) >>> dest_obj = context.addTile(center=vec3(2, 0, 0), size=vec2(2, 2)) >>> context.setObjectData(source_obj, "material", "wood") >>> context.copyObjectData(source_obj, dest_obj) >>> # dest_obj now has material data

Definition at line 1558 of file Context.py.

◆ copyPrimitive()

Union[int, List[int]] pyhelios.Context.Context.copyPrimitive	(		self,
		Union[int, List[int]]	UUID )

Copy one or more primitives.

   Creates a duplicate of the specified primitive(s) with all associated data.
   The copy is placed at the same location as the original.

Parameters

UUID	Single primitive UUID or list of UUIDs to copy

Returns: Single UUID of copied primitive (if UUID is int) or List of UUIDs of copied primitives (if UUID is list)

Example: >>> context = Context() >>> original_uuid = context.addPatch(center=vec3(0, 0, 0), size=vec2(1, 1)) >>> # Copy single primitive >>> copied_uuid = context.copyPrimitive(original_uuid) >>> # Copy multiple primitives >>> copied_uuids = context.copyPrimitive([uuid1, uuid2, uuid3])

Definition at line 1470 of file Context.py.

◆ copyPrimitiveData()

None pyhelios.Context.Context.copyPrimitiveData	(		self,
		int	sourceUUID,
		int	destinationUUID )

Copy all primitive data from source to destination primitive.

   Copies all associated data (primitive data fields) from the source
   primitive to the destination primitive. Both primitives must already exist.

Parameters

sourceUUID	UUID of the source primitive
destinationUUID	UUID of the destination primitive

Example: >>> context = Context() >>> source_uuid = context.addPatch(center=vec3(0, 0, 0), size=vec2(1, 1)) >>> dest_uuid = context.addPatch(center=vec3(1, 0, 0), size=vec2(1, 1)) >>> context.setPrimitiveData(source_uuid, "temperature", 25.5) >>> context.copyPrimitiveData(source_uuid, dest_uuid) >>> # dest_uuid now has temperature data

Definition at line 1498 of file Context.py.

◆ deleteMaterial()

pyhelios.Context.Context.deleteMaterial	(		self,
		str	material_label )

Delete a material from the context.

   Primitives using this material will be reassigned to the default material.

Parameters

material_label Label of the material to delete

Exceptions

RuntimeError If material doesn't exist

Definition at line 3429 of file Context.py.

◆ deleteObject()

None pyhelios.Context.Context.deleteObject	(		self,
		Union[int, List[int]]	objIDs_or_objID )

Delete one or more compound objects from the context.

   This removes the compound object(s) AND all their child primitives.
   Use this when you want to delete an entire object hierarchy at once.

Parameters

objIDs_or_objID Single object ID (int) or list of object IDs to delete

Exceptions

RuntimeError	If any object ID doesn't exist in the context
ValueError	If object ID is invalid (negative)
NotImplementedError	If delete functions not available in current library build

Example: >>> context = Context() >>> # Create a compound object (e.g., a tile with multiple patches) >>> patch_ids = context.addTile(center=vec3(0, 0, 0), size=vec2(2, 2), ... tile_divisions=int2(2, 2)) >>> obj_id = context.getPrimitiveParentObjectID(patch_ids[0]) >>> context.deleteObject(obj_id) # Deletes tile and all its patches

Definition at line 3326 of file Context.py.

◆ deletePrimitive()

None pyhelios.Context.Context.deletePrimitive	(		self,
		Union[int, List[int]]	uuids_or_uuid )

Delete one or more primitives from the context.

   This removes the primitive(s) entirely from the context. If a primitive
   belongs to a compound object, it will be removed from that object. If the
   object becomes empty after removal, it is automatically deleted.

Parameters

uuids_or_uuid Single UUID (int) or list of UUIDs to delete

Exceptions

RuntimeError	If any UUID doesn't exist in the context
ValueError	If UUID is invalid (negative)
NotImplementedError	If delete functions not available in current library build

Example: >>> context = Context() >>> patch_id = context.addPatch(center=vec3(0, 0, 0), size=vec2(1, 1)) >>> context.deletePrimitive(patch_id) # Single deletion >>> >>> # Multiple deletion >>> ids = [context.addPatch() for _ in range(5)] >>> context.deletePrimitive(ids) # Delete all at once

Definition at line 3291 of file Context.py.

◆ doesMaterialExist()

bool pyhelios.Context.Context.doesMaterialExist	(		self,
		str	material_label )

Check if a material with the given label exists.

Definition at line 3411 of file Context.py.

◆ doesPrimitiveDataExist()

bool pyhelios.Context.Context.doesPrimitiveDataExist	(		self,
		int	uuid,
		str	label )

Check if primitive data exists for a specific primitive and label.

Parameters

uuid	UUID of the primitive
label	String key for the data

Returns: True if the data exists, False otherwise

Definition at line 2702 of file Context.py.

◆ doesTimeseriesVariableExist()

bool pyhelios.Context.Context.doesTimeseriesVariableExist	(		self,
		str	label )

Check whether a timeseries variable exists.

Parameters

label Name of the timeseries variable

Returns: True if the variable exists, False otherwise

Exceptions

ValueError	If label is empty
NotImplementedError	If timeseries functions not available

Example: >>> if context.doesTimeseriesVariableExist("temperature"): ... print("Temperature data loaded")

Definition at line 3186 of file Context.py.

◆ get_available_plugins()

List[str] pyhelios.Context.Context.get_available_plugins ( self )

Get list of available plugins for this PyHelios instance.

Returns: List of available plugin names

Definition at line 3346 of file Context.py.

◆ get_missing_plugins()

List[str] pyhelios.Context.Context.get_missing_plugins	(		self,
		List[str]	requested_plugins )

Get list of requested plugins that are not available.

Parameters

requested_plugins List of plugin names to check

Returns: List of missing plugin names

Definition at line 3383 of file Context.py.

◆ get_plugin_capabilities()

dict pyhelios.Context.Context.get_plugin_capabilities ( self )

Get detailed information about available plugin capabilities.

Returns: Dictionary mapping plugin names to capability information

Definition at line 3367 of file Context.py.

◆ getAllObjectIDs()

List[int] pyhelios.Context.Context.getAllObjectIDs ( self )

Definition at line 545 of file Context.py.

◆ getAllPrimitiveAreas()

'np.ndarray' pyhelios.Context.Context.getAllPrimitiveAreas ( self )

Get areas for all primitives.

Returns ndarray of shape (N,).

Definition at line 3758 of file Context.py.

◆ getAllPrimitiveColors()

'np.ndarray' pyhelios.Context.Context.getAllPrimitiveColors ( self )

Get colors for all primitives.

Returns ndarray of shape (N, 3).

Definition at line 3754 of file Context.py.

◆ getAllPrimitiveInfo()

List[PrimitiveInfo] pyhelios.Context.Context.getAllPrimitiveInfo ( self )

Get physical properties and geometry information for all primitives in the context.

Returns: List of PrimitiveInfo objects for all primitives

Definition at line 599 of file Context.py.

◆ getAllPrimitiveMaterialLabels()

List[str] pyhelios.Context.Context.getAllPrimitiveMaterialLabels ( self )

Get material labels for all primitives.

Returns list of strings.

Definition at line 3778 of file Context.py.

◆ getAllPrimitiveNormals()

'np.ndarray' pyhelios.Context.Context.getAllPrimitiveNormals ( self )

Get normals for all primitives.

Returns ndarray of shape (N, 3).

Definition at line 3750 of file Context.py.

◆ getAllPrimitiveSolidFractions()

'np.ndarray' pyhelios.Context.Context.getAllPrimitiveSolidFractions ( self )

Get solid fractions for all primitives.

Returns ndarray of shape (N,).

Definition at line 3766 of file Context.py.

◆ getAllPrimitiveTextureFiles()

List[str] pyhelios.Context.Context.getAllPrimitiveTextureFiles ( self )

Get texture files for all primitives.

Returns list of strings.

Definition at line 3774 of file Context.py.

◆ getAllPrimitiveTypes()

'np.ndarray' pyhelios.Context.Context.getAllPrimitiveTypes ( self )

Get types for all primitives.

Returns ndarray of shape (N,) uint32.

Definition at line 3762 of file Context.py.

◆ getAllPrimitiveVertices()

pyhelios.Context.Context.getAllPrimitiveVertices ( self )

Get vertices for all primitives.

Returns (flat_data, offsets) tuple.

Definition at line 3770 of file Context.py.

◆ getAllUUIDs()

List[int] pyhelios.Context.Context.getAllUUIDs ( self )

Definition at line 535 of file Context.py.

◆ getDate()

pyhelios.Context.Context.getDate ( self )

Get the current simulation date.

Returns: Tuple of (year, month, day) as integers

Exceptions

NotImplementedError If time/date functions not available in current library build

Example: >>> year, month, day = context.getDate() >>> print(f"Current date: {year}-{month:02d}-{day:02d}")

Definition at line 2966 of file Context.py.

◆ getMaterialColor()

pyhelios.Context.Context.getMaterialColor	(		self,
		str	material_label )

Get the RGBA color of a material.

Parameters

material_label Label of the material

Returns: RGBAcolor object

Exceptions

RuntimeError If material doesn't exist

Definition at line 3444 of file Context.py.

◆ getMaterialTexture()

str pyhelios.Context.Context.getMaterialTexture	(		self,
		str	material_label )

Get the texture file path for a material.

Parameters

material_label Label of the material

Returns: Texture file path, or empty string if no texture

Exceptions

RuntimeError If material doesn't exist

Definition at line 3487 of file Context.py.

◆ getMaterialTwosidedFlag()

int pyhelios.Context.Context.getMaterialTwosidedFlag	(		self,
		str	material_label )

Get the two-sided rendering flag for a material (0 = one-sided, 1 = two-sided).

Definition at line 3514 of file Context.py.

◆ getNativePtr()

pyhelios.Context.Context.getNativePtr ( self )

Definition at line 305 of file Context.py.

◆ getObjectCount()

int pyhelios.Context.Context.getObjectCount ( self )

Definition at line 541 of file Context.py.

◆ getPrimitiveArea()

pyhelios.Context.Context.getPrimitiveArea	(		self,
			uuid )

Get the area of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: float for single UUID, or np.ndarray of shape (N,) for list

Definition at line 451 of file Context.py.

◆ getPrimitiveColor()

pyhelios.Context.Context.getPrimitiveColor	(		self,
			uuid )

Get the color of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: RGBcolor for single UUID, or np.ndarray of shape (N, 3) for list

Definition at line 519 of file Context.py.

◆ getPrimitiveCount()

int pyhelios.Context.Context.getPrimitiveCount ( self )

Definition at line 531 of file Context.py.

◆ getPrimitiveData()

pyhelios.Context.Context.getPrimitiveData	(		self,
		int	uuid,
		str	label,
		type	data_type = None )

Get primitive data for a specific primitive.

If data_type is provided, it works like before. If data_type is None, it automatically detects the type and returns the appropriate value.

Parameters

uuid	UUID of the primitive
label	String key for the data
data_type	Optional. Python type to retrieve (int, uint, float, double, bool, str, vec2, vec3, vec4, int2, int3, int4, etc.) If None, auto-detects the type using C++ getPrimitiveDataType().

Returns: The stored value of the specified or auto-detected type

Definition at line 2629 of file Context.py.

◆ getPrimitiveDataArray()

np.ndarray pyhelios.Context.Context.getPrimitiveDataArray	(		self,
		List[int]	uuids,
		str	label )

Get primitive data values for multiple primitives as a NumPy array.

   This method retrieves primitive data for a list of UUIDs and returns the values
   as a NumPy array. The output array has the same length as the input UUID list,
   with each index corresponding to the primitive data value for that UUID.

Parameters

uuids	List of primitive UUIDs to get data for
label	String key for the primitive data to retrieve

Returns

NumPy array of primitive data values corresponding to each UUID. The array type depends on the data type:

int data: int32 array
uint data: uint32 array
float data: float32 array
double data: float64 array
vector data: float32 array with shape (N, vector_size)
string data: object array of strings

Exceptions

ValueError	If UUID list is empty or UUIDs don't exist
RuntimeError	If context is in mock mode or data doesn't exist for some UUIDs

Definition at line 2769 of file Context.py.

◆ getPrimitiveDataFloat()

float pyhelios.Context.Context.getPrimitiveDataFloat	(		self,
		int	uuid,
		str	label )

Convenience method to get float primitive data.

Parameters

uuid	UUID of the primitive
label	String key for the data

Returns: Float value stored for the primitive

Definition at line 2715 of file Context.py.

◆ getPrimitiveDataSize()

int pyhelios.Context.Context.getPrimitiveDataSize	(		self,
		int	uuid,
		str	label )

Get the size/length of primitive data (for vector data).

Parameters

uuid	UUID of the primitive
label	String key for the data

Returns: Size of data array, or 1 for scalar data

Definition at line 2741 of file Context.py.

◆ getPrimitiveDataType()

int pyhelios.Context.Context.getPrimitiveDataType	(		self,
		int	uuid,
		str	label )

Get the Helios data type of primitive data.

Parameters

uuid	UUID of the primitive
label	String key for the data

Returns: HeliosDataType enum value as integer

Definition at line 2728 of file Context.py.

◆ getPrimitiveInfo()

PrimitiveInfo pyhelios.Context.Context.getPrimitiveInfo	(		self,
		int	uuid )

Get physical properties and geometry information for a single primitive.

Parameters

uuid	UUID of the primitive

Returns: PrimitiveInfo object containing physical properties and geometry

Definition at line 560 of file Context.py.

◆ getPrimitiveMaterialLabel()

pyhelios.Context.Context.getPrimitiveMaterialLabel	(		self,
			uuid )

Get the material label assigned to a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: str for single UUID, or List[str] for list

Exceptions

RuntimeError If primitive doesn't exist

Definition at line 3573 of file Context.py.

◆ getPrimitiveNormal()

pyhelios.Context.Context.getPrimitiveNormal	(		self,
			uuid )

Get the normal vector of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: vec3 for single UUID, or np.ndarray of shape (N, 3) for list

Definition at line 470 of file Context.py.

◆ getPrimitivesInfoForObject()

List[PrimitiveInfo] pyhelios.Context.Context.getPrimitivesInfoForObject	(		self,
		int	object_id )

Get physical properties and geometry information for all primitives belonging to a specific object.

Parameters

object_id ID of the object

Returns: List of PrimitiveInfo objects for primitives in the object

Definition at line 612 of file Context.py.

◆ getPrimitiveSolidFraction()

pyhelios.Context.Context.getPrimitiveSolidFraction	(		self,
			uuid )

Get the solid fraction of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: float for single UUID, or np.ndarray of shape (N,) for list

Definition at line 3704 of file Context.py.

◆ getPrimitivesUsingMaterial()

List[int] pyhelios.Context.Context.getPrimitivesUsingMaterial	(		self,
		str	material_label )

Get all primitive UUIDs that use a specific material.

Parameters

material_label Label of the material

Returns: List of primitive UUIDs using the material

Exceptions

RuntimeError If material doesn't exist

Definition at line 3612 of file Context.py.

◆ getPrimitiveTextureFile()

pyhelios.Context.Context.getPrimitiveTextureFile	(		self,
			uuid )

Get the texture file path of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: str for single UUID, or List[str] for list

Definition at line 3627 of file Context.py.

◆ getPrimitiveTextureSize()

int2 pyhelios.Context.Context.getPrimitiveTextureSize	(		self,
		int	uuid )

Get the texture size (width, height) of a primitive.

Parameters

uuid	UUID of the primitive

Returns: int2 with width and height of the texture

Definition at line 3657 of file Context.py.

◆ getPrimitiveTextureUV()

pyhelios.Context.Context.getPrimitiveTextureUV	(		self,
			uuid )

Get the texture UV coordinates of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: List[vec2] for single UUID, or tuple of (flat_data, offsets) for list

Definition at line 3670 of file Context.py.

◆ getPrimitiveTwosidedFlag()

int pyhelios.Context.Context.getPrimitiveTwosidedFlag	(		self,
		int	uuid,
		int	default_value = 1 )

Get two-sided rendering flag for a primitive.

   Checks material first, then primitive data if no material assigned.

Parameters

uuid	UUID of the primitive
default_value	Default value if no material/data (default 1 = two-sided)

Returns: Two-sided flag (0 = one-sided, 1 = two-sided)

Definition at line 3597 of file Context.py.

◆ getPrimitiveType()

pyhelios.Context.Context.getPrimitiveType	(		self,
			uuid )

Get the type of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: PrimitiveType for single UUID, or np.ndarray of shape (N,) uint32 for list

Definition at line 431 of file Context.py.

◆ getPrimitiveVertices()

pyhelios.Context.Context.getPrimitiveVertices	(		self,
			uuid )

Get vertices of a primitive or multiple primitives.

Parameters

uuid	Single UUID (int) or list of UUIDs

Returns: List[vec3] for single UUID, or tuple of (flat_data, offsets) for list where flat_data is a float32 ndarray and offsets is a uint32 ndarray of length N+1. Vertices for primitive i are at flat_data[offsets[i]:offsets[i+1]].

Definition at line 493 of file Context.py.

◆ getTime()

pyhelios.Context.Context.getTime ( self )

Get the current simulation time.

Returns: Tuple of (hour, minute, second) as integers

Exceptions

NotImplementedError If time/date functions not available in current library build

Example: >>> hour, minute, second = context.getTime() >>> print(f"Current time: {hour:02d}:{minute:02d}:{second:02d}")

Definition at line 2950 of file Context.py.

◆ getTimeseriesLength()

int pyhelios.Context.Context.getTimeseriesLength	(		self,
		str	label )

Get the number of data points in a timeseries variable.

Parameters

label Name of the timeseries variable

Returns: Number of data points

Exceptions

ValueError	If label is empty
NotImplementedError	If timeseries functions not available

Example: >>> n = context.getTimeseriesLength("temperature") >>> print(f"Timeseries has {n} data points")

Definition at line 3162 of file Context.py.

◆ is_plugin_available()

bool pyhelios.Context.Context.is_plugin_available	(		self,
		str	plugin_name )

Check if a specific plugin is available.

Parameters

plugin_name Name of the plugin to check

Returns: True if plugin is available, False otherwise

Definition at line 3358 of file Context.py.

◆ isGeometryDirty()

bool pyhelios.Context.Context.isGeometryDirty ( self )

Definition at line 318 of file Context.py.

◆ isMaterialTextureColorOverridden()

bool pyhelios.Context.Context.isMaterialTextureColorOverridden	(		self,
		str	material_label )

Check if material texture color is overridden by material color.

Definition at line 3506 of file Context.py.

◆ isPrimitiveTextureColorOverridden()

bool pyhelios.Context.Context.isPrimitiveTextureColorOverridden	(		self,
		int	uuid )

Check if primitive texture color is overridden.

Parameters

uuid	UUID of the primitive

Returns: True if texture color is overridden with constant RGB

Definition at line 3741 of file Context.py.

◆ listMaterials()

List[str] pyhelios.Context.Context.listMaterials ( self )

Get list of all material labels in the context.

Definition at line 3415 of file Context.py.

◆ listTimeseriesVariables()

List[str] pyhelios.Context.Context.listTimeseriesVariables ( self )

List all existing timeseries variables.

Returns: List of timeseries variable names

Exceptions

NotImplementedError If timeseries functions not available

Example: >>> variables = context.listTimeseriesVariables() >>> for var in variables: ... print(f" {var}: {context.getTimeseriesLength(var)} points")

Definition at line 3207 of file Context.py.

◆ loadOBJ()

List[int] pyhelios.Context.Context.loadOBJ	(		self,
		str	filename,
		Optional[vec3]	origin = None,
		Optional[float]	height = None,
		Optional[vec3]	scale = None,
		Optional[SphericalCoord]	rotation = None,
		Optional[RGBcolor]	color = None,
		str	upaxis = "YUP",
		bool	silent = False )

Load geometry from an OBJ (Wavefront) file.

Parameters

filename	Path to the OBJ file to load
origin	Origin point for positioning the geometry (optional)
height	Height scaling factor (optional, alternative to scale)
scale	Scale factor for all dimensions (optional, alternative to height)
rotation	Rotation to apply to the geometry (optional)
color	Default color for geometry without color data (optional)
upaxis	Up axis orientation ("YUP" or "ZUP")
silent	If True, suppress loading output messages

Returns: List of UUIDs for the loaded primitives

Definition at line 2008 of file Context.py.

◆ loadPLY()

List[int] pyhelios.Context.Context.loadPLY	(		self,
		str	filename,
		Optional[vec3]	origin = None,
		Optional[float]	height = None,
		Optional[SphericalCoord]	rotation = None,
		Optional[RGBcolor]	color = None,
		str	upaxis = "YUP",
		bool	silent = False )

Load geometry from a PLY (Stanford Polygon) file.

Parameters

filename	Path to the PLY file to load
origin	Origin point for positioning the geometry (optional)
height	Height scaling factor (optional)
rotation	Rotation to apply to the geometry (optional)
color	Default color for geometry without color data (optional)
upaxis	Up axis orientation ("YUP" or "ZUP")
silent	If True, suppress loading output messages

Returns: List of UUIDs for the loaded primitives

Definition at line 1951 of file Context.py.

◆ loadTabularTimeseriesData()

pyhelios.Context.Context.loadTabularTimeseriesData	(		self,
		str	data_file,
		List[str]	column_labels,
		str	delimiter = ",",
		str	date_string_format = "YYYYMMDD",
		int	headerlines = 0 )

Load tabular timeseries data from a text file.

   The file should contain columns of data with dates/times and measured values.
   Column labels specify how each column should be interpreted. Special labels
   include "year", "DOY", "date", "datetime", "hour", "minute", "second", "time".
   Other labels become timeseries variable names.

Parameters

data_file	Path to the text file containing tabular data
column_labels	List of column label strings specifying what each column contains
delimiter	Column delimiter string (default: ",")
date_string_format	Format of date strings in the file. Supported formats: "YYYYMMDD", "YYYYMMDDHH", "YYYYMMDDHHMM", "DD/MM/YYYY", "MM/DD/YYYY", "DDMMYYYY", "YYYY-MM-DD", "DD/MM/YYYY HH:MM", "MM/DD/YYYY HH:MM", "ISO8601" (default: "YYYYMMDD")
headerlines	Number of header lines to skip (default: 0)

Exceptions

ValueError	If data_file is empty, column_labels is empty, or delimiter is empty
RuntimeError	If the file cannot be read or parsed
NotImplementedError	If timeseries functions not available

Example: >>> context.loadTabularTimeseriesData( ... "weather_data.csv", ... column_labels=["date", "hour", "temperature", "humidity"], ... delimiter=",", ... headerlines=1 ... ) >>> temp = context.queryTimeseriesData("temperature", index=0)

Definition at line 3244 of file Context.py.

◆ loadXML()

List[int] pyhelios.Context.Context.loadXML	(		self,
		str	filename,
		bool	quiet = False )

Load geometry from a Helios XML file.

Parameters

filename	Path to the XML file to load
quiet	If True, suppress loading output messages

Returns: List of UUIDs for the loaded primitives

Definition at line 2059 of file Context.py.

◆ markGeometryClean()

pyhelios.Context.Context.markGeometryClean ( self )

Definition at line 309 of file Context.py.

◆ markGeometryDirty()

pyhelios.Context.Context.markGeometryDirty ( self )

Definition at line 313 of file Context.py.

◆ overridePrimitiveTextureColor()

None pyhelios.Context.Context.overridePrimitiveTextureColor	(		self,
		int	uuid )

Override texture color with constant RGB color for a primitive.

Parameters

uuid	UUID of the primitive

Definition at line 3720 of file Context.py.

◆ primitiveTextureHasTransparencyChannel()

bool pyhelios.Context.Context.primitiveTextureHasTransparencyChannel	(		self,
		int	uuid )

Check if primitive texture has a transparency channel.

Parameters

uuid	UUID of the primitive

Returns: True if texture has transparency channel

Definition at line 3692 of file Context.py.

◆ print_plugin_status()

pyhelios.Context.Context.print_plugin_status ( self )

Print detailed plugin status information.

Definition at line 3371 of file Context.py.

◆ queryTimeseriesData()

float pyhelios.Context.Context.queryTimeseriesData	(		self,
		str	label,
		'Date'	date = None,
		'Time'	time = None,
		int	index = None )

Query a timeseries data value.

   Three modes of operation:
   - With date and time: returns interpolated value at the specified date/time
   - With index: returns value at the specified data point index
   - With neither: returns value at the current Context date/time

Parameters

label Name of the timeseries variable

Date: Date to query at (requires time as well)

Parameters

time	Time to query at (requires date as well)
index	Index of the data point (0 = earliest)

Returns: The timeseries value as a float

Exceptions

ValueError	If both date/time and index are provided, or if date without time
NotImplementedError	If timeseries functions not available

Example: >>> # Query at specific date/time >>> val = context.queryTimeseriesData("temperature", date=Date(2024, 6, 15), time=Time(12, 0, 0)) >>> # Query by index >>> val = context.queryTimeseriesData("temperature", index=0) >>> # Query at current context time >>> val = context.queryTimeseriesData("temperature")

Definition at line 3057 of file Context.py.

◆ queryTimeseriesDate()

'Date' pyhelios.Context.Context.queryTimeseriesDate	(		self,
		str	label,
		int	index )

Get the Date associated with a timeseries data point.

Parameters

label	Name of the timeseries variable
index	Index of the data point (0 = earliest)

Returns: Date object for the data point

Exceptions

ValueError	If label is empty or index is negative
NotImplementedError	If timeseries functions not available

Example: >>> d = context.queryTimeseriesDate("temperature", 0) >>> print(f"{d.year}-{d.month:02d}-{d.day:02d}")

Definition at line 3135 of file Context.py.

◆ queryTimeseriesTime()

'Time' pyhelios.Context.Context.queryTimeseriesTime	(		self,
		str	label,
		int	index )

Get the Time associated with a timeseries data point.

Parameters

label	Name of the timeseries variable
index	Index of the data point (0 = earliest)

Returns: Time object for the data point

Exceptions

ValueError	If label is empty or index is negative
NotImplementedError	If timeseries functions not available

Example: >>> t = context.queryTimeseriesTime("temperature", 0) >>> print(f"{t.hour:02d}:{t.minute:02d}:{t.second:02d}")

Definition at line 3107 of file Context.py.

◆ rotateObject()

None pyhelios.Context.Context.rotateObject	(		self,
		Union[int, List[int]]	ObjID,
		float	angle,
		Union[str, vec3]	axis,
		Optional[vec3]	origin = None,
		bool	about_origin = False )

Rotate one or more objects.

Parameters

ObjID	Single object ID or list of object IDs to rotate
angle	Rotation angle in radians
axis	Rotation axis - either 'x', 'y', 'z' or a vec3 direction vector
origin	Optional rotation origin point. If None, rotates about object center. If provided with string axis, raises ValueError.
about_origin	If True, rotate about global origin (0,0,0). Cannot be used with origin parameter.

Exceptions

ValueError If axis is invalid or if origin and about_origin are both specified

Definition at line 1709 of file Context.py.

◆ rotatePrimitive()

None pyhelios.Context.Context.rotatePrimitive	(		self,
		Union[int, List[int]]	UUID,
		float	angle,
		Union[str, vec3]	axis,
		Optional[vec3]	origin = None )

Rotate one or more primitives.

Parameters

UUID	Single UUID or list of UUIDs to rotate
angle	Rotation angle in radians
axis	Rotation axis - either 'x', 'y', 'z' or a vec3 direction vector
origin	Optional rotation origin point. If None, rotates about primitive center. If provided with string axis, raises ValueError.

Exceptions

ValueError If axis is invalid or if origin is provided with string axis

Definition at line 1646 of file Context.py.

◆ scaleConeObjectGirth()

None pyhelios.Context.Context.scaleConeObjectGirth	(		self,
		int	ObjID,
		float	scale_factor )

Scale the girth of a Cone object by scaling the radii at both nodes.

Parameters

ObjID	Object ID of the Cone to scale
scale_factor	Factor by which to scale the cone girth (e.g., 2.0 doubles girth)

Exceptions

ValueError	If ObjID is not an integer or scale_factor is invalid
HeliosRuntimeError	If operation fails (e.g., ObjID is not a Cone object)

Note: Added in helios-core v1.3.59 as a replacement for the removed getConeObjectPointer() method, enforcing better encapsulation.

Example: >>> cone_id = context.addConeObject(10, [0,0,0], [0,0,1], 0.1, 0.05) >>> context.scaleConeObjectGirth(cone_id, 2.0) # Double the cone girth

Definition at line 1926 of file Context.py.

◆ scaleConeObjectLength()

None pyhelios.Context.Context.scaleConeObjectLength	(		self,
		int	ObjID,
		float	scale_factor )

Scale the length of a Cone object by scaling the distance between its two nodes.

Parameters

ObjID	Object ID of the Cone to scale
scale_factor	Factor by which to scale the cone length (e.g., 2.0 doubles length)

Exceptions

ValueError	If ObjID is not an integer or scale_factor is invalid
HeliosRuntimeError	If operation fails (e.g., ObjID is not a Cone object)

Note: Added in helios-core v1.3.59 as a replacement for the removed getConeObjectPointer() method, enforcing better encapsulation.

Example: >>> cone_id = context.addConeObject(10, [0,0,0], [0,0,1], 0.1, 0.05) >>> context.scaleConeObjectLength(cone_id, 1.5) # Make cone 50% longer

Definition at line 1897 of file Context.py.

◆ scaleObject()

None pyhelios.Context.Context.scaleObject	(		self,
		Union[int, List[int]]	ObjID,
		vec3	scale,
		Optional[vec3]	point = None,
		bool	about_center = False,
		bool	about_origin = False )

Scale one or more objects.

Parameters

ObjID	Single object ID or list of object IDs to scale
scale	Scale factors as vec3(x, y, z)
point	Optional point to scale about
about_center	If True, scale about object center (default behavior)
about_origin	If True, scale about global origin (0,0,0)

Exceptions

ValueError If parameters are invalid or conflicting options specified

Definition at line 1826 of file Context.py.

◆ scalePrimitive()

None pyhelios.Context.Context.scalePrimitive	(		self,
		Union[int, List[int]]	UUID,
		vec3	scale,
		Optional[vec3]	point = None )

Scale one or more primitives.

Parameters

UUID	Single UUID or list of UUIDs to scale
scale	Scale factors as vec3(x, y, z)
point	Optional point to scale about. If None, scales about primitive center.

Exceptions

ValueError If scale or point parameters are invalid

Definition at line 1784 of file Context.py.

◆ seedRandomGenerator()

pyhelios.Context.Context.seedRandomGenerator	(		self,
		int	seed )

Seed the random number generator for reproducible stochastic results.

Parameters

seed	Integer seed value for random number generation

Note: This is critical for reproducible results in stochastic simulations (e.g., LiDAR scans with beam divergence, random perturbations).

Definition at line 332 of file Context.py.

◆ setCurrentTimeseriesPoint()

pyhelios.Context.Context.setCurrentTimeseriesPoint	(		self,
		str	label,
		int	index )

Set the Context date and time from a timeseries data point index.

Parameters

label	Name of the timeseries variable
index	Index of the data point (0 = earliest, chronologically ordered)

Exceptions

ValueError	If label is empty or index is negative
NotImplementedError	If timeseries functions not available

Example: >>> context.setCurrentTimeseriesPoint("temperature", 0)

Definition at line 3019 of file Context.py.

◆ setDate()

pyhelios.Context.Context.setDate	(		self,
		int	year,
		int	month,
		int	day )

Set the simulation date.

Parameters

year	Year (1900-3000)
month	Month (1-12)
day	Day (1-31)

Exceptions

ValueError	If date values are out of range
NotImplementedError	If time/date functions not available in current library build

Example: >>> context.setDate(2023, 6, 21) # Set to June 21, 2023

Definition at line 2917 of file Context.py.

◆ setDateJulian()

pyhelios.Context.Context.setDateJulian	(		self,
		int	julian_day,
		int	year )

Set the simulation date using Julian day number.

Parameters

julian_day	Julian day (1-366)
year	Year (1900-3000)

Exceptions

ValueError	If values are out of range
NotImplementedError	If time/date functions not available in current library build

Example: >>> context.setDateJulian(172, 2023) # Set to day 172 of 2023 (June 21)

Definition at line 2934 of file Context.py.

◆ setMaterialColor()

pyhelios.Context.Context.setMaterialColor	(		self,
		str	material_label,
			color )

Set the RGBA color of a material.

   This affects all primitives that reference this material.

Parameters

material_label	Label of the material
color	RGBAcolor object or tuple/list of (r, g, b, a) values

Exceptions

RuntimeError If material doesn't exist

Example: >>> from pyhelios.types import RGBAcolor >>> context.setMaterialColor("wood", RGBAcolor(0.6, 0.4, 0.2, 1.0)) >>> context.setMaterialColor("wood", (0.6, 0.4, 0.2, 1.0))

Definition at line 3466 of file Context.py.

◆ setMaterialTexture()

pyhelios.Context.Context.setMaterialTexture	(		self,
		str	material_label,
		str	texture_file )

Set the texture file for a material.

   This affects all primitives that reference this material.

Parameters

material_label	Label of the material
texture_file	Path to texture image file

Exceptions

RuntimeError If material doesn't exist or texture file not found

Definition at line 3502 of file Context.py.

◆ setMaterialTextureColorOverride()

pyhelios.Context.Context.setMaterialTextureColorOverride	(		self,
		str	material_label,
		bool	override )

Set whether material color overrides texture color.

Definition at line 3510 of file Context.py.

◆ setMaterialTwosidedFlag()

pyhelios.Context.Context.setMaterialTwosidedFlag	(		self,
		str	material_label,
		int	twosided_flag )

Set the two-sided rendering flag for a material (0 = one-sided, 1 = two-sided).

Definition at line 3518 of file Context.py.

◆ setPrimitiveDataDouble()

None pyhelios.Context.Context.setPrimitiveDataDouble	(		self,
			uuids_or_uuid,
		str	label,
		float	value )

Set primitive data as 64-bit double for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
value	Double value (broadcast to all UUIDs if list provided)

Definition at line 2476 of file Context.py.

◆ setPrimitiveDataFloat()

None pyhelios.Context.Context.setPrimitiveDataFloat	(		self,
			uuids_or_uuid,
		str	label,
		float	value )

Set primitive data as 32-bit float for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
value	Float value (broadcast to all UUIDs if list provided)

Definition at line 2462 of file Context.py.

◆ setPrimitiveDataInt()

None pyhelios.Context.Context.setPrimitiveDataInt	(		self,
			uuids_or_uuid,
		str	label,
		int	value )

Set primitive data as signed 32-bit integer for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
value	Signed integer value (broadcast to all UUIDs if list provided)

Definition at line 2432 of file Context.py.

◆ setPrimitiveDataInt2()

None pyhelios.Context.Context.setPrimitiveDataInt2	(		self,
			uuids_or_uuid,
		str	label,
			x_or_vec,
		int	y = None )

Set primitive data as int2 for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
x_or_vec	Either x component (int) or int2 object
y	Y component (if x_or_vec is int)

Definition at line 2565 of file Context.py.

◆ setPrimitiveDataInt3()

None pyhelios.Context.Context.setPrimitiveDataInt3	(		self,
			uuids_or_uuid,
		str	label,
			x_or_vec,
		int	y = None,
		int	z = None )

Set primitive data as int3 for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
x_or_vec	Either x component (int) or int3 object
y	Y component (if x_or_vec is int)
z	Z component (if x_or_vec is int)

Definition at line 2585 of file Context.py.

◆ setPrimitiveDataInt4()

None pyhelios.Context.Context.setPrimitiveDataInt4	(		self,
			uuids_or_uuid,
		str	label,
			x_or_vec,
		int	y = None,
		int	z = None,
		int	w = None )

Set primitive data as int4 for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
x_or_vec	Either x component (int) or int4 object
y	Y component (if x_or_vec is int)
z	Z component (if x_or_vec is int)
w	W component (if x_or_vec is int)

Definition at line 2606 of file Context.py.

◆ setPrimitiveDataString()

None pyhelios.Context.Context.setPrimitiveDataString	(		self,
			uuids_or_uuid,
		str	label,
		str	value )

Set primitive data as string for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
value	String value (broadcast to all UUIDs if list provided)

Definition at line 2490 of file Context.py.

◆ setPrimitiveDataUInt()

None pyhelios.Context.Context.setPrimitiveDataUInt	(		self,
			uuids_or_uuid,
		str	label,
		int	value )

Set primitive data as unsigned 32-bit integer for one or multiple primitives.

   Critical for properties like 'twosided_flag' which must be uint in C++.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
value	Unsigned integer value (broadcast to all UUIDs if list provided)

Definition at line 2448 of file Context.py.

◆ setPrimitiveDataVec2()

None pyhelios.Context.Context.setPrimitiveDataVec2	(		self,
			uuids_or_uuid,
		str	label,
			x_or_vec,
		float	y = None )

Set primitive data as vec2 for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
x_or_vec	Either x component (float) or vec2 object
y	Y component (if x_or_vec is float)

Definition at line 2505 of file Context.py.

◆ setPrimitiveDataVec3()

None pyhelios.Context.Context.setPrimitiveDataVec3	(		self,
			uuids_or_uuid,
		str	label,
			x_or_vec,
		float	y = None,
		float	z = None )

Set primitive data as vec3 for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
x_or_vec	Either x component (float) or vec3 object
y	Y component (if x_or_vec is float)
z	Z component (if x_or_vec is float)

Definition at line 2525 of file Context.py.

◆ setPrimitiveDataVec4()

None pyhelios.Context.Context.setPrimitiveDataVec4	(		self,
			uuids_or_uuid,
		str	label,
			x_or_vec,
		float	y = None,
		float	z = None,
		float	w = None )

Set primitive data as vec4 for one or multiple primitives.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
x_or_vec	Either x component (float) or vec4 object
y	Y component (if x_or_vec is float)
z	Z component (if x_or_vec is float)
w	W component (if x_or_vec is float)

Definition at line 2546 of file Context.py.

◆ setPrimitiveTextureFile()

None pyhelios.Context.Context.setPrimitiveTextureFile	(		self,
		int	uuid,
		str	texture_file )

Set the texture file path of a primitive.

Parameters

uuid	UUID of the primitive
texture_file	Path to the texture file

Definition at line 3645 of file Context.py.

◆ setTime()

pyhelios.Context.Context.setTime	(		self,
		int	hour,
		int	minute = 0,
		int	second = 0 )

Set the simulation time.

Parameters

hour	Hour (0-23)
minute	Minute (0-59), defaults to 0
second	Second (0-59), defaults to 0

Exceptions

ValueError	If time values are out of range
NotImplementedError	If time/date functions not available in current library build

Example: >>> context.setTime(14, 30) # Set to 2:30 PM >>> context.setTime(9, 15, 30) # Set to 9:15:30 AM

Definition at line 2899 of file Context.py.

◆ translateObject()

None pyhelios.Context.Context.translateObject	(		self,
		Union[int, List[int]]	ObjID,
		vec3	shift )

Translate one or more compound objects by a shift vector.

   Moves the specified compound object(s) and all their constituent
   primitives by the given shift vector without changing orientation or size.

Parameters

ObjID	Single object ID or list of object IDs to translate
shift	3D vector representing the translation [x, y, z]

Example: >>> context = Context() >>> tile_uuids = context.addTile(center=vec3(0, 0, 0), size=vec2(2, 2)) >>> obj_id = context.getPrimitiveParentObjectID(tile_uuids[0]) # Get object ID >>> # Translate single object >>> context.translateObject(obj_id, vec3(5, 0, 0)) # Move 5 units in x >>> # Translate multiple objects >>> context.translateObject([obj1, obj2, obj3], vec3(0, 2, 0)) # Move 2 units in y

Definition at line 1619 of file Context.py.

◆ translatePrimitive()

None pyhelios.Context.Context.translatePrimitive	(		self,
		Union[int, List[int]]	UUID,
		vec3	shift )

Translate one or more primitives by a shift vector.

   Moves the specified primitive(s) by the given shift vector without
   changing their orientation or size.

Parameters

UUID	Single primitive UUID or list of UUIDs to translate
shift	3D vector representing the translation [x, y, z]

Example: >>> context = Context() >>> patch_uuid = context.addPatch(center=vec3(0, 0, 0), size=vec2(1, 1)) >>> # Translate single primitive >>> context.translatePrimitive(patch_uuid, vec3(1, 0, 0)) # Move 1 unit in x >>> # Translate multiple primitives >>> context.translatePrimitive([uuid1, uuid2, uuid3], vec3(0, 0, 1)) # Move 1 unit in z

Definition at line 1586 of file Context.py.

◆ usePrimitiveTextureColor()

None pyhelios.Context.Context.usePrimitiveTextureColor	(		self,
		int	uuid )

Use texture map color instead of constant RGB for a primitive.

Parameters

uuid	UUID of the primitive

Definition at line 3729 of file Context.py.

◆ writeOBJ()

None pyhelios.Context.Context.writeOBJ	(		self,
		str	filename,
		Optional[List[int]]	UUIDs = None,
		Optional[List[str]]	primitive_data_fields = None,
		bool	write_normals = False,
		bool	silent = False )

Write geometry to an OBJ (Wavefront) file.

Parameters

filename	Path to the output OBJ file
UUIDs	Optional list of primitive UUIDs to export. If None, exports all primitives
primitive_data_fields	Optional list of primitive data field names to export
write_normals	Whether to include vertex normals in the output
silent	Whether to suppress output messages during export

Exceptions

ValueError	If filename is invalid, UUIDs are invalid, or data fields don't exist
PermissionError	If output directory is not writable
FileNotFoundError	If UUIDs do not exist in context
RuntimeError	If Context is in mock mode

Example: >>> context.writeOBJ("output.obj") # Export all primitives >>> context.writeOBJ("subset.obj", [uuid1, uuid2]) # Export specific primitives >>> context.writeOBJ("with_data.obj", [uuid1], ["temperature", "area"]) # Export with data

Definition at line 2125 of file Context.py.

◆ writePLY()

None pyhelios.Context.Context.writePLY	(		self,
		str	filename,
		Optional[List[int]]	UUIDs = None )

Write geometry to a PLY (Stanford Polygon) file.

Parameters

filename	Path to the output PLY file
UUIDs	Optional list of primitive UUIDs to export. If None, exports all primitives

Exceptions

ValueError	If filename is invalid or UUIDs are invalid
PermissionError	If output directory is not writable
FileNotFoundError	If UUIDs do not exist in context
RuntimeError	If Context is in mock mode

Example: >>> context.writePLY("output.ply") # Export all primitives >>> context.writePLY("subset.ply", [uuid1, uuid2]) # Export specific primitives

Definition at line 2083 of file Context.py.

◆ writePrimitiveData()

None pyhelios.Context.Context.writePrimitiveData	(		self,
		str	filename,
		List[str]	column_labels,
		Optional[List[int]]	UUIDs = None,
		bool	print_header = False )

Write primitive data to an ASCII text file.

   Outputs a space-separated text file where each row corresponds to a primitive
   and each column corresponds to a primitive data label.

Parameters

filename	Path to the output file
column_labels	List of primitive data labels to include as columns. Use "UUID" to include primitive UUIDs as a column. The order determines the column order in the output file.
UUIDs	Optional list of primitive UUIDs to include. If None, includes all primitives.
print_header	If True, writes column labels as the first line of the file

Exceptions

ValueError	If filename is invalid, column_labels is empty, or UUIDs list is empty when provided
HeliosFileIOError	If file cannot be written
HeliosRuntimeError	If a column label doesn't exist for any primitive

Example: >>> # Write temperature and area for all primitives >>> context.writePrimitiveData("output.txt", ["UUID", "temperature", "area"])

: >>> # Write with header row >>> context.writePrimitiveData("output.txt", ["UUID", "radiation_flux"], print_header=True)

: >>> # Write only for selected primitives >>> context.writePrimitiveData("subset.txt", ["temperature"], UUIDs=[uuid1, uuid2])

Definition at line 2191 of file Context.py.

Member Data Documentation

◆ _lifecycle_state

str pyhelios.Context.Context._lifecycle_state = 'initializing'

protected

Definition at line 85 of file Context.py.

◆ _plugin_registry

pyhelios.Context.Context._plugin_registry = get_plugin_registry()

protected

Definition at line 82 of file Context.py.

◆ context

pyhelios.Context.Context.context = None

Definition at line 93 of file Context.py.

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

pyhelios/Context.py

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ _check_context_available()

◆ _validate_file_path()

◆ _validate_output_file_path()

◆ _validate_uuid()

◆ addBox()

◆ addBoxObject()

◆ addCone()

◆ addConeObject()

◆ addDisk()

◆ addDiskObject()

◆ addMaterial()

◆ addPatch()

◆ addSphere()

◆ addSphereObject()

◆ addTile()

◆ addTileObject()

◆ addTimeseriesData()

◆ addTriangle()

◆ addTrianglesFromArrays()

◆ addTrianglesFromArraysTextured()

Single texture usage (backward compatible)

Multi-texture usage (Open3D style)

◆ addTriangleTextured()

◆ addTube()

◆ addTubeObject()

◆ assignMaterialToObject()

◆ assignMaterialToPrimitive()

◆ colorPrimitiveByDataPseudocolor()

◆ copyObject()

◆ copyObjectData()

◆ copyPrimitive()

◆ copyPrimitiveData()

◆ deleteMaterial()

◆ deleteObject()

◆ deletePrimitive()

◆ doesMaterialExist()

◆ doesPrimitiveDataExist()

◆ doesTimeseriesVariableExist()

◆ get_available_plugins()

◆ get_missing_plugins()

◆ get_plugin_capabilities()

◆ getAllObjectIDs()

◆ getAllPrimitiveAreas()

◆ getAllPrimitiveColors()

◆ getAllPrimitiveInfo()

◆ getAllPrimitiveMaterialLabels()

◆ getAllPrimitiveNormals()

◆ getAllPrimitiveSolidFractions()

◆ getAllPrimitiveTextureFiles()

◆ getAllPrimitiveTypes()

◆ getAllPrimitiveVertices()

◆ getAllUUIDs()

◆ getDate()

◆ getMaterialColor()

◆ getMaterialTexture()

◆ getMaterialTwosidedFlag()

◆ getNativePtr()

◆ getObjectCount()

◆ getPrimitiveArea()

◆ getPrimitiveColor()

◆ getPrimitiveCount()

◆ getPrimitiveData()

◆ getPrimitiveDataArray()

◆ getPrimitiveDataFloat()

◆ getPrimitiveDataSize()

◆ getPrimitiveDataType()

◆ getPrimitiveInfo()

◆ getPrimitiveMaterialLabel()

◆ getPrimitiveNormal()

◆ init()

◆ del()

◆ enter()

◆ exit()