High-level interface for LiDAR point cloud operations. More...

Detailed Description

High-level interface for LiDAR point cloud operations.

Supports synthetic scanning, point cloud filtering, triangulation, and leaf area density calculations.

Example: >>> from pyhelios import LiDARCloud >>> from pyhelios.types import vec3 >>> >>> with LiDARCloud() as lidar: ... # Add a scan ... scan_id = lidar.addScan( ... origin=vec3(0, 0, 1), ... Ntheta=100, theta_range=(0, 1.57), ... Nphi=100, phi_range=(-3.14, 3.14), ... exit_diameter=0.01, beam_divergence=0.001 ... ) ... ... # Add hit points ... lidar.addHitPoint(scan_id, vec3(1, 0, 0), vec3(1, 0, 0)) ... ... # Export point cloud ... lidar.exportPointCloud("output.xyz")

Definition at line 63 of file LiDARCloud.py.

Public Member Functions
	__init__ (self)
	Initialize LiDARCloud.

	__enter__ (self)
	Context manager entry.

	__exit__ (self, exc_type, exc_val, exc_tb)
	Context manager exit - cleanup resources.

	__del__ (self)
	Fallback destructor for cleanup without context manage.

int	addScan (self, Union[vec3, List[float], Tuple[float, float, float]] origin, int Ntheta, Tuple[float, float] theta_range, int Nphi, Tuple[float, float] phi_range, float exit_diameter, float beam_divergence, Optional[List[str]] column_format=None, float range_noise_stddev=0.0, float angle_noise_stddev=0.0, float scan_tilt_roll=0.0, float scan_tilt_pitch=0.0)
	Add a LiDAR scan to the point cloud.

