High-level interface for 3D visualization and rendering. More...

Detailed Description

High-level interface for 3D visualization and rendering.

This class provides a user-friendly wrapper around the native Helios visualizer plugin with automatic plugin availability checking and graceful error handling.

The visualizer provides OpenGL-based 3D rendering with interactive controls, image export, and comprehensive scene configuration options.

Definition at line 136 of file Visualizer.py.

Public Member Functions
	__init__ (self, int width, int height, int antialiasing_samples=4, bool headless=False)
	Initialize Visualizer with graceful plugin handling.

	__enter__ (self)
	Context manager entry.

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

None	buildContextGeometry (self, Context context, Optional[List[int]] uuids=None)
	Build Context geometry in the visualizer.

None	plotInteractive (self)
	Open interactive visualization window.

None	plotUpdate (self)
	Update visualization (non-interactive).

None	printWindow (self, str filename, Optional[str] image_format=None)
	Save current visualization to image file.

None	closeWindow (self)
	Close visualization window.

None	setCameraPosition (self, vec3 position, vec3 lookAt)
	Set camera position using Cartesian coordinates.

None	setCameraPositionSpherical (self, SphericalCoord angle, vec3 lookAt)
	Set camera position using spherical coordinates.

None	setBackgroundColor (self, RGBcolor color)
	Set background color.

None	setBackgroundTransparent (self)
	Enable transparent background mode (v1.3.53+).

None	setBackgroundImage (self, str texture_file)
	Set custom background image texture (v1.3.53+).

None	setBackgroundSkyTexture (self, Optional[str] texture_file=None, int divisions=50)
	Set sky sphere texture background with automatic scaling (v1.3.53+).

None	setLightDirection (self, vec3 direction)
	Set light direction.

None	setLightingModel (self, Union[int, str] lighting_model)
	Set lighting model.

None	colorContextPrimitivesByData (self, str data_name, Optional[List[int]] uuids=None)
	Color context primitives based on primitive data values.

None	setCameraFieldOfView (self, float angle_FOV)
	Set camera field of view angle.

Tuple[vec3, vec3]	getCameraPosition (self)
	Get current camera position and look-at point.

RGBcolor	getBackgroundColor (self)
	Get current background color.

None	setLightIntensityFactor (self, float intensity_factor)
	Set light intensity scaling factor.

Tuple[int, int]	getWindowSize (self)
	Get window size in pixels.

Tuple[int, int]	getFramebufferSize (self)
	Get framebuffer size in pixels.

None	printWindowDefault (self)
	Print window with default filename.

None	displayImageFromPixels (self, List[int] pixel_data, int width, int height)
	Display image from RGBA pixel data.

None	displayImageFromFile (self, str filename)
	Display image from file.

None	displayImageWithBoundingBoxes (self, str image_file, str bbox_file, str classes_file="", float line_width=2.0, int fontsize=12)
	Display an image with YOLO bounding boxes overlaid.

None	displayImageWithSegmentationMasks (self, str image_file, str mask_file, float fill_opacity=0.4, float line_width=2.0, int fontsize=12, bool show_labels=True)
	Display an image with COCO segmentation masks overlaid.

None	enableExactColorMode (self)
	Render primitive colors exactly as they are set in the Context.

None	disableExactColorMode (self)
	Restore the default brightening of primitive colors.

None	enableLinearPipeline (self)
	Enable the physically-based linear-light rendering pipeline.

None	disableLinearPipeline (self)
	Disable the linear-light pipeline, shading directly in sRGB space.

bool	isLinearPipelineEnabled (self)
	Check whether the linear-light rendering pipeline is enabled.

None	setExposure (self, float exposure)
	Set the linear exposure multiplier applied before tone mapping.

float	getExposure (self)
	Get the linear exposure multiplier applied before tone mapping.

None	setPhongMaterial (self, float ambient, float diffuse, float specular, float shininess)
	Set the Phong material parameters used to shade Context primitives.

Tuple[float, float, float, float]	getPhongMaterial (self)
	Get the Phong material parameters used to shade Context primitives.

None	setAmbientColors (self, RGBcolor sky_color, RGBcolor ground_color)
	Set the hemispheric ambient sky and ground-bounce colors.

RGBcolor	getAmbientSkyColor (self)
	Get the hemispheric ambient sky color.

RGBcolor	getAmbientGroundColor (self)
	Get the hemispheric ambient ground-bounce color.

None	enableSmoothShading (self)
	Enable smooth per-vertex-normal shading.

None	disableSmoothShading (self)
	Select flat (per-face) shading.

bool	isSmoothShadingEnabled (self)
	Check whether smooth per-vertex-normal shading is enabled.

bool	isHeadlessMultisamplingActive (self)
	Check whether headless rendering obtained multisampled framebuffer attachments.

vec2	getTextboxSize (self, str textstring, int fontsize, str fontname)
	Measure the rendered size of a text string without adding it to the visualizer.

	getWindowPixelsRGB (self, Optional[List[int]] buffer=None)
	Get RGB pixel data from the current window.

Tuple[List[float], int, int]	getDepthMap (self)
	Get the normalized depth map of the current view.

None	plotDepthMap (self)
	Plot depth map visualization.

Tuple[List[float], int, int]	getDepthImage (self)
	Get the distance from the camera to the nearest surface in each pixel of the current view.

Tuple[List[int], int, int]	getPixelUUIDs (self)
	Get the Context primitive visible in each pixel of the current view.

None	writeImageBoundingBoxes (self, primitive_data_labels=None, object_data_labels=None, object_class_ids=None, str image_file="", str classes_txt_file="classes.txt", str image_path="./")
	Write bounding boxes for the current view in Ultralytics YOLO format.

None	writeImageSegmentationMasks (self, primitive_data_labels=None, object_data_labels=None, object_class_ids=None, str json_filename="", str image_file="", Optional[List[str]] data_attribute_labels=None, bool append_file=False)
	Write segmentation masks for the current view in COCO JSON format.

None	writeDepthImageData (self, str filename)
	Write the depth image of the current view to a text file.

None	writeDepthImageDataEXR (self, str filename)
	Write the depth image of the current view to an EXR file with lossless float compression.

None	writeNormDepthImage (self, str filename, float max_depth)
	Write the depth image of the current view as a grayscale JPEG, normalized between the nearest depth and a maximum depth.

None	clearGeometry (self)
	Clear all geometry from visualizer.

None	clearContextGeometry (self)
	Clear context geometry from visualizer.

None	deleteGeometry (self, int geometry_id)
	Delete specific geometry by ID.

None	updateContextPrimitiveColors (self)
	Update context primitive colors.

List[vec3]	getGeometryVertices (self, int geometry_id)
	Get vertices of a geometry primitive.

None	setGeometryVertices (self, int geometry_id, List[vec3] vertices)
	Set vertices of a geometry primitive.

None	addCoordinateAxes (self)
	Add coordinate axes at origin with unit length.

None	addCoordinateAxesCustom (self, vec3 origin, vec3 length, str sign="both")
	Add coordinate axes with custom properties.

None	disableCoordinateAxes (self)
	Remove coordinate axes.

None	addGridWireFrame (self, vec3 center, vec3 size, List[int] subdivisions)
	Add grid wireframe.

None	enableColorbar (self)
	Enable colorbar.

None	disableColorbar (self)
	Disable colorbar.

None	setColorbarPosition (self, vec3 position)
	Set colorbar position.

None	setColorbarSize (self, float width, float height)
	Set colorbar size.

None	setColorbarRange (self, float min_val, float max_val)
	Set colorbar range.

None	setColorbarTicks (self, List[float] ticks)
	Set colorbar tick marks.

None	setColorbarTitle (self, str title)
	Set colorbar title.

None	setColorbarFontColor (self, RGBcolor color)
	Set colorbar font color.

None	setColorbarFontSize (self, int font_size)
	Set colorbar font size.

None	setColormap (self, Union[int, str] colormap)
	Set predefined colormap.

None	setCustomColormap (self, List[RGBcolor] colors, List[float] divisions)
	Set custom colormap.

None	colorContextPrimitivesByObjectData (self, str data_name, Optional[List[int]] obj_ids=None)
	Color context primitives by object data.

None	colorContextPrimitivesRandomly (self, Optional[List[int]] uuids=None)
	Color context primitives randomly.

None	colorContextObjectsRandomly (self, Optional[List[int]] obj_ids=None)
	Color context objects randomly.

None	clearColor (self)
	Clear primitive colors from previous coloring operations.

None	hideWatermark (self)
	Hide Helios logo watermark.

None	showWatermark (self)
	Show Helios logo watermark.

None	updateWatermark (self)
	Update watermark geometry to match current window size.

None	hideNavigationGizmo (self)
	Hide navigation gizmo (coordinate axes indicator in corner).

None	showNavigationGizmo (self)
	Show navigation gizmo (coordinate axes indicator in corner).

None	enableMessages (self)
	Enable standard output from visualizer plugin.

None	disableMessages (self)
	Disable standard output from visualizer plugin.

