pyhelios.Context.Context Class Reference

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 87 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)
int	getGeometryRevision (self)
	Get a counter that advances whenever any primitive is modified or deleted.
int	getShapeRevision (self)
	Get a counter that advances whenever a primitive's shape changes or a primitive is deleted.
	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	addPatchTextured (self, vec3 center, vec2 size, str texture_file, Optional[SphericalCoord] rotation=None, Optional[vec2] uv_center=None, Optional[vec2] uv_size=None)
	Add a textured patch primitive to the context.
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)
bool	doesPrimitiveExist (self, uuid)
	Check if a primitive exists for a given UUID or list of UUIDs.
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	addAdaptiveTileObject (self, vec3 center=vec3(0, 0, 0), vec2 size=vec2(1, 1), SphericalCoord rotation=SphericalCoord(1, 0, 0), Optional[AdaptiveTileRefinement] refinement=None, Optional[RGBcolor] color=None, Optional[str] texturefile=None, Optional[int2] texture_repeat=None)
	Add a patch subdivided into sub-patches whose size adapts with distance from a target point.
int	predictAdaptiveTileObjectSubpatchCount (self, vec2 size, Optional[AdaptiveTileRefinement] refinement=None, Optional[int2] texture_repeat=None)
	Determine how many sub-patches an adaptive tile object would contain, without building geometry.
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.
	updateTimeseriesData (self, str label, 'Date' date, 'Time' time, float new_value)
	Update the value of an existing timeseries data point.
	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.
	clearTimeseriesData (self)
	Clear all timeseries data from the Context.
	deleteTimeseriesVariable (self, str label)
	Delete a single timeseries variable and all of its data points.
	deleteTimeseriesDataPoint (self, 'Date' date, 'Time' time, Optional[str] label=None)
	Delete a single timeseries data point at the given date and time.
	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.
	resolveMaterialTextures (self, uuids, colors_np)
	Resolve material texture suppression for export.
	packGPUBuffers (self, uuids)
	Pack GPU-ready geometry buffers for a set of primitives in a single C++ pass.
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, uuids_or_uuid)
	Override texture color with the primitive's constant RGB color.
None	usePrimitiveTextureColor (self, uuids_or_uuid)
	Use texture-map color instead of the constant RGB color.
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.
None	hidePrimitive (self, uuids_or_uuid)
	Hide one or more primitives.
None	showPrimitive (self, uuids_or_uuid)
	Show one or more previously hidden primitives.
bool	isPrimitiveHidden (self, int uuid)
	Check if a primitive is hidden.
None	hideObject (self, objids_or_objid)
	Hide one or more compound objects (and all their primitives).
None	showObject (self, objids_or_objid)
	Show one or more previously hidden compound objects.
bool	isObjectHidden (self, int objID)
	Check if a compound object is hidden.
None	setObjectDataInt (self, objids_or_objid, str label, int value)
	Set object data as signed 32-bit integer.
None	setObjectDataUInt (self, objids_or_objid, str label, int value)
	Set object data as unsigned 32-bit integer.
None	setObjectDataFloat (self, objids_or_objid, str label, float value)
	Set object data as 32-bit float.
None	setObjectDataDouble (self, objids_or_objid, str label, float value)
	Set object data as 64-bit double.
None	setObjectDataString (self, objids_or_objid, str label, str value)
	Set object data as string.
None	setObjectDataVec2 (self, objids_or_objid, str label, x_or_vec, float y=None)
	Set object data as vec2.
None	setObjectDataVec3 (self, objids_or_objid, str label, x_or_vec, float y=None, float z=None)
	Set object data as vec3.
None	setObjectDataVec4 (self, objids_or_objid, str label, x_or_vec, float y=None, float z=None, float w=None)
	Set object data as vec4.
None	setObjectDataInt2 (self, objids_or_objid, str label, x_or_vec, int y=None)
	Set object data as int2.
None	setObjectDataInt3 (self, objids_or_objid, str label, x_or_vec, int y=None, int z=None)
	Set object data as int3.
None	setObjectDataInt4 (self, objids_or_objid, str label, x_or_vec, int y=None, int z=None, int w=None)
	Set object data as int4.
	getObjectData (self, int objID, str label, type data_type=None)
	Get object data with optional type specification.
float	getObjectDataFloat (self, int objID, str label)
	Get float object data.
int	getObjectDataInt (self, int objID, str label)
	Get int object data.
str	getObjectDataString (self, int objID, str label)
	Get string object data.
int	getObjectDataType (self, int objID, str label)
	Get the HeliosDataType enum for object data.
int	getObjectDataSize (self, int objID, str label)
	Get the size of object data array.
bool	doesObjectDataExist (self, int objID, str label)
	Check if object data exists.
np.ndarray	getObjectDataArray (self, List[int] objids, str label)
	Get object data values for multiple objects as a NumPy array.
None	clearObjectData (self, objids_or_objid, str label)
	Clear object data.
None	clearAllObjectData (self, str label)
	Remove a named data field from every compound object in the Context.
List[str]	listObjectData (self, int objID)
	List all data labels on a specific object.
List[str]	listAllObjectDataLabels (self)
	List all object data labels in context.
None	duplicateObjectData (self, int objID, str old_label, str new_label)
	Copy object data to a new label.
None	renameObjectData (self, int objID, str old_label, str new_label)
	Rename an object data label.
List[int]	filterObjectsByData (self, List[int] objIDs, str label, value, str comparator="=")
	Filter objects by data value.
None	setGlobalDataInt (self, str label, int value)
	Set global data as signed 32-bit integer.
None	setGlobalDataUInt (self, str label, int value)
	Set global data as unsigned 32-bit integer.
None	setGlobalDataFloat (self, str label, float value)
	Set global data as 32-bit float.
None	setGlobalDataDouble (self, str label, float value)
	Set global data as 64-bit double.
None	setGlobalDataString (self, str label, str value)
	Set global data as string.
None	setGlobalDataVec2 (self, str label, x_or_vec, float y=None)
	Set global data as vec2.
None	setGlobalDataVec3 (self, str label, x_or_vec, float y=None, float z=None)
	Set global data as vec3.
None	setGlobalDataVec4 (self, str label, x_or_vec, float y=None, float z=None, float w=None)
	Set global data as vec4.
None	setGlobalDataInt2 (self, str label, x_or_vec, int y=None)
	Set global data as int2.
None	setGlobalDataInt3 (self, str label, x_or_vec, int y=None, int z=None)
	Set global data as int3.
None	setGlobalDataInt4 (self, str label, x_or_vec, int y=None, int z=None, int w=None)
	Set global data as int4.
	getGlobalData (self, str label, type data_type=None)
	Get global data with optional type specification.
float	getGlobalDataFloat (self, str label)
	Get float global data.
int	getGlobalDataInt (self, str label)
	Get int global data.
str	getGlobalDataString (self, str label)
	Get string global data.
int	getGlobalDataType (self, str label)
	Get the HeliosDataType enum for global data.
int	getGlobalDataSize (self, str label)
	Get the size of global data array.
bool	doesGlobalDataExist (self, str label)
	Check if global data exists.
None	clearGlobalData (self, str label)
	Clear global data.
None	renameGlobalData (self, str old_label, str new_label)
	Rename a global data label.
None	duplicateGlobalData (self, str old_label, str new_label)
	Duplicate global data to a new label.
List[str]	listGlobalData (self)
	List all global data labels.
None	incrementGlobalData (self, str label, increment)
	Increment global data.
	calculatePrimitiveDataMean (self, List[int] uuids, str label, type return_type=float)
	Calculate arithmetic mean of primitive data across UUIDs.
	calculatePrimitiveDataAreaWeightedMean (self, List[int] uuids, str label, type return_type=float)
	Calculate area-weighted mean of primitive data.
	calculatePrimitiveDataSum (self, List[int] uuids, str label, type return_type=float)
	Calculate sum of primitive data across UUIDs.
	calculatePrimitiveDataAreaWeightedSum (self, List[int] uuids, str label, type return_type=float)
	Calculate area-weighted sum of primitive data.
None	scalePrimitiveData (self, uuids_or_label, label_or_factor, factor=None)
	Scale primitive data by a factor.
None	incrementPrimitiveData (self, List[int] uuids, str label, increment, str data_type=None)
	Increment primitive data for the given UUIDs.
None	aggregatePrimitiveDataSum (self, List[int] uuids, List[str] labels, str result_label)
	Sum multiple primitive data fields into a new field.
None	aggregatePrimitiveDataProduct (self, List[int] uuids, List[str] labels, str result_label)
	Multiply multiple primitive data fields into a new field.
float	sumPrimitiveSurfaceArea (self, List[int] uuids)
	Calculate total one-sided surface area for a set of primitives.
float	calculateAreaIndex (self, List[int] leaf_uuids, Optional[List[int]] wood_uuids=None, Optional[float] ground_area=None)
	Calculate the one-sided area index on a ground-area basis.
List[int]	filterPrimitivesByData (self, List[int] uuids, str label, value, str comparator="=")
	Filter primitives by data value.
int	getObjectType (self, int objID)
	Return the integer-coded helios::ObjectType of a compound object.
vec3	getObjectCenter (self, int objID)
	getObjectBoundingBox (self, objIDs)
	Get axis-aligned bounding box for one object or a list of objects.
List[int]	getObjectPrimitiveUUIDs (self, objIDs)
	Get flattened primitive UUIDs for one object, a list of objects, or a list-of-lists.
	getTileObjectAreaRatio (self, objIDs)
	Get tile-object area ratio for one or multiple tile objects.
vec3	getTileObjectCenter (self, int objID)
vec2	getTileObjectSize (self, int objID)
int2	getTileObjectSubdivisionCount (self, int objID)
vec3	getTileObjectNormal (self, int objID)
List[vec2]	getTileObjectTextureUV (self, int objID)
List[vec3]	getTileObjectVertices (self, int objID)
int2	getTileObjectTextureRepeat (self, int objID)
	Get the texture repeat count requested when the tile object was created.
int2	getTileObjectEffectiveTextureRepeat (self, int objID)
	Get the texture repeat count actually applied to the sub-patches of a tile object.
vec3	getAdaptiveTileObjectCenter (self, int objID)
	Get the Cartesian coordinates of the center of an adaptive tile object.
vec2	getAdaptiveTileObjectSize (self, int objID)
	Get the dimensions of an entire adaptive tile object.
vec3	getAdaptiveTileObjectNormal (self, int objID)
	Get a unit vector normal to an adaptive tile object surface.
List[vec3]	getAdaptiveTileObjectVertices (self, int objID)
	Get the Cartesian coordinates of each of the four corners of an adaptive tile object.
AdaptiveTileRefinement	getAdaptiveTileObjectRefinement (self, int objID)
	Get the refinement parameters that were requested when the object was created.
int2	getAdaptiveTileObjectBaseSubdivisionCount (self, int objID)
	Get the number of coarsest-level cells spanning an adaptive tile in x and y.
int	getAdaptiveTileObjectMaxRefinementLevel (self, int objID)
	Get the maximum quadtree refinement level, i.e.
vec2	getAdaptiveTileObjectSubpatchSizeRange (self, int objID)
	Get the sub-patch edge lengths actually achieved, as opposed to those requested.
int2	getAdaptiveTileObjectTextureRepeat (self, int objID)
	Get the texture repeat count of an adaptive tile object.
vec3	getSphereObjectCenter (self, int objID)
vec3	getSphereObjectRadius (self, int objID)
	Get per-axis radii of a sphere object.
int	getSphereObjectSubdivisionCount (self, int objID)
float	getSphereObjectVolume (self, int objID)
vec3	getBoxObjectCenter (self, int objID)
vec3	getBoxObjectSize (self, int objID)
int3	getBoxObjectSubdivisionCount (self, int objID)
float	getBoxObjectVolume (self, int objID)
vec3	getDiskObjectCenter (self, int objID)
vec2	getDiskObjectSize (self, int objID)
int	getDiskObjectSubdivisionCount (self, int objID)
int	getTubeObjectSubdivisionCount (self, int objID)
int	getTubeObjectNodeCount (self, int objID)
List[vec3]	getTubeObjectNodes (self, int objID)
List[float]	getTubeObjectNodeRadii (self, int objID)
List[RGBcolor]	getTubeObjectNodeColors (self, int objID)
float	getTubeObjectVolume (self, int objID)
float	getTubeObjectSegmentVolume (self, int objID, int segment_index)
int	getConeObjectSubdivisionCount (self, int objID)
List[vec3]	getConeObjectNodes (self, int objID)
List[float]	getConeObjectNodeRadii (self, int objID)
vec3	getConeObjectNode (self, int objID, int number)
float	getConeObjectNodeRadius (self, int objID, int number)
vec3	getConeObjectAxisUnitVector (self, int objID)
float	getConeObjectLength (self, int objID)
float	getConeObjectVolume (self, int objID)
vec3	getPatchCenter (self, int uuid)
vec2	getPatchSize (self, int uuid)
vec3	getTriangleVertex (self, int uuid, int number)
vec3	getVoxelCenter (self, int uuid)
vec3	getVoxelSize (self, int uuid)
int	getPatchCount (self, bool include_hidden=True)
int	getTriangleCount (self, bool include_hidden=True)
	getPrimitiveBoundingBox (self, uuids)
	Get axis-aligned bounding box for one primitive or a list of primitives.
None	setPrimitiveColor (self, uuids, color)
	Set the RGB or RGBA color of one primitive or a list of primitives.
None	clearPrimitiveData (self, uuids, str label)
	Remove a named data field from one primitive or a list of primitives.
None	clearAllPrimitiveData (self, str label)
	Remove a named data field from every primitive in the Context.
List[str]	listPrimitiveData (self, int uuid)
	List all data labels attached to a primitive.
None	cropDomainX (self, vec2 xbounds)
None	cropDomainY (self, vec2 ybounds)
None	cropDomainZ (self, vec2 zbounds)
Optional[List[int]]	cropDomain (self, *args)
	Crop the context domain to the given XYZ bounds.
bool	doesObjectExist (self, int objID)
	Return True if a compound object with the given ID exists.
bool	doesObjectContainPrimitive (self, int objID, int uuid)
	Return True if the given primitive UUID belongs to the given object.
bool	doesMaterialDataExist (self, str material_label, str data_label)
	Return True if the named material has data stored under data_label.
bool	objectHasTexture (self, int objID)
	Return True if the compound object has a texture assigned.
bool	isPrimitiveDirty (self, int uuid)
	Return True if the primitive's geometry has been modified since the last clean mark.
bool	isObjectDataValueCachingEnabled (self, str label)
	Return True if value caching is enabled for the given object-data label.
bool	isPrimitiveDataValueCachingEnabled (self, str label)
	Return True if value caching is enabled for the given primitive-data label.
bool	areObjectPrimitivesComplete (self, int objID)
	Return True if all primitives originally belonging to this object still exist (i.e., none have been deleted).
int	getJulianDate (self)
	Get the current simulation date as Julian day (1-366).
int	getMaterialCount (self)
	Return the total number of materials registered in the context.
float	getObjectArea (self, int objID)
	Return the total surface area (one-sided) of all primitives in the object.
int	getObjectPrimitiveCount (self, int objID)
	Return the number of primitives currently belonging to the object.
float	getPolymeshObjectVolume (self, int objID)
	Return the enclosed volume of a polymesh object.
float	getPolymeshObjectSurfaceArea (self, int objID)
	Return the total surface area of a polymesh object, summed over every face.
bool	isPolymeshObjectClosed (self, int objID)
	Return True if a polymesh object is a closed surface, i.e.
None	setPolymeshObjectVertices (self, int objID, List[vec3] vertices)
	Move every shared vertex of a polymesh object, deforming the mesh.
