0.1.15
Loading...
Searching...
No Matches
pyhelios.LiDARCloud.LiDARCloud Class Reference

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 51 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)
 Add a LiDAR scan to the point cloud.
 
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.
 
 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.
 
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.
 
 deleteHitPoint (self, int index)
 Delete a hit point from the cloud.
 
 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.
 
 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)
 Export point cloud to ASCII file.
 
 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³)
 
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)
 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.
 

Protected Attributes

 _cloud_ptr = lidar_wrapper.createLiDARcloud()
 

Constructor & Destructor Documentation

◆ __init__()

pyhelios.LiDARCloud.LiDARCloud.__init__ ( self)

Initialize LiDARCloud.

Exceptions
LiDARErrorIf plugin not available in current build
RuntimeErrorIf cloud initialization fails

Definition at line 60 of file LiDARCloud.py.

◆ __del__()

pyhelios.LiDARCloud.LiDARCloud.__del__ ( self)

Fallback destructor for cleanup without context manage.

Definition at line 88 of file LiDARCloud.py.

Member Function Documentation

◆ __enter__()

pyhelios.LiDARCloud.LiDARCloud.__enter__ ( self)

Context manager entry.

Definition at line 78 of file LiDARCloud.py.

◆ __exit__()

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

Context manager exit - cleanup resources.

Definition at line 82 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
centerGrid center position (vec3 or 3-element list)
sizeGrid dimensions [x, y, z] (vec3 or 3-element list)
ndivNumber of divisions [nx, ny, nz] (3-element list)
rotationAzimuthal 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 358 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
centerCell center position (vec3 or 3-element list)
sizeCell dimensions [x, y, z] (vec3 or 3-element list)
rotationAzimuthal rotation angle (radians, default 0.0)

Definition at line 396 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
scanIDScan ID this hit belongs to
xyzHit point coordinates (vec3 or 3-element list)
directionRay direction (vec3/SphericalCoord or 2-3 element list)
colorOptional RGB color (RGBcolor or 3-element list)

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

Add a LiDAR scan to the point cloud.

Parameters
originScanner position (vec3 or 3-element list/tuple)
NthetaNumber of scan points in zenith direction
theta_rangeZenith angle range (min, max) in radians
NphiNumber of scan points in azimuthal direction
phi_rangeAzimuthal angle range (min, max) in radians
exit_diameterLaser beam exit diameter (meters)
beam_divergenceBeam divergence angle (radians)
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 ... )

Definition at line 120 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
contextHelios 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 649 of file LiDARCloud.py.

◆ calculateHitGridCell()

pyhelios.LiDARCloud.LiDARCloud.calculateHitGridCell ( self)

Calculate hit point grid cell assignments.

Definition at line 464 of file LiDARCloud.py.

◆ calculateLeafArea()

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

Calculate leaf area for each grid cell.

   Requires triangulation to have been performed first.
Parameters
contextHelios Context instance
min_voxel_hitsOptional minimum number of hits required per voxel
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 562 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
contextHelios Context instance containing primitive geometry

Definition at line 596 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
contextHelios Context instance containing primitive geometry

Definition at line 581 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
rotationRotation angles (SphericalCoord or 2-3 element list)

Definition at line 276 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
shiftTranslation vector (vec3 or 3-element list)

Definition at line 258 of file LiDARCloud.py.

◆ deleteHitPoint()

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

Delete a hit point from the cloud.

Definition at line 247 of file LiDARCloud.py.

◆ disableCDGPUAcceleration()

pyhelios.LiDARCloud.LiDARCloud.disableCDGPUAcceleration ( self)

Disable GPU acceleration (use CPU ray tracing)

Definition at line 672 of file LiDARCloud.py.

◆ disableMessages()

pyhelios.LiDARCloud.LiDARCloud.disableMessages ( self)

Disable console output messages.

Definition at line 334 of file LiDARCloud.py.

◆ distanceFilter()

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

Filter hit points by maximum distance from scanne.

Definition at line 305 of file LiDARCloud.py.

◆ enableCDGPUAcceleration()

pyhelios.LiDARCloud.LiDARCloud.enableCDGPUAcceleration ( self)