int	addScanMultibeam (self, Union[vec3, List[float], Tuple[float, float, float]] origin, List[float] beam_zenith_angles, int Nphi, Tuple[float, float] phi_range, float exit_diameter, float beam_divergence, Optional[List[str]] column_format=None, float range_noise_stddev=0.0, float angle_noise_stddev=0.0, float scan_tilt_roll=0.0, float scan_tilt_pitch=0.0)
	Add a spinning multibeam LiDAR scan (rotating multi-channel sensor, e.g.

int	getScanCount (self)
	Get total number of scans in the cloud.

vec3	getScanOrigin (self, int scanID)
	Get origin of a specific scan.

int	getScanSizeTheta (self, int scanID)
	Get number of zenith scan points for a scan.

int	getScanSizePhi (self, int scanID)
	Get number of azimuthal scan points for a scan.

float	getScanRangeNoiseStdDev (self, int scanID)
	Get the range (along-beam) measurement noise standard deviation for a scan (meters).

float	getScanAngleNoiseStdDev (self, int scanID)
	Get the angular (beam-pointing) jitter standard deviation for a scan (radians).

float	getScanTiltRoll (self, int scanID)
	Get the global scanner tilt roll angle for a scan (radians; 0.0 if level).

float	getScanTiltPitch (self, int scanID)
	Get the global scanner tilt pitch angle for a scan (radians; 0.0 if level).

int	getScanPattern (self, int scanID)
	Get the scan pattern for a scan.

List[float]	getScanBeamZenithAngles (self, int scanID)
	Get the per-channel beam zenith angles (radians) for a multibeam scan.

	addHitPoint (self, int scanID, Union[vec3, List[float], Tuple[float, float, float]] xyz, Union[vec3, SphericalCoord, List[float], Tuple[float, float]] direction, Optional[Union[RGBcolor, List[float], Tuple[float, float, float]]] color=None)
	Add a hit point to the point cloud.

	addHitPoints (self, int scanID, xyz_array, direction_array, color_array=None)
	Add many hit points to the point cloud in a single bulk call.

	addHitPointsWithData (self, int scanID, xyz_array, direction_array, data_labels=None, data_values=None, color_array=None)
	Add many hit points carrying a per-hit data map in a single bulk call.

int	getHitCount (self)
	Get total number of hit points in cloud.

vec3	getHitXYZ (self, int index)
	Get coordinates of a hit point.

SphericalCoord	getHitRaydir (self, int index)
	Get ray direction of a hit point.

RGBcolor	getHitColor (self, int index)
	Get color of a hit point.

int	getHitScanID (self, int index)
	Get the scan ID a hit point belongs to.

bool	doesHitDataExist (self, int index, str label)
	Check whether a named scalar data value exists for a hit point.

float	getHitData (self, int index, str label)
	Get a named scalar data value for a hit point.

List[float]	getHitDataAll (self, str label)
	Bulk-export a named scalar data value for all hits in a single FFI call.

Tuple[List[vec3], List[RGBcolor]]	getHitsXYZRGB (self)
	Bulk-export coordinates and colors for all hits in a single FFI call.

	deleteHitPoint (self, int index)
	Delete a hit point from the cloud.

bool	isHitMiss (self, int index)
	Return True if a hit is a "miss" (a fired pulse that returned nothing).

bool	hasMisses (self)
	Return True if the cloud contains at least one miss.

	coordinateShift (self, Union[vec3, List[float], Tuple[float, float, float]] shift)
	Translate all hit points by a shift vector.

	coordinateRotation (self, Union[SphericalCoord, List[float], Tuple[float, float]] rotation)
	Rotate all hit points by spherical rotation angles.

	triangulateHitPoints (self, float Lmax, float max_aspect_ratio=4.0)
	Generate triangle mesh from hit points using Delaunay triangulation.

int	getTriangleCount (self)
	Get number of triangles in the mesh.

dict	getTriangulationStats (self)
	Filter diagnostics from the most recent triangulateHitPoints() call.

	getTriangleVerticesAll (self)
	Bulk-export every triangle's vertices and source scan in one call.

	distanceFilter (self, float maxdistance)
	Filter hit points by maximum distance from scanne.

	reflectanceFilter (self, float minreflectance)
	Filter hit points by minimum reflectance value.

	firstHitFilter (self)
	Keep only first return hit points.

	lastHitFilter (self)
	Keep only last return hit points.

	exportPointCloud (self, str filename, bool write_header=True)
	Export point cloud to ASCII file.

	exportLeafAreaUncertainty (self, str filename)
	Export per-voxel leaf-area sampling uncertainty to a self-describing ASCII file.

	exportScans (self, str filename)
	Export all scans to an XML metadata file plus one ASCII data file per scan.

	loadXML (self, str filename)
	Load scan metadata from XML file.

	disableMessages (self)
	Disable console output messages.

	enableMessages (self)
	Enable console output messages.

	addGrid (self, Union[vec3, List[float], Tuple[float, float, float]] center, Union[vec3, List[float], Tuple[float, float, float]] size, Union[List[int], Tuple[int, int, int]] ndiv, float rotation=0.0)
	Add a rectangular grid of voxel cells.

	addGridCell (self, Union[vec3, List[float], Tuple[float, float, float]] center, Union[vec3, List[float], Tuple[float, float, float]] size, float rotation=0.0)
	Add a single grid cell.

int	getGridCellCount (self)
	Get total number of grid cells.

vec3	getCellCenter (self, int index)
	Get center position of a grid cell.

vec3	getCellSize (self, int index)
	Get size of a grid cell.

float	getCellLeafArea (self, int index)
	Get leaf area of a grid cell (m²)

float	getCellLeafAreaDensity (self, int index)
	Get leaf area density of a grid cell (m²/m³)

int	getCellBeamCount (self, int index)
	Get the beam count N that entered a grid cell during the leaf-area inversion.

float	getCellRelativeDensityIndex (self, int index)
	Get the relative density index (I_rdi) for a grid cell.

float	getCellMeanPathLength (self, int index)
	Get the mean beam path length (m) through a grid cell.

float	getCellLADVariance (self, int index)
	Get the per-voxel LAD sampling variance for a grid cell.

	getCellLeafAreaConfidenceInterval (self, int index, float confidence_level=0.95)
	Get the leaf-area confidence interval for a single grid cell.

	getGroupLADConfidenceInterval (self, List[int] indices, float confidence_level=0.95)
	Get the group-scale LAD confidence interval over a set of grid cells (recommended).

float	getCellGtheta (self, int index)
	Get G(theta) value for a grid cell.

	setCellGtheta (self, float Gtheta, int index)
	Set G(theta) value for a grid cell.

	calculateHitGridCell (self)
	Calculate hit point grid cell assignments.

	gapfillMisses (self)
	Gapfill sky/miss points where rays didn't hit geometry.

	syntheticScan (self, Context context, Optional[int] rays_per_pulse=None, Optional[float] pulse_distance_threshold=None, bool scan_grid_only=False, bool record_misses=True, bool append=False)
	Perform synthetic LiDAR scan of geometry in Context.

	calculateLeafArea (self, Context context, Optional[int] min_voxel_hits=None, Optional[float] element_width=None)
	Calculate leaf area for each grid cell.

	calculateSyntheticLeafArea (self, Context context)
	Calculate synthetic leaf area (for validation of synthetic scans).

	calculateSyntheticGtheta (self, Context context)
	Calculate synthetic G(theta) (for validation of synthetic scans).

	exportTriangleNormals (self, str filename)
	Export triangle normal vectors to file.

	exportTriangleAreas (self, str filename)
	Export triangle areas to file.

	exportLeafAreas (self, str filename)
	Export leaf areas for each grid cell to file.

	exportLeafAreaDensities (self, str filename)
	Export leaf area densities for each grid cell to file.

	exportGtheta (self, str filename)
	Export G(theta) values for each grid cell to file.

	addTrianglesToContext (self, Context context)
	Add triangulated mesh to Context as triangle primitives.

	initializeCollisionDetection (self, Context context)
	Initialize CollisionDetection plugin for ray tracing.

	enableCDGPUAcceleration (self)
	Enable GPU acceleration for collision detection ray tracing.

	disableCDGPUAcceleration (self)
	Disable GPU acceleration (use CPU ray tracing)

bool	is_available (self)
	Check if LiDAR is available in current build.

Static Public Member Functions
float	getMissDistance ()
	Return the LIDAR_MISS_DISTANCE constant (meters): the distance at which a miss point is placed along its beam.

Protected Attributes
	_cloud_ptr = lidar_wrapper.createLiDARcloud()

Constructor & Destructor Documentation

◆ init()

pyhelios.LiDARCloud.LiDARCloud.__init__ ( self )

Initialize LiDARCloud.

Exceptions

LiDARError	If plugin not available in current build
RuntimeError	If cloud initialization fails

Definition at line 72 of file LiDARCloud.py.

◆ del()

pyhelios.LiDARCloud.LiDARCloud.__del__ ( self )

Fallback destructor for cleanup without context manage.

Definition at line 100 of file LiDARCloud.py.

Member Function Documentation

◆ enter()

pyhelios.LiDARCloud.LiDARCloud.__enter__ ( self )

Context manager entry.

Definition at line 90 of file LiDARCloud.py.

◆ exit()

pyhelios.LiDARCloud.LiDARCloud.__exit__	(	self,
		exc_type,
		exc_val,
		exc_tb )

Context manager exit - cleanup resources.

Definition at line 94 of file LiDARCloud.py.

◆ addGrid()

pyhelios.LiDARCloud.LiDARCloud.addGrid	(		self,
		Union[vec3, List[float], Tuple[float, float, float]]	center,
		Union[vec3, List[float], Tuple[float, float, float]]	size,
		Union[List[int], Tuple[int, int, int]]	ndiv,
		float	rotation = 0.0 )

Add a rectangular grid of voxel cells.

Parameters

center	Grid center position (vec3 or 3-element list)
size	Grid dimensions [x, y, z] (vec3 or 3-element list)
ndiv	Number of divisions [nx, ny, nz] (3-element list)
rotation	Azimuthal rotation angle (radians, default 0.0)

Example: >>> lidar.addGrid( ... center=vec3(0, 0, 0.5), ... size=vec3(10, 10, 1), ... ndiv=[10, 10, 5], ... rotation=0.0 ... )

Definition at line 759 of file LiDARCloud.py.

◆ addGridCell()

pyhelios.LiDARCloud.LiDARCloud.addGridCell	(		self,
		Union[vec3, List[float], Tuple[float, float, float]]	center,
		Union[vec3, List[float], Tuple[float, float, float]]	size,
		float	rotation = 0.0 )

Add a single grid cell.

Parameters

center	Cell center position (vec3 or 3-element list)
size	Cell dimensions [x, y, z] (vec3 or 3-element list)
rotation	Azimuthal rotation angle (radians, default 0.0)

Definition at line 797 of file LiDARCloud.py.

◆ addHitPoint()

pyhelios.LiDARCloud.LiDARCloud.addHitPoint	(		self,
		int	scanID,
		Union[vec3, List[float], Tuple[float, float, float]]	xyz,
		Union[vec3, SphericalCoord, List[float], Tuple[float, float]]	direction,
		Optional[Union[RGBcolor, List[float], Tuple[float, float, float]]]	color = None )

Add a hit point to the point cloud.

Parameters

scanID	Scan ID this hit belongs to
xyz	Hit point coordinates (vec3 or 3-element list)
direction	Ray direction (vec3/SphericalCoord or 2-3 element list)
color	Optional RGB color (RGBcolor or 3-element list)

Definition at line 349 of file LiDARCloud.py.

◆ addHitPoints()

pyhelios.LiDARCloud.LiDARCloud.addHitPoints	(		self,
		int	scanID,
			xyz_array,
			direction_array,
			color_array = None )

Add many hit points to the point cloud in a single bulk call.

   This skips the per-point Python loop by passing contiguous buffers
   straight to the native library in one FFI call.

Parameters

scanID	Scan ID these hits belong to
xyz_array	Hit point coordinates, shape (N, 3) [x, y, z]
direction_array	Ray directions, shape (N, 3) [radius, elevation, azimuth] (azimuth is currently ignored, matching addHitPoint)
color_array	Optional RGB colors, shape (N, 3) [r, g, b]

Definition at line 403 of file LiDARCloud.py.

◆ addHitPointsWithData()

pyhelios.LiDARCloud.LiDARCloud.addHitPointsWithData	(		self,
		int	scanID,
			xyz_array,
			direction_array,
			data_labels = None,
			data_values = None,
			color_array = None )

Add many hit points carrying a per-hit data map in a single bulk call.

   Like addHitPoints, but also populates each hit's named-scalar data map —
   the in-memory equivalent of what the ASCII loader does for non-standard
   columns. This is the path multi-return LAD needs (timestamp/target_index/
   target_count land in the map so gapfillMisses() can group beams by pulse).

Parameters

scanID	Scan ID these hits belong to (the scan must already exist)
xyz_array	Hit point coordinates, shape (N, 3) [x, y, z]
direction_array	Ray directions, shape (N, 3) [radius, elevation, azimuth].
Pass	origin) to match loadASCIIFile; the full SphericalCoord (incl. radius) is used.
data_labels	Optional list of data-map key names (length k)
data_values	Optional (N, k) values for those keys (float64)
color_array	Optional RGB colors, shape (N, 3) [r, g, b]