bool	doesObjectHaveSharedVertexTopology (self, int objID)
	Return True if a compound object reports which member primitives meet at each vertex.
int	getObjectSharedVertexCount (self, int objID, VertexWeldMode weld_mode=VertexWeldMode.WELD_FULL)
	Return the number of distinct shared vertices in a compound object's mesh.
List[int]	getObjectPrimitiveSharedVertexIndices (self, int objID, int uuid, VertexWeldMode weld_mode=VertexWeldMode.WELD_FULL)
	Return the shared mesh vertex each vertex of a primitive belongs to.
List[List[int]]	getObjectPrimitiveSharedVertexIndicesMulti (self, int objID, List[int] uuids, VertexWeldMode weld_mode=VertexWeldMode.WELD_FULL)
	Return shared mesh vertex indices for many primitives of a compound object at once.
List[int]	getPrimitiveSharedVertexIndices (self, int uuid, VertexWeldMode weld_mode=VertexWeldMode.WELD_FULL)
	Return a primitive's shared mesh vertex indices without naming its parent object.
List[vec3]	getPolymeshObjectVertices (self, int objID)
	Return the deduplicated shared vertex positions of a polymesh object.
List[int3]	getPolymeshObjectFaces (self, int objID)
	Return the vertex index triples defining each face of a polymesh object.
List[vec3]	getPolymeshObjectVertexNormals (self, int objID)
	Return the per-vertex normals of a polymesh object.
List[vec2]	getPolymeshObjectVertexUV (self, int objID)
	Return the per-vertex texture coordinates of a polymesh object, or an empty list if it has none.
bool	doesPolymeshObjectHaveVertexNormals (self, int objID)
	Return True if a polymesh object carries per-vertex normals.
VertexNormalSource	getPolymeshObjectVertexNormalSource (self, int objID)
	Return where a polymesh object's vertex normals came from.
int	getPolymeshObjectVertexCount (self, int objID)
	Return the number of shared vertices in a polymesh object.
int	getPolymeshObjectFaceCount (self, int objID)
	Return the number of faces in a polymesh object.
int	getPolymeshObjectFaceIndexForPrimitive (self, int objID, int uuid)
	Return the index into :meth:getPolymeshObjectFaces of the face made up by a member primitive.
int	getPolymeshObjectPrimitiveUUIDForFace (self, int objID, int face_index)
	Return the UUID of the primitive making up a given face of a polymesh object.
None	computePolymeshObjectVertexNormals (self, int objID, float crease_angle_degrees=30.0)
	Compute per-vertex normals for a polymesh object by area-weighted averaging.
List[int2]	getPolymeshObjectBoundaryEdges (self, int objID)
	Return the boundary edges of a polymesh object as vertex index pairs.
List[List[int]]	getPolymeshObjectConnectedComponents (self, int objID)
	Return the connected components of a polymesh object.
None	setPolymeshObjectTopology (self, int objID, List[vec3] vertices, List[int3] faces, List[int] face_UUIDs, Optional[List[vec3]] vertex_normals=None, Optional[List[vec2]] vertex_uv=None, VertexNormalSource normal_source=VertexNormalSource.NONE)
	Attach an indexed face set to a polymesh object built programmatically.
bool	doesObjectHaveAnalyticVertexNormals (self, int objID)
	Return True if a compound object can report analytic vertex normals.
Union[List[vec3], List[List[vec3]]]	getObjectPrimitiveVertexNormals (self, int objID, Union[int, List[int]] uuid)
	Return the analytic surface normals at each vertex of a member primitive.
int	getMaterialIDFromLabel (self, str material_label)
	Look up a material ID from its human-readable label.
int	getPrimitiveMaterialID (self, int uuid)
	Return the material ID assigned to the given primitive.
int	getGlobalDataVersion (self, str label)
	Return the version counter for a global data entry.
int	getPrimitiveParentObjectID (self, int uuid)
	Return the ID of the compound object the primitive belongs to.
str	getObjectTextureFile (self, int objID)
	Return the filesystem path of the texture assigned to the object, or an empty string if no texture is assigned.
List[str]	listAllPrimitiveDataLabels (self)
	Return the union of all primitive-data labels used across every primitive in the context.
List[str]	getLoadedXMLFiles (self)
	Return the list of XML file paths that have been loaded into this context.
None	printObjectInfo (self, int objID)
	Print summary info for the object to stdout (for debugging).
None	printPrimitiveInfo (self, int uuid)
	Print summary info for the primitive to stdout (for debugging).
None	enablePrimitiveDataValueCaching (self, str label)
	Enable value caching for the given primitive-data label.
None	disablePrimitiveDataValueCaching (self, str label)
	Disable value caching for the given primitive-data label.
None	enableObjectDataValueCaching (self, str label)
	Enable value caching for the given object-data label.
None	disableObjectDataValueCaching (self, str label)
	Disable value caching for the given object-data label.
None	setObjectDataFromPrimitiveDataMean (self, int objID, str label)
	Compute the mean of the given primitive-data label across the object's primitives and store it as object data on the object itself under the same label.
None	renameMaterial (self, str old_label, str new_label)
	Rename an existing material.
None	renamePrimitiveData (self, int uuid, str old_label, str new_label)
	Rename a primitive-data label on a single primitive.
None	clearMaterialData (self, str material_label, str data_label)
	Clear the named data entry on the given material.
List[int]	getDeletedUUIDs (self)
	Return the list of UUIDs that have been deleted from the context.
List[int]	getDirtyUUIDs (self, bool include_deleted=True)
	Return the list of UUIDs whose geometry has been modified since the last markGeometryClean call.
List[int]	getUniquePrimitiveParentObjectIDs (self, List[int] uuids, bool include_zero=True)
	Return the unique set of compound-object IDs that the given primitives belong to.
vec3	getObjectAverageNormal (self, int objID)
	Return the area-weighted average normal of all primitives in the object.
None	setObjectAverageNormal (self, int objID, vec3 origin, vec3 new_normal)
	Rotate the object so its area-weighted average normal aligns with new_normal.
None	setObjectOrigin (self, int objID, vec3 origin)
	Translate the object so its origin is moved to the given point.
None	setPrimitiveAzimuth (self, int uuid, vec3 origin, float new_azimuth)
	Rotate a single primitive about the given origin so its azimuth equals new_azimuth (radians).
None	setPrimitiveElevation (self, int uuid, vec3 origin, float new_elevation)
	Rotate a single primitive about the given origin so its elevation equals new_elevation (radians).
None	setTriangleVertices (self, int uuid, vec3 vertex0, vec3 vertex1, vec3 vertex2)
	Replace the three vertices of an existing triangle primitive.
None	setPrimitiveNormal (self, uuids_or_uuid, vec3 origin, vec3 new_normal)
	Rotate one or more primitives so their normals align with new_normal.
None	setPrimitiveParentObjectID (self, uuids_or_uuid, int objID)
	Reassign one or more primitives to belong to the given compound object.
None	setMaterialDataInt (self, str material_label, str data_label, int value)
	Set int data on a material.
None	setMaterialDataUInt (self, str material_label, str data_label, int value)
	Set unsigned int data on a material.
None	setMaterialDataFloat (self, str material_label, str data_label, float value)
	Set float data on a material.
None	setMaterialDataDouble (self, str material_label, str data_label, float value)
	Set double-precision float data on a material.
None	setMaterialDataString (self, str material_label, str data_label, str value)
	Set string data on a material.
None	setMaterialDataVec2 (self, str material_label, str data_label, vec2 value)
	Set vec2 data on a material.
None	setMaterialDataVec3 (self, str material_label, str data_label, vec3 value)
	Set vec3 data on a material.
None	setMaterialDataVec4 (self, str material_label, str data_label, vec4 value)
	Set vec4 data on a material.
None	setMaterialDataInt2 (self, str material_label, str data_label, int2 value)
	Set int2 data on a material.
None	setMaterialDataInt3 (self, str material_label, str data_label, int3 value)
	Set int3 data on a material.
None	setMaterialDataInt4 (self, str material_label, str data_label, int4 value)
	Set int4 data on a material.
int	getMaterialDataInt (self, str material_label, str data_label)
int	getMaterialDataUInt (self, str material_label, str data_label)
float	getMaterialDataFloat (self, str material_label, str data_label)
float	getMaterialDataDouble (self, str material_label, str data_label)
str	getMaterialDataString (self, str material_label, str data_label)
vec2	getMaterialDataVec2 (self, str material_label, str data_label)
vec3	getMaterialDataVec3 (self, str material_label, str data_label)
vec4	getMaterialDataVec4 (self, str material_label, str data_label)
int2	getMaterialDataInt2 (self, str material_label, str data_label)
int3	getMaterialDataInt3 (self, str material_label, str data_label)
int4	getMaterialDataInt4 (self, str material_label, str data_label)
int	getMaterialDataType (self, str material_label, str data_label)
	Return the HeliosDataType enum value for the given material data entry.
None	setMaterialData (self, str material_label, str data_label, value)
	Set material data with type detection from the Python value.
	getMaterialData (self, str material_label, str data_label, type data_type=None)
	Get material data, auto-detecting the type from Helios storage if not specified.
List	getUniquePrimitiveDataValues (self, str label, type dtype)
	Return the unique values stored under label across all primitives.
List	getUniqueObjectDataValues (self, str label, type dtype)
	Return the unique values stored under label across all compound objects.
'np.ndarray'	getObjectTransformationMatrix (self, int objID)
	Return the object's 4x4 transformation matrix as a (4,4) float32 ndarray.
None	setObjectTransformationMatrix (self, objIDs_or_objID, T)
	Set the 4x4 transformation matrix on one or more compound objects.
'np.ndarray'	getPrimitiveTransformationMatrix (self, int uuid)
	Return the primitive's 4x4 transformation matrix as a (4,4) float32 ndarray (row-major; see getObjectTransformationMatrix for layout details).
None	setPrimitiveTransformationMatrix (self, uuids_or_uuid, T)
	Set the 4x4 transformation matrix on one or more primitives.
	getDomainBoundingBox (self, Optional[List[int]] uuids=None)
	Return the axis-aligned bounding box of the domain (or a UUID subset).
	getDomainBoundingSphere (self, Optional[List[int]] uuids=None)
	Return the bounding sphere of the domain (or a UUID subset).
None	setTubeNodes (self, int objID, List[vec3] nodes)
	Replace the node positions of an existing tube object.
None	setTubeRadii (self, int objID, List[float] radii)
	Replace the per-node radii of an existing tube object.
None	scaleTubeGirth (self, int objID, float scale_factor)
	Scale the radii of an existing tube object by scale_factor.
None	scaleTubeLength (self, int objID, float scale_factor)
	Scale the lengths between tube nodes by scale_factor.
None	pruneTubeNodes (self, int objID, int node_index)
	Remove all tube nodes from index node_index to the end.
None	appendTubeSegment (self, int objID, vec3 node_position, float radius, *, Optional[RGBcolor] color=None, Optional[str] texture_file=None, Optional[vec2] uv=None)
	Append a new segment to an existing tube object.
int	addPolymeshObject (self, List[int] uuids)
	Group the given primitives into a new polymesh compound object and return its ID.
None	setObjectColor (self, objIDs_or_objID, color)
	Set the color of one or more compound objects.
None	overrideObjectTextureColor (self, objIDs_or_objID)
	Override the texture mapping with the object's vertex color.
None	useObjectTextureColor (self, objIDs_or_objID)
	Restore use of the texture color (undoes overrideObjectTextureColor).
None	markPrimitiveDirty (self, uuids_or_uuid)
	Mark one or more primitives as dirty (geometry has been modified).
None	markPrimitiveClean (self, uuids_or_uuid)
	Mark one or more primitives as clean (cancels dirty state).
None	setTileObjectSubdivisionCount (self, objIDs_or_objID, int2 subdiv)
	Set the (Nx, Ny) subdivision count of one or more tile objects.
None	setTileObjectSubdivisionByAreaRatio (self, objIDs_or_objID, float area_ratio)
	Set tile object subdivision dynamically based on a target area ratio.
List[int]	cleanDeletedUUIDs (self, List[int] uuids)
	Return a new list with deleted UUIDs removed; the input list is not mutated.
List[int]	cleanDeletedObjectIDs (self, List[int] objIDs)
	Return a new list with deleted object IDs removed; input is not mutated.
None	writeXML (self, str filename, Optional[List[int]] uuids=None, bool quiet=False)
	Write the context (or a UUID subset) to an XML file.
None	writeXML_byobject (self, str filename, List[int] objIDs, bool quiet=False)
	Write a subset of compound objects to an XML file.
	randu (self, low=None, high=None)
	Draw a uniform random number using the Context's RNG.
float	randn (self, mean=None, stddev=None)
	Draw a normal random number using the Context's RNG.
None	setLocation (self, location_or_lat, longitude=None, utc_offset=None, altitude=0.0)
	Set the geographic location used by solar/radiation calculations.
Location	getLocation (self)
	Return the Context's currently-configured geographic location.
List[RGBcolor]	generateColormap (self, str name, int n_colors)
	Generate a colormap with n_colors entries from a named colormap.
List[str]	generateTexturesFromColormap (self, str texture_file, List[RGBcolor] colormap)
	Generate one texture file per color in colormap derived from texture_file.
Optional[ 'np.ndarray']	getPrimitiveTextureTransparencyData (self, int uuid)
	Return the primitive's texture transparency mask as a 2D bool ndarray.

Static Public Member Functions
List[str]	getColormapNames ()
	Get the names of all predefined Helios colormaps.
Tuple[List[RGBcolor], List[float]]	getColormapControlPoints (str name)
	Get the control points that define a predefined Helios colormap.

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.
	_validate_uuids (self, uuids)
	Validate that every UUID in uuids 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.
List[PrimitiveInfo]	_batchPrimitiveInfo (self, List[int] uuids)
	Build PrimitiveInfo for many primitives with a fixed number of native calls.
	_check_primitive_data_exists (self, List[int] uuids, str label)
	Raise if any of uuids lacks primitive data label.

Static Protected Member Functions
List[float]	_marshal_mat4 (value)
	Coerce a 4x4 transformation matrix input into a flat list of 16 floats.
'np.ndarray'	_mat4_to_ndarray (List[float] flat)
	Convert a flat list of 16 floats (row-major) to a (4,4) numpy ndarray.

Protected Attributes
	_plugin_registry = get_plugin_registry()
str	_lifecycle_state = 'initializing'

Constructor & Destructor Documentation

__init__()

pyhelios.Context.Context.__init__

(

self

)

Definition at line 89 of file Context.py.

__del__()

pyhelios.Context.Context.__del__

(

self

)

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

Definition at line 339 of file Context.py.

Member Function Documentation

__enter__()

pyhelios.Context.Context.__enter__

(

self

)

Definition at line 329 of file Context.py.

__exit__()

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

Definition at line 332 of file Context.py.

_batchPrimitiveInfo()

List[PrimitiveInfo] pyhelios.Context.Context._batchPrimitiveInfo ( self, List[int] uuids )

protected

Build PrimitiveInfo for many primitives with a fixed number of native calls.

   Field-for-field identical to calling :meth:`getPrimitiveInfo` on each UUID,
   but each of the eight fields has a list-accepting getter backed by a native
   ``getBatch*`` call. Doing it per primitive costs eight native round-trips
   each — 77.5 ms for 5,000 primitives against 4.6 ms batched.

Parameters

uuids

Primitives to describe, in the order to return them

Returns

List of PrimitiveInfo, one per UUID, in the order given

Definition at line 805 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 142 of file Context.py.

_check_primitive_data_exists()

pyhelios.Context.Context._check_primitive_data_exists ( self, List[int] uuids, str label )