Enable GPU acceleration for collision detection ray tracing.

Definition at line 668 of file LiDARCloud.py.

◆ enableMessages()

pyhelios.LiDARCloud.LiDARCloud.enableMessages ( self)

Enable console output messages.

Definition at line 338 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 627 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 621 of file LiDARCloud.py.

◆ exportLeafAreas()

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

Export leaf areas for each grid cell to file.

Definition at line 615 of file LiDARCloud.py.

◆ exportPointCloud()

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

Export point cloud to ASCII file.

Definition at line 322 of file LiDARCloud.py.

◆ exportTriangleAreas()

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

Export triangle areas to file.

Definition at line 609 of file LiDARCloud.py.

◆ exportTriangleNormals()

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

Export triangle normal vectors to file.

Definition at line 603 of file LiDARCloud.py.

◆ firstHitFilter()

pyhelios.LiDARCloud.LiDARCloud.firstHitFilter ( self)

Keep only first return hit points.

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

◆ getCellCenter()

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

Get center position of a grid cell.

Definition at line 426 of file LiDARCloud.py.

◆ getCellGtheta()

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

Get G(theta) value for a grid cell.

Definition at line 452 of file LiDARCloud.py.

◆ getCellLeafArea()

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

Get leaf area of a grid cell (m²)

Definition at line 440 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 446 of file LiDARCloud.py.

◆ getCellSize()

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

Get size of a grid cell.

Definition at line 433 of file LiDARCloud.py.

◆ getGridCellCount()

int pyhelios.LiDARCloud.LiDARCloud.getGridCellCount ( self)

Get total number of grid cells.

Definition at line 422 of file LiDARCloud.py.

◆ getHitColor()

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

Get color of a hit point.

Definition at line 240 of file LiDARCloud.py.

◆ getHitCount()

int pyhelios.LiDARCloud.LiDARCloud.getHitCount ( self)

Get total number of hit points in cloud.

Definition at line 222 of file LiDARCloud.py.

◆ getHitRaydir()

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

Get ray direction of a hit point.

Definition at line 233 of file LiDARCloud.py.

◆ getHitXYZ()

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

Get coordinates of a hit point.

Definition at line 226 of file LiDARCloud.py.

◆ getScanCount()

int pyhelios.LiDARCloud.LiDARCloud.getScanCount ( self)

Get total number of scans in the cloud.

Definition at line 149 of file LiDARCloud.py.

◆ getScanOrigin()

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

Get origin of a specific scan.

Definition at line 153 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 166 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 160 of file LiDARCloud.py.

◆ getTriangleCount()

int pyhelios.LiDARCloud.LiDARCloud.getTriangleCount ( self)

Get number of triangles in the mesh.

Definition at line 301 of file LiDARCloud.py.

◆ initializeCollisionDetection()

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

Initialize CollisionDetection plugin for ray tracing.

   Required before performing synthetic scans.
Parameters
contextHelios Context instance containing geometry

Definition at line 662 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 681 of file LiDARCloud.py.

◆ lastHitFilter()

pyhelios.LiDARCloud.LiDARCloud.lastHitFilter ( self)

Keep only last return hit points.

Definition at line 318 of file LiDARCloud.py.

◆ loadXML()

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

Load scan metadata from XML file.

Definition at line 328 of file LiDARCloud.py.

◆ reflectanceFilter()

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

Filter hit points by minimum reflectance value.

Definition at line 310 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 458 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
contextHelios Context containing geometry to scan
rays_per_pulseNumber of rays per pulse (None=discrete-return, typical: 100)
pulse_distance_thresholdDistance threshold for aggregating hits (meters, required for waveform)
scan_grid_onlyIf True, only scan within defined grid cells
record_missesIf True, record miss/sky points where rays don't hit geometry
appendIf 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 517 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
LmaxMaximum triangle edge length
max_aspect_ratioMaximum triangle aspect ratio (default 4.0)

Definition at line 295 of file LiDARCloud.py.

Member Data Documentation

◆ _cloud_ptr

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

Definition at line 73 of file LiDARCloud.py.


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