Definition at line 446 of file LiDARCloud.py.

◆ addScan()

int pyhelios.LiDARCloud.LiDARCloud.addScan	(		self,
		Union[vec3, List[float], Tuple[float, float, float]]	origin,
		int	Ntheta,
		Tuple[float, float]	theta_range,
		int	Nphi,
		Tuple[float, float]	phi_range,
		float	exit_diameter,
		float	beam_divergence,
		Optional[List[str]]	column_format = None,
		float	range_noise_stddev = 0.0,
		float	angle_noise_stddev = 0.0,
		float	scan_tilt_roll = 0.0,
		float	scan_tilt_pitch = 0.0 )

Add a LiDAR scan to the point cloud.

Parameters

origin	Scanner position (vec3 or 3-element list/tuple)
Ntheta	Number of scan points in zenith direction
theta_range	Zenith angle range (min, max) in radians
Nphi	Number of scan points in azimuthal direction
phi_range	Azimuthal angle range (min, max) in radians
exit_diameter	Laser beam exit diameter (meters)
beam_divergence	Beam divergence angle (radians)
column_format	Optional list of column-format labels. Non-standard labels (anything other than geometry/standard tokens like x/y/z/r/g/b/raydir) cause syntheticScan to sample that named primitive data from the struck primitive onto each hit's data map, retrievable via getHitData(). Defaults to None (empty format).

One label is special: "reflectivity_lidar" modulates each hit's "intensity" (intensity *= reflectivity) rather than being stored as its own hit-data key, so getHitData(i, "reflectivity_lidar") will NOT return it.

Parameters

range_noise_stddev	Standard deviation of Gaussian range (along-beam) measurement noise in meters. Only affects synthetic-scan generation. Defaults to 0.0 (noise disabled).
angle_noise_stddev	Standard deviation of Gaussian angular (beam-pointing) jitter in radians. Only affects synthetic-scan generation. Defaults to 0.0 (jitter disabled).
scan_tilt_roll	Global scanner tilt roll angle in radians, modeling residual tilt of the scanner spin axis away from plumb (right-hand rotation about the body lateral axis). Only affects synthetic-scan generation. Defaults to 0.0 (level).
scan_tilt_pitch	Global scanner tilt pitch angle in radians (right-hand rotation about the body forward/azimuth-zero axis). Only affects synthetic-scan generation. Defaults to 0.0 (level).

Returns: Scan ID for referencing this scan