protected

Raise if any of uuids lacks primitive data label.

   Costs one native call per primitive, so call it only where the read that
   follows is itself per-primitive, or to diagnose a failure that has already
   happened.

Exceptions

ValueError

naming the first primitive that lacks the data

Definition at line 3228 of file Context.py.

_marshal_mat4()

List[float] pyhelios.Context.Context._marshal_mat4 ( value )

staticprotected

Coerce a 4x4 transformation matrix input into a flat list of 16 floats.

Accepts numpy.ndarray of shape (4,4) or (16,), list/tuple of 16 floats,
   or nested list/tuple of shape (4,4). Helios stores transformation matrices
   in **row-major** order: T[i*4 + j] = element (i, j). A numpy ndarray of
   shape (4,4) maps directly via .ravel() since numpy is row-major by default.

Definition at line 6568 of file Context.py.

_mat4_to_ndarray()

'np.ndarray' pyhelios.Context.Context._mat4_to_ndarray ( List[float] flat )

staticprotected

Convert a flat list of 16 floats (row-major) to a (4,4) numpy ndarray.

Definition at line 6597 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 256 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 299 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 186 of file Context.py.

_validate_uuids()

pyhelios.Context.Context._validate_uuids ( self, uuids )

protected

Validate that every UUID in uuids exists in this context.

   Use this for any UUID list rather than calling :meth:`_validate_uuid` in a
   loop. Existence is checked against the context's UUID list, which must be
   fetched from the native layer and searched; doing that per element makes
   validating N UUIDs O(N^2) with N native round-trips. At 20,000 primitives
   that cost ~15 s, swamping the work being validated. Fetching once and
   testing set membership makes it linear.

   Checks run per element in order -- type first, then existence -- so the
   error raised for a given list is the same one the per-element loop raised.
   The context's UUID list is fetched lazily, on the first element that needs
   it, and reused for the rest of the call.

Parameters

uuids

Iterable of UUIDs to validate

Exceptions

RuntimeError

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

Definition at line 211 of file Context.py.

addAdaptiveTileObject()

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

Add a patch subdivided into sub-patches whose size adapts with distance from a target point.

   Sub-patches are generated by recursive quadtree subdivision, so they are fine near
   ``refinement.target`` and progressively coarser away from it. This is intended for ground
   planes, where fine resolution is needed to resolve shadows cast near an object of interest
   but the remainder of the domain only needs to occlude the horizon. The sub-patches exactly
   partition the tile with no gaps and no overlaps, and the achieved sizes are typically
   within about 20% of those requested.

Parameters

center	Center position of tile (default: origin)
size	Size in x and y directions (default: 1x1)
rotation	Spherical rotation (default: no rotation)
refinement	Parameters controlling the adaptive sub-patch resolution (default: AdaptiveTileRefinement())
color	Optional RGB color
texturefile	Optional texture image file path
texture_repeat	Optional texture repetitions in x and y. Unlike :meth:addTileObject, the count is applied exactly – the base grid is snapped to a multiple of it rather than the count being reduced.

Returns

Object ID of the created compound object

Exceptions

ValueError	If parameters are invalid
RuntimeError	If the refinement is rejected by helios, e.g. because subpatch_size_max exceeds half the smaller tile dimension, or because the requested refinement would generate more than 2,000,000 sub-patches
NotImplementedError	If object-returning functions unavailable

Note

Sub-patches are ordered by quadtree traversal, not row-major, so they cannot be indexed by grid position. Adaptive tiles have no subdivision count, so :meth:getTileObjectSubdivisionCount and :meth:setTileObjectSubdivisionCount do not apply to them.

Examples

>>> # Ground plane resolved finely beneath a plant at the origin >>> refinement = AdaptiveTileRefinement( ... target=vec2(0, 0), subpatch_size_min=0.02, subpatch_size_max=2.0 ... ) >>> obj_id = ctx.addAdaptiveTileObject( ... center=vec3(0, 0, 0), size=vec2(50, 50), refinement=refinement ... )

>>> # Check the cost before committing to it >>> ctx.predictAdaptiveTileObjectSubpatchCount(vec2(50, 50), refinement) # doctest: +SKIP 21374

Definition at line 1588 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 1123 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 1703 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 1328 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 1747 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 1199 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 1785 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 3999 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 440 of file Context.py.

addPatchTextured()

int pyhelios.Context.Context.addPatchTextured	(		self,
		vec3	center,
		vec2	size,
		str	texture_file,
		Optional[SphericalCoord]	rotation = None,
		Optional[vec2]	uv_center = None,
		Optional[vec2]	uv_size = None )

Add a textured patch primitive to the context.

   Creates a rectangular patch with a texture image mapped to its surface.

Parameters

center	3D position of the patch center
size	Width and height of the patch
texture_file	Path to texture image file (supports PNG, JPG, JPEG, TGA, BMP)
rotation	Optional spherical rotation (defaults to no rotation)
uv_center	Optional UV center of texture map (required if uv_size is provided)
uv_size	Optional UV size of texture map (required if uv_center is provided)

Returns

UUID of the created textured patch primitive

Exceptions

ValueError	If arguments have wrong types or UV params are partially specified
FileNotFoundError	If texture file doesn't exist
RuntimeError	If context is in mock mode

Example

>>> context = Context() >>> uuid = context.addPatchTextured( ... center=vec3(0, 0, 0), ... size=vec2(2, 2), ... texture_file="texture.png" ... )

Definition at line 476 of file Context.py.

addPolymeshObject()

int pyhelios.Context.Context.addPolymeshObject	(		self,
		List[int]	uuids )

Group the given primitives into a new polymesh compound object and return its ID.

Definition at line 6778 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 984 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 1398 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 916 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 1488 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
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 3458 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 527 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 2662 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 2759 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 569 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 1044 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 1831 of file Context.py.

aggregatePrimitiveDataProduct()

None pyhelios.Context.Context.aggregatePrimitiveDataProduct	(		self,
		List[int]	uuids,
		List[str]	labels,
		str	result_label )

Multiply multiple primitive data fields into a new field.

Definition at line 5013 of file Context.py.

aggregatePrimitiveDataSum()

None pyhelios.Context.Context.aggregatePrimitiveDataSum	(		self,
		List[int]	uuids,
		List[str]	labels,
		str	result_label )

Sum multiple primitive data fields into a new field.

Definition at line 5009 of file Context.py.

appendTubeSegment()

None pyhelios.Context.Context.appendTubeSegment	(		self,
		int	objID,
		vec3	node_position,
		float	radius,
		*	,
		Optional[RGBcolor]	color = None,
		Optional[str]	texture_file = None,
		Optional[vec2]	uv = None )

Append a new segment to an existing tube object.

   Pass exactly one of ``color`` (an RGBcolor) or both ``texture_file`` and
   ``uv`` (a vec2 of texture u-fractions) to specify how the new segment
   should be shaded.

Definition at line 6739 of file Context.py.

areObjectPrimitivesComplete()

bool pyhelios.Context.Context.areObjectPrimitivesComplete	(		self,
		int	objID )

Return True if all primitives originally belonging to this object still exist (i.e., none have been deleted).

Definition at line 5595 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 4148 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 4127 of file Context.py.

calculateAreaIndex()

float pyhelios.Context.Context.calculateAreaIndex	(		self,
		List[int]	leaf_uuids,
		Optional[List[int]]	wood_uuids = None,
		Optional[float]	ground_area = None )

Calculate the one-sided area index on a ground-area basis.

   This is the quantity :math:`L` appearing in Beer's law,
   :math:`\\exp(-G L / \\cos\\theta)`: total one-sided area divided by the ground
   area over which it is distributed.

Parameters

leaf_uuids	UUIDs of leaf primitives.
wood_uuids	Optional UUIDs of woody (branch, trunk, stem) primitives. When given, the result is a plant area index rather than a leaf area index. Woody area is counted as one half of its summed one-sided area, because a tube or cone encloses the branch and so sums to the full cylinder surface rather than the projected area Beer's law requires. If woody elements are instead represented by non-enclosing planar primitives that are already one-sided silhouettes, this halving underestimates them by a factor of two.
ground_area	Optional ground area basis in m^2. When omitted, the basis is the horizontal (x-y) footprint of the bounding box of all primitives in the
Context	so a ground primitive extending beyond the canopy enlarges the basis and lowers the reported index. Supply this explicitly whenever the domain is not cropped tightly to the canopy.

Returns

One-sided area index (m^2 area per m^2 ground area).

Exceptions

ValueError	If ``leaf_uuids`` is empty or ``ground_area`` is not positive.
RuntimeError	If any primitive is a voxel, whose area is its total enclosing surface area rather than a one-sided area.

Example

>>> lai = context.calculateAreaIndex(leaf_uuids) >>> pai = context.calculateAreaIndex(leaf_uuids, wood_uuids) >>> lai = context.calculateAreaIndex(leaf_uuids, ground_area=100.0)

Definition at line 5054 of file Context.py.

calculatePrimitiveDataAreaWeightedMean()

pyhelios.Context.Context.calculatePrimitiveDataAreaWeightedMean	(		self,
		List[int]	uuids,
		str	label,
		type	return_type = float )

Calculate area-weighted mean of primitive data.

Definition at line 4939 of file Context.py.

calculatePrimitiveDataAreaWeightedSum()

pyhelios.Context.Context.calculatePrimitiveDataAreaWeightedSum	(		self,
		List[int]	uuids,
		str	label,
		type	return_type = float )

Calculate area-weighted sum of primitive data.

Definition at line 4955 of file Context.py.

calculatePrimitiveDataMean()

pyhelios.Context.Context.calculatePrimitiveDataMean	(		self,
		List[int]	uuids,
		str	label,
		type	return_type = float )

Calculate arithmetic mean of primitive data across UUIDs.

Parameters

uuids	List of primitive UUIDs.
label	Data label.
return_type	float (default), "double", or vec3.

Definition at line 4927 of file Context.py.

calculatePrimitiveDataSum()

pyhelios.Context.Context.calculatePrimitiveDataSum	(		self,
		List[int]	uuids,
		str	label,
		type	return_type = float )

Calculate sum of primitive data across UUIDs.

Definition at line 4946 of file Context.py.

cleanDeletedObjectIDs()

List[int] pyhelios.Context.Context.cleanDeletedObjectIDs	(		self,
		List[int]	objIDs )

Return a new list with deleted object IDs removed; input is not mutated.

Definition at line 6901 of file Context.py.

cleanDeletedUUIDs()

List[int] pyhelios.Context.Context.cleanDeletedUUIDs	(		self,
		List[int]	uuids )

Return a new list with deleted UUIDs removed; the input list is not mutated.

   This mirrors the convention used by ``cropDomain``, which returns the
   survivors rather than mutating in place.

Definition at line 6894 of file Context.py.

clearAllObjectData()

None pyhelios.Context.Context.clearAllObjectData	(		self,
		str	label )

Remove a named data field from every compound object in the Context.

   Clears the data with the given label from all objects (including hidden ones) and
   releases the registered data type for the label, so it may subsequently be
   re-registered with a different type. Requires helios-core v1.3.73 or newer.

Definition at line 4733 of file Context.py.

clearAllPrimitiveData()

None pyhelios.Context.Context.clearAllPrimitiveData	(		self,
		str	label )

Remove a named data field from every primitive in the Context.

   Clears the data with the given label from all primitives (including hidden ones)
   and releases the registered data type for the label, so it may subsequently be
   re-registered with a different type. Requires helios-core v1.3.73 or newer.

Definition at line 5495 of file Context.py.

clearGlobalData()

None pyhelios.Context.Context.clearGlobalData	(		self,
		str	label )

Clear global data.

Definition at line 4894 of file Context.py.

clearMaterialData()

None pyhelios.Context.Context.clearMaterialData	(		self,
		str	material_label,
		str	data_label )

Clear the named data entry on the given material.

Definition at line 6124 of file Context.py.

clearObjectData()

None pyhelios.Context.Context.clearObjectData	(		self,
			objids_or_objid,
		str	label )

Clear object data.

Accepts single ID or list.

Definition at line 4721 of file Context.py.

clearPrimitiveData()

None pyhelios.Context.Context.clearPrimitiveData	(		self,
			uuids,
		str	label )

Remove a named data field from one primitive or a list of primitives.

Definition at line 5482 of file Context.py.

clearTimeseriesData()

pyhelios.Context.Context.clearTimeseriesData

(

self

)

Clear all timeseries data from the Context.

   Removes all timeseries variables and their associated date/time values.

Exceptions

NotImplementedError

If timeseries functions not available

Example

>>> context.clearTimeseriesData() >>> context.listTimeseriesVariables() []

Definition at line 3727 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: "hot", "cool", "lava", "rainbow", "parula", "gray", "green", "lines" or "algae" (see :meth:getColormapNames)
ncolors	Number of discrete colors in color map (default: 10). Must be at least 2.
max_val	Maximum value for color scale (auto-determined if None)
min_val	Minimum value for color scale (auto-determined if None) If all primitives have the same data value (or ``min_val`` equals ``max_val``), they are all given the first color of the colormap.

Definition at line 3340 of file Context.py.

computePolymeshObjectVertexNormals()

None pyhelios.Context.Context.computePolymeshObjectVertexNormals	(		self,
		int	objID,
		float	crease_angle_degrees = 30.0 )

Compute per-vertex normals for a polymesh object by area-weighted averaging.

   Vertices are split across edges whose dihedral angle exceeds
   ``crease_angle_degrees``, so hard edges stay hard rather than being smoothed
   away. The resulting normals are reported as
   :attr:`VertexNormalSource.COMPUTED`.

   The file loaders call this automatically for a mesh whose source file supplied
   no normals (helios-core v1.3.85+), so it is only needed for a mesh assembled
   programmatically through :meth:`setPolymeshObjectTopology`, or to regenerate
   normals at a different crease angle or after the mesh has been deformed with
   :meth:`setPolymeshObjectVertices`.

Parameters

objID	Object ID of the polymesh object
crease_angle_degrees	Dihedral angle above which an edge is kept hard

Definition at line 5907 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 1954 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 1982 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 1894 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.setPrimitiveDataFloat(source_uuid, "temperature", 25.5) >>> context.copyPrimitiveData(source_uuid, dest_uuid) >>> # dest_uuid now has temperature data

Definition at line 1922 of file Context.py.

cropDomain()

Optional[List[int]] pyhelios.Context.Context.cropDomain	(		self,
		*	args )

Crop the context domain to the given XYZ bounds.

   Two call forms:
cropDomain  vec2, ybounds: vec2, zbounds: vec2)
           -> crop ALL primitives; returns None.
cropDomain  List[int], xbounds: vec2, ybounds: vec2, zbounds: vec2)
           -> crop only the given primitives; returns the list of primitives
              that survived (in-bounds UUIDs). The input list is NOT mutated.

Definition at line 5533 of file Context.py.

cropDomainX()

None pyhelios.Context.Context.cropDomainX	(		self,
		vec2	xbounds )

Definition at line 5506 of file Context.py.

cropDomainY()

None pyhelios.Context.Context.cropDomainY	(		self,
		vec2	ybounds )

Definition at line 5512 of file Context.py.

cropDomainZ()

None pyhelios.Context.Context.cropDomainZ	(		self,
		vec2	zbounds )

Definition at line 5518 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 4021 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 3918 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 3883 of file Context.py.

deleteTimeseriesDataPoint()

pyhelios.Context.Context.deleteTimeseriesDataPoint	(		self,
		'Date'	date,
		'Time'	time,
		Optional[str]	label = None )

Delete a single timeseries data point at the given date and time.

   If ``label`` is provided, only that variable's matching point is removed. If ``label``
   is omitted (None), the matching point is removed from every timeseries variable.