None	plotOnce (self, bool get_keystrokes=True)
	Run one rendering loop.

None	plotUpdateWithVisibility (self, bool hide_window=False)
	Update visualization with window visibility control.

None	setPointCullingEnabled (self, bool enabled)
	Enable or disable point cloud culling optimization.

None	setPointCullingThreshold (self, int threshold)
	Set the minimum number of points required to trigger culling.

None	setPointMaxRenderDistance (self, float distance)
	Set the maximum rendering distance for points.

None	setPointLODFactor (self, float factor)
	Set the level-of-detail factor for distance-based culling.

dict	getPointRenderingMetrics (self)
	Get point cloud rendering performance metrics.

	__del__ (self)
	Destructor to ensure proper cleanup.

Public Attributes
	width = width

	height = height

	antialiasing_samples = antialiasing_samples

	headless = headless

	visualizer = None

Static Public Attributes
int	LIGHTING_NONE = 0

int	LIGHTING_PHONG = 1

int	LIGHTING_PHONG_SHADOWED = 2

int	COLORMAP_HOT = 0

int	COLORMAP_COOL = 1

int	COLORMAP_RAINBOW = 2

int	COLORMAP_LAVA = 3

int	COLORMAP_PARULA = 4

int	COLORMAP_GRAY = 5

int	COLORMAP_LINES = 7

int	COLORMAP_ALGAE = 8

int	COLORMAP_GREEN = 9

Protected Member Functions
	_check_context_alive (self)
	Raise if a Context was loaded and has since been destroyed.

None	_write_depth_output (self, writer, str filename, str description, *args)
	Validate a depth-output filename and call the given wrapper writer.

Static Protected Member Functions
	_normalize_annotation_labels (primitive_data_labels, object_data_labels, object_class_ids)
	Validate the label arguments shared by the annotation writers.

Protected Attributes
	_context

Constructor & Destructor Documentation

◆ init()

pyhelios.Visualizer.Visualizer.__init__	(		self,
		int	width,
		int	height,
		int	antialiasing_samples = 4,
		bool	headless = False )

Initialize Visualizer with graceful plugin handling.

Parameters

width	Window width in pixels
height	Window height in pixels
antialiasing_samples	Number of antialiasing samples (default: 4). Pass 0 to disable antialiasing, which is required for exact color reproduction – see :meth:`enableExactColorMode`.
headless	Enable headless mode for offscreen rendering (default: False)

Exceptions

VisualizerError	If visualizer plugin is not available
ValueError	If parameters are invalid

Definition at line 169 of file Visualizer.py.

◆ del()

pyhelios.Visualizer.Visualizer.__del__ ( self )

Destructor to ensure proper cleanup.

Definition at line 3108 of file Visualizer.py.

Member Function Documentation

◆ enter()

pyhelios.Visualizer.Visualizer.__enter__ ( self )

Context manager entry.

Definition at line 269 of file Visualizer.py.

◆ exit()

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

Context manager exit with proper cleanup.

Definition at line 273 of file Visualizer.py.

◆ _check_context_alive()

pyhelios.Visualizer.Visualizer._check_context_alive ( self )

protected

Raise if a Context was loaded and has since been destroyed.

Definition at line 264 of file Visualizer.py.

◆ _normalize_annotation_labels()

pyhelios.Visualizer.Visualizer._normalize_annotation_labels	(	primitive_data_labels,
		object_data_labels,
		object_class_ids )

staticprotected

Validate the label arguments shared by the annotation writers.

Returns: Tuple of (labels list, class ID list, use_object_data flag)

Definition at line 1828 of file Visualizer.py.

◆ _write_depth_output()

None pyhelios.Visualizer.Visualizer._write_depth_output	(		self,
			writer,
		str	filename,
		str	description,
		*	args )

protected

Validate a depth-output filename and call the given wrapper writer.

Definition at line 2018 of file Visualizer.py.

◆ addCoordinateAxes()

None pyhelios.Visualizer.Visualizer.addCoordinateAxes ( self )

Add coordinate axes at origin with unit length.

Exceptions

VisualizerError If operation fails

Definition at line 2254 of file Visualizer.py.

◆ addCoordinateAxesCustom()

None pyhelios.Visualizer.Visualizer.addCoordinateAxesCustom	(		self,
		vec3	origin,
		vec3	length,
		str	sign = "both" )

Add coordinate axes with custom properties.

Parameters

origin	Axes origin position
length	Axes length in each direction
sign	Axis direction ("both" or "positive")

Exceptions

ValueError	If parameters are invalid
VisualizerError	If operation fails

Definition at line 2275 of file Visualizer.py.

◆ addGridWireFrame()

None pyhelios.Visualizer.Visualizer.addGridWireFrame	(		self,
		vec3	center,
		vec3	size,
		List[int]	subdivisions )

Add grid wireframe.

Parameters

center	Grid center position
size	Grid size in each direction
subdivisions	Grid subdivisions [x, y, z]

Exceptions

ValueError	If parameters are invalid
VisualizerError	If operation fails

Definition at line 2320 of file Visualizer.py.

◆ buildContextGeometry()

None pyhelios.Visualizer.Visualizer.buildContextGeometry	(		self,
		Context	context,
		Optional[List[int]]	uuids = None )

Build Context geometry in the visualizer.

   This method loads geometry from a Helios Context into the visualizer
   for rendering. If no UUIDs are specified, all geometry is loaded.

Parameters

context	Helios Context instance containing geometry
uuids	Optional list of primitive UUIDs to visualize (default: all)

Exceptions

VisualizerError	If geometry building fails
ValueError	If parameters are invalid

Definition at line 299 of file Visualizer.py.

◆ clearColor()

None pyhelios.Visualizer.Visualizer.clearColor ( self )

Clear primitive colors from previous coloring operations.

Exceptions

VisualizerError If operation fails

Definition at line 2744 of file Visualizer.py.

◆ clearContextGeometry()

None pyhelios.Visualizer.Visualizer.clearContextGeometry ( self )

Clear context geometry from visualizer.

Exceptions

VisualizerError If operation fails

Definition at line 2125 of file Visualizer.py.

◆ clearGeometry()

None pyhelios.Visualizer.Visualizer.clearGeometry ( self )

Clear all geometry from visualizer.

Warning: Do NOT use this to refresh a scene between animation frames. The visualizer syncs from the Context incrementally using the Context's dirty flags. Clearing discards the visualizer's geometry while the Context primitives remain marked clean, so the next rebuild pulls in nothing and subsequent frames render empty – printWindow() then silently writes no file.

To animate a changing Context, just call buildContextGeometry() and plotUpdate() each frame without clearing; additions, deletions and modifications are all picked up automatically.

Exceptions

VisualizerError If operation fails

Definition at line 2110 of file Visualizer.py.

◆ closeWindow()

None pyhelios.Visualizer.Visualizer.closeWindow ( self )

Close visualization window.

   This method closes any open visualization window. It's safe to call
   even if no window is open.

Exceptions

VisualizerError If window closing fails

Definition at line 475 of file Visualizer.py.

◆ colorContextObjectsRandomly()

None pyhelios.Visualizer.Visualizer.colorContextObjectsRandomly	(		self,
		Optional[List[int]]	obj_ids = None )

Color context objects randomly.

Parameters

obj_ids Optional list of object IDs to color (None for all)

Exceptions

ValueError	If object IDs are invalid
VisualizerError	If operation fails

Definition at line 2717 of file Visualizer.py.

◆ colorContextPrimitivesByData()

None pyhelios.Visualizer.Visualizer.colorContextPrimitivesByData	(		self,
		str	data_name,
		Optional[List[int]]	uuids = None )

Color context primitives based on primitive data values.

   This method maps primitive data values to colors using the current colormap.
   The visualization will be updated to show data variations across primitives.

   The data must have been previously set on the primitives in the Context using
   context.setPrimitiveDataFloat(UUID, data_name, value) before calling this method.

Parameters

data_name	Name of the primitive data to use for coloring. This should match the data label used with setPrimitiveDataFloat().
uuids	Optional list of specific primitive UUIDs to color. If None, all primitives in context will be colored.

Exceptions

VisualizerError	If visualizer is not initialized or operation fails
ValueError	If data_name is invalid or UUIDs are malformed

Example: >>> # Set data on primitives in context >>> context.setPrimitiveDataFloat(patch_uuid, "radiation_flux_SW", 450.2) >>> context.setPrimitiveDataFloat(triangle_uuid, "radiation_flux_SW", 320.1) >>> >>> # Build geometry and color by data >>> visualizer.buildContextGeometry(context) >>> visualizer.colorContextPrimitivesByData("radiation_flux_SW") >>> visualizer.plotInteractive()

: >>> # Color only specific primitives >>> visualizer.colorContextPrimitivesByData("temperature", [uuid1, uuid2, uuid3])

Definition at line 770 of file Visualizer.py.

◆ colorContextPrimitivesByObjectData()

None pyhelios.Visualizer.Visualizer.colorContextPrimitivesByObjectData	(		self,
		str	data_name,
		Optional[List[int]]	obj_ids = None )