Example: >>> scan_id = lidar.addScan( ... origin=vec3(0, 0, 1), ... Ntheta=100, theta_range=(0, 1.57), ... Nphi=100, phi_range=(-3.14, 3.14), ... exit_diameter=0.01, beam_divergence=0.001, ... column_format=["my_scalar"] ... )

Definition at line 154 of file LiDARCloud.py.

◆ addScanMultibeam()

int pyhelios.LiDARCloud.LiDARCloud.addScanMultibeam	(		self,
		Union[vec3, List[float], Tuple[float, float, float]]	origin,
		List[float]	beam_zenith_angles,
		int	Nphi,
		Tuple[float, float]	phi_range,
		float	exit_diameter,
		float	beam_divergence,
		Optional[List[str]]	column_format = None,
		float	range_noise_stddev = 0.0,
		float	angle_noise_stddev = 0.0,
		float	scan_tilt_roll = 0.0,
		float	scan_tilt_pitch = 0.0 )

Add a spinning multibeam LiDAR scan (rotating multi-channel sensor, e.g.

Velodyne/Ouster/Hesai).

   Each laser channel is fired at a fixed zenith angle (taken from ``beam_zenith_angles``) as the
   sensor head rotates through ``Nphi`` uniform azimuth steps. The scan is stored as an
   (len(beam_zenith_angles) x Nphi) table, so all downstream processing is shared with raster scans.

Parameters

origin	Scanner position (vec3 or 3-element list/tuple)
beam_zenith_angles	Per-channel zenith angles in radians (0 = upward, pi/2 = horizontal, pi = downward). Manufacturer spec sheets typically list channel angles as elevation above the horizon; zenith = pi/2 - elevation. Its length sets Ntheta (number of channels).
Nphi	Number of azimuth steps (columns) per rotation
phi_range	Azimuthal angle range (min, max) in radians
exit_diameter	Laser beam exit diameter (meters)
beam_divergence	Beam divergence angle (radians)
column_format	Optional list of column-format labels (see addScan)
range_noise_stddev	Std. dev. of Gaussian range noise in meters (default 0)
angle_noise_stddev	Std. dev. of Gaussian angular jitter in radians (default 0)
scan_tilt_roll	Global scanner tilt roll angle in radians (default 0, level)
scan_tilt_pitch	Global scanner tilt pitch angle in radians (default 0, level)

Returns: Scan ID for referencing this scan

Definition at line 223 of file LiDARCloud.py.

◆ addTrianglesToContext()

pyhelios.LiDARCloud.LiDARCloud.addTrianglesToContext	(		self,
		Context	context )

Add triangulated mesh to Context as triangle primitives.

   Converts the triangulated point cloud mesh into Context triangle
   primitives that can be used for further analysis or visualization.

Parameters

context Helios Context instance

Example: >>> with Context() as context: ... with LiDARCloud() as lidar: ... lidar.loadXML("scan.xml") ... lidar.triangulateHitPoints(Lmax=0.5, max_aspect_ratio=5) ... lidar.addTrianglesToContext(context) ... print(f"Added {context.getPrimitiveCount()} triangles to context")

Definition at line 1131 of file LiDARCloud.py.

◆ calculateHitGridCell()

pyhelios.LiDARCloud.LiDARCloud.calculateHitGridCell ( self )

Calculate hit point grid cell assignments.

Definition at line 923 of file LiDARCloud.py.

◆ calculateLeafArea()

pyhelios.LiDARCloud.LiDARCloud.calculateLeafArea	(		self,
		Context	context,
		Optional[int]	min_voxel_hits = None,
		Optional[float]	element_width = None )

Calculate leaf area for each grid cell.

   Requires triangulation to have been performed first.

   .. note::
       The cloud must contain misses (transmitted beams that returned nothing) — the
       inversion fails fast without them. Misses are produced by
       ``syntheticScan(..., record_misses=True)`` (the default) or by
       :meth:`gapfillMisses`. Use :meth:`hasMisses` to check.

Parameters

context	Helios Context instance
min_voxel_hits	Optional minimum number of hits required per voxel
element_width	Optional characteristic vegetation element width (meters). When provided, per-voxel sampling uncertainty (Pimont et al. 2018) is computed alongside the leaf-area estimate and becomes available via :meth:`getCellLADVariance`, :meth:`getCellLeafAreaConfidenceInterval`, and :meth:`getGroupLADConfidenceInterval`. `element_width <= 0` yields a sampling-only variance. Requires `min_voxel_hits` to also be specified.

Example: >>> from pyhelios import Context, LiDARCloud >>> with Context() as context: ... with LiDARCloud() as lidar: ... # ... load data, add grid, triangulate ... ... lidar.calculateLeafArea(context)

Definition at line 1036 of file LiDARCloud.py.

◆ calculateSyntheticGtheta()

pyhelios.LiDARCloud.LiDARCloud.calculateSyntheticGtheta	(		self,
		Context	context )

Calculate synthetic G(theta) (for validation of synthetic scans).

   Uses exact primitive geometry to calculate G(theta), useful for
   validating synthetic scan accuracy.

Parameters

context Helios Context instance containing primitive geometry

Definition at line 1078 of file LiDARCloud.py.

◆ calculateSyntheticLeafArea()

pyhelios.LiDARCloud.LiDARCloud.calculateSyntheticLeafArea	(		self,
		Context	context )

Calculate synthetic leaf area (for validation of synthetic scans).

   Uses exact primitive geometry to calculate leaf area, useful for
   validating synthetic scan accuracy.

Parameters

context Helios Context instance containing primitive geometry

Definition at line 1063 of file LiDARCloud.py.

◆ coordinateRotation()

pyhelios.LiDARCloud.LiDARCloud.coordinateRotation	(		self,
		Union[SphericalCoord, List[float], Tuple[float, float]]	rotation )

Rotate all hit points by spherical rotation angles.

Parameters

rotation Rotation angles (SphericalCoord or 2-3 element list)

Definition at line 617 of file LiDARCloud.py.