Parameters

date	Date of the data point to delete.
time	Time of the data point to delete.
label	Optional name of the timeseries variable. None applies to all variables.

Exceptions

ValueError	If date/time are wrong types, or label is an empty string.
NotImplementedError	If running against helios-core older than v1.3.73.

Note

If no matching data point exists, the underlying Helios API issues a non-fatal warning to stderr and the call is otherwise a no-op. Matching uses the same (date, time) encoding as :meth:addTimeseriesData.

Example

>>> from pyhelios.types import Date, Time >>> context.deleteTimeseriesDataPoint(Date(2024, 6, 15), Time(12, 0, 0), "temperature")

Definition at line 3782 of file Context.py.

deleteTimeseriesVariable()

pyhelios.Context.Context.deleteTimeseriesVariable	(		self,
		str	label )

Delete a single timeseries variable and all of its data points.

   Complements :meth:`clearTimeseriesData` (which removes all variables) and
   :meth:`updateTimeseriesData` (which modifies a single point).

Parameters

label

Name of the timeseries variable to delete.

Exceptions

ValueError	If ``label`` is empty.
NotImplementedError	If running against helios-core older than v1.3.72.

Note

If the variable does not exist, the underlying Helios API issues a non-fatal warning to stderr and the call is otherwise a no-op.

Example

>>> context.addTimeseriesData("temperature", 25.3, Date(2024, 6, 15), Time(12, 0, 0)) >>> context.deleteTimeseriesVariable("temperature") >>> context.doesTimeseriesVariableExist("temperature") False

Definition at line 3753 of file Context.py.

disableObjectDataValueCaching()

None pyhelios.Context.Context.disableObjectDataValueCaching	(		self,
		str	label )

Disable value caching for the given object-data label.

Definition at line 6102 of file Context.py.

disablePrimitiveDataValueCaching()

None pyhelios.Context.Context.disablePrimitiveDataValueCaching	(		self,
		str	label )

Disable value caching for the given primitive-data label.

Definition at line 6091 of file Context.py.

doesGlobalDataExist()

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

Check if global data exists.

Definition at line 4890 of file Context.py.

doesMaterialDataExist()

bool pyhelios.Context.Context.doesMaterialDataExist	(		self,
		str	material_label,
		str	data_label )

Return True if the named material has data stored under data_label.

Definition at line 5569 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 4003 of file Context.py.

doesObjectContainPrimitive()

bool pyhelios.Context.Context.doesObjectContainPrimitive	(		self,
		int	objID,
		int	uuid )

Return True if the given primitive UUID belongs to the given object.

Definition at line 5564 of file Context.py.

doesObjectDataExist()

bool pyhelios.Context.Context.doesObjectDataExist	(		self,
		int	objID,
		str	label )

Check if object data exists.

Definition at line 4679 of file Context.py.

doesObjectExist()

bool pyhelios.Context.Context.doesObjectExist	(		self,
		int	objID )

Return True if a compound object with the given ID exists.

Definition at line 5559 of file Context.py.

doesObjectHaveAnalyticVertexNormals()

bool pyhelios.Context.Context.doesObjectHaveAnalyticVertexNormals	(		self,
		int	objID )

Return True if a compound object can report analytic vertex normals.

   True for Sphere, Tube and Cone objects, which approximate a curved shape and can
   evaluate its true surface normal. False for object types built from genuinely
   flat faces, such as a tile or box.

Definition at line 5998 of file Context.py.

doesObjectHaveSharedVertexTopology()

bool pyhelios.Context.Context.doesObjectHaveSharedVertexTopology	(		self,
		int	objID )

Return True if a compound object reports which member primitives meet at each vertex.

   True for Tile, AdaptiveTile, Sphere, Tube and Cone objects, and for a Polymesh that
   carries a face table. False for a Box, a Disk, and for a polymesh assembled from
   loose primitives by :meth:`addPolymeshObject`, which has no topology.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.84

Definition at line 5699 of file Context.py.

doesPolymeshObjectHaveVertexNormals()

bool pyhelios.Context.Context.doesPolymeshObjectHaveVertexNormals	(		self,
		int	objID )

Return True if a polymesh object carries per-vertex normals.

Definition at line 5849 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 3175 of file Context.py.

doesPrimitiveExist()

bool pyhelios.Context.Context.doesPrimitiveExist	(		self,
			uuid )

Check if a primitive exists for a given UUID or list of UUIDs.

Parameters

uuid	A single UUID (int) or a list of UUIDs.

Returns

True if the primitive(s) exist, False otherwise. For a list, returns True only if ALL primitives exist.

Definition at line 714 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 3689 of file Context.py.

duplicateGlobalData()

None pyhelios.Context.Context.duplicateGlobalData	(		self,
		str	old_label,
		str	new_label )

Duplicate global data to a new label.

Definition at line 4902 of file Context.py.

duplicateObjectData()

None pyhelios.Context.Context.duplicateObjectData	(		self,
		int	objID,
		str	old_label,
		str	new_label )

Copy object data to a new label.

Definition at line 4746 of file Context.py.

enableObjectDataValueCaching()

None pyhelios.Context.Context.enableObjectDataValueCaching	(		self,
		str	label )

Enable value caching for the given object-data label.

Required before using getUniqueObjectDataValues for that label.

Definition at line 6097 of file Context.py.

enablePrimitiveDataValueCaching()

None pyhelios.Context.Context.enablePrimitiveDataValueCaching	(		self,
		str	label )

Enable value caching for the given primitive-data label.

Required before using getUniquePrimitiveDataValues for that label.

Definition at line 6086 of file Context.py.

filterObjectsByData()

List[int] pyhelios.Context.Context.filterObjectsByData	(		self,
		List[int]	objIDs,
		str	label,
			value,
		str	comparator = "=" )

Filter objects by data value.

Auto-dispatches based on value type.

Definition at line 4754 of file Context.py.

filterPrimitivesByData()

List[int] pyhelios.Context.Context.filterPrimitivesByData	(		self,
		List[int]	uuids,
		str	label,
			value,
		str	comparator = "=" )

Filter primitives by data value.

Auto-dispatches based on value type.

Parameters

uuids	UUIDs to filter.
label	Data label to compare.
value	Filter value (float, int, or str).
comparator	Comparison operator ("=", "<", ">", "<=", ">="). Not used for strings.

Definition at line 5079 of file Context.py.

generateColormap()

List[RGBcolor] pyhelios.Context.Context.generateColormap	(		self,
		str	name,
		int	n_colors )

Generate a colormap with n_colors entries from a named colormap.

Parameters

name	Helios colormap name: "hot", "cool", "lava", "rainbow", "parula", "gray", "green", "lines" or "algae" (see :meth:getColormapNames).
n_colors	Number of colors in the returned ramp. Must be at least 2.

Returns

A list of RGBcolor instances of length n_colors.

Exceptions

HeliosRuntimeError

If ``name`` is not a predefined colormap (the error lists the valid names) or n_colors is less than 2.

Definition at line 7028 of file Context.py.

generateTexturesFromColormap()

List[str] pyhelios.Context.Context.generateTexturesFromColormap	(		self,
		str	texture_file,
		List[RGBcolor]	colormap )

Generate one texture file per color in colormap derived from texture_file.

Returns the list of generated file paths.

Definition at line 7076 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 3938 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 3975 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 3959 of file Context.py.

getAdaptiveTileObjectBaseSubdivisionCount()

int2 pyhelios.Context.Context.getAdaptiveTileObjectBaseSubdivisionCount	(		self,
		int	objID )

Get the number of coarsest-level cells spanning an adaptive tile in x and y.

   The base grid is the uniform grid of unrefined cells that the quadtree refines within. It
   is derived from the requested sub-patch size range and the tile dimensions.

Definition at line 5245 of file Context.py.

getAdaptiveTileObjectCenter()

vec3 pyhelios.Context.Context.getAdaptiveTileObjectCenter	(		self,
		int	objID )

Get the Cartesian coordinates of the center of an adaptive tile object.

Definition at line 5210 of file Context.py.

getAdaptiveTileObjectMaxRefinementLevel()

int pyhelios.Context.Context.getAdaptiveTileObjectMaxRefinementLevel	(		self,
		int	objID )

Get the maximum quadtree refinement level, i.e.

the number of times a base cell may be subdivided.

Definition at line 5251 of file Context.py.

getAdaptiveTileObjectNormal()

vec3 pyhelios.Context.Context.getAdaptiveTileObjectNormal	(		self,
		int	objID )

Get a unit vector normal to an adaptive tile object surface.

Definition at line 5222 of file Context.py.

getAdaptiveTileObjectRefinement()

AdaptiveTileRefinement pyhelios.Context.Context.getAdaptiveTileObjectRefinement	(		self,
		int	objID )

Get the refinement parameters that were requested when the object was created.

Definition at line 5234 of file Context.py.

getAdaptiveTileObjectSize()

vec2 pyhelios.Context.Context.getAdaptiveTileObjectSize	(		self,
		int	objID )

Get the dimensions of an entire adaptive tile object.

Definition at line 5216 of file Context.py.

getAdaptiveTileObjectSubpatchSizeRange()

vec2 pyhelios.Context.Context.getAdaptiveTileObjectSubpatchSizeRange	(		self,
		int	objID )

Get the sub-patch edge lengths actually achieved, as opposed to those requested.

Returns

A vec2 holding the achieved minimum edge length in x and the achieved maximum edge length in y.

Definition at line 5261 of file Context.py.

getAdaptiveTileObjectTextureRepeat()

int2 pyhelios.Context.Context.getAdaptiveTileObjectTextureRepeat	(		self,
		int	objID )

Get the texture repeat count of an adaptive tile object.

   The base grid is snapped to a multiple of the requested repeat count when the object is
   created, so unlike :meth:`getTileObjectTextureRepeat` the requested count is always applied
   exactly and there is no effective-repeat variant.

Definition at line 5272 of file Context.py.

getAdaptiveTileObjectVertices()

List[vec3] pyhelios.Context.Context.getAdaptiveTileObjectVertices	(		self,
		int	objID )

Get the Cartesian coordinates of each of the four corners of an adaptive tile object.

Definition at line 5228 of file Context.py.

getAllObjectIDs()

List[int] pyhelios.Context.Context.getAllObjectIDs

(

self

)

Definition at line 731 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 4396 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 4392 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 872 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 4416 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 4388 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 4404 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 4412 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 4400 of file Context.py.

getAllPrimitiveVertices()

pyhelios.Context.Context.getAllPrimitiveVertices

(

self

)

Get vertices for all primitives.

Returns (flat_data, offsets) tuple.

Definition at line 4408 of file Context.py.

getAllUUIDs()

List[int] pyhelios.Context.Context.getAllUUIDs

(

self

)

Definition at line 721 of file Context.py.

getBoxObjectCenter()

vec3 pyhelios.Context.Context.getBoxObjectCenter	(		self,
		int	objID )

Definition at line 5302 of file Context.py.

getBoxObjectSize()

vec3 pyhelios.Context.Context.getBoxObjectSize	(		self,
		int	objID )

Definition at line 5307 of file Context.py.

getBoxObjectSubdivisionCount()

int3 pyhelios.Context.Context.getBoxObjectSubdivisionCount	(		self,
		int	objID )

Definition at line 5312 of file Context.py.

getBoxObjectVolume()

float pyhelios.Context.Context.getBoxObjectVolume	(		self,
		int	objID )

Definition at line 5317 of file Context.py.

getColormapControlPoints()

Tuple[List[RGBcolor], List[float]] pyhelios.Context.Context.getColormapControlPoints ( str name )

static

Get the control points that define a predefined Helios colormap.

   A colormap is a set of colors placed at normalized positions between 0 and 1,
   with colors linearly interpolated between them. These control points are the
   single definition of each named colormap, and are also what the Visualizer's
   predefined colormaps are built from. No Context instance is needed.

Parameters

name	Colormap name (see :meth:getColormapNames).

Returns

Tuple (colors, positions): the RGBcolor of each control point, and its normalized position, in increasing order from 0 to 1.

Exceptions

ValueError	If ``name`` is not a string.
HeliosRuntimeError	If ``name`` is not a predefined colormap (the error lists the valid names).

Definition at line 7067 of file Context.py.

getColormapNames()

List[str] pyhelios.Context.Context.getColormapNames ( )

static

Get the names of all predefined Helios colormaps.

   These are the names accepted by :meth:`generateColormap`,
   :meth:`colorPrimitiveByDataPseudocolor` and :meth:`getColormapControlPoints`
   (as of helios-core 1.3.89: "hot", "cool", "lava", "rainbow", "parula", "gray",
   "green", "lines" and "algae"). No Context instance is needed.

Returns

List of colormap names.

Definition at line 7044 of file Context.py.

getConeObjectAxisUnitVector()

vec3 pyhelios.Context.Context.getConeObjectAxisUnitVector	(		self,
		int	objID )

Definition at line 5390 of file Context.py.

getConeObjectLength()

float pyhelios.Context.Context.getConeObjectLength	(		self,
		int	objID )

Definition at line 5395 of file Context.py.

getConeObjectNode()

vec3 pyhelios.Context.Context.getConeObjectNode	(		self,
		int	objID,
		int	number )

Definition at line 5381 of file Context.py.

getConeObjectNodeRadii()

List[float] pyhelios.Context.Context.getConeObjectNodeRadii	(		self,
		int	objID )

Definition at line 5377 of file Context.py.

getConeObjectNodeRadius()

float pyhelios.Context.Context.getConeObjectNodeRadius	(		self,
		int	objID,
		int	number )

Definition at line 5386 of file Context.py.

getConeObjectNodes()

List[vec3] pyhelios.Context.Context.getConeObjectNodes	(		self,
		int	objID )

Definition at line 5372 of file Context.py.

getConeObjectSubdivisionCount()

int pyhelios.Context.Context.getConeObjectSubdivisionCount	(		self,
		int	objID )

Definition at line 5368 of file Context.py.

getConeObjectVolume()

float pyhelios.Context.Context.getConeObjectVolume	(		self,
		int	objID )

Definition at line 5399 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 3434 of file Context.py.

getDeletedUUIDs()

List[int] pyhelios.Context.Context.getDeletedUUIDs

(

self

)

Return the list of UUIDs that have been deleted from the context.

   These UUIDs are tombstoned and will not appear in getAllUUIDs(), but their
   IDs are tracked so they can be excluded from external references.

Definition at line 6139 of file Context.py.

getDirtyUUIDs()

List[int] pyhelios.Context.Context.getDirtyUUIDs	(		self,
		bool	include_deleted = True )

Return the list of UUIDs whose geometry has been modified since the last markGeometryClean call.

Parameters

include_deleted

If True (default), include UUIDs that were deleted while dirty. If False, only return UUIDs that still exist.

Definition at line 6150 of file Context.py.

getDiskObjectCenter()

vec3 pyhelios.Context.Context.getDiskObjectCenter	(		self,
		int	objID )

Definition at line 5322 of file Context.py.

getDiskObjectSize()

vec2 pyhelios.Context.Context.getDiskObjectSize	(		self,
		int	objID )

Definition at line 5327 of file Context.py.

getDiskObjectSubdivisionCount()

int pyhelios.Context.Context.getDiskObjectSubdivisionCount	(		self,
		int	objID )

Definition at line 5332 of file Context.py.

getDomainBoundingBox()

pyhelios.Context.Context.getDomainBoundingBox	(		self,
		Optional[List[int]]	uuids = None )

Return the axis-aligned bounding box of the domain (or a UUID subset).

Parameters

uuids

Optional list of primitive UUIDs to restrict the computation to. If None (default), uses every primitive in the context.