Color context primitives by object data.

Parameters

data_name	Name of object data to use for coloring
obj_ids	Optional list of object IDs to color (None for all)

Exceptions

ValueError	If parameters are invalid
VisualizerError	If operation fails

Definition at line 2652 of file Visualizer.py.

◆ colorContextPrimitivesRandomly()

None pyhelios.Visualizer.Visualizer.colorContextPrimitivesRandomly	(		self,
		Optional[List[int]]	uuids = None )

Color context primitives randomly.

Parameters

uuids Optional list of primitive UUIDs to color (None for all)

Exceptions

ValueError	If UUIDs are invalid
VisualizerError	If operation fails

Definition at line 2686 of file Visualizer.py.

◆ deleteGeometry()

None pyhelios.Visualizer.Visualizer.deleteGeometry	(		self,
		int	geometry_id )

Delete specific geometry by ID.

Parameters

geometry_id ID of geometry to delete

Exceptions

ValueError	If geometry ID is invalid
VisualizerError	If operation fails

Definition at line 2144 of file Visualizer.py.

◆ disableColorbar()

None pyhelios.Visualizer.Visualizer.disableColorbar ( self )

Disable colorbar.

Exceptions

VisualizerError If operation fails

Definition at line 2364 of file Visualizer.py.

◆ disableCoordinateAxes()

None pyhelios.Visualizer.Visualizer.disableCoordinateAxes ( self )

Remove coordinate axes.

Exceptions

VisualizerError If operation fails

Definition at line 2299 of file Visualizer.py.

◆ disableExactColorMode()

None pyhelios.Visualizer.Visualizer.disableExactColorMode ( self )

Restore the default brightening of primitive colors.

   This also restores the linear-light pipeline (see :meth:`enableLinearPipeline`).

Exceptions

VisualizerError If the operation fails

Example: >>> vis.disableExactColorMode()

Definition at line 1186 of file Visualizer.py.

◆ disableLinearPipeline()

None pyhelios.Visualizer.Visualizer.disableLinearPipeline ( self )

Disable the linear-light pipeline, shading directly in sRGB space.

   This reproduces the rendering behavior of helios-core versions before 1.3.83.

Exceptions

VisualizerError If the operation fails

Example: >>> vis.disableLinearPipeline()

Definition at line 1228 of file Visualizer.py.

◆ disableMessages()

None pyhelios.Visualizer.Visualizer.disableMessages ( self )

Disable standard output from visualizer plugin.

Exceptions

VisualizerError If operation fails

Definition at line 2867 of file Visualizer.py.

◆ disableSmoothShading()

None pyhelios.Visualizer.Visualizer.disableSmoothShading ( self )

Select flat (per-face) shading.

   Useful for alpha-masked cutout geometry such as leaf textures, where interpolated
   normals can look worse than a single flat normal per face.

Exceptions

VisualizerError If the operation fails

Example: >>> vis.disableSmoothShading()

Definition at line 1474 of file Visualizer.py.

◆ displayImageFromFile()

None pyhelios.Visualizer.Visualizer.displayImageFromFile	(		self,
		str	filename )

Display image from file.

Parameters

filename Path to image file

Exceptions

ValueError	If filename is invalid
VisualizerError	If operation fails

Definition at line 1008 of file Visualizer.py.

◆ displayImageFromPixels()

None pyhelios.Visualizer.Visualizer.displayImageFromPixels	(		self,
		List[int]	pixel_data,
		int	width,
		int	height )

Display image from RGBA pixel data.

Parameters

pixel_data	RGBA pixel data as list of integers (0-255)
width	Image width in pixels
height	Image height in pixels

Exceptions

ValueError	If parameters are invalid
VisualizerError	If operation fails

Definition at line 976 of file Visualizer.py.

◆ displayImageWithBoundingBoxes()

None pyhelios.Visualizer.Visualizer.displayImageWithBoundingBoxes	(		self,
		str	image_file,
		str	bbox_file,
		str	classes_file = "",
		float	line_width = 2.0,
		int	fontsize = 12 )

Display an image with YOLO bounding boxes overlaid.

   Each box is drawn as a colored outline with its class name on a filled chip in
   the box's top-left corner. Boxes are colored by class ID from a fixed palette of
   seven colors, so classes whose IDs differ by a multiple of seven share a color.

   This reads the annotation format written by
   :meth:`pyhelios.RadiationModel.writeImageBoundingBoxes`.

Parameters

image_file	Path to the image file (JPEG or PNG)
bbox_file	Path to the YOLO-format bounding box annotation file
classes_file	Path to the class name file. If empty (the default), a file named "classes.txt" beside `bbox_file` is used when one exists; otherwise boxes are labeled with their numeric class ID.
line_width	Width of the box outlines in screen pixels
fontsize	Size of the class label font in points

Exceptions

ValueError	If a path is not a non-empty string, or a numeric argument is out of range
VisualizerError	If the operation fails

Note: Like :meth:displayImageFromFile, this clears any existing geometry and does not return until the window is closed.

Example: >>> vis.displayImageWithBoundingBoxes("scene.jpeg", "scene.txt")

Definition at line 1050 of file Visualizer.py.

◆ displayImageWithSegmentationMasks()

None pyhelios.Visualizer.Visualizer.displayImageWithSegmentationMasks	(		self,
		str	image_file,
		str	mask_file,
		float	fill_opacity = 0.4,
		float	line_width = 2.0,
		int	fontsize = 12,
		bool	show_labels = True )

Display an image with COCO segmentation masks overlaid.

   Each mask is drawn as a translucent filled polygon with a solid outline and its
   class name on a filled chip. Masks are colored by their position in the file
   rather than by class, so two touching objects of the same class stay
   distinguishable.

   This reads the annotation format written by
   :meth:`pyhelios.RadiationModel.writeImageSegmentationMasks`.

Parameters

image_file	Path to the image file (JPEG or PNG)
mask_file	Path to the COCO JSON segmentation mask file
fill_opacity	Opacity of the translucent fill, between 0 and 1. A value of 0 draws the outline without a fill.
line_width	Width of the mask outlines in screen pixels
fontsize	Size of the class label font in points
show_labels	Whether to draw the class name chip on each mask. Pass False to see the masks alone, which helps when many overlapping chips would cover the image.

Exceptions

ValueError	If a path is not a non-empty string, or a numeric argument is out of range
VisualizerError	If the operation fails

Note: Like :meth:displayImageFromFile, this clears any existing geometry and does not return until the window is closed.

Example: >>> vis.displayImageWithSegmentationMasks("scene.jpeg", "annotations.json")

Definition at line 1112 of file Visualizer.py.

◆ enableColorbar()

None pyhelios.Visualizer.Visualizer.enableColorbar ( self )

Enable colorbar.

Exceptions

VisualizerError If operation fails

Definition at line 2349 of file Visualizer.py.

◆ enableExactColorMode()

None pyhelios.Visualizer.Visualizer.enableExactColorMode ( self )

Render primitive colors exactly as they are set in the Context.

   By default the fragment shader multiplies primitive colors by 1.5, which
   brightens ordinary renders but means a color read back out of the framebuffer is
   not the color that was set. This mode disables that multiplier, which is required
   when the framebuffer carries data rather than an image -- for example when object
   IDs are encoded as RGB values and decoded from the rendered pixels.

   Exact reproduction additionally requires that no lighting be applied (see
   :meth:`setLightingModel` with ``LIGHTING_NONE``, the default) and that the
   Visualizer was constructed with ``antialiasing_samples=0``, since antialiasing
   blends colors at primitive edges and produces pixels that decode to meaningless
   IDs.

   This also disables the linear-light pipeline (see :meth:`disableLinearPipeline`),
   since tone mapping would likewise alter the values read back.

Exceptions

VisualizerError If the operation fails

Example: >>> vis = Visualizer(800, 600, antialiasing_samples=0) >>> vis.enableExactColorMode()

Definition at line 1167 of file Visualizer.py.

◆ enableLinearPipeline()

None pyhelios.Visualizer.Visualizer.enableLinearPipeline ( self )

Enable the physically-based linear-light rendering pipeline.

   This is the default. Albedo is decoded from sRGB to linear light before shading,
   and the shaded radiance is tone-mapped through an ACES filmic curve and
   re-encoded to sRGB. Compared with shading directly on non-linear sRGB values,
   mid-tones are brighter, shadow terminators are smoother, and bright surfaces roll
   off rather than clipping flat against the 8-bit framebuffer.

Exceptions

VisualizerError If the operation fails

Example: >>> vis.enableLinearPipeline()

Definition at line 1209 of file Visualizer.py.

◆ enableMessages()

None pyhelios.Visualizer.Visualizer.enableMessages ( self )

Enable standard output from visualizer plugin.

Exceptions

VisualizerError If operation fails

Definition at line 2852 of file Visualizer.py.

◆ enableSmoothShading()

None pyhelios.Visualizer.Visualizer.enableSmoothShading ( self )