◆ coordinateShift()

pyhelios.LiDARCloud.LiDARCloud.coordinateShift	(		self,
		Union[vec3, List[float], Tuple[float, float, float]]	shift )

Translate all hit points by a shift vector.

Parameters

shift Translation vector (vec3 or 3-element list)

Definition at line 599 of file LiDARCloud.py.

◆ deleteHitPoint()

pyhelios.LiDARCloud.LiDARCloud.deleteHitPoint	(		self,
		int	index )

Delete a hit point from the cloud.

Definition at line 564 of file LiDARCloud.py.

◆ disableCDGPUAcceleration()

pyhelios.LiDARCloud.LiDARCloud.disableCDGPUAcceleration ( self )

Disable GPU acceleration (use CPU ray tracing)

Definition at line 1154 of file LiDARCloud.py.

◆ disableMessages()

pyhelios.LiDARCloud.LiDARCloud.disableMessages ( self )

Disable console output messages.

Definition at line 735 of file LiDARCloud.py.

◆ distanceFilter()

pyhelios.LiDARCloud.LiDARCloud.distanceFilter	(		self,
		float	maxdistance )

Filter hit points by maximum distance from scanne.

Definition at line 673 of file LiDARCloud.py.

◆ doesHitDataExist()

bool pyhelios.LiDARCloud.LiDARCloud.doesHitDataExist	(		self,
		int	index,
		str	label )

Check whether a named scalar data value exists for a hit point.

   Per-hit data computed by syntheticScan includes 'intensity', 'distance',
   'timestamp', 'target_index', 'target_count', 'deviation', 'nRaysHit', plus any
   primitive-data labels listed in the scan's column_format.

Definition at line 519 of file LiDARCloud.py.

◆ enableCDGPUAcceleration()

pyhelios.LiDARCloud.LiDARCloud.enableCDGPUAcceleration ( self )

Enable GPU acceleration for collision detection ray tracing.

Definition at line 1150 of file LiDARCloud.py.

◆ enableMessages()

pyhelios.LiDARCloud.LiDARCloud.enableMessages ( self )

Enable console output messages.

Definition at line 739 of file LiDARCloud.py.

◆ exportGtheta()

pyhelios.LiDARCloud.LiDARCloud.exportGtheta	(		self,
		str	filename )

Export G(theta) values for each grid cell to file.

Definition at line 1109 of file LiDARCloud.py.

◆ exportLeafAreaDensities()

pyhelios.LiDARCloud.LiDARCloud.exportLeafAreaDensities	(		self,
		str	filename )

Export leaf area densities for each grid cell to file.

Definition at line 1103 of file LiDARCloud.py.

◆ exportLeafAreas()

pyhelios.LiDARCloud.LiDARCloud.exportLeafAreas	(		self,
		str	filename )

Export leaf areas for each grid cell to file.

Definition at line 1097 of file LiDARCloud.py.

◆ exportLeafAreaUncertainty()

pyhelios.LiDARCloud.LiDARCloud.exportLeafAreaUncertainty	(		self,
		str	filename )

Export per-voxel leaf-area sampling uncertainty to a self-describing ASCII file.

   The file has a ``#``-prefixed header and one row per grid cell:
   ``cell_index leaf_area beam_count I_rdi LAD_std_error ci_valid``. Requires that
   :meth:`calculateLeafArea` has been run with an ``element_width`` (the uncertainty
   overload).

Definition at line 710 of file LiDARCloud.py.

◆ exportPointCloud()

pyhelios.LiDARCloud.LiDARCloud.exportPointCloud	(		self,
		str	filename,
		bool	write_header = True )

Export point cloud to ASCII file.

Parameters

filename	Output file path.
write_header	If True (default), prepend a `#`-prefixed comment line listing the column field names (CloudCompare convention). The loader skips `#`-prefixed lines, so headered files round-trip through `loadXML()`. Set False for a bare data file.

Definition at line 698 of file LiDARCloud.py.

◆ exportScans()

pyhelios.LiDARCloud.LiDARCloud.exportScans	(		self,
		str	filename )

Export all scans to an XML metadata file plus one ASCII data file per scan.

Parameters

filename Path of the XML metadata file to write (e.g. "output/scans.xml"). One ASCII data file is auto-generated per scan, named by stripping the XML extension and appending "_<scanID>.xyz" (e.g. "output/scans_0.xyz"). The resulting XML can be re-loaded with loadXML() from the same working directory.

Definition at line 723 of file LiDARCloud.py.

◆ exportTriangleAreas()

pyhelios.LiDARCloud.LiDARCloud.exportTriangleAreas	(		self,
		str	filename )

Export triangle areas to file.

Definition at line 1091 of file LiDARCloud.py.

◆ exportTriangleNormals()

pyhelios.LiDARCloud.LiDARCloud.exportTriangleNormals	(		self,
		str	filename )

Export triangle normal vectors to file.

Definition at line 1085 of file LiDARCloud.py.

◆ firstHitFilter()

pyhelios.LiDARCloud.LiDARCloud.firstHitFilter ( self )

Keep only first return hit points.

Definition at line 682 of file LiDARCloud.py.

◆ gapfillMisses()

pyhelios.LiDARCloud.LiDARCloud.gapfillMisses ( self )

Gapfill sky/miss points where rays didn't hit geometry.

   Important for accurate leaf area calculations with real LiDAR data.
   Should be called before triangulation when processing real data.

Definition at line 932 of file LiDARCloud.py.

◆ getCellBeamCount()

int pyhelios.LiDARCloud.LiDARCloud.getCellBeamCount	(		self,
		int	index )

Get the beam count N that entered a grid cell during the leaf-area inversion.

   Returns -1 if :meth:`calculateLeafArea` has not been run for this cell.

Definition at line 856 of file LiDARCloud.py.

◆ getCellCenter()

vec3 pyhelios.LiDARCloud.LiDARCloud.getCellCenter	(		self,
		int	index )