Returns

(xbounds, ybounds, zbounds) where each element is a vec2(min, max).

Definition at line 6668 of file Context.py.

getDomainBoundingSphere()

pyhelios.Context.Context.getDomainBoundingSphere	(		self,
		Optional[List[int]]	uuids = None )

Return the bounding sphere of the domain (or a UUID subset).

Returns

(center, radius) where center is a vec3 and radius is a float.

Definition at line 6683 of file Context.py.

getGeometryRevision()

int pyhelios.Context.Context.getGeometryRevision

(

self

)

Get a counter that advances whenever any primitive is modified or deleted.

   Any change to a primitive advances it, including setting its primitive data or
   color. If two calls return the same value, no primitive was modified or deleted in
   between, so code that tracks geometry changes can skip scanning for them. Unlike
   the dirty flags, the counter is not reset by :meth:`markGeometryClean`.

   Creating a primitive is not guaranteed to advance the counter; compare
   :meth:`getPrimitiveCount` as well to detect new primitives.

Returns

Current geometry revision

Exceptions

NotImplementedError

If the native library predates helios-core v1.3.92

Example

>>> rev = context.getGeometryRevision() >>> context.setPrimitiveDataFloat(uuid, "temperature", 25.0) >>> context.getGeometryRevision() != rev True

Definition at line 397 of file Context.py.

getGlobalData()

pyhelios.Context.Context.getGlobalData	(		self,
		str	label,
		type	data_type = None )

Get global data with optional type specification.

Auto-detects type if not specified.

Definition at line 4835 of file Context.py.

getGlobalDataFloat()

float pyhelios.Context.Context.getGlobalDataFloat	(		self,
		str	label )

Get float global data.

Definition at line 4870 of file Context.py.

getGlobalDataInt()

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

Get int global data.

Definition at line 4874 of file Context.py.

getGlobalDataSize()

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

Get the size of global data array.

Definition at line 4886 of file Context.py.

getGlobalDataString()

str pyhelios.Context.Context.getGlobalDataString	(		self,
		str	label )

Get string global data.

Definition at line 4878 of file Context.py.

getGlobalDataType()

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

Get the HeliosDataType enum for global data.

Definition at line 4882 of file Context.py.

getGlobalDataVersion()

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

Return the version counter for a global data entry.

Increments on each update; useful for cache invalidation.

Definition at line 6040 of file Context.py.

getJulianDate()

int pyhelios.Context.Context.getJulianDate

(

self

)

Get the current simulation date as Julian day (1-366).

Definition at line 5602 of file Context.py.

getLoadedXMLFiles()

List[str] pyhelios.Context.Context.getLoadedXMLFiles

(

self

)

Return the list of XML file paths that have been loaded into this context.

Definition at line 6068 of file Context.py.

getLocation()

Location pyhelios.Context.Context.getLocation

(

self

)

Return the Context's currently-configured geographic location.

Definition at line 7005 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 4036 of file Context.py.

getMaterialCount()

int pyhelios.Context.Context.getMaterialCount

(

self

)

Return the total number of materials registered in the context.

Definition at line 5607 of file Context.py.

getMaterialData()

pyhelios.Context.Context.getMaterialData	(		self,
		str	material_label,
		str	data_label,
		type	data_type = None )

Get material data, auto-detecting the type from Helios storage if not specified.

Parameters

material_label	Name of the material.
data_label	Data entry label.
data_type	Optional Python type (int, float, str, vec2, vec3, vec4, int2, int3, int4) or string ('uint', 'double'). If None, the type is queried via getMaterialDataType and dispatched automatically.

Definition at line 6451 of file Context.py.

getMaterialDataDouble()

float pyhelios.Context.Context.getMaterialDataDouble	(		self,
		str	material_label,
		str	data_label )

Definition at line 6357 of file Context.py.

getMaterialDataFloat()

float pyhelios.Context.Context.getMaterialDataFloat	(		self,
		str	material_label,
		str	data_label )

Definition at line 6353 of file Context.py.

getMaterialDataInt()

int pyhelios.Context.Context.getMaterialDataInt	(		self,
		str	material_label,
		str	data_label )

Definition at line 6345 of file Context.py.

getMaterialDataInt2()

int2 pyhelios.Context.Context.getMaterialDataInt2	(		self,
		str	material_label,
		str	data_label )

Definition at line 6380 of file Context.py.

getMaterialDataInt3()

int3 pyhelios.Context.Context.getMaterialDataInt3	(		self,
		str	material_label,
		str	data_label )

Definition at line 6385 of file Context.py.

getMaterialDataInt4()

int4 pyhelios.Context.Context.getMaterialDataInt4	(		self,
		str	material_label,
		str	data_label )

Definition at line 6390 of file Context.py.

getMaterialDataString()

str pyhelios.Context.Context.getMaterialDataString	(		self,
		str	material_label,
		str	data_label )

Definition at line 6361 of file Context.py.

getMaterialDataType()

int pyhelios.Context.Context.getMaterialDataType	(		self,
		str	material_label,
		str	data_label )

Return the HeliosDataType enum value for the given material data entry.

   Encoding (from Helios core): 0=INT, 1=UINT, 2=FLOAT, 3=DOUBLE,
   4=VEC2, 5=VEC3, 6=VEC4, 7=INT2, 8=INT3, 9=INT4, 10=STRING.

Definition at line 6400 of file Context.py.

getMaterialDataUInt()

int pyhelios.Context.Context.getMaterialDataUInt	(		self,
		str	material_label,
		str	data_label )

Definition at line 6349 of file Context.py.

getMaterialDataVec2()

vec2 pyhelios.Context.Context.getMaterialDataVec2	(		self,
		str	material_label,
		str	data_label )

Definition at line 6365 of file Context.py.

getMaterialDataVec3()

vec3 pyhelios.Context.Context.getMaterialDataVec3	(		self,
		str	material_label,
		str	data_label )

Definition at line 6370 of file Context.py.

getMaterialDataVec4()

vec4 pyhelios.Context.Context.getMaterialDataVec4	(		self,
		str	material_label,
		str	data_label )

Definition at line 6375 of file Context.py.

getMaterialIDFromLabel()

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

Look up a material ID from its human-readable label.

Definition at line 6029 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 4079 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 4106 of file Context.py.

getNativePtr()

pyhelios.Context.Context.getNativePtr

(

self

)

Definition at line 357 of file Context.py.

getObjectArea()

float pyhelios.Context.Context.getObjectArea	(		self,
		int	objID )

Return the total surface area (one-sided) of all primitives in the object.

Definition at line 5612 of file Context.py.

getObjectAverageNormal()

vec3 pyhelios.Context.Context.getObjectAverageNormal	(		self,
		int	objID )

Return the area-weighted average normal of all primitives in the object.

Definition at line 6175 of file Context.py.

getObjectBoundingBox()

pyhelios.Context.Context.getObjectBoundingBox	(		self,
			objIDs )

Get axis-aligned bounding box for one object or a list of objects.

   The box encloses every vertex of every primitive belonging to the given
   object(s).

Parameters

objIDs

Single object ID (int) or list of object IDs.

Returns

Tuple of (min_corner: vec3, max_corner: vec3).

Exceptions

HeliosRuntimeError

If an object ID does not exist, or if the given object(s) contain no primitives at all (a bounding box would be undefined).

Definition at line 5122 of file Context.py.

getObjectCenter()

vec3 pyhelios.Context.Context.getObjectCenter	(		self,
		int	objID )

Definition at line 5101 of file Context.py.

getObjectCount()

int pyhelios.Context.Context.getObjectCount

(

self

)

Definition at line 727 of file Context.py.

getObjectData()

pyhelios.Context.Context.getObjectData	(		self,
		int	objID,
		str	label,
		type	data_type = None )

Get object data with optional type specification.

Auto-detects type if not specified.

Definition at line 4624 of file Context.py.

getObjectDataArray()

np.ndarray pyhelios.Context.Context.getObjectDataArray	(		self,
		List[int]	objids,
		str	label )

Get object data values for multiple objects as a NumPy array.

   Reads one label across every object in a single call, in the order the
   IDs were given; much faster than reading objects one at a time.

Parameters

objids	Object IDs to read, controlling the result order
label	Object data label to retrieve

Returns

NumPy array with one entry per object: int32, uint32, float32 or float64 for the scalar types, and shape (N, components) for the vec2/3/4 and int2/3/4 types.

Exceptions

ValueError	If the ID list is empty or the label does not exist
NotImplementedError	If the data type has no bulk getter

Definition at line 4700 of file Context.py.

getObjectDataFloat()

float pyhelios.Context.Context.getObjectDataFloat	(		self,
		int	objID,
		str	label )

Get float object data.

Definition at line 4659 of file Context.py.

getObjectDataInt()

int pyhelios.Context.Context.getObjectDataInt	(		self,
		int	objID,
		str	label )

Get int object data.

Definition at line 4663 of file Context.py.

getObjectDataSize()

int pyhelios.Context.Context.getObjectDataSize	(		self,
		int	objID,
		str	label )

Get the size of object data array.

Definition at line 4675 of file Context.py.

getObjectDataString()

str pyhelios.Context.Context.getObjectDataString	(		self,
		int	objID,
		str	label )

Get string object data.

Definition at line 4667 of file Context.py.

getObjectDataType()

int pyhelios.Context.Context.getObjectDataType	(		self,
		int	objID,
		str	label )

Get the HeliosDataType enum for object data.

Definition at line 4671 of file Context.py.

getObjectPrimitiveCount()

int pyhelios.Context.Context.getObjectPrimitiveCount	(		self,
		int	objID )

Return the number of primitives currently belonging to the object.

Definition at line 5617 of file Context.py.

getObjectPrimitiveSharedVertexIndices()

List[int] pyhelios.Context.Context.getObjectPrimitiveSharedVertexIndices	(		self,
		int	objID,
		int	uuid,
		VertexWeldMode	weld_mode = VertexWeldMode.WELD_FULL )

Return the shared mesh vertex each vertex of a primitive belongs to.

   Indices are in the same order as :meth:`getPrimitiveVertices`, and two primitives
   meeting at a corner report the same index there. This is what lets a per-face
   quantity be averaged onto the vertices neighbouring faces have in common.

Parameters

objID	Object ID of the compound object the primitive belongs to
uuid	UUID of the primitive
weld_mode	See :class:VertexWeldMode

Returns

One index per vertex of the primitive; empty if the object exposes no topology.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.84

Note

When walking a whole object, prefer :meth:getObjectPrimitiveSharedVertexIndicesMulti – this per-primitive form is O(n) per call on Sphere, Tube and Cone objects, so a full walk is O(n^2).

Definition at line 5748 of file Context.py.

getObjectPrimitiveSharedVertexIndicesMulti()

List[List[int]] pyhelios.Context.Context.getObjectPrimitiveSharedVertexIndicesMulti	(		self,
		int	objID,
		List[int]	uuids,
		VertexWeldMode	weld_mode = VertexWeldMode.WELD_FULL )

Return shared mesh vertex indices for many primitives of a compound object at once.

   Equivalent to calling :meth:`getObjectPrimitiveSharedVertexIndices` for each UUID,
   except that any per-object quantity needed to locate the vertices is prepared once
   for the whole batch. Prefer this overload when walking an entire object.

Parameters

objID	Object ID of the compound object the primitives belong to
uuids	UUIDs of the primitives
weld_mode	See :class:VertexWeldMode

Returns

A list parallel to uuids, each entry holding one shared vertex index per vertex of the corresponding primitive.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.84

Definition at line 5776 of file Context.py.

getObjectPrimitiveUUIDs()

List[int] pyhelios.Context.Context.getObjectPrimitiveUUIDs	(		self,
			objIDs )

Get flattened primitive UUIDs for one object, a list of objects, or a list-of-lists.

Parameters

objIDs

int, List[int], or List[List[int]].

Returns

Flat list of primitive UUIDs (union across all objects).

Definition at line 5138 of file Context.py.

getObjectPrimitiveVertexNormals()

Union[List[vec3], List[List[vec3]]] pyhelios.Context.Context.getObjectPrimitiveVertexNormals	(		self,
		int	objID,
		Union[int, List[int]]	uuid )

Return the analytic surface normals at each vertex of a member primitive.

   Normals are evaluated from the object's own shape definition rather than stored,
   so they account for taper and stay correct after the object is transformed or its
   nodes and radii change. Returns an empty list for an object with no analytic
   normals (see :meth:`doesObjectHaveAnalyticVertexNormals`).

Parameters

objID	Object ID of the compound object
uuid	UUID of a member primitive, or a list of them

Returns

A list of vec3 for a single UUID, or a list of such lists for a list of UUIDs

Definition at line 6017 of file Context.py.

getObjectSharedVertexCount()

int pyhelios.Context.Context.getObjectSharedVertexCount	(		self,
		int	objID,
		VertexWeldMode	weld_mode = VertexWeldMode.WELD_FULL )

Return the number of distinct shared vertices in a compound object's mesh.

   This is one greater than the largest index
   :meth:`getObjectPrimitiveSharedVertexIndices` can return, and zero if the object
   exposes no topology.

Parameters

objID	Object ID of the compound object
weld_mode	Granularity at which coincident vertices are treated as the same shared vertex. See :class:VertexWeldMode.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.84

Definition at line 5718 of file Context.py.

getObjectTextureFile()

str pyhelios.Context.Context.getObjectTextureFile	(		self,
		int	objID )

Return the filesystem path of the texture assigned to the object, or an empty string if no texture is assigned.

Definition at line 6057 of file Context.py.

getObjectTransformationMatrix()

'np.ndarray' pyhelios.Context.Context.getObjectTransformationMatrix	(		self,
		int	objID )

Return the object's 4x4 transformation matrix as a (4,4) float32 ndarray.

   Helios stores matrices in row-major order, so element (i, j) is at
   position [i, j] of the returned ndarray. The translation column is at
   positions [0, 3], [1, 3], [2, 3].

Definition at line 6608 of file Context.py.

getObjectType()

int pyhelios.Context.Context.getObjectType	(		self,
		int	objID )

Return the integer-coded helios::ObjectType of a compound object.

   Values follow the C++ `helios::ObjectType` enum
   (0=tile, 1=sphere, 2=tube, 3=box, 4=disk, 5=polymesh, 6=cone,
   7=adaptive_tile).

Definition at line 5097 of file Context.py.

getPatchCenter()

vec3 pyhelios.Context.Context.getPatchCenter	(		self,
		int	uuid )

Definition at line 5405 of file Context.py.

getPatchCount()

int pyhelios.Context.Context.getPatchCount	(		self,
		bool	include_hidden = True )

Definition at line 5430 of file Context.py.

getPatchSize()

vec2 pyhelios.Context.Context.getPatchSize	(		self,
		int	uuid )

Definition at line 5410 of file Context.py.

getPolymeshObjectBoundaryEdges()

List[int2] pyhelios.Context.Context.getPolymeshObjectBoundaryEdges	(		self,
		int	objID )

Return the boundary edges of a polymesh object as vertex index pairs.

   A boundary edge is one referenced by exactly one face. An empty list means the
   mesh is closed.

Definition at line 5919 of file Context.py.

getPolymeshObjectConnectedComponents()

List[List[int]] pyhelios.Context.Context.getPolymeshObjectConnectedComponents	(		self,
		int	objID )

Return the connected components of a polymesh object.

   Each component is a list of face indices into :meth:`getPolymeshObjectFaces`.
   More than one component means the mesh is made of separate disjoint pieces.

Definition at line 5930 of file Context.py.

getPolymeshObjectFaceCount()

int pyhelios.Context.Context.getPolymeshObjectFaceCount	(		self,
		int	objID )

