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

Examples

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

Public Member Functions
	__init__ (self)

	__enter__ (self)

	__exit__ (self, exc_type, exc_value, traceback)

	getNativePtr (self)

	markGeometryClean (self)

	markGeometryDirty (self)

bool	isGeometryDirty (self)

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

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

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

PrimitiveType	getPrimitiveType (self, int uuid)

float	getPrimitiveArea (self, int uuid)

vec3	getPrimitiveNormal (self, int uuid)

List[vec3]	getPrimitiveVertices (self, int uuid)

RGBcolor	getPrimitiveColor (self, int uuid)

int	getPrimitiveCount (self)

List[int]	getAllUUIDs (self)

int	getObjectCount (self)

List[int]	getAllObjectIDs (self)

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

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

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

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

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

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

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

List[int]	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.

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, int uuid, str label, int value)
	Set primitive data as signed 32-bit integer.

None	setPrimitiveDataUInt (self, int uuid, str label, int value)
	Set primitive data as unsigned 32-bit integer.

None	setPrimitiveDataFloat (self, int uuid, str label, float value)
	Set primitive data as 32-bit float.

None	setPrimitiveDataString (self, int uuid, str label, str value)
	Set primitive data as string.

	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.

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.

Public Attributes
	context = None

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

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

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

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

Protected Attributes
	_plugin_registry = get_plugin_registry()

str	_lifecycle_state = 'initializing'

Constructor & Destructor Documentation

◆ init()

pyhelios.Context.Context.__init__ ( self )

Definition at line 79 of file Context.py.

Member Function Documentation

◆ enter()

pyhelios.Context.Context.__enter__ ( self )

Definition at line 284 of file Context.py.

◆ exit()

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

Definition at line 287 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 132 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 211 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 254 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 176 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

Examples

>>> 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 733 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 311 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

Examples

>>> 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 590 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

Examples

>>> 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 520 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 331 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 989 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

Examples

# 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 1082 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

Examples

>>> 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 375 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

Examples

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

◆ colorPrimitiveByDataPseudocolor()

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

Color primitives based on primitive data values using pseudocolor mapping.

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

Parameters

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

Definition at line 1484 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 1314 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 1598 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 1635 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 1619 of file Context.py.

◆ getAllObjectIDs()

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

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

◆ getAllUUIDs()

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

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

Examples

>>> year, month, day = context.getDate()

>>> print(f"Current date: {year}-{month:02d}-{day:02d}")

Definition at line 1588 of file Context.py.

◆ getNativePtr()

pyhelios.Context.Context.getNativePtr ( self )

Definition at line 293 of file Context.py.

◆ getObjectCount()

int pyhelios.Context.Context.getObjectCount ( self )

Definition at line 430 of file Context.py.

◆ getPrimitiveArea()

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

Definition at line 396 of file Context.py.

◆ getPrimitiveColor()

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

Definition at line 415 of file Context.py.

◆ getPrimitiveCount()

int pyhelios.Context.Context.getPrimitiveCount ( self )

Definition at line 420 of file Context.py.

◆ getPrimitiveData()

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

Get primitive data for a specific primitive.

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

Parameters

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

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

Definition at line 1241 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 1381 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 1327 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 1353 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 1340 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 449 of file Context.py.

◆ getPrimitiveNormal()

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

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

◆ getPrimitiveType()

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

Definition at line 391 of file Context.py.

◆ getPrimitiveVertices()

List[vec3] pyhelios.Context.Context.getPrimitiveVertices	(		self,
		int	uuid )

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

Examples

>>> hour, minute, second = context.getTime()

>>> print(f"Current time: {hour:02d}:{minute:02d}:{second:02d}")

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

◆ isGeometryDirty()

bool pyhelios.Context.Context.isGeometryDirty ( self )

Definition at line 306 of file Context.py.

◆ loadOBJ()

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

Load geometry from an OBJ (Wavefront) file.

Parameters

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

Returns: List of UUIDs for the loaded primitives

Definition at line 826 of file Context.py.

◆ loadPLY()

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

Load geometry from a PLY (Stanford Polygon) file.

Parameters

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