Get center position of a grid cell.

Definition at line 827 of file LiDARCloud.py.

◆ getCellGtheta()

float pyhelios.LiDARCloud.LiDARCloud.getCellGtheta	(		self,
		int	index )

Get G(theta) value for a grid cell.

Definition at line 911 of file LiDARCloud.py.

◆ getCellLADVariance()

float pyhelios.LiDARCloud.LiDARCloud.getCellLADVariance	(		self,
		int	index )

Get the per-voxel LAD sampling variance for a grid cell.

   Returns -1 if uncertainty has not been computed (call :meth:`calculateLeafArea`
   with an ``element_width``).

Definition at line 878 of file LiDARCloud.py.

◆ getCellLeafArea()

float pyhelios.LiDARCloud.LiDARCloud.getCellLeafArea	(		self,
		int	index )

Get leaf area of a grid cell (m²)

Definition at line 841 of file LiDARCloud.py.

◆ getCellLeafAreaConfidenceInterval()

pyhelios.LiDARCloud.LiDARCloud.getCellLeafAreaConfidenceInterval	(		self,
		int	index,
		float	confidence_level = 0.95 )

Get the leaf-area confidence interval for a single grid cell.

   Returns a ``(valid, lower, upper)`` tuple. ``valid`` is False when the interval is
   gated out by the Pimont validity envelope (single-voxel intervals are often
   untrustworthy; prefer :meth:`getGroupLADConfidenceInterval`). Requires
   :meth:`calculateLeafArea` to have been run with an ``element_width``.

Definition at line 890 of file LiDARCloud.py.

◆ getCellLeafAreaDensity()

float pyhelios.LiDARCloud.LiDARCloud.getCellLeafAreaDensity	(		self,
		int	index )

Get leaf area density of a grid cell (m²/m³)

Definition at line 847 of file LiDARCloud.py.

◆ getCellMeanPathLength()

float pyhelios.LiDARCloud.LiDARCloud.getCellMeanPathLength	(		self,
		int	index )

Get the mean beam path length (m) through a grid cell.

Definition at line 868 of file LiDARCloud.py.

◆ getCellRelativeDensityIndex()

float pyhelios.LiDARCloud.LiDARCloud.getCellRelativeDensityIndex	(		self,
		int	index )

Get the relative density index (I_rdi) for a grid cell.

Definition at line 862 of file LiDARCloud.py.

◆ getCellSize()

vec3 pyhelios.LiDARCloud.LiDARCloud.getCellSize	(		self,
		int	index )

Get size of a grid cell.

Definition at line 834 of file LiDARCloud.py.

◆ getGridCellCount()

int pyhelios.LiDARCloud.LiDARCloud.getGridCellCount ( self )

Get total number of grid cells.

Definition at line 823 of file LiDARCloud.py.

◆ getGroupLADConfidenceInterval()

pyhelios.LiDARCloud.LiDARCloud.getGroupLADConfidenceInterval	(		self,
		List[int]	indices,
		float	confidence_level = 0.95 )

Get the group-scale LAD confidence interval over a set of grid cells (recommended).

   Returns a ``(valid, mean_lad, lower, upper)`` tuple (Pimont et al. 2018, Eq. 39,
   assuming voxel independence). Requires :meth:`calculateLeafArea` to have been run
   with an ``element_width``.

Definition at line 902 of file LiDARCloud.py.

◆ getHitColor()

RGBcolor pyhelios.LiDARCloud.LiDARCloud.getHitColor	(		self,
		int	index )

Get color of a hit point.

Definition at line 501 of file LiDARCloud.py.

◆ getHitCount()

int pyhelios.LiDARCloud.LiDARCloud.getHitCount ( self )

Get total number of hit points in cloud.

Definition at line 482 of file LiDARCloud.py.

◆ getHitData()

float pyhelios.LiDARCloud.LiDARCloud.getHitData	(		self,
		int	index,
		str	label )

Get a named scalar data value for a hit point.

   Raises HeliosError if the label does not exist for this hit; guard with
   doesHitDataExist() when unsure.

Definition at line 529 of file LiDARCloud.py.

◆ getHitDataAll()

List[float] pyhelios.LiDARCloud.LiDARCloud.getHitDataAll	(		self,
		str	label )

Bulk-export a named scalar data value for all hits in a single FFI call.

   Returns a list of length getHitCount(); entries are NaN where the label is
   absent for that hit. Much faster than looping getHitData() for large clouds.

Note: values are returned at float32 precision (vs. getHitData(), which returns full float64). Use getHitData() per-hit if full precision is required.

Definition at line 542 of file LiDARCloud.py.

◆ getHitRaydir()

SphericalCoord pyhelios.LiDARCloud.LiDARCloud.getHitRaydir	(		self,
		int	index )

Get ray direction of a hit point.

Definition at line 493 of file LiDARCloud.py.

◆ getHitScanID()

int pyhelios.LiDARCloud.LiDARCloud.getHitScanID	(		self,
		int	index )

Get the scan ID a hit point belongs to.

Definition at line 508 of file LiDARCloud.py.

◆ getHitsXYZRGB()

Tuple[List[vec3], List[RGBcolor]] pyhelios.LiDARCloud.LiDARCloud.getHitsXYZRGB ( self )

Bulk-export coordinates and colors for all hits in a single FFI call.

   Returns (positions, colors) where positions is a list of vec3 and colors a list
   of RGBcolor, each of length getHitCount(). Much faster than looping
   getHitXYZ()/getHitColor() for large clouds.

Definition at line 554 of file LiDARCloud.py.

◆ getHitXYZ()

vec3 pyhelios.LiDARCloud.LiDARCloud.getHitXYZ	(		self,
		int	index )

Get coordinates of a hit point.

Definition at line 486 of file LiDARCloud.py.

◆ getMissDistance()

float pyhelios.LiDARCloud.LiDARCloud.getMissDistance ( )

static