Return the number of faces in a polymesh object.

Definition at line 5875 of file Context.py.

getPolymeshObjectFaceIndexForPrimitive()

int pyhelios.Context.Context.getPolymeshObjectFaceIndexForPrimitive	(		self,
		int	objID,
		int	uuid )

Return the index into :meth:getPolymeshObjectFaces of the face made up by a member primitive.

Definition at line 5880 of file Context.py.

getPolymeshObjectFaces()

List[int3] pyhelios.Context.Context.getPolymeshObjectFaces	(		self,
		int	objID )

Return the vertex index triples defining each face of a polymesh object.

Definition at line 5822 of file Context.py.

getPolymeshObjectPrimitiveUUIDForFace()

int pyhelios.Context.Context.getPolymeshObjectPrimitiveUUIDForFace	(		self,
		int	objID,
		int	face_index )

Return the UUID of the primitive making up a given face of a polymesh object.

Definition at line 5885 of file Context.py.

getPolymeshObjectSurfaceArea()

float pyhelios.Context.Context.getPolymeshObjectSurfaceArea	(		self,
		int	objID )

Return the total surface area of a polymesh object, summed over every face.

Definition at line 5634 of file Context.py.

getPolymeshObjectVertexCount()

int pyhelios.Context.Context.getPolymeshObjectVertexCount	(		self,
		int	objID )

Return the number of shared vertices in a polymesh object.

Definition at line 5870 of file Context.py.

getPolymeshObjectVertexNormals()

List[vec3] pyhelios.Context.Context.getPolymeshObjectVertexNormals	(		self,
		int	objID )

Return the per-vertex normals of a polymesh object.

   Returns an empty list if the mesh carries none. A mesh loaded by :meth:`loadOBJ`
   or :meth:`loadPLY` always has them (helios-core v1.3.85+): normals authored in the
   file are kept, and a file that supplies none has them generated from the mesh
   connectivity. Only a mesh assembled programmatically through
   :meth:`setPolymeshObjectTopology` without normals carries none; call
   :meth:`computePolymeshObjectVertexNormals` to generate them.

Definition at line 5837 of file Context.py.

getPolymeshObjectVertexNormalSource()

VertexNormalSource pyhelios.Context.Context.getPolymeshObjectVertexNormalSource	(		self,
		int	objID )

Return where a polymesh object's vertex normals came from.

   ``AUTHORED`` means they were read from the source file (OBJ ``vn`` records, or
   PLY ``nx``/``ny``/``nz`` properties); ``COMPUTED`` means they were generated,
   either by the file loader because the file supplied none (helios-core v1.3.85+)
   or by :meth:`computePolymeshObjectVertexNormals`; ``NONE`` means the mesh has no
   vertex normals, which only arises for a mesh assembled programmatically through
   :meth:`setPolymeshObjectTopology`.

Definition at line 5863 of file Context.py.

getPolymeshObjectVertexUV()

List[vec2] pyhelios.Context.Context.getPolymeshObjectVertexUV	(		self,
		int	objID )

Return the per-vertex texture coordinates of a polymesh object, or an empty list if it has none.

Definition at line 5843 of file Context.py.

getPolymeshObjectVertices()

List[vec3] pyhelios.Context.Context.getPolymeshObjectVertices	(		self,
		int	objID )

Return the deduplicated shared vertex positions of a polymesh object.

   Returns an empty list for a mesh with no retained topology, such as one built
   with :meth:`addPolymeshObject` and not given a face set.

Definition at line 5816 of file Context.py.

getPolymeshObjectVolume()

float pyhelios.Context.Context.getPolymeshObjectVolume	(		self,
		int	objID )

Return the enclosed volume of a polymesh object.

   Since helios-core 1.3.84 a mesh carrying a face table is separated into its
   connected pieces and the volume of those that are closed is summed, so a solid
   shape modelled with an open stalk reports the shape's volume. An error is raised
   only when no piece is closed. A mesh carrying no face table has its closure
   checked by matching facets on coincident corners.

Definition at line 5629 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 621 of file Context.py.

getPrimitiveBoundingBox()

pyhelios.Context.Context.getPrimitiveBoundingBox	(		self,
			uuids )

Get axis-aligned bounding box for one primitive or a list of primitives.

Parameters

uuids

Single UUID (int) or list of UUIDs.

Returns

Tuple of (min_corner: vec3, max_corner: vec3).

Definition at line 5446 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 689 of file Context.py.

getPrimitiveCount()

int pyhelios.Context.Context.getPrimitiveCount

(

self

)

Definition at line 701 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 given, the value is read as that type; if None, the stored type is detected automatically.

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, the stored type is detected automatically.

Returns

The stored value of the specified or auto-detected type

Definition at line 3102 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 3258 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 3188 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 3214 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 3201 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 746 of file Context.py.

getPrimitiveMaterialID()

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

Return the material ID assigned to the given primitive.

Definition at line 6034 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 4165 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 640 of file Context.py.

getPrimitiveParentObjectID()

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

Return the ID of the compound object the primitive belongs to.

   Returns 0 if the primitive is not part of any compound object (the documented
   "no parent" sentinel). Raises ``HeliosRuntimeError`` if ``uuid`` does not exist.

Definition at line 6049 of file Context.py.

getPrimitiveSharedVertexIndices()

List[int] pyhelios.Context.Context.getPrimitiveSharedVertexIndices	(		self,
		int	uuid,
		VertexWeldMode	weld_mode = VertexWeldMode.WELD_FULL )

Return a primitive's shared mesh vertex indices without naming its parent object.

   Resolves the primitive's parent object and forwards to it.

Parameters

uuid	UUID of the primitive
weld_mode	See :class:VertexWeldMode

Returns

One index per vertex of the primitive. Empty if the primitive belongs to no object, or to one that exposes no topology.

Exceptions

RuntimeError

If the native library predates helios-core v1.3.84

Definition at line 5801 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 884 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 4334 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 4204 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 4219 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 4287 of file Context.py.

getPrimitiveTextureTransparencyData()

Optional['np.ndarray'] pyhelios.Context.Context.getPrimitiveTextureTransparencyData	(		self,
		int	uuid )

Return the primitive's texture transparency mask as a 2D bool ndarray.

   Returns None if the primitive has no associated transparency channel
   (e.g., it is untextured or its texture has no alpha). The returned
   ndarray has shape (height, width) and dtype ``bool``.

Definition at line 7099 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 4300 of file Context.py.

getPrimitiveTransformationMatrix()

'np.ndarray' pyhelios.Context.Context.getPrimitiveTransformationMatrix	(		self,
		int	uuid )

Return the primitive's 4x4 transformation matrix as a (4,4) float32 ndarray (row-major; see getObjectTransformationMatrix for layout details).

Definition at line 6634 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 4189 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 601 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 663 of file Context.py.

getShapeRevision()

int pyhelios.Context.Context.getShapeRevision

(

self

)

Get a counter that advances whenever a primitive's shape changes or a primitive is deleted.

   A shape change is any change to a primitive's vertices or transformation
   (translation, rotation, scaling, setting its vertices or transformation matrix),
   its texture file or (u,v) coordinates, or its solid fraction. Unlike
   :meth:`getGeometryRevision`, setting primitive data or color does not advance this
   counter, so a cache of geometry can tell that it is stale without being invalidated
   by data writes. :meth:`markGeometryDirty` also advances it, and it is not reset by
   :meth:`markGeometryClean`.

   Creating a primitive is not guaranteed to advance the counter; compare
   :meth:`getPrimitiveCount` as well to detect new primitives.

Returns

Current shape revision

Exceptions

NotImplementedError

If the native library predates helios-core v1.3.92

Definition at line 421 of file Context.py.

getSphereObjectCenter()

vec3 pyhelios.Context.Context.getSphereObjectCenter	(		self,
		int	objID )

Definition at line 5278 of file Context.py.

getSphereObjectRadius()

vec3 pyhelios.Context.Context.getSphereObjectRadius	(		self,
		int	objID )

Get per-axis radii of a sphere object.

Note

Helios spheres are spheroids with three independent radii (rx, ry, rz). Returns a vec3 (not a scalar).

Definition at line 5288 of file Context.py.

getSphereObjectSubdivisionCount()

int pyhelios.Context.Context.getSphereObjectSubdivisionCount	(		self,
		int	objID )

Definition at line 5293 of file Context.py.

getSphereObjectVolume()

float pyhelios.Context.Context.getSphereObjectVolume	(		self,
		int	objID )

Definition at line 5297 of file Context.py.

getTileObjectAreaRatio()

pyhelios.Context.Context.getTileObjectAreaRatio	(		self,
			objIDs )

Get tile-object area ratio for one or multiple tile objects.

Definition at line 5148 of file Context.py.

getTileObjectCenter()

vec3 pyhelios.Context.Context.getTileObjectCenter	(		self,
		int	objID )

Definition at line 5154 of file Context.py.

getTileObjectEffectiveTextureRepeat()

int2 pyhelios.Context.Context.getTileObjectEffectiveTextureRepeat	(		self,
		int	objID )

Get the texture repeat count actually applied to the sub-patches of a tile object.

   This is the requested count (see :meth:`getTileObjectTextureRepeat`) reduced so that it
   evenly divides the subdivision count.

Definition at line 5203 of file Context.py.

getTileObjectNormal()

vec3 pyhelios.Context.Context.getTileObjectNormal	(		self,
		int	objID )

Definition at line 5169 of file Context.py.

getTileObjectSize()

vec2 pyhelios.Context.Context.getTileObjectSize	(		self,
		int	objID )

Definition at line 5159 of file Context.py.

getTileObjectSubdivisionCount()

int2 pyhelios.Context.Context.getTileObjectSubdivisionCount	(		self,
		int	objID )

Definition at line 5164 of file Context.py.

getTileObjectTextureRepeat()

int2 pyhelios.Context.Context.getTileObjectTextureRepeat	(		self,
		int	objID )

Get the texture repeat count requested when the tile object was created.

   The repeat actually applied to the sub-patch texture coordinates is reduced whenever the
   requested count does not evenly divide the subdivision count; use
   :meth:`getTileObjectEffectiveTextureRepeat` to query that value.

   It is the requested rather than the reduced count that is retained on the object and
   re-applied when :meth:`setTileObjectSubdivisionCount` changes the subdivision count.

Definition at line 5193 of file Context.py.

getTileObjectTextureUV()

List[vec2] pyhelios.Context.Context.getTileObjectTextureUV	(		self,
		int	objID )

Definition at line 5174 of file Context.py.

getTileObjectVertices()

List[vec3] pyhelios.Context.Context.getTileObjectVertices	(		self,
		int	objID )

Definition at line 5179 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 3418 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 3665 of file Context.py.

getTriangleCount()

int pyhelios.Context.Context.getTriangleCount	(		self,
		bool	include_hidden = True )

Definition at line 5434 of file Context.py.

getTriangleVertex()

vec3 pyhelios.Context.Context.getTriangleVertex	(		self,
		int	uuid,
		int	number )

Definition at line 5415 of file Context.py.

getTubeObjectNodeColors()

List[RGBcolor] pyhelios.Context.Context.getTubeObjectNodeColors	(		self,
		int	objID )

Definition at line 5354 of file Context.py.

getTubeObjectNodeCount()

int pyhelios.Context.Context.getTubeObjectNodeCount	(		self,
		int	objID )

Definition at line 5341 of file Context.py.

getTubeObjectNodeRadii()

List[float] pyhelios.Context.Context.getTubeObjectNodeRadii	(		self,
		int	objID )

Definition at line 5350 of file Context.py.

getTubeObjectNodes()

List[vec3] pyhelios.Context.Context.getTubeObjectNodes	(		self,
		int	objID )

Definition at line 5345 of file Context.py.

getTubeObjectSegmentVolume()

float pyhelios.Context.Context.getTubeObjectSegmentVolume	(		self,
		int	objID,
		int	segment_index )

Definition at line 5363 of file Context.py.

getTubeObjectSubdivisionCount()

int pyhelios.Context.Context.getTubeObjectSubdivisionCount	(		self,
		int	objID )

Definition at line 5337 of file Context.py.

getTubeObjectVolume()

float pyhelios.Context.Context.getTubeObjectVolume	(		self,
		int	objID )

Definition at line 5359 of file Context.py.

getUniqueObjectDataValues()

List pyhelios.Context.Context.getUniqueObjectDataValues	(		self,
		str	label,
		type	dtype )

Return the unique values stored under label across all compound objects.

   Requires value caching to be enabled for ``label`` first via
   ``enableObjectDataValueCaching(label)``. Supported ``dtype`` values:
   ``int``, ``str``, or the string ``'uint'``.

Definition at line 6541 of file Context.py.

getUniquePrimitiveDataValues()

List pyhelios.Context.Context.getUniquePrimitiveDataValues	(		self,
		str	label,
		type	dtype )

Return the unique values stored under label across all primitives.

   Requires value caching to be enabled for ``label`` first via
   ``enablePrimitiveDataValueCaching(label)``. Supported ``dtype`` values:
   ``int``, ``str``, or the string ``'uint'``.

Definition at line 6522 of file Context.py.

getUniquePrimitiveParentObjectIDs()

List[int] pyhelios.Context.Context.getUniquePrimitiveParentObjectIDs	(		self,
		List[int]	uuids,
		bool	include_zero = True )

Return the unique set of compound-object IDs that the given primitives belong to.

Parameters

uuids	List of primitive UUIDs to inspect.
include_zero	If True (default), include the sentinel object ID 0 (i.e., primitives with no parent object). If False, only return IDs of real compound objects.

Definition at line 6163 of file Context.py.

getVoxelCenter()

vec3 pyhelios.Context.Context.getVoxelCenter	(		self,
		int	uuid )

Definition at line 5420 of file Context.py.

getVoxelSize()

vec3 pyhelios.Context.Context.getVoxelSize	(		self,
		int	uuid )

Definition at line 5425 of file Context.py.

hideObject()

None pyhelios.Context.Context.hideObject	(		self,
			objids_or_objid )

Hide one or more compound objects (and all their primitives).

Parameters

objids_or_objid

Single object ID (int) or list of object IDs to hide.

Definition at line 4459 of file Context.py.

hidePrimitive()

None pyhelios.Context.Context.hidePrimitive	(		self,
			uuids_or_uuid )

Hide one or more primitives.

Hidden primitives are excluded from getAllUUIDs().

Parameters

uuids_or_uuid

Single UUID (int) or list of UUIDs to hide.

Definition at line 4426 of file Context.py.

incrementGlobalData()

None pyhelios.Context.Context.incrementGlobalData	(		self,
		str	label,
			increment )

Increment global data.

Auto-dispatches based on increment type.

Definition at line 4910 of file Context.py.

incrementPrimitiveData()

None pyhelios.Context.Context.incrementPrimitiveData	(		self,
		List[int]	uuids,
		str	label,
			increment,
		str	data_type = None )

Increment primitive data for the given UUIDs.

   Each Helios increment overload only acts on fields whose stored type matches;
   fields of a different type are left unchanged. By default the overload is
   inferred from the Python type of ``increment`` (``int`` -> int, ``float`` ->
   float). To target an unsigned-int or double field, pass ``data_type``
   explicitly as one of ``'int'``, ``'uint'``, ``'float'``, ``'double'``.

Parameters

uuids	UUIDs whose data field to increment.
label	Data field label.
increment	Amount to add.
data_type	Optional explicit field type to target.

Definition at line 4987 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 3950 of file Context.py.

isGeometryDirty()

bool pyhelios.Context.Context.isGeometryDirty

(

self

)

Definition at line 370 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 4098 of file Context.py.

isObjectDataValueCachingEnabled()

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