Enable smooth per-vertex-normal shading.

   This is the default. Only geometry that supplies distinct vertex normals is
affected    Sphere, Tube and Cone objects, and Polymesh objects loaded from an OBJ
   or PLY file that carries them. Patches, triangles and voxels added directly to
   the Context carry the face normal replicated across their vertices and render
   identically either way.

Exceptions

VisualizerError If the operation fails

Example: >>> vis.enableSmoothShading()

Definition at line 1454 of file Visualizer.py.

◆ getAmbientGroundColor()

RGBcolor pyhelios.Visualizer.Visualizer.getAmbientGroundColor ( self )

Get the hemispheric ambient ground-bounce color.

Returns: Color of ambient light bouncing from below

Exceptions

VisualizerError If the operation fails

Example: >>> vis.getAmbientGroundColor()

Definition at line 1430 of file Visualizer.py.

◆ getAmbientSkyColor()

RGBcolor pyhelios.Visualizer.Visualizer.getAmbientSkyColor ( self )

Get the hemispheric ambient sky color.

Returns: Color of ambient light arriving from above

Exceptions

VisualizerError If the operation fails

Example: >>> vis.getAmbientSkyColor()

Definition at line 1409 of file Visualizer.py.

◆ getBackgroundColor()

RGBcolor pyhelios.Visualizer.Visualizer.getBackgroundColor ( self )

Get current background color.

Returns: Background color as RGBcolor object

Exceptions

VisualizerError If operation fails

Definition at line 860 of file Visualizer.py.

◆ getCameraPosition()

Tuple[vec3, vec3] pyhelios.Visualizer.Visualizer.getCameraPosition ( self )

Get current camera position and look-at point.

Returns: Tuple of (camera_position, look_at_point) as vec3 objects

Exceptions

VisualizerError If operation fails

Definition at line 835 of file Visualizer.py.

◆ getDepthImage()

Tuple[List[float], int, int] pyhelios.Visualizer.Visualizer.getDepthImage ( self )

Get the distance from the camera to the nearest surface in each pixel of the current view.

   The depth is the distance in world units from the camera to the visible surface,
   measured along the camera viewing direction, so geometry lying in a plane
   perpendicular to the viewing direction has one depth across the whole image. This is
   the same definition as the camera depth images of the radiation plug-in
   (:meth:`pyhelios.RadiationModel.writeDepthImageData`).

   The frame is rendered as part of the call if needed, as for :meth:`printWindow`.

Returns: Tuple of (depth_pixels, width, height). depth_pixels is row-major with row 0 at the TOP of the image (the orientation of an image saved by :meth:printWindow). Pixels in which no geometry is visible hold -1. width and height are the framebuffer dimensions (see :meth:getFramebufferSize).

Exceptions

VisualizerError If the operation fails

Note

Geometry nearer than the near clipping plane (5% of the camera-to-look-at distance, and no nearer than 0.1) is not visible and is absent here.
Semi-transparent primitives (color alpha < 1) are treated as opaque.
Lines, points, the sky dome and 2D overlays (colorbar, watermark, text) have no depth; a pixel showing only these holds -1.