Return the LIDAR_MISS_DISTANCE constant (meters): the distance at which a miss point is placed along its beam.

Definition at line 590 of file LiDARCloud.py.

◆ getScanAngleNoiseStdDev()

float pyhelios.LiDARCloud.LiDARCloud.getScanAngleNoiseStdDev	(		self,
		int	scanID )

Get the angular (beam-pointing) jitter standard deviation for a scan (radians).

   Returns the value supplied to addScan() as ``angle_noise_stddev`` (0.0 if disabled).

Definition at line 303 of file LiDARCloud.py.

◆ getScanBeamZenithAngles()

List[float] pyhelios.LiDARCloud.LiDARCloud.getScanBeamZenithAngles	(		self,
		int	scanID )

Get the per-channel beam zenith angles (radians) for a multibeam scan.

   Returns an empty list for a raster scan.

Definition at line 335 of file LiDARCloud.py.

◆ getScanCount()

int pyhelios.LiDARCloud.LiDARCloud.getScanCount ( self )

Get total number of scans in the cloud.

Definition at line 268 of file LiDARCloud.py.

◆ getScanOrigin()

vec3 pyhelios.LiDARCloud.LiDARCloud.getScanOrigin	(		self,
		int	scanID )

Get origin of a specific scan.

Definition at line 272 of file LiDARCloud.py.

◆ getScanPattern()

int pyhelios.LiDARCloud.LiDARCloud.getScanPattern	(		self,
		int	scanID )

Get the scan pattern for a scan.

   Returns an integer: 0 = raster (uniform angular grid), 1 = spinning multibeam
   (rotating multi-channel sensor). Compare against ``ScanPattern.RASTER`` /
   ``ScanPattern.SPINNING_MULTIBEAM``.

Definition at line 326 of file LiDARCloud.py.

◆ getScanRangeNoiseStdDev()

float pyhelios.LiDARCloud.LiDARCloud.getScanRangeNoiseStdDev	(		self,
		int	scanID )

Get the range (along-beam) measurement noise standard deviation for a scan (meters).

   Returns the value supplied to addScan() as ``range_noise_stddev`` (0.0 if disabled).

Definition at line 294 of file LiDARCloud.py.

◆ getScanSizePhi()

int pyhelios.LiDARCloud.LiDARCloud.getScanSizePhi	(		self,
		int	scanID )

Get number of azimuthal scan points for a scan.

Definition at line 285 of file LiDARCloud.py.

◆ getScanSizeTheta()

int pyhelios.LiDARCloud.LiDARCloud.getScanSizeTheta	(		self,
		int	scanID )

Get number of zenith scan points for a scan.

Definition at line 279 of file LiDARCloud.py.

◆ getScanTiltPitch()

float pyhelios.LiDARCloud.LiDARCloud.getScanTiltPitch	(		self,
		int	scanID )

Get the global scanner tilt pitch angle for a scan (radians; 0.0 if level).

Definition at line 315 of file LiDARCloud.py.

◆ getScanTiltRoll()

float pyhelios.LiDARCloud.LiDARCloud.getScanTiltRoll	(		self,
		int	scanID )

Get the global scanner tilt roll angle for a scan (radians; 0.0 if level).

Definition at line 309 of file LiDARCloud.py.

◆ getTriangleCount()

int pyhelios.LiDARCloud.LiDARCloud.getTriangleCount ( self )

Get number of triangles in the mesh.

Definition at line 642 of file LiDARCloud.py.

◆ getTriangleVerticesAll()

pyhelios.LiDARCloud.LiDARCloud.getTriangleVerticesAll ( self )

Bulk-export every triangle's vertices and source scan in one call.

   Returns (xyz_flat, scan_ids): xyz_flat is a (T*9,) float32 array laid out
   [v0x,v0y,v0z, v1x,v1y,v1z, v2x,v2y,v2z] per triangle, scan_ids is a (T,)
   int32 array. Avoids the Context round-trip and the per-triangle
   getPrimitiveVertices loop.

Definition at line 668 of file LiDARCloud.py.

◆ getTriangulationStats()

dict pyhelios.LiDARCloud.LiDARCloud.getTriangulationStats ( self )

Filter diagnostics from the most recent triangulateHitPoints() call.

   Returns a dict::

       {"candidates", "dropped_lmax", "dropped_aspect", "dropped_degenerate"}

   Each dropped triangle is attributed to one primary reason (Lmax, then
   aspect, then degenerate), so ``candidates == getTriangleCount() +
   dropped_lmax + dropped_aspect + dropped_degenerate``. All zero if
   triangulation has not been run. Use this to tell whether an empty or
   sparse mesh is data-limited (few candidates) or filter-limited (many
   candidates dropped by Lmax/aspect).

Definition at line 658 of file LiDARCloud.py.

◆ hasMisses()

bool pyhelios.LiDARCloud.LiDARCloud.hasMisses ( self )

Return True if the cloud contains at least one miss.

   :meth:`calculateLeafArea` requires misses and fails fast without them.

Definition at line 584 of file LiDARCloud.py.

◆ initializeCollisionDetection()

pyhelios.LiDARCloud.LiDARCloud.initializeCollisionDetection	(		self,
		Context	context )

Initialize CollisionDetection plugin for ray tracing.

   Required before performing synthetic scans.

Parameters

context Helios Context instance containing geometry

Definition at line 1144 of file LiDARCloud.py.

◆ is_available()

bool pyhelios.LiDARCloud.LiDARCloud.is_available ( self )

Check if LiDAR is available in current build.

Returns: True if plugin is available, False otherwise

Definition at line 1163 of file LiDARCloud.py.

◆ isHitMiss()

bool pyhelios.LiDARCloud.LiDARCloud.isHitMiss	(		self,
		int	index )

Return True if a hit is a "miss" (a fired pulse that returned nothing).

   Misses are the transmitted beams that form the denominator of the per-voxel
   transmission probability used by :meth:`calculateLeafArea`. They are produced by
   ``syntheticScan(..., record_misses=True)`` and by :meth:`gapfillMisses`.