Return True if value caching is enabled for the given object-data label.

Definition at line 5584 of file Context.py.

isObjectHidden()

bool pyhelios.Context.Context.isObjectHidden	(		self,
		int	objID )

Check if a compound object is hidden.

Parameters

objID

Object ID.

Returns

True if the object is hidden.

Definition at line 4484 of file Context.py.

isPolymeshObjectClosed()

bool pyhelios.Context.Context.isPolymeshObjectClosed	(		self,
		int	objID )

Return True if a polymesh object is a closed surface, i.e.

has no boundary edges.

   Only a closed mesh has a well-defined enclosed volume. Since helios-core 1.3.84
   :meth:`getPolymeshObjectVolume` splits a mesh into its connected pieces and sums
   the volume of those that are closed, so it raises only when no piece is closed --
   a solid fruit modelled with an open stalk reports the fruit's volume.

Definition at line 5646 of file Context.py.

isPrimitiveDataValueCachingEnabled()

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

Return True if value caching is enabled for the given primitive-data label.

Definition at line 5589 of file Context.py.

isPrimitiveDirty()

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

Return True if the primitive's geometry has been modified since the last clean mark.

Definition at line 5579 of file Context.py.

isPrimitiveHidden()

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

Check if a primitive is hidden.

Parameters

uuid	UUID of the primitive.

Returns

True if the primitive is hidden.

Definition at line 4451 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 4379 of file Context.py.

listAllObjectDataLabels()

List[str] pyhelios.Context.Context.listAllObjectDataLabels

(

self

)

List all object data labels in context.

Definition at line 4742 of file Context.py.

listAllPrimitiveDataLabels()

List[str] pyhelios.Context.Context.listAllPrimitiveDataLabels

(

self

)

Return the union of all primitive-data labels used across every primitive in the context.

Definition at line 6063 of file Context.py.

listGlobalData()

List[str] pyhelios.Context.Context.listGlobalData

(

self

)

List all global data labels.

Definition at line 4906 of file Context.py.

listMaterials()

List[str] pyhelios.Context.Context.listMaterials

(

self

)

Get list of all material labels in the context.

Definition at line 4007 of file Context.py.

listObjectData()

List[str] pyhelios.Context.Context.listObjectData	(		self,
		int	objID )

List all data labels on a specific object.

Definition at line 4738 of file Context.py.

listPrimitiveData()

List[str] pyhelios.Context.Context.listPrimitiveData	(		self,
		int	uuid )

List all data labels attached to a primitive.

Definition at line 5500 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 3710 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	Absolute height in metres of the loaded geometry after scaling – not a multiplier (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 2431 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	Absolute height in metres of the loaded geometry after scaling – not a multiplier; the model is uniformly scaled so its vertical extent equals this value (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 2374 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 3836 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 2482 of file Context.py.

markGeometryClean()

pyhelios.Context.Context.markGeometryClean

(

self

)

Definition at line 361 of file Context.py.

markGeometryDirty()

pyhelios.Context.Context.markGeometryDirty

(

self

)

Definition at line 365 of file Context.py.

markPrimitiveClean()

None pyhelios.Context.Context.markPrimitiveClean	(		self,
			uuids_or_uuid )

Mark one or more primitives as clean (cancels dirty state).

Definition at line 6839 of file Context.py.

markPrimitiveDirty()

None pyhelios.Context.Context.markPrimitiveDirty	(		self,
			uuids_or_uuid )

Mark one or more primitives as dirty (geometry has been modified).

Definition at line 6831 of file Context.py.

objectHasTexture()

bool pyhelios.Context.Context.objectHasTexture	(		self,
		int	objID )

Return True if the compound object has a texture assigned.

Definition at line 5574 of file Context.py.

overrideObjectTextureColor()

None pyhelios.Context.Context.overrideObjectTextureColor	(		self,
			objIDs_or_objID )

Override the texture mapping with the object's vertex color.

Definition at line 6813 of file Context.py.

overridePrimitiveTextureColor()

None pyhelios.Context.Context.overridePrimitiveTextureColor	(		self,
			uuids_or_uuid )

Override texture color with the primitive's constant RGB color.

Parameters

uuids_or_uuid

A single UUID (int) or a list of UUIDs. When a list is given, the override is applied to all of them in a single bulk call.

Definition at line 4351 of file Context.py.

packGPUBuffers()

pyhelios.Context.Context.packGPUBuffers	(		self,
			uuids )

Pack GPU-ready geometry buffers for a set of primitives in a single C++ pass.

   Produces a binary blob containing contiguous typed arrays (positions,
   colors, uvs, indices, faceToUuid) grouped by texture, ready for
   zero-copy loading into Three.js BufferGeometry attributes.

Parameters

uuids

List of primitive UUIDs

Returns

bytes Binary blob of the typed arrays described above

Definition at line 4263 of file Context.py.

predictAdaptiveTileObjectSubpatchCount()

int pyhelios.Context.Context.predictAdaptiveTileObjectSubpatchCount	(		self,
		vec2	size,
		Optional[AdaptiveTileRefinement]	refinement = None,
		Optional[int2]	texture_repeat = None )

Determine how many sub-patches an adaptive tile object would contain, without building geometry.

   Runs the same quadtree traversal as :meth:`addAdaptiveTileObject` but counts cells instead
   of creating primitives. Useful for checking the cost of a set of refinement parameters
   before committing to it, since the sub-patch count is highly sensitive to
   ``refinement.transition_exponent``.

Parameters

size	Size of the tile in the x- and y-directions
refinement	Parameters controlling the adaptive sub-patch resolution (default: AdaptiveTileRefinement())
texture_repeat	Texture repetitions the tile would use (default: 1x1)

Returns

Number of sub-patches that would be created

Exceptions

ValueError	If parameters are invalid
RuntimeError	Raised for a refinement that would generate too many sub-patches, rather than reporting a count, so that this and :meth:addAdaptiveTileObject answer the question the same way

Examples

>>> refinement = AdaptiveTileRefinement(subpatch_size_min=0.02, subpatch_size_max=2.0) >>> ctx.predictAdaptiveTileObjectSubpatchCount(vec2(50, 50), refinement) # doctest: +SKIP 21374

Definition at line 1668 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 4322 of file Context.py.

print_plugin_status()

pyhelios.Context.Context.print_plugin_status

(

self

)

Print detailed plugin status information.

Definition at line 3963 of file Context.py.

printObjectInfo()

None pyhelios.Context.Context.printObjectInfo	(		self,
		int	objID )

Print summary info for the object to stdout (for debugging).

Definition at line 6075 of file Context.py.

printPrimitiveInfo()

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

Print summary info for the primitive to stdout (for debugging).

Definition at line 6080 of file Context.py.

pruneTubeNodes()

None pyhelios.Context.Context.pruneTubeNodes	(		self,
		int	objID,
		int	node_index )

Remove all tube nodes from index node_index to the end.

Definition at line 6729 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)
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 3560 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 3638 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 3610 of file Context.py.

randn()

float pyhelios.Context.Context.randn	(		self,
			mean = None,
			stddev = None )

Draw a normal random number using the Context's RNG.

   Two forms:
       ``randn()`` -> standard normal (mean 0, stddev 1)
       ``randn(mean: float, stddev: float)`` -> N(mean, stddev**2)

Definition at line 6968 of file Context.py.

randu()

pyhelios.Context.Context.randu	(		self,
			low = None,
			high = None )

Draw a uniform random number using the Context's RNG.

   Three forms:
       ``randu()`` -> float in [0, 1)
       ``randu(low: float, high: float)`` -> float in [low, high)
       ``randu(low: int, high: int)`` -> int in [low, high]

   Whether the integer or float overload is invoked is determined by
   ``isinstance(low, int)``; pass ``low/high`` as Python ints for the
   integer range form.

Definition at line 6948 of file Context.py.

renameGlobalData()

None pyhelios.Context.Context.renameGlobalData	(		self,
		str	old_label,
		str	new_label )

Rename a global data label.

Definition at line 4898 of file Context.py.

renameMaterial()

None pyhelios.Context.Context.renameMaterial	(		self,
		str	old_label,
		str	new_label )

Rename an existing material.

Definition at line 6114 of file Context.py.

renameObjectData()

None pyhelios.Context.Context.renameObjectData	(		self,
		int	objID,
		str	old_label,
		str	new_label )

Rename an object data label.

Definition at line 4750 of file Context.py.

renamePrimitiveData()

None pyhelios.Context.Context.renamePrimitiveData	(		self,
		int	uuid,
		str	old_label,
		str	new_label )

Rename a primitive-data label on a single primitive.

Definition at line 6119 of file Context.py.

resolveMaterialTextures()

pyhelios.Context.Context.resolveMaterialTextures	(		self,
			uuids,
			colors_np )

Resolve material texture suppression for export.

   For each primitive, applies material-based texture suppression rules:
   1. If primitive has texture but material has no texture -> suppress texture, use material color
   2. If both have texture and textureColorOverride -> prefix "mask:", use material color
   3. Otherwise -> leave unchanged

Parameters

uuids	List of primitive UUIDs
colors_np	numpy float32 array of shape (N, 3), modified IN-PLACE

Returns

List[str] of resolved texture file paths

Definition at line 4245 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 the object's own stored origin point (object_origin), which for most objects is its construction center — NOT the global origin (0,0,0). An object built away from the world origin therefore spins in place rather than orbiting the world origin. To orbit a specific point, pass that point as origin instead. Cannot be used with the origin parameter.

Exceptions

ValueError

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

Definition at line 2138 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 2070 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)

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

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 2324 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 the object's own stored origin point (object_origin), not the global origin (0,0,0). Pass point to scale about a specific location instead.

Exceptions

ValueError

If parameters are invalid or conflicting options specified

Definition at line 2257 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 2213 of file Context.py.

scalePrimitiveData()

None pyhelios.Context.Context.scalePrimitiveData	(		self,
			uuids_or_label,
			label_or_factor,
			factor = None )

Scale primitive data by a factor.

Overloads

scalePrimitiveData(uuids, label, factor) - scale for specific UUIDs scalePrimitiveData(label, factor) - scale for ALL primitives

Definition at line 4967 of file Context.py.

scaleTubeGirth()

None pyhelios.Context.Context.scaleTubeGirth	(		self,
		int	objID,
		float	scale_factor )

Scale the radii of an existing tube object by scale_factor.

Definition at line 6719 of file Context.py.

scaleTubeLength()

None pyhelios.Context.Context.scaleTubeLength	(		self,
		int	objID,
		float	scale_factor )

Scale the lengths between tube nodes by scale_factor.

Definition at line 6724 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 435 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 3522 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 3385 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 3402 of file Context.py.

setGlobalDataDouble()

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

Set global data as 64-bit double.

Definition at line 4779 of file Context.py.

setGlobalDataFloat()

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

Set global data as 32-bit float.

Definition at line 4775 of file Context.py.

setGlobalDataInt()

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

Set global data as signed 32-bit integer.

Definition at line 4767 of file Context.py.

setGlobalDataInt2()

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

Set global data as int2.

Definition at line 4811 of file Context.py.

setGlobalDataInt3()

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

Set global data as int3.

Definition at line 4819 of file Context.py.

setGlobalDataInt4()

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

Set global data as int4.

Definition at line 4827 of file Context.py.

setGlobalDataString()

None pyhelios.Context.Context.setGlobalDataString	(		self,
		str	label,
		str	value )

Set global data as string.

Definition at line 4783 of file Context.py.

setGlobalDataUInt()

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

Set global data as unsigned 32-bit integer.

Definition at line 4771 of file Context.py.

setGlobalDataVec2()

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

Set global data as vec2.

Definition at line 4787 of file Context.py.

setGlobalDataVec3()

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

Set global data as vec3.

Definition at line 4795 of file Context.py.

setGlobalDataVec4()

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

Set global data as vec4.

Definition at line 4803 of file Context.py.

setLocation()

None pyhelios.Context.Context.setLocation	(		self,
			location_or_lat,
			longitude = None,
			utc_offset = None,
			altitude = 0.0 )

Set the geographic location used by solar/radiation calculations.

   Two call forms:
       ``setLocation(loc: Location)``
       ``setLocation(latitude_deg: float, longitude_deg: float, utc_offset: float, altitude=0.0)``

   ``altitude`` is the height of the local Cartesian origin in meters above
   sea level. It is only used in the (lat, lon, utc) float form; when passing
   a ``Location`` object, the location's own altitude is used.

Definition at line 6988 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 4058 of file Context.py.

setMaterialData()

None pyhelios.Context.Context.setMaterialData	(		self,
		str	material_label,
		str	data_label,
			value )

Set material data with type detection from the Python value.

   Dispatches to the correct typed setter based on ``isinstance`` of ``value``.
   For unambiguous numeric width control (e.g., uint vs int), call the
   per-type method directly (``setMaterialDataUInt``, etc.).

Definition at line 6412 of file Context.py.

setMaterialDataDouble()

None pyhelios.Context.Context.setMaterialDataDouble	(		self,
		str	material_label,
		str	data_label,
		float	value )

Set double-precision float data on a material.

Definition at line 6292 of file Context.py.

setMaterialDataFloat()

None pyhelios.Context.Context.setMaterialDataFloat	(		self,
		str	material_label,
		str	data_label,
		float	value )

Set float data on a material.

Definition at line 6287 of file Context.py.

setMaterialDataInt()

None pyhelios.Context.Context.setMaterialDataInt	(		self,
		str	material_label,
		str	data_label,
		int	value )

Set int data on a material.

Affects all primitives that reference it.

Definition at line 6277 of file Context.py.

setMaterialDataInt2()

None pyhelios.Context.Context.setMaterialDataInt2	(		self,
		str	material_label,
		str	data_label,
		int2	value )

Set int2 data on a material.

Definition at line 6323 of file Context.py.

setMaterialDataInt3()

None pyhelios.Context.Context.setMaterialDataInt3	(		self,
		str	material_label,
		str	data_label,
		int3	value )

Set int3 data on a material.

Definition at line 6330 of file Context.py.

setMaterialDataInt4()

None pyhelios.Context.Context.setMaterialDataInt4	(		self,
		str	material_label,
		str	data_label,
		int4	value )

Set int4 data on a material.

Definition at line 6337 of file Context.py.

setMaterialDataString()

None pyhelios.Context.Context.setMaterialDataString	(		self,
		str	material_label,
		str	data_label,
		str	value )

Set string data on a material.

Definition at line 6297 of file Context.py.

setMaterialDataUInt()

None pyhelios.Context.Context.setMaterialDataUInt	(		self,
		str	material_label,
		str	data_label,
		int	value )

Set unsigned int data on a material.

Definition at line 6282 of file Context.py.

setMaterialDataVec2()

None pyhelios.Context.Context.setMaterialDataVec2	(		self,
		str	material_label,
		str	data_label,
		vec2	value )

Set vec2 data on a material.

Definition at line 6302 of file Context.py.

setMaterialDataVec3()

None pyhelios.Context.Context.setMaterialDataVec3	(		self,
		str	material_label,
		str	data_label,
		vec3	value )

Set vec3 data on a material.

Definition at line 6309 of file Context.py.

setMaterialDataVec4()

None pyhelios.Context.Context.setMaterialDataVec4	(		self,
		str	material_label,
		str	data_label,
		vec4	value )

Set vec4 data on a material.

Definition at line 6316 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 4094 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 4102 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 4110 of file Context.py.

setObjectAverageNormal()

None pyhelios.Context.Context.setObjectAverageNormal	(		self,
		int	objID,
		vec3	origin,
		vec3	new_normal )

Rotate the object so its area-weighted average normal aligns with new_normal.

The rotation is applied about the given origin point.