Example: >>> depth, width, height = visualizer.getDepthImage() >>> center = depth[(height // 2) * width + width // 2]

Definition at line 1766 of file Visualizer.py.

◆ getDepthMap()

Tuple[List[float], int, int] pyhelios.Visualizer.Visualizer.getDepthMap ( self )

Get the normalized depth map of the current view.

   The values are the non-linear depth buffer values of the current frame, rescaled
   between the nearest and farthest of them and inverted, so that 255 is the nearest
   surface in view and 0 the farthest (including background). This is the image shown
   by :meth:`plotDepthMap`. It is **not** a distance: use :meth:`getDepthImage` for
   depth in world units.

Returns: Tuple of (depth_pixels, width, height). depth_pixels is row-major with row 0 at the BOTTOM of the image. width and height are the framebuffer dimensions (see :meth:getFramebufferSize), which are larger than the window on a high-DPI display.

Exceptions

VisualizerError If operation fails

Definition at line 1692 of file Visualizer.py.

◆ getExposure()

float pyhelios.Visualizer.Visualizer.getExposure ( self )

Get the linear exposure multiplier applied before tone mapping.

Returns: Current exposure multiplier

Exceptions

VisualizerError If the operation fails

Example: >>> vis.getExposure() 1.0

Definition at line 1297 of file Visualizer.py.

◆ getFramebufferSize()

Tuple[int, int] pyhelios.Visualizer.Visualizer.getFramebufferSize ( self )

Get framebuffer size in pixels.

Returns: Tuple of (width, height) in pixels

Exceptions

VisualizerError If operation fails

Definition at line 934 of file Visualizer.py.

◆ getGeometryVertices()

List[vec3] pyhelios.Visualizer.Visualizer.getGeometryVertices	(		self,
		int	geometry_id )

Get vertices of a geometry primitive.

Parameters

geometry_id Unique identifier of the geometry primitive

Returns: List of vertices as vec3 objects

Exceptions

ValueError	If geometry ID is invalid
VisualizerError	If operation fails

Example: >>> # Get vertices of a specific geometry >>> vertices = visualizer.getGeometryVertices(geometry_id) >>> for vertex in vertices: ... print(f"Vertex: ({vertex.x}, {vertex.y}, {vertex.z})")

Definition at line 2192 of file Visualizer.py.

◆ getPhongMaterial()

Tuple[float, float, float, float] pyhelios.Visualizer.Visualizer.getPhongMaterial ( self )

Get the Phong material parameters used to shade Context primitives.

Returns: Tuple of (ambient, diffuse, specular, shininess)

Exceptions

VisualizerError If the operation fails

Example: >>> ambient, diffuse, specular, shininess = vis.getPhongMaterial()

Definition at line 1354 of file Visualizer.py.

◆ getPixelUUIDs()

Tuple[List[int], int, int] pyhelios.Visualizer.Visualizer.getPixelUUIDs ( self )

Get the Context primitive visible in each pixel of the current view.

   This is the pixel-to-primitive map from which bounding boxes and segmentation masks are
   computed. It is exact: it does not depend on primitive colors, lighting, or the
   anti-aliasing the Visualizer was created with, and producing it does not modify the
   Context. The frame is rendered as part of the call if needed, as for :meth:`printWindow`.

Returns: Tuple of (pixel_UUIDs, width, height). Each element of pixel_UUIDs is the UUID of the visible primitive plus one; 0 means no Context primitive is visible (background, or geometry added directly to the Visualizer). Subtract 1 from a non-zero value to get the UUID. The map is row-major with row 0 at the TOP of the image, and is in the form the :mod:pyhelios.annotation functions accept. width and height are the framebuffer dimensions.

Exceptions

VisualizerError If the operation fails

Note

A primitive whose texture has a transparency channel is visible only where its texture is opaque.
Semi-transparent primitives (color alpha < 1) are treated as opaque.
Lines, points, the sky dome and 2D overlays are not part of the map and do not hide primitives behind them.

Example: >>> pixels, width, height = visualizer.getPixelUUIDs() >>> visible = {p - 1 for p in pixels if p != 0}

Definition at line 1808 of file Visualizer.py.

◆ getPointRenderingMetrics()

dict pyhelios.Visualizer.Visualizer.getPointRenderingMetrics ( self )

Get point cloud rendering performance metrics.

   Provides detailed statistics about point cloud culling and rendering
   performance, useful for optimizing visualization settings.

Returns

Dictionary with keys:

'total_points' (int): Total number of points in the scene
'rendered_points' (int): Number of points actually rendered after culling
'culling_time_ms' (float): Time spent on culling in milliseconds

Exceptions

VisualizerError If operation fails

Example: >>> metrics = vis.getPointRenderingMetrics() >>> print(f"Total: {metrics['total_points']}") >>> print(f"Rendered: {metrics['rendered_points']}") >>> cull_rate = (1 - metrics['rendered_points']/metrics['total_points']) * 100 >>> print(f"Culling rate: {cull_rate:.1f}%")

Note: Metrics are only meaningful after calling plotUpdate() or plotInteractive(). The culling_time_ms represents CPU time spent on culling calculations, not total frame time.

Definition at line 3092 of file Visualizer.py.

◆ getTextboxSize()

vec2 pyhelios.Visualizer.Visualizer.getTextboxSize	(		self,
		str	textstring,
		int	fontsize,
		str	fontname )

Measure the rendered size of a text string without adding it to the visualizer.

   Returns the extent that :meth:`addTextboxByCenter` would occupy for the same
   string, font and font size. The width is the sum of the glyph advances, so it
   includes the side bearings; the height is that of the tallest glyph in the
   string, so it depends on which characters the string contains. The ``_`` and
   ``^`` subscript and superscript markers are handled as
   :meth:`addTextboxByCenter` handles them: they occupy no width themselves and
   halve the size of the character that follows.

Parameters

textstring	Text to be measured
fontsize	Size of the text font in points
fontname	Name of a font in the visualizer fonts directory, e.g. "OpenSans-Regular"

Returns: Width and height of the text in window-normalized units.

Exceptions

ValueError	If an argument is invalid
VisualizerError	If the operation fails

Note: The result depends on the current framebuffer dimensions and DPI scale, and therefore changes when the window is resized.

Example: >>> size = vis.getTextboxSize("Leaf area", 14, "OpenSans-Regular") >>> print(f"{size.x:.3f} x {size.y:.3f}")

Definition at line 1567 of file Visualizer.py.

◆ getWindowPixelsRGB()

pyhelios.Visualizer.Visualizer.getWindowPixelsRGB	(		self,
		Optional[List[int]]	buffer = None )

Get RGB pixel data from the current window.

   Data is stored as r-g-b * column * row, so indices (0,1,2) are the RGB values for row 0
   column 0, indices (3,4,5) are row 0 column 1, and so on.

   Call without arguments to have the buffer allocated for you at the correct size -- this is
   the recommended form and cannot be undersized::

       pixels, width, height = visualizer.getWindowPixelsRGB()

Parameters

buffer Optional pre-allocated list to fill in place. It must hold exactly 3 * width * height elements, where width and height come from :meth:getFramebufferSize – not :meth:getWindowSize and not the dimensions passed to the constructor. On a high-DPI (Retina) display the framebuffer is larger than the window, typically by a factor of two per axis, so a buffer sized from the window dimensions is four times too small.

Returns: If buffer is None, a tuple of (pixel_data, width, height). Otherwise None; buffer is filled in place.

Exceptions

ValueError	If ``buffer`` is not a list, or is not sized for the current framebuffer
VisualizerError	If operation fails

Definition at line 1619 of file Visualizer.py.

◆ getWindowSize()

Tuple[int, int] pyhelios.Visualizer.Visualizer.getWindowSize ( self )

Get window size in pixels.

Returns: Tuple of (width, height) in pixels

Exceptions

VisualizerError If operation fails

Definition at line 911 of file Visualizer.py.

◆ hideNavigationGizmo()

None pyhelios.Visualizer.Visualizer.hideNavigationGizmo ( self )

Hide navigation gizmo (coordinate axes indicator in corner).

   The navigation gizmo shows XYZ axes orientation and can be clicked
   to snap the camera to standard views (top, front, side, etc.).

Exceptions

VisualizerError If operation fails

Definition at line 2811 of file Visualizer.py.

◆ hideWatermark()

None pyhelios.Visualizer.Visualizer.hideWatermark ( self )

Hide Helios logo watermark.

Exceptions

VisualizerError If operation fails

Definition at line 2761 of file Visualizer.py.

◆ isHeadlessMultisamplingActive()

bool pyhelios.Visualizer.Visualizer.isHeadlessMultisamplingActive ( self )

Check whether headless rendering obtained multisampled framebuffer attachments.

   Headless rendering draws into a multisampled framebuffer using the sample count
   given to the constructor and resolves it before readback, so saved images are
   anti-aliased. The requested count is clamped to the driver maximum, and a driver
   that refuses the attachments falls back silently -- this query is how to detect
   that.

Returns: True if multisampled attachments were obtained

Note: macOS drives OpenGL through a translation layer that accepts the attachments but does not rasterize into them, so this can report True while the saved image is not actually anti-aliased.

Exceptions

VisualizerError If the operation fails

Example: >>> vis.isHeadlessMultisamplingActive() True

Definition at line 1527 of file Visualizer.py.

◆ isLinearPipelineEnabled()

bool pyhelios.Visualizer.Visualizer.isLinearPipelineEnabled ( self )

Check whether the linear-light rendering pipeline is enabled.

Returns: True if the linear pipeline is enabled

Exceptions

VisualizerError If the operation fails

Example: >>> vis.isLinearPipelineEnabled() True

Definition at line 1249 of file Visualizer.py.

◆ isSmoothShadingEnabled()

bool pyhelios.Visualizer.Visualizer.isSmoothShadingEnabled ( self )

Check whether smooth per-vertex-normal shading is enabled.

Returns: True if smooth shading is enabled

Exceptions

VisualizerError If the operation fails

Example: >>> vis.isSmoothShadingEnabled() True

Definition at line 1495 of file Visualizer.py.

◆ plotDepthMap()

None pyhelios.Visualizer.Visualizer.plotDepthMap ( self )

Plot depth map visualization.

Exceptions

VisualizerError If operation fails

Definition at line 1723 of file Visualizer.py.

◆ plotInteractive()

None pyhelios.Visualizer.Visualizer.plotInteractive ( self )

Open interactive visualization window.

   This method opens a window with the current scene and allows user
   interaction (camera rotation, zooming, etc.). The program will pause
   until the window is closed by the user.

   Interactive controls:
   - Mouse scroll: Zoom in/out
   - Left mouse + drag: Rotate camera
   - Right mouse + drag: Pan camera
   - Arrow keys: Camera movement
   - +/- keys: Zoom in/out

Exceptions

VisualizerError If visualization fails, or if the Visualizer was constructed with headless=True (helios-core 1.3.85+ raises rather than driving a window that was never shown or does not exist)

Definition at line 348 of file Visualizer.py.

◆ plotOnce()

None pyhelios.Visualizer.Visualizer.plotOnce	(		self,
		bool	get_keystrokes = True )

Run one rendering loop.

   Any geometry pending upload is transferred to the GPU before rendering, but unlike
   :meth:`plotUpdate` the Context geometry is not rebuilt. Call :meth:`buildContextGeometry`
   or :meth:`plotUpdate` if primitives have been added to or changed in the Context since the
   last render.

Parameters

get_keystrokes Whether to process keystrokes

Exceptions

VisualizerError If operation fails

Definition at line 2890 of file Visualizer.py.

◆ plotUpdate()

None pyhelios.Visualizer.Visualizer.plotUpdate ( self )

Update visualization (non-interactive).

   This method updates the visualization window without user interaction.
   The program continues immediately after rendering. Useful for batch
   processing or creating image sequences.

   In headless mode, automatically hides the window to prevent graphics driver crashes on some platforms.

Exceptions

VisualizerError If visualization update fails

Definition at line 372 of file Visualizer.py.

◆ plotUpdateWithVisibility()

None pyhelios.Visualizer.Visualizer.plotUpdateWithVisibility	(		self,
		bool	hide_window = False )

Update visualization with window visibility control.

Parameters

hide_window Whether to hide the window during update

Exceptions

VisualizerError If operation fails

Definition at line 2908 of file Visualizer.py.

◆ printWindow()

None pyhelios.Visualizer.Visualizer.printWindow	(		self,
		str	filename,
		Optional[str]	image_format = None )

Save current visualization to image file.

   This method exports the current visualization to an image file.
   Starting from v1.3.53, supports both JPEG and PNG formats.

   The frame is rendered as part of the capture (helios-core 1.3.85+), so it is
   not necessary to call :meth:`plotUpdate` beforehand: handing the Visualizer a
   Context with :meth:`buildContextGeometry` and calling this straight away
   produces a correct image. Calling :meth:`plotUpdate` first is harmless but
   redundant. The navigation gizmo is always absent from the captured image.

Parameters

filename	Output filename for image Can be absolute or relative to user's current working directory Extension (.jpg, .png) is recommended but not required
image_format	Image format - "jpeg" or "png" (v1.3.53+). If None, automatically detects from filename extension. Defaults to "jpeg" if not detectable from extension.

Exceptions

VisualizerError	If image saving fails
ValueError	If filename or format is invalid

Note: PNG format is required to preserve transparent backgrounds when using setBackgroundTransparent(). JPEG format will render transparent areas as black.

Example: >>> visualizer.printWindow("output.jpg") # Auto-detects JPEG >>> visualizer.printWindow("output.png") # Auto-detects PNG >>> visualizer.printWindow("output.img", image_format="png") # Explicit PNG

Definition at line 419 of file Visualizer.py.

◆ printWindowDefault()

None pyhelios.Visualizer.Visualizer.printWindowDefault ( self )

Print window with default filename.

Exceptions

VisualizerError If operation fails

Definition at line 954 of file Visualizer.py.

◆ setAmbientColors()

None pyhelios.Visualizer.Visualizer.setAmbientColors	(		self,
		RGBcolor	sky_color,
		RGBcolor	ground_color )

Set the hemispheric ambient sky and ground-bounce colors.

   Ambient light is blended between the two according to surface orientation:
   upward-facing surfaces pick up ``sky_color``, downward-facing surfaces
   ``ground_color``. Setting both to the same value recovers the single constant
   ambient term used before helios-core 1.3.83.

Parameters

sky_color	Color of light arriving from above
ground_color	Color of light bouncing from below

Exceptions

ValueError	If either argument is not an RGBcolor
VisualizerError	If the operation fails

Example: >>> vis.setAmbientColors(RGBcolor(0.5, 0.6, 0.75), RGBcolor(0.35, 0.3, 0.22))

Definition at line 1381 of file Visualizer.py.

◆ setBackgroundColor()

None pyhelios.Visualizer.Visualizer.setBackgroundColor	(		self,
		RGBcolor	color )

Set background color.

Parameters

color Background color as RGBcolor with values in range [0, 1]

Exceptions

VisualizerError	If color setting fails
ValueError	If color values are invalid

Definition at line 549 of file Visualizer.py.

◆ setBackgroundImage()

None pyhelios.Visualizer.Visualizer.setBackgroundImage	(		self,
		str	texture_file )

Set custom background image texture (v1.3.53+).

Parameters

texture_file Path to background image file Can be absolute or relative to working directory

Exceptions

VisualizerError	If background image setting fails
ValueError	If texture file path is invalid

Definition at line 601 of file Visualizer.py.

◆ setBackgroundSkyTexture()

None pyhelios.Visualizer.Visualizer.setBackgroundSkyTexture	(		self,
		Optional[str]	texture_file = None,
		int	divisions = 50 )

Set sky sphere texture background with automatic scaling (v1.3.53+).

   Creates a sky sphere that automatically scales with the scene.
   Replaces the deprecated addSkyDomeByCenter() method.

Parameters

texture_file	Path to spherical/equirectangular texture image If None, uses default gradient sky texture
divisions	Number of sphere tessellation divisions (default: 50) Higher values create smoother sphere but use more GPU

Exceptions

VisualizerError	If sky texture setting fails
ValueError	If parameters are invalid

Example: >>> visualizer.setBackgroundSkyTexture() # Default gradient sky >>> visualizer.setBackgroundSkyTexture("sky_hdri.jpg", divisions=100)

Definition at line 637 of file Visualizer.py.

◆ setBackgroundTransparent()

None pyhelios.Visualizer.Visualizer.setBackgroundTransparent ( self )

Enable transparent background mode (v1.3.53+).

   Sets the background to transparent with checkerboard pattern display.
   Requires PNG output format to preserve transparency.

Note: When using transparent background, use printWindow() with PNG format to save transparent images.

Exceptions

VisualizerError If transparent background setting fails

Definition at line 579 of file Visualizer.py.

◆ setCameraFieldOfView()

None pyhelios.Visualizer.Visualizer.setCameraFieldOfView	(		self,
		float	angle_FOV )

Set camera field of view angle.

Parameters

angle_FOV Field of view angle in degrees

Exceptions

ValueError	If angle is invalid
VisualizerError	If operation fails

Definition at line 810 of file Visualizer.py.

◆ setCameraPosition()

None pyhelios.Visualizer.Visualizer.setCameraPosition	(		self,
		vec3	position,
		vec3	lookAt )

Set camera position using Cartesian coordinates.

Parameters

position	Camera position as vec3 in world coordinates
lookAt	Camera look-at point as vec3 in world coordinates

Exceptions

VisualizerError	If camera positioning fails
ValueError	If parameters are invalid

Definition at line 496 of file Visualizer.py.

◆ setCameraPositionSpherical()

None pyhelios.Visualizer.Visualizer.setCameraPositionSpherical	(		self,
		SphericalCoord	angle,
		vec3	lookAt )

Set camera position using spherical coordinates.

Parameters

angle	Camera position as SphericalCoord (radius, elevation, azimuth)
lookAt	Camera look-at point as vec3 in world coordinates

Exceptions

VisualizerError	If camera positioning fails
ValueError	If parameters are invalid

Definition at line 523 of file Visualizer.py.

◆ setColorbarFontColor()

None pyhelios.Visualizer.Visualizer.setColorbarFontColor	(		self,
		RGBcolor	color )

Set colorbar font color.

Parameters

color Font color

Exceptions

ValueError	If color is invalid
VisualizerError	If operation fails

Definition at line 2519 of file Visualizer.py.

◆ setColorbarFontSize()

None pyhelios.Visualizer.Visualizer.setColorbarFontSize	(		self,
		int	font_size )

Set colorbar font size.

Parameters

font_size Font size

Exceptions

ValueError	If font size is invalid
VisualizerError	If operation fails

Definition at line 2542 of file Visualizer.py.

◆ setColorbarPosition()

None pyhelios.Visualizer.Visualizer.setColorbarPosition	(		self,
		vec3	position )

Set colorbar position.

Parameters

position Colorbar position

Exceptions

ValueError	If position is invalid
VisualizerError	If operation fails

Definition at line 2383 of file Visualizer.py.

◆ setColorbarRange()

None pyhelios.Visualizer.Visualizer.setColorbarRange	(		self,
		float	min_val,
		float	max_val )

Set colorbar range.

   Setting a range explicitly stops the colorbar from auto-ranging over the data, including
   for the degenerate range ``setColorbarRange(0, 0)``.

Parameters

min_val	Minimum value
max_val	Maximum value. Must be greater than or equal to `min_val`; helios ignores an inverted range.

Exceptions

ValueError	If range is invalid
VisualizerError	If operation fails

Definition at line 2437 of file Visualizer.py.

◆ setColorbarSize()

None pyhelios.Visualizer.Visualizer.setColorbarSize	(		self,
		float	width,
		float	height )

Set colorbar size.

Parameters

width	Colorbar width
height	Colorbar height

Exceptions

ValueError	If size is invalid
VisualizerError	If operation fails

Definition at line 2407 of file Visualizer.py.

◆ setColorbarTicks()

None pyhelios.Visualizer.Visualizer.setColorbarTicks	(		self,
		List[float]	ticks )

Set colorbar tick marks.

Parameters

ticks List of tick values

Note: If a tick value falls outside the colorbar range, the range is automatically expanded to fit it. Because the colormap limits follow the colorbar range, this changes the colors shown as well as the labels. To keep an explicit range authoritative, call :meth:setColorbarRange after :meth:setColorbarTicks.

Exceptions

ValueError	If ticks are invalid
VisualizerError	If operation fails

Definition at line 2469 of file Visualizer.py.

◆ setColorbarTitle()

None pyhelios.Visualizer.Visualizer.setColorbarTitle	(		self,
		str	title )

Set colorbar title.

Parameters

title Colorbar title

Exceptions

ValueError	If title is invalid
VisualizerError	If operation fails

Definition at line 2497 of file Visualizer.py.

◆ setColormap()

None pyhelios.Visualizer.Visualizer.setColormap	(		self,
		Union[int, str]	colormap )

Set predefined colormap.

Parameters

colormap Colormap ID (one of the COLORMAP_* class constants: 0-5 or 7-9) or name ("HOT", "COOL", "RAINBOW", "LAVA", "PARULA", "GRAY", "LINES", "ALGAE", "GREEN"). ID 6 is the custom colormap, which is set with :meth:setCustomColormap. Each predefined colormap is identical to the Context colormap of the same name (see :meth:pyhelios.Context.Context.getColormapControlPoints).

Exceptions

ValueError	If colormap is invalid
VisualizerError	If operation fails

Definition at line 2571 of file Visualizer.py.

◆ setCustomColormap()

None pyhelios.Visualizer.Visualizer.setCustomColormap	(		self,
		List[RGBcolor]	colors,
		List[float]	divisions )

Set custom colormap.

Parameters

colors	List of RGB colors
divisions	List of division points (same length as colors)

Exceptions

ValueError	If parameters are invalid
VisualizerError	If operation fails

Definition at line 2609 of file Visualizer.py.

◆ setExposure()

None pyhelios.Visualizer.Visualizer.setExposure	(		self,
		float	exposure )

Set the linear exposure multiplier applied before tone mapping.

   Only has an effect while the linear pipeline is enabled.

Parameters

exposure Exposure multiplier; must be positive

Exceptions

ValueError	If exposure is not positive
VisualizerError	If the operation fails

Example: >>> vis.setExposure(1.5)

Definition at line 1272 of file Visualizer.py.

◆ setGeometryVertices()

None pyhelios.Visualizer.Visualizer.setGeometryVertices	(		self,
		int	geometry_id,
		List[vec3]	vertices )

Set vertices of a geometry primitive.

   This allows dynamic modification of geometry shapes during visualization.
   Useful for animating geometry or adjusting shapes based on simulation results.

Parameters

geometry_id	Unique identifier of the geometry primitive
vertices	List of new vertices as vec3 objects

Exceptions

ValueError	If parameters are invalid
VisualizerError	If operation fails

Example: >>> # Modify vertices of an existing geometry >>> vertices = visualizer.getGeometryVertices(geometry_id) >>> # Scale all vertices by 2x >>> scaled_vertices = [vec3(v.x*2, v.y*2, v.z*2) for v in vertices] >>> visualizer.setGeometryVertices(geometry_id, scaled_vertices)

Definition at line 2227 of file Visualizer.py.

◆ setLightDirection()

None pyhelios.Visualizer.Visualizer.setLightDirection	(		self,
		vec3	direction )

Set light direction.

Parameters

direction Vector pointing from the scene toward the light source; for example, vec3(0, 0, 1) places the light directly overhead. It does not need to be a unit vector.

Exceptions

VisualizerError	If light direction setting fails
ValueError	If direction is invalid

Definition at line 680 of file Visualizer.py.

◆ setLightingModel()

None pyhelios.Visualizer.Visualizer.setLightingModel	(		self,
		Union[int, str]	lighting_model )

Set lighting model.

Parameters

lighting_model

Lighting model, either:

0 or "none": No lighting
1 or "phong": Phong shading
2 or "phong_shadowed": Phong shading with shadows

Exceptions

VisualizerError	If lighting model setting fails
ValueError	If lighting model is invalid

Definition at line 711 of file Visualizer.py.

◆ setLightIntensityFactor()

None pyhelios.Visualizer.Visualizer.setLightIntensityFactor	(		self,
		float	intensity_factor )

Set light intensity scaling factor.

Parameters

intensity_factor Light intensity scaling factor (typically 0.1 to 10.0)

Exceptions

ValueError	If intensity factor is invalid
VisualizerError	If operation fails

Definition at line 886 of file Visualizer.py.

◆ setPhongMaterial()

None pyhelios.Visualizer.Visualizer.setPhongMaterial	(		self,
		float	ambient,
		float	diffuse,
		float	specular,
		float	shininess )

Set the Phong material parameters used to shade Context primitives.

   Surfaces are shaded as ``ambient*A + diffuse*max(0, N.L) +
   specular*max(0, N.H)^shininess``, where ``A`` is the hemispheric ambient term set
   by :meth:`setAmbientColors`. Setting ``specular`` to zero removes the highlight,
   recovering the appearance of helios-core versions before 1.3.83. Has no effect
   under ``LIGHTING_NONE``.

   Individual materials can override any of these parameters by attaching
   ``phong_ambient``, ``phong_diffuse``, ``phong_specular`` or ``phong_shininess``
   material data with :meth:`Context.setMaterialDataFloat`; each parameter falls
   back individually to the value set here.

Parameters

ambient	Ambient reflectance weight
diffuse	Diffuse reflectance weight
specular	Specular highlight strength
shininess	Specular exponent controlling highlight tightness

Exceptions

VisualizerError If the operation fails

Example: >>> vis.setPhongMaterial(1.0, 0.8, 0.0, 32.0) # no specular highlight

Definition at line 1331 of file Visualizer.py.

◆ setPointCullingEnabled()

None pyhelios.Visualizer.Visualizer.setPointCullingEnabled	(		self,
		bool	enabled )

Enable or disable point cloud culling optimization.

   Point culling improves rendering performance for large point clouds by
   selectively rendering only points that are visible based on distance
   and density criteria.

Parameters

enabled True to enable culling, False to disable (default: True)

Exceptions

ValueError	If enabled is not a boolean
VisualizerError	If operation fails

Example: >>> with Visualizer(800, 600) as vis: ... vis.setPointCullingEnabled(False) # Disable for highest quality ... vis.setPointCullingEnabled(True) # Enable for better performance

Definition at line 2940 of file Visualizer.py.

◆ setPointCullingThreshold()

None pyhelios.Visualizer.Visualizer.setPointCullingThreshold	(		self,
		int	threshold )

Set the minimum number of points required to trigger culling.

   Culling is only activated when the total point count exceeds this threshold.
   This prevents unnecessary culling overhead for small point clouds.

Parameters

threshold Point count threshold (default: 10000). Set to 0 to always enable.

Exceptions

ValueError	If threshold is not a non-negative integer
VisualizerError	If operation fails

Example: >>> vis.setPointCullingThreshold(50000) # Only cull for >50k points >>> vis.setPointCullingThreshold(0) # Always enable culling

Definition at line 2969 of file Visualizer.py.

◆ setPointLODFactor()

None pyhelios.Visualizer.Visualizer.setPointLODFactor	(		self,
		float	factor )

Set the level-of-detail factor for distance-based culling.

   Controls how aggressively points are culled based on distance from camera.
   Higher values result in more aggressive culling (better performance, lower quality).
   Lower values preserve more points (higher quality, lower performance).

Parameters

factor LOD factor (default: 10.0, typical range: 1.0-50.0). Must be positive.

Exceptions

ValueError	If factor is not positive
VisualizerError	If operation fails

Example: >>> vis.setPointLODFactor(5.0) # Conservative culling >>> vis.setPointLODFactor(10.0) # Default culling >>> vis.setPointLODFactor(25.0) # Aggressive culling

Note: The LOD factor determines the rate at which point density decreases with distance. Higher factors mean points are culled more quickly as distance increases.

Definition at line 3045 of file Visualizer.py.

◆ setPointMaxRenderDistance()

None pyhelios.Visualizer.Visualizer.setPointMaxRenderDistance	(		self,
		float	distance )

Set the maximum rendering distance for points.

   Points beyond this distance from the camera are not rendered, improving
   performance for large scenes. The distance is measured in world units.

Parameters

distance Maximum distance in world units. Use 0 for auto mode (scene_size * 5.0)

Exceptions

ValueError	If distance is negative
VisualizerError	If operation fails

Example: >>> vis.setPointMaxRenderDistance(0.0) # Auto mode >>> vis.setPointMaxRenderDistance(100.0) # Fixed distance

Note: Setting distance to 0 enables automatic mode, which calculates the render distance based on the scene bounding box dimensions.

Definition at line 3004 of file Visualizer.py.

◆ showNavigationGizmo()

None pyhelios.Visualizer.Visualizer.showNavigationGizmo ( self )

Show navigation gizmo (coordinate axes indicator in corner).

   The navigation gizmo shows XYZ axes orientation and can be clicked
   to snap the camera to standard views (top, front, side, etc.).

Note: Navigation gizmo is shown by default in v1.3.53+.

Exceptions

VisualizerError If operation fails

Definition at line 2833 of file Visualizer.py.

◆ showWatermark()

None pyhelios.Visualizer.Visualizer.showWatermark ( self )

Show Helios logo watermark.

Exceptions

VisualizerError If operation fails

Definition at line 2776 of file Visualizer.py.

◆ updateContextPrimitiveColors()

None pyhelios.Visualizer.Visualizer.updateContextPrimitiveColors ( self )

Update context primitive colors.

Exceptions

VisualizerError If operation fails

Definition at line 2162 of file Visualizer.py.

◆ updateWatermark()

None pyhelios.Visualizer.Visualizer.updateWatermark ( self )

Update watermark geometry to match current window size.

Exceptions

VisualizerError If operation fails

Definition at line 2791 of file Visualizer.py.

◆ writeDepthImageData()

None pyhelios.Visualizer.Visualizer.writeDepthImageData	(		self,
		str	filename )

Write the depth image of the current view to a text file.

   The file holds one line per image row, starting from the top of the image, with the
   depth of each pixel in that row separated by spaces. See :meth:`getDepthImage` for the
   definition of depth. Pixels in which no geometry is visible are written as -1.

Parameters

filename Text file to write, which may include a path

Exceptions

ValueError	If filename is empty
VisualizerError	If writing fails

Definition at line 2047 of file Visualizer.py.

◆ writeDepthImageDataEXR()

None pyhelios.Visualizer.Visualizer.writeDepthImageDataEXR	(		self,
		str	filename )

Write the depth image of the current view to an EXR file with lossless float compression.

   See :meth:`getDepthImage` for the definition of depth. Pixels in which no geometry is
   visible are written as -1.

Parameters

filename EXR file to write, which may include a path

Exceptions

ValueError	If filename is empty
VisualizerError	If writing fails

Definition at line 2063 of file Visualizer.py.

◆ writeImageBoundingBoxes()

None pyhelios.Visualizer.Visualizer.writeImageBoundingBoxes	(		self,
			primitive_data_labels = None,
			object_data_labels = None,
			object_class_ids = None,
		str	image_file = "",
		str	classes_txt_file = "classes.txt",
		str	image_path = "./" )

Write bounding boxes for the current view in Ultralytics YOLO format.

   Objects are identified by a primitive data label (or, with ``object_data_labels``, an
   object data label of each primitive's parent object) of type ``uint`` or ``int``: all
   visible primitives carrying the same value of the label form one object, and one box is
   written per distinct value. Primitives without the label are not annotated. This is the
   labeling convention of :meth:`pyhelios.RadiationModel.writeImageBoundingBoxes`, and the
   boxes are computed by the same native routine.

   A box encloses whole every pixel in which the object is visible, so even an object
   visible in a single pixel has a box. The boxes are written to a text file named after
   the image with its extension replaced by ".txt", in ``image_path``, and describe the view
   at the time of the call. Save the image itself with :meth:`printWindow`, and check the
   output with :meth:`displayImageWithBoundingBoxes`.

   Supply exactly one of ``primitive_data_labels`` or ``object_data_labels``.

Parameters

primitive_data_labels	Primitive data label (str) or list of labels
object_data_labels	Object data label (str) or list of labels
object_class_ids	Class ID (int) for a single label, or a list of class IDs in the same order as the labels
image_file	Name of the image these boxes annotate. Only its stem is used, to name the output file.
classes_txt_file	Name of the class file to write within `image_path`. Each line holds a class ID and the data label it was given for.
image_path	Directory in which the output files are written (default: current working directory)

Exceptions

ValueError	If both or neither label arguments are given, lengths differ, or a class ID is negative
TypeError	If an argument has the wrong type
VisualizerError	If writing fails (e.g. the output directory cannot be written)

Note: Only uint and int label data is read. A primitive whose label has another type is treated as unlabeled and gets no box; this is not an error.

Example: >>> context.setPrimitiveDataUInt(leaf_uuids, "leaf_id", 1) >>> visualizer.printWindow("scene.jpeg") >>> visualizer.writeImageBoundingBoxes(primitive_data_labels="leaf_id", ... object_class_ids=0, image_file="scene.jpeg")

Definition at line 1911 of file Visualizer.py.

◆ writeImageSegmentationMasks()

None pyhelios.Visualizer.Visualizer.writeImageSegmentationMasks	(		self,
			primitive_data_labels = None,
			object_data_labels = None,
			object_class_ids = None,
		str	json_filename = "",
		str	image_file = "",
		Optional[List[str]]	data_attribute_labels = None,
		bool	append_file = False )

Write segmentation masks for the current view in COCO JSON format.

   Objects are identified by a primitive data label (or, with ``object_data_labels``, an
   object data label) of type ``uint`` or ``int``, as for :meth:`writeImageBoundingBoxes`.
   Each connected region of pixels sharing one value of the label becomes one annotation
   holding the outline of that region, so an object split in two by something in front of
   it yields two annotations. Parts hidden behind other geometry are not included. A region
   of only one or two pixels is too small to outline and is not written. This is the
   convention of :meth:`pyhelios.RadiationModel.writeImageSegmentationMasks`.

   Supply exactly one of ``primitive_data_labels`` or ``object_data_labels``. The output
   can be checked with :meth:`displayImageWithSegmentationMasks`.

Parameters

primitive_data_labels	Primitive data label (str) or list of labels
object_data_labels	Object data label (str) or list of labels
object_class_ids	Class ID (COCO category ID) for a single label, or a list in the same order as the labels
json_filename	Output JSON file, which may include a path. ".json" is appended if it has no such extension.
image_file	Image file these masks annotate, which must already exist (see :meth:`printWindow`)
data_attribute_labels	Optional primitive or object data labels of type int, uint, float or double whose mean over the pixels of each mask is written to that annotation's "attributes". A label that exists as both is read from primitive data. Labels that do not exist are ignored.
append_file	If True, annotations are added to an existing JSON file so one file can describe many images. If False, a new file is written.

Exceptions

ValueError	If both or neither label arguments are given, lengths differ, or a class ID is negative
TypeError	If an argument has the wrong type
VisualizerError	If writing fails (e.g. the image file does not exist)

Example: >>> visualizer.printWindow("scene.jpeg") >>> visualizer.writeImageSegmentationMasks(primitive_data_labels="leaf_id", ... object_class_ids=0, ... json_filename="annotations.json", ... image_file="scene.jpeg")

Definition at line 1981 of file Visualizer.py.

◆ writeNormDepthImage()

None pyhelios.Visualizer.Visualizer.writeNormDepthImage	(		self,
		str	filename,
		float	max_depth )

Write the depth image of the current view as a grayscale JPEG, normalized between the nearest depth and a maximum depth.

The nearest visible surface is white and anything at or beyond max_depth is black. Pixels in which no geometry is visible are treated as lying at max_depth.

Parameters

filename	JPEG file to write, which may include a path
max_depth	Depth that maps to black, in world units (e.g. the far side of the scene). Must be greater than zero.

Exceptions

ValueError	If filename is empty or max_depth is not positive
VisualizerError	If writing fails

Definition at line 2082 of file Visualizer.py.

Member Data Documentation

◆ _context

pyhelios.Visualizer.Visualizer._context

protected

Definition at line 266 of file Visualizer.py.

◆ antialiasing_samples

pyhelios.Visualizer.Visualizer.antialiasing_samples = antialiasing_samples

Definition at line 190 of file Visualizer.py.

◆ COLORMAP_ALGAE

int pyhelios.Visualizer.Visualizer.COLORMAP_ALGAE = 8

static

Definition at line 151 of file Visualizer.py.

◆ COLORMAP_COOL

int pyhelios.Visualizer.Visualizer.COLORMAP_COOL = 1

static

Definition at line 145 of file Visualizer.py.

◆ COLORMAP_GRAY

int pyhelios.Visualizer.Visualizer.COLORMAP_GRAY = 5

static

Definition at line 149 of file Visualizer.py.

◆ COLORMAP_GREEN

int pyhelios.Visualizer.Visualizer.COLORMAP_GREEN = 9

static

Definition at line 152 of file Visualizer.py.

◆ COLORMAP_HOT

int pyhelios.Visualizer.Visualizer.COLORMAP_HOT = 0

static

Definition at line 144 of file Visualizer.py.

◆ COLORMAP_LAVA

int pyhelios.Visualizer.Visualizer.COLORMAP_LAVA = 3

static

Definition at line 147 of file Visualizer.py.

◆ COLORMAP_LINES

int pyhelios.Visualizer.Visualizer.COLORMAP_LINES = 7

static

Definition at line 150 of file Visualizer.py.

◆ COLORMAP_PARULA

int pyhelios.Visualizer.Visualizer.COLORMAP_PARULA = 4

static

Definition at line 148 of file Visualizer.py.

◆ COLORMAP_RAINBOW

int pyhelios.Visualizer.Visualizer.COLORMAP_RAINBOW = 2

static

Definition at line 146 of file Visualizer.py.

◆ headless

pyhelios.Visualizer.Visualizer.headless = headless

Definition at line 191 of file Visualizer.py.

◆ height

pyhelios.Visualizer.Visualizer.height = height

Definition at line 189 of file Visualizer.py.

◆ LIGHTING_NONE

pyhelios.Visualizer.Visualizer.LIGHTING_NONE = 0

static

Definition at line 139 of file Visualizer.py.

◆ LIGHTING_PHONG

pyhelios.Visualizer.Visualizer.LIGHTING_PHONG = 1

static

Definition at line 140 of file Visualizer.py.

◆ LIGHTING_PHONG_SHADOWED

int pyhelios.Visualizer.Visualizer.LIGHTING_PHONG_SHADOWED = 2

static

Definition at line 141 of file Visualizer.py.

◆ visualizer

pyhelios.Visualizer.Visualizer.visualizer = None

Definition at line 192 of file Visualizer.py.

◆ width

pyhelios.Visualizer.Visualizer.width = width

Definition at line 188 of file Visualizer.py.

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

pyhelios/Visualizer.py

Detailed Description

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ _check_context_alive()

◆ _normalize_annotation_labels()

◆ _write_depth_output()

◆ addCoordinateAxes()

◆ addCoordinateAxesCustom()

◆ addGridWireFrame()

◆ buildContextGeometry()

◆ clearColor()

◆ clearContextGeometry()

◆ clearGeometry()

◆ closeWindow()

◆ colorContextObjectsRandomly()

◆ colorContextPrimitivesByData()

◆ colorContextPrimitivesByObjectData()

◆ colorContextPrimitivesRandomly()

◆ deleteGeometry()

◆ disableColorbar()

◆ disableCoordinateAxes()

◆ disableExactColorMode()

◆ disableLinearPipeline()

◆ disableMessages()

◆ disableSmoothShading()

◆ displayImageFromFile()

◆ displayImageFromPixels()

◆ displayImageWithBoundingBoxes()

◆ displayImageWithSegmentationMasks()

◆ enableColorbar()

◆ enableExactColorMode()

◆ enableLinearPipeline()

◆ enableMessages()

◆ enableSmoothShading()

◆ getAmbientGroundColor()

◆ getAmbientSkyColor()

◆ getBackgroundColor()

◆ getCameraPosition()

◆ getDepthImage()

◆ getDepthMap()

◆ getExposure()

◆ getFramebufferSize()

◆ getGeometryVertices()

◆ getPhongMaterial()

◆ getPixelUUIDs()

◆ getPointRenderingMetrics()

◆ getTextboxSize()

◆ getWindowPixelsRGB()

◆ getWindowSize()

◆ hideNavigationGizmo()

◆ hideWatermark()

◆ isHeadlessMultisamplingActive()

◆ isLinearPipelineEnabled()

◆ isSmoothShadingEnabled()

◆ plotDepthMap()

◆ plotInteractive()

◆ plotOnce()

◆ plotUpdate()

◆ plotUpdateWithVisibility()

◆ printWindow()

◆ printWindowDefault()

◆ setAmbientColors()

◆ setBackgroundColor()

◆ setBackgroundImage()

◆ setBackgroundSkyTexture()

◆ setBackgroundTransparent()

◆ setCameraFieldOfView()

◆ setCameraPosition()

◆ setCameraPositionSpherical()

◆ setColorbarFontColor()

◆ init()

◆ del()

◆ enter()

◆ exit()