Definition at line 575 of file LiDARCloud.py.

◆ lastHitFilter()

pyhelios.LiDARCloud.LiDARCloud.lastHitFilter ( self )

Keep only last return hit points.

Definition at line 686 of file LiDARCloud.py.

◆ loadXML()

pyhelios.LiDARCloud.LiDARCloud.loadXML	(		self,
		str	filename )

Load scan metadata from XML file.

Definition at line 729 of file LiDARCloud.py.

◆ reflectanceFilter()

pyhelios.LiDARCloud.LiDARCloud.reflectanceFilter	(		self,
		float	minreflectance )

Filter hit points by minimum reflectance value.

Definition at line 678 of file LiDARCloud.py.

◆ setCellGtheta()

pyhelios.LiDARCloud.LiDARCloud.setCellGtheta	(		self,
		float	Gtheta,
		int	index )

Set G(theta) value for a grid cell.

Definition at line 917 of file LiDARCloud.py.

◆ syntheticScan()

pyhelios.LiDARCloud.LiDARCloud.syntheticScan	(		self,
		Context	context,
		Optional[int]	rays_per_pulse = None,
		Optional[float]	pulse_distance_threshold = None,
		bool	scan_grid_only = False,
		bool	record_misses = True,
		bool	append = False )

Perform synthetic LiDAR scan of geometry in Context.

   Requires scan metadata to be defined first via addScan() or loadXML().
   Uses ray tracing to simulate LiDAR instrument measurements.

Parameters

context	Helios Context containing geometry to scan
rays_per_pulse	Number of rays per pulse (None=discrete-return, typical: 100)
pulse_distance_threshold	Distance threshold for aggregating hits (meters, required for waveform)
scan_grid_only	If True, only scan within defined grid cells
record_misses	If True, record miss/sky points where rays don't hit geometry
append	If True, append to existing hits; if False, clear existing hits Example (Discrete-return): >>> from pyhelios import Context, LiDARCloud >>> from pyhelios.types import vec3 >>> with Context() as context: ... # Add geometry ... context.addPatch(center=vec3(0, 0, 0.5), size=vec2(1, 1))
...	... with LiDARCloud() as lidar: ... # Define scan parameters ... scan_id = lidar.addScan( ... origin=vec3(0, 0, 2), ... Ntheta=100, theta_range=(0, 1.57), ... Nphi=100, phi_range=(0, 6.28), ... exit_diameter=0, beam_divergence=0 ... )
...	... # Perform discrete-return scan ... lidar.syntheticScan(context)

Example (Full-waveform): >>> lidar.syntheticScan( ... context, ... rays_per_pulse=100, ... pulse_distance_threshold=0.02, ... record_misses=True ... )

Definition at line 976 of file LiDARCloud.py.

◆ triangulateHitPoints()

pyhelios.LiDARCloud.LiDARCloud.triangulateHitPoints	(		self,
		float	Lmax,
		float	max_aspect_ratio = 4.0 )

Generate triangle mesh from hit points using Delaunay triangulation.

Parameters

Lmax	Maximum triangle edge length
max_aspect_ratio	Maximum triangle aspect ratio (default 4.0)

Definition at line 636 of file LiDARCloud.py.

Member Data Documentation

◆ _cloud_ptr

pyhelios.LiDARCloud.LiDARCloud._cloud_ptr = lidar_wrapper.createLiDARcloud()

protected

Definition at line 85 of file LiDARCloud.py.

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

pyhelios/LiDARCloud.py

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ addGrid()

◆ addGridCell()

◆ addHitPoint()

◆ addHitPoints()

◆ addHitPointsWithData()

◆ addScan()

◆ addScanMultibeam()

◆ addTrianglesToContext()

◆ calculateHitGridCell()

◆ calculateLeafArea()

◆ calculateSyntheticGtheta()

◆ calculateSyntheticLeafArea()

◆ coordinateRotation()

◆ coordinateShift()

◆ deleteHitPoint()

◆ disableCDGPUAcceleration()

◆ disableMessages()

◆ distanceFilter()

◆ doesHitDataExist()

◆ enableCDGPUAcceleration()

◆ enableMessages()

◆ exportGtheta()

◆ exportLeafAreaDensities()

◆ exportLeafAreas()

◆ exportLeafAreaUncertainty()

◆ exportPointCloud()

◆ exportScans()

◆ exportTriangleAreas()

◆ exportTriangleNormals()

◆ firstHitFilter()

◆ gapfillMisses()

◆ getCellBeamCount()

◆ getCellCenter()

◆ getCellGtheta()

◆ getCellLADVariance()

◆ getCellLeafArea()

◆ getCellLeafAreaConfidenceInterval()

◆ getCellLeafAreaDensity()

◆ getCellMeanPathLength()

◆ getCellRelativeDensityIndex()

◆ getCellSize()

◆ getGridCellCount()

◆ getGroupLADConfidenceInterval()

◆ getHitColor()

◆ getHitCount()

◆ getHitData()

◆ getHitDataAll()

◆ getHitRaydir()

◆ getHitScanID()

◆ getHitsXYZRGB()

◆ getHitXYZ()

◆ getMissDistance()

◆ getScanAngleNoiseStdDev()

◆ getScanBeamZenithAngles()

◆ getScanCount()

◆ getScanOrigin()

◆ getScanPattern()

◆ getScanRangeNoiseStdDev()

◆ getScanSizePhi()

◆ getScanSizeTheta()

◆ getScanTiltPitch()

◆ getScanTiltRoll()

◆ getTriangleCount()

◆ getTriangleVerticesAll()

◆ getTriangulationStats()

◆ hasMisses()

◆ initializeCollisionDetection()

◆ is_available()

◆ isHitMiss()

◆ lastHitFilter()

◆ init()

◆ del()

◆ enter()

◆ exit()