Definition at line 6182 of file Context.py.

setObjectColor()

None pyhelios.Context.Context.setObjectColor	(		self,
			objIDs_or_objID,
			color )

Set the color of one or more compound objects.

   Accepts a single object ID or list/tuple of IDs. ``color`` must be an
   ``RGBcolor`` or ``RGBAcolor``.

Definition at line 6793 of file Context.py.

setObjectDataDouble()

None pyhelios.Context.Context.setObjectDataDouble	(		self,
			objids_or_objid,
		str	label,
		float	value )

Set object data as 64-bit double.

Scalar broadcasts to all objIDs; a list of values sets a distinct value per objID.

Definition at line 4520 of file Context.py.

setObjectDataFloat()

None pyhelios.Context.Context.setObjectDataFloat	(		self,
			objids_or_objid,
		str	label,
		float	value )

Set object data as 32-bit float.

Scalar broadcasts to all objIDs; a list of values sets a distinct value per objID.

Definition at line 4510 of file Context.py.

setObjectDataFromPrimitiveDataMean()

None pyhelios.Context.Context.setObjectDataFromPrimitiveDataMean	(		self,
		int	objID,
		str	label )

Compute the mean of the given primitive-data label across the object's primitives and store it as object data on the object itself under the same label.

Definition at line 6109 of file Context.py.

setObjectDataInt()

None pyhelios.Context.Context.setObjectDataInt	(		self,
			objids_or_objid,
		str	label,
		int	value )

Set object data as signed 32-bit integer.

Scalar broadcasts to all objIDs; a list of values sets a distinct value per objID.

Definition at line 4490 of file Context.py.

setObjectDataInt2()

None pyhelios.Context.Context.setObjectDataInt2	(		self,
			objids_or_objid,
		str	label,
			x_or_vec,
		int	y = None )

Set object data as int2.

Accepts an int2 / x,y components, or a list of int2 (one per objID).

Definition at line 4582 of file Context.py.

setObjectDataInt3()

None pyhelios.Context.Context.setObjectDataInt3	(		self,
			objids_or_objid,
		str	label,
			x_or_vec,
		int	y = None,
		int	z = None )

Set object data as int3.

Accepts an int3 / x,y,z components, or a list of int3 (one per objID).

Definition at line 4596 of file Context.py.

setObjectDataInt4()

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

Set object data as int4.

Accepts an int4 / x,y,z,w components, or a list of int4 (one per objID).

Definition at line 4610 of file Context.py.

setObjectDataString()

None pyhelios.Context.Context.setObjectDataString	(		self,
			objids_or_objid,
		str	label,
		str	value )

Set object data as string.

Scalar broadcasts to all objIDs; a list of strings sets a distinct value per objID.

Definition at line 4530 of file Context.py.

setObjectDataUInt()

None pyhelios.Context.Context.setObjectDataUInt	(		self,
			objids_or_objid,
		str	label,
		int	value )

Set object data as unsigned 32-bit integer.

Scalar broadcasts to all objIDs; a list of values sets a distinct value per objID.

Definition at line 4500 of file Context.py.

setObjectDataVec2()

None pyhelios.Context.Context.setObjectDataVec2	(		self,
			objids_or_objid,
		str	label,
			x_or_vec,
		float	y = None )

Set object data as vec2.

Accepts a vec2 / x,y components, or a list of vec2 (one per objID).

Definition at line 4540 of file Context.py.

setObjectDataVec3()

None pyhelios.Context.Context.setObjectDataVec3	(		self,
			objids_or_objid,
		str	label,
			x_or_vec,
		float	y = None,
		float	z = None )

Set object data as vec3.

Accepts a vec3 / x,y,z components, or a list of vec3 (one per objID).

Definition at line 4554 of file Context.py.

setObjectDataVec4()

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

Set object data as vec4.

Accepts a vec4 / x,y,z,w components, or a list of vec4 (one per objID).

Definition at line 4568 of file Context.py.

setObjectOrigin()

None pyhelios.Context.Context.setObjectOrigin	(		self,
		int	objID,
		vec3	origin )

Translate the object so its origin is moved to the given point.

Definition at line 6193 of file Context.py.

setObjectTransformationMatrix()

None pyhelios.Context.Context.setObjectTransformationMatrix	(		self,
			objIDs_or_objID,
			T )

Set the 4x4 transformation matrix on one or more compound objects.

Parameters

objIDs_or_objID	A single object ID (int) or a list/tuple of object IDs.
T	A 4x4 matrix as numpy.ndarray((4,4) | (16,) float), list of 16 floats, or a nested 4x4 list. Row-major; T[i, j] is element (i, j).

Definition at line 6620 of file Context.py.

setPolymeshObjectTopology()

None pyhelios.Context.Context.setPolymeshObjectTopology	(		self,
		int	objID,
		List[vec3]	vertices,
		List[int3]	faces,
		List[int]	face_UUIDs,
		Optional[List[vec3]]	vertex_normals = None,
		Optional[List[vec2]]	vertex_uv = None,
		VertexNormalSource	normal_source = VertexNormalSource.NONE )

Attach an indexed face set to a polymesh object built programmatically.

   Meshes loaded from an OBJ or PLY file retain the connectivity of the source file
   automatically. This is for a mesh assembled with :meth:`addPolymeshObject`, which
   otherwise has no topology and behaves as a triangle soup: its face count is zero,
   it cannot report a volume, and it is written out as independent per-triangle
   vertices.

Parameters

objID	Object ID of the polymesh object
vertices	Shared vertex positions in global Cartesian coordinates
faces	Vertex index triples defining each face
face_UUIDs	UUID of the primitive corresponding to each face, parallel to faces
vertex_normals	Per-vertex normals, or None if the mesh has none
vertex_uv	Per-vertex texture coordinates, or None if the mesh has none
normal_source	Provenance of the supplied vertex normals

Exceptions

ValueError

If an argument has the wrong type or ``face_UUIDs`` is not parallel to faces

Definition at line 5956 of file Context.py.

setPolymeshObjectVertices()

None pyhelios.Context.Context.setPolymeshObjectVertices	(		self,
		int	objID,
		List[vec3]	vertices )

Move every shared vertex of a polymesh object, deforming the mesh.

   Writes every shared vertex in one pass and pushes the new positions out to the
   member primitives, so faces that meet at a vertex stay welded. This is the
   supported way to deform a mesh: transforming the member primitives individually
   leaves each shared vertex wherever the last facet processed put it.

   The topology is unchanged, so ``vertices`` must be parallel to and the same length
   as the list returned by :meth:`getPolymeshObjectVertices`. Texture coordinates are
   not touched, and neither is the solid fraction of the member primitives -- so
   deforming a textured mesh does not re-rasterize its alpha mask.

Parameters

objID	Object ID of the polymesh object
vertices	New vertex positions in global Cartesian coordinates

Exceptions

RuntimeError	If the native library predates helios-core v1.3.84
ValueError	If a vertex is not a vec3

Note

Vertex normals are NOT recomputed and no longer describe the deformed surface; call :meth:computePolymeshObjectVertexNormals again if exact normals matter.

Example

>>> verts = context.getPolymeshObjectVertices(objID) >>> stretched = [vec3(v.x, v.y, v.z * 2.0) for v in verts] >>> context.setPolymeshObjectVertices(objID, stretched)

Definition at line 5680 of file Context.py.

setPrimitiveAzimuth()

None pyhelios.Context.Context.setPrimitiveAzimuth	(		self,
		int	uuid,
		vec3	origin,
		float	new_azimuth )

Rotate a single primitive about the given origin so its azimuth equals new_azimuth (radians).

Definition at line 6203 of file Context.py.

setPrimitiveColor()

None pyhelios.Context.Context.setPrimitiveColor	(		self,
			uuids,
			color )

Set the RGB or RGBA color of one primitive or a list of primitives.

Parameters

uuids	Single UUID (int) or list of UUIDs.
color	RGBcolor or RGBAcolor.

Definition at line 5462 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 scalar (broadcast to all UUIDs), or a list of values (one per UUID) to set a distinct value on each primitive.

Definition at line 2924 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 scalar (broadcast to all UUIDs), or a list of values (one per UUID) to set a distinct value on each primitive.

Definition at line 2906 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 scalar (broadcast to all UUIDs), or a list of values (one per UUID) to set a distinct value on each primitive.

Definition at line 2868 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 3029 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 3052 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 3076 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 scalar (broadcast to all UUIDs), or a list of strings (one per UUID) to set a distinct value on each primitive.

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

   Use this for built-in flags such as 'twosided_flag', which must be stored as unsigned integers.

Parameters

uuids_or_uuid	Single UUID (int) or list of UUIDs to set data for
label	String key for the data
value	Unsigned integer scalar (broadcast to all UUIDs), or a list of values (one per UUID) to set a distinct value on each primitive.

Definition at line 2888 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 2960 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 2983 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 3007 of file Context.py.

setPrimitiveElevation()

None pyhelios.Context.Context.setPrimitiveElevation	(		self,
		int	uuid,
		vec3	origin,
		float	new_elevation )

Rotate a single primitive about the given origin so its elevation equals new_elevation (radians).

Definition at line 6213 of file Context.py.

setPrimitiveNormal()

None pyhelios.Context.Context.setPrimitiveNormal	(		self,
			uuids_or_uuid,
		vec3	origin,
		vec3	new_normal )

Rotate one or more primitives so their normals align with new_normal.

   Accepts either a single UUID (int) or a list/tuple of UUIDs.
   The rotation is applied about the given origin point.

Definition at line 6238 of file Context.py.

setPrimitiveParentObjectID()

None pyhelios.Context.Context.setPrimitiveParentObjectID	(		self,
			uuids_or_uuid,
		int	objID )

Reassign one or more primitives to belong to the given compound object.

   Accepts either a single UUID (int) or a list/tuple of UUIDs. Pass objID=0
   to detach primitive(s) from any object.

Definition at line 6258 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 4275 of file Context.py.

setPrimitiveTransformationMatrix()

None pyhelios.Context.Context.setPrimitiveTransformationMatrix	(		self,
			uuids_or_uuid,
			T )

Set the 4x4 transformation matrix on one or more primitives.

Parameters

uuids_or_uuid	A single UUID (int) or a list/tuple of UUIDs.
T	A 4x4 matrix; see setObjectTransformationMatrix for accepted formats.

Definition at line 6645 of file Context.py.

setTileObjectSubdivisionByAreaRatio()

None pyhelios.Context.Context.setTileObjectSubdivisionByAreaRatio	(		self,
			objIDs_or_objID,
		float	area_ratio )

Set tile object subdivision dynamically based on a target area ratio.

   ``area_ratio`` is the approximate ratio between the whole tile's area and an
   individual sub-patch's area, so each tile is subdivided into roughly
   ``area_ratio`` sub-patches. It must be >= 1 (a sub-patch cannot be larger than
   the tile). The tile's position, size, and orientation are preserved.

Definition at line 6868 of file Context.py.

setTileObjectSubdivisionCount()

None pyhelios.Context.Context.setTileObjectSubdivisionCount	(		self,
			objIDs_or_objID,
		int2	subdiv )

Set the (Nx, Ny) subdivision count of one or more tile objects.

Definition at line 6849 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 3367 of file Context.py.

setTriangleVertices()

None pyhelios.Context.Context.setTriangleVertices	(		self,
		int	uuid,
		vec3	vertex0,
		vec3	vertex1,
		vec3	vertex2 )

Replace the three vertices of an existing triangle primitive.

Definition at line 6224 of file Context.py.

setTubeNodes()

None pyhelios.Context.Context.setTubeNodes	(		self,
		int	objID,
		List[vec3]	nodes )

Replace the node positions of an existing tube object.

Definition at line 6700 of file Context.py.

setTubeRadii()

None pyhelios.Context.Context.setTubeRadii	(		self,
		int	objID,
		List[float]	radii )

Replace the per-node radii of an existing tube object.

Definition at line 6712 of file Context.py.

showObject()

None pyhelios.Context.Context.showObject	(		self,
			objids_or_objid )

Show one or more previously hidden compound objects.

Parameters

objids_or_objid

Single object ID (int) or list of object IDs to show.

Definition at line 4470 of file Context.py.

showPrimitive()

None pyhelios.Context.Context.showPrimitive	(		self,
			uuids_or_uuid )

Show one or more previously hidden primitives.

Parameters

uuids_or_uuid

Single UUID (int) or list of UUIDs to show.

Definition at line 4437 of file Context.py.

sumPrimitiveSurfaceArea()

float pyhelios.Context.Context.sumPrimitiveSurfaceArea	(		self,
		List[int]	uuids )

Calculate total one-sided surface area for a set of primitives.

Definition at line 5017 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 2043 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 2010 of file Context.py.

updateTimeseriesData()

pyhelios.Context.Context.updateTimeseriesData	(		self,
		str	label,
		'Date'	date,
		'Time'	time,
		float	new_value )

Update the value of an existing timeseries data point.

Parameters

label	Name of the timeseries variable (must already exist)
date	Date of the existing point (must match exactly)
time	Time of the existing point (must match exactly)
new_value	Replacement value

Exceptions

ValueError	If label is empty, or date/time are wrong types
HeliosRuntimeError	If the variable does not exist or no point matches the (date, time)
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)) >>> context.updateTimeseriesData("temperature", Date(2024, 6, 15), Time(12, 0, 0), 26.5)

Definition at line 3492 of file Context.py.

useObjectTextureColor()

None pyhelios.Context.Context.useObjectTextureColor	(		self,
			objIDs_or_objID )

Restore use of the texture color (undoes overrideObjectTextureColor).

Definition at line 6821 of file Context.py.

usePrimitiveTextureColor()

None pyhelios.Context.Context.usePrimitiveTextureColor	(		self,
			uuids_or_uuid )

Use texture-map color instead of the constant RGB color.

Parameters

uuids_or_uuid

A single UUID (int) or a list of UUIDs. When a list is given, all of them are restored in a single bulk call.

Definition at line 4364 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. For each label, an ASCII file <stem>_<label>.dat is written next to the OBJ file with one value per line: line i holds the value for face i of the OBJ file, counting faces in the order they appear. A patch is written as two triangular faces, so its value appears on two consecutive lines. Every primitive in UUIDs must carry each label with type int, uint, float, double or string; otherwise an error is raised before any file is written.
write_normals	Whether to include vertex normals in the output
silent	Whether to suppress output messages during export

Exceptions

ValueError	If filename is invalid or UUIDs are invalid
HeliosRuntimeError	If a primitive lacks a requested data field or the field is not a scalar type
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 2555 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 2506 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. If a primitive does not have a label, or its data is not a scalar type (int, uint, float, double or string), 0 is written in its place and a single warning is printed for the call.
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
HeliosRuntimeError	If the output file cannot be opened for writing

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 2621 of file Context.py.

writeXML()

None pyhelios.Context.Context.writeXML	(		self,
		str	filename,
		Optional[List[int]]	uuids = None,
		bool	quiet = False )

Write the context (or a UUID subset) to an XML file.

Parameters

filename	Output file path. Must end in .xml.
uuids	Optional list of primitive UUIDs to restrict the export. If None (default), all primitives are written.
quiet	Suppress informational console output.

Definition at line 6917 of file Context.py.

writeXML_byobject()

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

Write a subset of compound objects to an XML file.

Definition at line 6928 of file Context.py.

Member Data Documentation

_lifecycle_state

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

protected

Definition at line 94 of file Context.py.

_plugin_registry

pyhelios.Context.Context._plugin_registry = get_plugin_registry()

protected

Definition at line 91 of file Context.py.

context

pyhelios.Context.Context.context = None

Definition at line 102 of file Context.py.

---

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

• pyhelios/Context.py