Returns: List of UUIDs for the loaded primitives

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

◆ markGeometryClean()

pyhelios.Context.Context.markGeometryClean ( self )

Definition at line 297 of file Context.py.

◆ markGeometryDirty()

pyhelios.Context.Context.markGeometryDirty ( self )

Definition at line 301 of file Context.py.

◆ print_plugin_status()

pyhelios.Context.Context.print_plugin_status ( self )

Print detailed plugin status information.

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

Examples

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

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

Examples

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

Definition at line 1552 of file Context.py.

◆ setPrimitiveDataFloat()

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

Set primitive data as 32-bit float.

Parameters

uuid	UUID of the primitive
label	String key for the data
value	Float value

Definition at line 1214 of file Context.py.

◆ setPrimitiveDataInt()

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

Set primitive data as signed 32-bit integer.

Parameters

uuid	UUID of the primitive
label	String key for the data
value	Signed integer value

Definition at line 1190 of file Context.py.

◆ setPrimitiveDataString()

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

Set primitive data as string.

Parameters

uuid	UUID of the primitive
label	String key for the data
value	String value

Definition at line 1225 of file Context.py.

◆ setPrimitiveDataUInt()

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

Set primitive data as unsigned 32-bit integer.

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

Parameters

uuid	UUID of the primitive
label	String key for the data
value	Unsigned integer value (will be cast to uint32)

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

Examples

>>> context.setTime(14, 30) # Set to 2:30 PM

>>> context.setTime(9, 15, 30) # Set to 9:15:30 AM

Definition at line 1513 of file Context.py.

◆ writeOBJ()

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

Write geometry to an OBJ (Wavefront) file.

Parameters

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

Exceptions

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

Examples

>>> 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 936 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

Examples

>>> context.writePLY("output.ply") # Export all primitives

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

Definition at line 892 of file Context.py.

Member Data Documentation

◆ _lifecycle_state

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

protected

Definition at line 84 of file Context.py.

◆ _plugin_registry

pyhelios.Context.Context._plugin_registry = get_plugin_registry()

protected

Definition at line 81 of file Context.py.

◆ context

pyhelios.Context.Context.context = None

Definition at line 92 of file Context.py.

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

pyhelios/Context.py

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ _check_context_available()

◆ _validate_file_path()

◆ _validate_output_file_path()

◆ _validate_uuid()

◆ addBox()

◆ addPatch()

◆ addSphere()

◆ addTile()

◆ addTriangle()

◆ addTrianglesFromArrays()

◆ addTrianglesFromArraysTextured()

◆ addTriangleTextured()

◆ addTube()

◆ colorPrimitiveByDataPseudocolor()

◆ doesPrimitiveDataExist()

◆ get_available_plugins()

◆ get_missing_plugins()

◆ get_plugin_capabilities()

◆ getAllObjectIDs()

◆ getAllPrimitiveInfo()

◆ getAllUUIDs()

◆ getDate()

◆ getNativePtr()

◆ getObjectCount()

◆ getPrimitiveArea()

◆ getPrimitiveColor()

◆ getPrimitiveCount()

◆ getPrimitiveData()

◆ getPrimitiveDataArray()

◆ getPrimitiveDataFloat()

◆ getPrimitiveDataSize()

◆ getPrimitiveDataType()

◆ getPrimitiveInfo()

◆ getPrimitiveNormal()

◆ getPrimitivesInfoForObject()

◆ getPrimitiveType()

◆ getPrimitiveVertices()

◆ getTime()

◆ is_plugin_available()

◆ isGeometryDirty()

◆ loadOBJ()

◆ loadPLY()

◆ loadXML()

◆ markGeometryClean()

◆ markGeometryDirty()

◆ print_plugin_status()

◆ setDate()

◆ setDateJulian()

◆ setPrimitiveDataFloat()

◆ setPrimitiveDataInt()

◆ setPrimitiveDataString()

◆ setPrimitiveDataUInt()

◆ setTime()

◆ writeOBJ()

◆ writePLY()

Member Data Documentation

◆ _lifecycle_state

◆ _plugin_registry

◆ context

◆ init()

◆ enter()

◆ exit()