Class for GPU-accelerated collision detection and spatial queries in Helios. More...

#include <CollisionDetection.h>

Data Structures
struct	AngularBins
	Angular bin structure for rasterization-based collision detection. More...

struct	Cone
	Structure representing a cone for collision detection. More...

struct	HitResult
	Structure representing the result of a ray-primitive intersection. More...

struct	MemoryUsageStats
	Get memory usage statistics for different BVH layouts. More...

struct	OptimalPathResult
	Structure representing the result of optimal cone path detection. More...

struct	RayPacket
	Optimized ray packet for streaming processing Organizes ray data in Structure-of-Arrays format for better memory access. More...

struct	RayQuery
	Structure representing a ray query for generic ray-tracing operations. More...

struct	RayStream
	Streaming ray tracer interface Enables efficient batch processing of ray packets. More...

struct	RayTracingStats
	Structure for batch ray-tracing statistics. More...

Public Types
enum class	BVHOptimizationMode { SOA_UNCOMPRESSED }
	BVH optimization modes for performance improvements. More...

Public Member Functions
	CollisionDetection (helios::Context *context)
	Constructor for CollisionDetection class.

	~CollisionDetection ()
	Destructor for CollisionDetection class.

std::vector< uint >	findCollisions (uint UUID, bool allow_spatial_culling=true)
	Find all primitives/objects that collide with a given primitive.

std::vector< uint >	findCollisions (const std::vector< uint > &UUIDs, bool allow_spatial_culling=true)
	Find all primitives/objects that collide with any of the given primitives.

std::vector< uint >	findCollisions (const std::vector< uint > &primitive_UUIDs, const std::vector< uint > &object_IDs, bool allow_spatial_culling=true)
	Find collisions between primitives and compound objects.

std::vector< uint >	findCollisions (const std::vector< uint > &query_UUIDs, const std::vector< uint > &query_object_IDs, const std::vector< uint > &target_UUIDs, const std::vector< uint > &target_object_IDs, bool allow_spatial_culling=true)
	Find collisions restricting both query and target geometry.

HitResult	castRay (const RayQuery &ray_query)
	Cast a single ray and return detailed intersection information.

HitResult	castRay (const helios::vec3 &origin, const helios::vec3 &direction, float max_distance=-1.0f, const std::vector< uint > &target_UUIDs={})
	Cast a single ray with simplified parameters.

std::vector< HitResult >	castRays (const std::vector< RayQuery > &ray_queries, RayTracingStats *stats=nullptr)
	Cast multiple rays in batch for improved performance.

void	setBVHOptimizationMode (BVHOptimizationMode mode)
	Set BVH optimization mode for performance improvements.

BVHOptimizationMode	getBVHOptimizationMode () const
	Get current BVH optimization mode.

std::vector< HitResult >	castRaysOptimized (const std::vector< RayQuery > &ray_queries, RayTracingStats *stats=nullptr)
	Cast rays using optimized Structure-of-Arrays BVH layout.

bool	processRayStream (RayStream &ray_stream, RayTracingStats *stats=nullptr)
	Cast ray packets using streaming interface for optimal GPU utilization.

MemoryUsageStats	getBVHMemoryUsage () const

std::vector< std::vector< std::vector< std::vector< HitResult > > > >	performGridRayIntersection (const helios::vec3 &grid_center, const helios::vec3 &grid_size, const helios::int3 &grid_divisions, const std::vector< RayQuery > &ray_queries)
	Perform grid-based ray intersection for voxel operations.

std::vector< std::vector< HitResult > >	calculateVoxelPathLengths (const helios::vec3 &scan_origin, const std::vector< helios::vec3 > &ray_directions, const std::vector< helios::vec3 > &voxel_centers, const std::vector< helios::vec3 > &voxel_sizes)
	Calculate ray path lengths through individual voxels for LiDAR processing.

void	calculateRayPathLengthsDetailed (const helios::vec3 &grid_center, const helios::vec3 &grid_size, const helios::int3 &grid_divisions, const std::vector< helios::vec3 > &ray_origins, const std::vector< helios::vec3 > &ray_directions, std::vector< HitResult > &hit_results)
	Enhanced ray path length calculations with detailed statistics.

OptimalPathResult	findOptimalConePath (const helios::vec3 &apex, const helios::vec3 &centralAxis, float half_angle, float height=0.0f, int initialSamples=256)
	Find the radial direction through a cone toward the largest gap.

void	calculateGridIntersection (const helios::vec3 &grid_center, const helios::vec3 &grid_size, const helios::int3 &grid_divisions, const std::vector< uint > &UUIDs={})
	Calculate which primitives fall within a 3D grid.

std::vector< std::vector< std::vector< std::vector< uint > > > >	getGridCells ()
	Get all grid cells and their contained primitives.

std::vector< uint >	getGridIntersections (int i, int j, int k)
	Get primitives in a specific grid cell.

std::vector< uint >	slicePrimitive (uint UUID, const std::vector< helios::vec3 > &voxel_face_vertices, helios::WarningAggregator &warnings)
	Slice a primitive (patch or triangle) into multiple triangles using a planar face.

std::vector< uint >	slicePrimitivesUsingGrid (const std::vector< uint > &UUIDs, const helios::vec3 &grid_center, const helios::vec3 &grid_size, const helios::int3 &grid_divisions)
	Slice primitives along a regular 3D grid.

void	calculatePrimitiveVoxelIntersection (const std::vector< uint > &UUIDs={})
	Calculate voxel-primitive intersections using OpenMP parallelization.

helios::vec3	linesIntersection (const helios::vec3 &line1_point, const helios::vec3 &line1_direction, const helios::vec3 &line2_point, const helios::vec3 &line2_direction) const
	Calculate 3D line intersection point.

bool	approxSame (float a, float b, float absTol, float relTol) const
	Compare floats with dual tolerance (absolute + relative)

bool	approxSame (const helios::vec3 &a, const helios::vec3 &b, float absTol) const
	Compare vec3's element-wise with absolute tolerance.

helios::vec2	interpolate_texture_UV_to_slice_point (const helios::vec3 &p1, const helios::vec2 &uv1, const helios::vec3 &p2, const helios::vec2 &uv2, const helios::vec3 &ps) const
	Interpolate UV texture coordinates to slice point.

void	calculateVoxelRayPathLengths (const helios::vec3 &grid_center, const helios::vec3 &grid_size, const helios::int3 &grid_divisions, const std::vector< helios::vec3 > &ray_origins, const std::vector< helios::vec3 > &ray_directions)
	Calculate ray path lengths and transmission statistics for a voxel grid.

void	setVoxelTransmissionProbability (int P_denom, int P_trans, const helios::int3 &ijk)
	Set transmission probability counts for a voxel.

void	getVoxelTransmissionProbability (const helios::int3 &ijk, int &P_denom, int &P_trans) const
	Get transmission probability counts for a voxel.

void	setVoxelRbar (float r_bar, const helios::int3 &ijk)
	Set average ray propagation distance for a voxel.

float	getVoxelRbar (const helios::int3 &ijk) const
	Get average ray propagation distance for a voxel.

void	getVoxelRayHitCounts (const helios::int3 &ijk, int &hit_before, int &hit_after, int &hit_inside) const
	Get ray classification counts for a voxel (for Beer's law calculations)

std::vector< float >	getVoxelRayPathLengths (const helios::int3 &ijk) const
	Get individual ray path lengths for a voxel (for Beer's law calculations)

void	clearVoxelData ()
	Clear all voxel ray statistics data.

int	optimizeLayout (const std::vector< uint > &UUIDs, float learning_rate=0.01f, int max_iterations=1000)
	Optimize layout of primitives/objects to minimize collisions.

std::vector< std::pair< uint, uint > >	findCollisionsWithinDistance (const std::vector< uint > &query_UUIDs, const std::vector< uint > &target_UUIDs, float max_distance)
	Find collisions within a specified distance threshold.

void	setMaxCollisionDistance (float distance)
	Set maximum distance for collision detection queries.

float	getMaxCollisionDistance () const
	Get current maximum collision distance.

std::vector< uint >	filterGeometryByDistance (const helios::vec3 &query_center, float max_radius, const std::vector< uint > &candidate_UUIDs={})
	Filter geometry by spatial proximity for efficient collision detection.

bool	findNearestPrimitiveDistance (const helios::vec3 &origin, const helios::vec3 &direction, const std::vector< uint > &candidate_UUIDs, float &distance, helios::vec3 &obstacle_direction)
	Determine the distance to the nearest primitive in any direction, filtered by direction component.

bool	findNearestSolidObstacleInCone (const helios::vec3 &apex, const helios::vec3 &axis, float half_angle, float height, const std::vector< uint > &candidate_UUIDs, float &distance, helios::vec3 &obstacle_direction, int num_rays=64)
	Find the nearest solid obstacle within a cone using ray casting.

bool	findNearestSolidObstacleInCone (const helios::vec3 &apex, const helios::vec3 &axis, float half_angle, float height, const std::vector< uint > &candidate_UUIDs, const std::vector< uint > &plant_primitives, float &distance, helios::vec3 &obstacle_direction, int num_rays=64)
	Find nearest solid obstacle in cone with tree identification for per-tree BVH optimization.

void	buildBVH (const std::vector< uint > &UUIDs={})
	Build or rebuild the BVH acceleration structure.

void	updateBVH (const std::vector< uint > &UUIDs, bool force_rebuild=false)
	Efficiently update BVH with new geometry (avoids full rebuild when possible)

void	setStaticGeometry (const std::vector< uint > &UUIDs)
	Mark specific geometry as static (will be cached for efficiency)

void	rebuildBVH ()
	Force a complete rebuild of the BVH.

void	disableAutomaticBVHRebuilds ()
	Disable automatic BVH rebuilds (caller must manually manage rebuilds)

void	enableAutomaticBVHRebuilds ()
	Enable automatic BVH rebuilds (default behavior)

void	enableHierarchicalBVH ()
	Enable hierarchical BVH with separate static and dynamic geometry.

void	disableHierarchicalBVH ()
	Disable hierarchical BVH (use single unified BVH)

void	buildStaticBVH ()
	Build static BVH for obstacles and non-growing geometry.

void	enableTreeBasedBVH (float isolation_distance=5.0f)
	Enable tree-based BVH isolation for spatially separated trees.

void	disableTreeBasedBVH ()
	Disable tree-based BVH isolation.

bool	isTreeBasedBVHEnabled () const
	Check if tree-based BVH isolation is enabled.

void	initializeObstacleSpatialGrid ()
	Initialize spatial grid for fast static obstacle lookups.

void	registerTree (uint tree_object_id, const std::vector< uint > &tree_primitives)
	Register a tree object for per-tree BVH isolation.

void	setStaticObstacles (const std::vector< uint > &obstacle_primitives)
	Set static obstacle geometry for per-tree collision detection.

std::vector< uint >	getRelevantGeometryForTree (const helios::vec3 &query_position, const std::vector< uint > &query_primitives={}, float max_distance=15.0f)
	Get relevant geometry for tree-based collision detection.

bool	isBVHValid () const
	Check if BVH is valid and up-to-date.

void	enableGPUAcceleration ()
	Enable GPU acceleration for collision detection.

void	disableGPUAcceleration ()
	Disable GPU acceleration (use CPU-only algorithms)

bool	isGPUAccelerationEnabled () const
	Check if GPU acceleration is enabled.

void	disableMessages ()
	Disable console output messages.

void	enableMessages ()
	Enable console output messages.

size_t	getPrimitiveCount () const
	Get the number of primitives in the BVH.

void	getBVHStatistics (size_t &node_count, size_t &leaf_count, size_t &max_depth) const
	Get BVH statistics.

Static Public Member Functions
static int	selfTest (int argc, char **argv)
	Self-test routine to verify plugin functionality.

Static Public Attributes
static constexpr size_t	WARP_SIZE = 32
	Ray streaming for efficient GPU processing Processes multiple rays simultaneously for better GPU utilization.

static constexpr size_t	RAY_BATCH_SIZE = 1024
	Optimal batch size for ray processing.

Detailed Description

Class for GPU-accelerated collision detection and spatial queries in Helios.

The CollisionDetection class provides efficient algorithms for:

Primitive/CompoundObject collision detection using BVH acceleration
Cone intersection queries from arbitrary points
Grid-based intersection queries (replacing voxel primitives)
Layout optimization to minimize collisions

Definition at line 34 of file CollisionDetection.h.

Member Enumeration Documentation

◆ BVHOptimizationMode

enum class CollisionDetection::BVHOptimizationMode

strong

BVH optimization modes for performance improvements.

Enumerator
SOA_UNCOMPRESSED	Structure-of-Arrays, full precision.

Definition at line 367 of file CollisionDetection.h.

Constructor & Destructor Documentation

◆ CollisionDetection()

CollisionDetection::CollisionDetection ( helios::Context * context )

explicit

Constructor for CollisionDetection class.

Parameters

[in] context Pointer to the Helios context

Definition at line 67 of file CollisionDetection.cpp.

◆ ~CollisionDetection()

CollisionDetection::~CollisionDetection ( )

Destructor for CollisionDetection class.

Definition at line 127 of file CollisionDetection.cpp.

Member Function Documentation

◆ approxSame() [1/2]

bool CollisionDetection::approxSame	(	const helios::vec3 &	a,
		const helios::vec3 &	b,
		float	absTol
	)		const

Compare vec3's element-wise with absolute tolerance.

Definition at line 45 of file CollisionDetection_Slicing.cpp.

◆ approxSame() [2/2]

bool CollisionDetection::approxSame	(	float	a,
		float	b,
		float	absTol,
		float	relTol
	)		const

Compare floats with dual tolerance (absolute + relative)

Parameters

[in]	a	First value
[in]	b	Second value
[in]	absTol	Absolute tolerance
[in]	relTol	Relative tolerance

Returns: True if |a-b| ≤ absTol OR |a-b|/max(|a|,|b|) ≤ relTol

Definition at line 41 of file CollisionDetection_Slicing.cpp.

◆ buildBVH()

void CollisionDetection::buildBVH ( const std::vector< uint > & UUIDs = {} )

Build or rebuild the BVH acceleration structure.

Parameters

[in] UUIDs Optional vector of specific UUIDs to include (empty = all primitives)

Definition at line 337 of file CollisionDetection.cpp.

◆ buildStaticBVH()

void CollisionDetection::buildStaticBVH ( )

Build static BVH for obstacles and non-growing geometry.

Builds the static BVH using geometry set by setStaticGeometry(). Should be called after enabling hierarchical BVH and setting static geometry.

Definition at line 543 of file CollisionDetection.cpp.

◆ calculateGridIntersection()

void CollisionDetection::calculateGridIntersection	(	const helios::vec3 &	grid_center,
		const helios::vec3 &	grid_size,
		const helios::int3 &	grid_divisions,
		const std::vector< uint > &	UUIDs = `{}`
	)

Calculate which primitives fall within a 3D grid.

Parameters

[in]	grid_center	Center point of the 3D grid
[in]	grid_size	Size of the grid in x, y, z dimensions
[in]	grid_divisions	Number of divisions in x, y, z dimensions
[in]	UUIDs	Optional vector of specific UUIDs to test (empty = all primitives)

Definition at line 2135 of file CollisionDetection.cpp.

◆ calculatePrimitiveVoxelIntersection()

void CollisionDetection::calculatePrimitiveVoxelIntersection ( const std::vector< uint > & UUIDs = {} )

Calculate voxel-primitive intersections using OpenMP parallelization.

Parameters

[in] UUIDs Optional primitive UUIDs (empty = all primitives)

Note: Requires actual voxel primitives in Context; Creates "inside_UUIDs" primitive data on voxels; Uses OpenMP for CPU parallel execution

Definition at line 1483 of file CollisionDetection_Slicing.cpp.

◆ calculateRayPathLengthsDetailed()

void CollisionDetection::calculateRayPathLengthsDetailed	(	const helios::vec3 &	grid_center,
		const helios::vec3 &	grid_size,
		const helios::int3 &	grid_divisions,
		const std::vector< helios::vec3 > &	ray_origins,
		const std::vector< helios::vec3 > &	ray_directions,
		std::vector< HitResult > &	hit_results
	)

Enhanced ray path length calculations with detailed statistics.

Parameters

[in]	grid_center	Center point of the 3D voxel grid
[in]	grid_size	Size of the grid in x, y, z dimensions
[in]	grid_divisions	Number of divisions in x, y, z dimensions
[in]	ray_origins	Vector of ray origin points
[in]	ray_directions	Vector of ray direction vectors (should be normalized)
[out]	hit_results	Vector of detailed hit results for each ray

Definition at line 380 of file CollisionDetection_RayTracing.cpp.

◆ calculateVoxelPathLengths()

std::vector< std::vector< CollisionDetection::HitResult > > CollisionDetection::calculateVoxelPathLengths	(	const helios::vec3 &	scan_origin,
		const std::vector< helios::vec3 > &	ray_directions,
		const std::vector< helios::vec3 > &	voxel_centers,
		const std::vector< helios::vec3 > &	voxel_sizes
	)

Calculate ray path lengths through individual voxels for LiDAR processing.

Parameters

[in]	scan_origin	Single vec3 LiDAR scanner position
[in]	ray_directions	Vector of normalized ray directions (10K-10M rays)
[in]	voxel_centers	Vector of voxel center positions (8-1000 voxels)
[in]	voxel_sizes	Vector of voxel dimensions (width,height,depth)

Returns: Vector of HitResult vectors, one per voxel, with path_length populated for each ray intersection

This method extends performGridRayIntersection to handle individual voxels with specific centers and sizes. Uses ray-AABB intersection with path_length = t_max - max(0, t_min) for each intersection. Performance target: 1M rays × 100 voxels in <2 seconds with OpenMP parallelization.

Definition at line 298 of file CollisionDetection_RayTracing.cpp.

◆ calculateVoxelRayPathLengths()

void CollisionDetection::calculateVoxelRayPathLengths	(	const helios::vec3 &	grid_center,
		const helios::vec3 &	grid_size,
		const helios::int3 &	grid_divisions,
		const std::vector< helios::vec3 > &	ray_origins,
		const std::vector< helios::vec3 > &	ray_directions
	)

Calculate ray path lengths and transmission statistics for a voxel grid.

Parameters

[in]	grid_center	Center point of the 3D voxel grid
[in]	grid_size	Size of the grid in x, y, z dimensions
[in]	grid_divisions	Number of divisions in x, y, z dimensions
[in]	ray_origins	Vector of ray origin points
[in]	ray_directions	Vector of ray direction vectors (should be normalized)

Definition at line 3117 of file CollisionDetection.cpp.

◆ castRay() [1/2]

CollisionDetection::HitResult CollisionDetection::castRay	(	const helios::vec3 &	origin,
		const helios::vec3 &	direction,
		float	max_distance = `-1.0f`,
		const std::vector< uint > &	target_UUIDs = `{}`
	)

Cast a single ray with simplified parameters.

Parameters

[in]	origin	Ray origin point
[in]	direction	Ray direction vector (should be normalized)
[in]	max_distance	Maximum ray distance (negative = infinite)
[in]	target_UUIDs	Target primitive UUIDs (empty = all primitives)

Returns: HitResult containing intersection details

Definition at line 80 of file CollisionDetection_RayTracing.cpp.

◆ castRay() [2/2]

CollisionDetection::HitResult CollisionDetection::castRay ( const RayQuery & ray_query )

Cast a single ray and return detailed intersection information.

Parameters

[in] ray_query Ray parameters (origin, direction, max distance, target UUIDs)

Returns: HitResult containing intersection details

Definition at line 76 of file CollisionDetection_RayTracing.cpp.

◆ castRays()

std::vector< CollisionDetection::HitResult > CollisionDetection::castRays	(	const std::vector< RayQuery > &	ray_queries,
		RayTracingStats *	stats = `nullptr`
	)

Cast multiple rays in batch for improved performance.

Parameters

[in]	ray_queries	Vector of ray parameters
[out]	stats	Optional ray-tracing statistics

Returns: Vector of HitResult corresponding to each input ray

Definition at line 210 of file CollisionDetection_RayTracing.cpp.

◆ castRaysOptimized()

std::vector< CollisionDetection::HitResult > CollisionDetection::castRaysOptimized	(	const std::vector< RayQuery > &	ray_queries,
		RayTracingStats *	stats = `nullptr`
	)

Cast rays using optimized Structure-of-Arrays BVH layout.

Parameters

[in]	ray_queries	Vector of ray parameters
[out]	stats	Optional ray-tracing statistics

Returns: Vector of HitResult corresponding to each input ray

Definition at line 441 of file CollisionDetection_RayTracing.cpp.

◆ clearVoxelData()

void CollisionDetection::clearVoxelData ( )

Clear all voxel ray statistics data.

Definition at line 3326 of file CollisionDetection.cpp.

◆ disableAutomaticBVHRebuilds()

void CollisionDetection::disableAutomaticBVHRebuilds ( )

Disable automatic BVH rebuilds (caller must manually manage rebuilds)

Definition at line 490 of file CollisionDetection.cpp.

◆ disableGPUAcceleration()

void CollisionDetection::disableGPUAcceleration ( )

Disable GPU acceleration (use CPU-only algorithms)

Definition at line 736 of file CollisionDetection.cpp.

◆ disableHierarchicalBVH()

void CollisionDetection::disableHierarchicalBVH ( )

Disable hierarchical BVH (use single unified BVH)

Definition at line 503 of file CollisionDetection.cpp.

◆ disableMessages()

void CollisionDetection::disableMessages ( )

Disable console output messages.

Definition at line 747 of file CollisionDetection.cpp.

◆ disableTreeBasedBVH()

void CollisionDetection::disableTreeBasedBVH ( )

Disable tree-based BVH isolation.

Definition at line 4264 of file CollisionDetection.cpp.

◆ enableAutomaticBVHRebuilds()

void CollisionDetection::enableAutomaticBVHRebuilds ( )

Enable automatic BVH rebuilds (default behavior)

Definition at line 494 of file CollisionDetection.cpp.

◆ enableGPUAcceleration()

void CollisionDetection::enableGPUAcceleration ( )

Enable GPU acceleration for collision detection.

Definition at line 723 of file CollisionDetection.cpp.

◆ enableHierarchicalBVH()

void CollisionDetection::enableHierarchicalBVH ( )

Enable hierarchical BVH with separate static and dynamic geometry.

Definition at line 498 of file CollisionDetection.cpp.

◆ enableMessages()

void CollisionDetection::enableMessages ( )

Enable console output messages.

Definition at line 751 of file CollisionDetection.cpp.

◆ enableTreeBasedBVH()

void CollisionDetection::enableTreeBasedBVH ( float isolation_distance = 5.0f )

Enable tree-based BVH isolation for spatially separated trees.

Parameters

[in] isolation_distance Spatial distance threshold for tree isolation

When enabled, creates separate BVHs for each tree object that are spatially separated by at least isolation_distance. This provides linear scaling for scenarios with multiple non-interacting trees.

Definition at line 4259 of file CollisionDetection.cpp.

◆ filterGeometryByDistance()

std::vector< uint > CollisionDetection::filterGeometryByDistance	(	const helios::vec3 &	query_center,
		float	max_radius,
		const std::vector< uint > &	candidate_UUIDs = `{}`
	)

Filter geometry by spatial proximity for efficient collision detection.

Parameters

[in]	query_center	Center point for spatial filtering
[in]	max_radius	Maximum radius for including geometry
[in]	candidate_UUIDs	Optional list of candidate UUIDs (empty = all geometry)

Returns: Vector of UUIDs within the specified radius

Definition at line 3067 of file CollisionDetection.cpp.

◆ findCollisions() [1/4]

std::vector< uint > CollisionDetection::findCollisions	(	const std::vector< uint > &	primitive_UUIDs,
		const std::vector< uint > &	object_IDs,
		bool	allow_spatial_culling = `true`
	)

Find collisions between primitives and compound objects.

Parameters

[in]	primitive_UUIDs	Vector of primitive UUIDs to test
[in]	object_IDs	Vector of compound object IDs to test against
[in]	allow_spatial_culling	If true, use tree-based BVH spatial culling for efficiency (default: true)

Returns: Vector of UUIDs that intersect

Definition at line 198 of file CollisionDetection.cpp.

◆ findCollisions() [2/4]

std::vector< uint > CollisionDetection::findCollisions	(	const std::vector< uint > &	query_UUIDs,
		const std::vector< uint > &	query_object_IDs,
		const std::vector< uint > &	target_UUIDs,
		const std::vector< uint > &	target_object_IDs,
		bool	allow_spatial_culling = `true`
	)

Find collisions restricting both query and target geometry.

Parameters

[in]	query_UUIDs	Vector of primitive UUIDs to test for collisions
[in]	query_object_IDs	Vector of object IDs to test for collisions
[in]	target_UUIDs	Vector of primitive UUIDs to test against (empty = all primitives)
[in]	target_object_IDs	Vector of object IDs to test against (empty = all objects)
[in]	allow_spatial_culling	If true, use tree-based BVH spatial culling for efficiency (default: true)

Returns: Vector of UUIDs from the target set that intersect with any query primitive

Definition at line 224 of file CollisionDetection.cpp.

◆ findCollisions() [3/4]

std::vector< uint > CollisionDetection::findCollisions	(	const std::vector< uint > &	UUIDs,
		bool	allow_spatial_culling = `true`
	)

Find all primitives/objects that collide with any of the given primitives.

Parameters

[in]	UUIDs	Vector of query primitive UUIDs
[in]	allow_spatial_culling	If true, use tree-based BVH spatial culling for efficiency (default: true)

Returns: Vector of UUIDs that intersect with any of the query primitives

Definition at line 137 of file CollisionDetection.cpp.

◆ findCollisions() [4/4]

std::vector< uint > CollisionDetection::findCollisions	(	uint	UUID,
		bool	allow_spatial_culling = `true`
	)

Find all primitives/objects that collide with a given primitive.

Parameters

[in]	UUID	Unique identifier of the query primitive
[in]	allow_spatial_culling	If true, use tree-based BVH spatial culling for efficiency (default: true)

Returns: Vector of UUIDs that intersect with the query primitive

Definition at line 133 of file CollisionDetection.cpp.

◆ findCollisionsWithinDistance()

std::vector< std::pair< uint, uint > > CollisionDetection::findCollisionsWithinDistance	(	const std::vector< uint > &	query_UUIDs,
		const std::vector< uint > &	target_UUIDs,
		float	max_distance
	)

Find collisions within a specified distance threshold.

Parameters

[in]	query_UUIDs	Vector of primitive UUIDs to test for collisions
[in]	target_UUIDs	Vector of primitive UUIDs to test against
[in]	max_distance	Maximum distance for collision consideration

Returns: Vector of collision pairs within distance threshold

Definition at line 2993 of file CollisionDetection.cpp.

◆ findNearestPrimitiveDistance()

bool CollisionDetection::findNearestPrimitiveDistance	(	const helios::vec3 &	origin,
		const helios::vec3 &	direction,
		const std::vector< uint > &	candidate_UUIDs,
		float &	distance,
		helios::vec3 &	obstacle_direction
	)

Determine the distance to the nearest primitive in any direction, filtered by direction component.

Parameters

[in]	origin	Origin location from which to search
[in]	direction	Unit direction vector to filter "forward" surfaces (dot product > 0)
[in]	candidate_UUIDs	Vector of primitive UUIDs to consider for intersection
[out]	distance	Distance to the nearest primitive (only valid if return is true)
[out]	obstacle_direction	Direction from origin to nearest obstacle (only valid if return is true)

Returns: True if a primitive is found that is "in front" of the direction vector, false otherwise

This method finds the nearest solid surface in any direction from the origin point, but only considers surfaces that are "in front" of the growth direction. A surface is considered "in front" if the vector from origin to the closest point on the surface has a positive dot product with the input direction vector.

Definition at line 2360 of file CollisionDetection.cpp.

◆ findNearestSolidObstacleInCone() [1/2]

bool CollisionDetection::findNearestSolidObstacleInCone	(	const helios::vec3 &	apex,
		const helios::vec3 &	axis,
		float	half_angle,
		float	height,
		const std::vector< uint > &	candidate_UUIDs,
		const std::vector< uint > &	plant_primitives,
		float &	distance,
		helios::vec3 &	obstacle_direction,
		int	num_rays = `64`
	)

Find nearest solid obstacle in cone with tree identification for per-tree BVH optimization.

Find the nearest solid obstacle within a cone-shaped detection volume with tree identification

This method is optimized for per-tree BVH systems by identifying the querying tree through plant primitive UUIDs, enabling efficient spatial filtering of collision candidates.

Parameters

[in]	apex	Location of the cone apex (plant growth point)
[in]	axis	Central axis direction of the cone (growth direction, normalized)
[in]	half_angle	Half-angle of the cone in radians
[in]	height	Height of the cone (detection distance)
[in]	candidate_UUIDs	Vector of obstacle primitive UUIDs to check for collisions
[in]	plant_primitives	Vector of plant primitive UUIDs to identify the querying tree
[out]	distance	Distance to the nearest obstacle surface
[out]	obstacle_direction	Direction vector from apex toward the nearest obstacle point
[in]	num_rays	Number of rays to cast within the cone for sampling

Returns: True if an obstacle was found within the cone, false otherwise

Definition at line 2539 of file CollisionDetection.cpp.

◆ findNearestSolidObstacleInCone() [2/2]

bool CollisionDetection::findNearestSolidObstacleInCone	(	const helios::vec3 &	apex,
		const helios::vec3 &	axis,
		float	half_angle,
		float	height,
		const std::vector< uint > &	candidate_UUIDs,
		float &	distance,
		helios::vec3 &	obstacle_direction,
		int	num_rays = `64`
	)

Find the nearest solid obstacle within a cone using ray casting.

Parameters

[in]	apex	Cone apex position
[in]	axis	Central axis of the cone (normalized)
[in]	half_angle	Half-angle of cone in radians
[in]	height	Maximum detection distance (cone height)
[in]	candidate_UUIDs	Vector of primitive UUIDs to consider as solid obstacles
[out]	distance	Distance to nearest obstacle (only valid if return is true)
[out]	obstacle_direction	Direction from apex to nearest obstacle (only valid if return is true)
[in]	num_rays	Number of rays to cast for detection (default: 64)

Returns: True if a solid obstacle is found within the cone, false otherwise

This method casts rays within a cone to find the nearest solid obstacle. Unlike the soft collision avoidance, this uses a smaller cone angle and returns the exact distance to the nearest primitive surface using accurate ray-primitive intersection tests.

Definition at line 2454 of file CollisionDetection.cpp.

◆ findOptimalConePath()

CollisionDetection::OptimalPathResult CollisionDetection::findOptimalConePath	(	const helios::vec3 &	apex,
		const helios::vec3 &	centralAxis,
		float	half_angle,
		float	height = `0.0f`,
		int	initialSamples = `256`
	)

Find the radial direction through a cone toward the largest gap.

Parameters

[in]	apex	Cone apex position
[in]	centralAxis	Central axis of the cone
[in]	half_angle	Half-angle of cone in radians
[in]	height	Height of cone (0 = infinite)
[in]	initialSamples	Number of initial uniform samples (default: 256)

Returns: OptimalPathResult containing the optimal direction and collision count

Definition at line 1661 of file CollisionDetection.cpp.

◆ getBVHMemoryUsage()

CollisionDetection::MemoryUsageStats CollisionDetection::getBVHMemoryUsage ( ) const

Definition at line 520 of file CollisionDetection_RayTracing.cpp.

◆ getBVHOptimizationMode()

CollisionDetection::BVHOptimizationMode CollisionDetection::getBVHOptimizationMode ( ) const

Get current BVH optimization mode.

Returns: Current optimization mode

Definition at line 431 of file CollisionDetection_RayTracing.cpp.

◆ getBVHStatistics()

void CollisionDetection::getBVHStatistics	(	size_t &	node_count,
		size_t &	leaf_count,
		size_t &	max_depth
	)		const

Get BVH statistics.

Parameters

[out]	node_count	Number of nodes in BVH
[out]	leaf_count	Number of leaf nodes in BVH
[out]	max_depth	Maximum depth of BVH

Definition at line 759 of file CollisionDetection.cpp.

◆ getGridCells()

std::vector< std::vector< std::vector< std::vector< uint > > > > CollisionDetection::getGridCells ( )

Get all grid cells and their contained primitives.

Returns: 3D vector indexed as [i][j][k] containing UUIDs in each cell

Definition at line 2151 of file CollisionDetection.cpp.

◆ getGridIntersections()

std::vector< uint > CollisionDetection::getGridIntersections	(	int	i,
		int	j,
		int	k
	)

Get primitives in a specific grid cell.

Parameters

[in]	i	Grid cell index in x-dimension
[in]	j	Grid cell index in y-dimension
[in]	k	Grid cell index in z-dimension

Returns: Vector of UUIDs in the specified grid cell

Definition at line 2155 of file CollisionDetection.cpp.

◆ getMaxCollisionDistance()

float CollisionDetection::getMaxCollisionDistance ( ) const

Get current maximum collision distance.

Returns: Current maximum distance threshold

Definition at line 3063 of file CollisionDetection.cpp.

◆ getPrimitiveCount()

size_t CollisionDetection::getPrimitiveCount ( ) const

Get the number of primitives in the BVH.

Returns: Number of primitives

Definition at line 755 of file CollisionDetection.cpp.

◆ getRelevantGeometryForTree()

std::vector< uint > CollisionDetection::getRelevantGeometryForTree	(	const helios::vec3 &	query_position,
		const std::vector< uint > &	query_primitives = `{}`,
		float	max_distance = `15.0f`
	)

Get relevant geometry for tree-based collision detection.

Parameters

[in]	query_position	Position of the collision query
[in]	query_primitives	Primitives making the query (to identify source tree)

Returns: Vector of primitive UUIDs that should be considered for collision

Returns geometry that includes:

Static obstacles (always relevant)
Source tree's own geometry
Nearby trees within interaction distance

Definition at line 4381 of file CollisionDetection.cpp.

◆ getVoxelRayHitCounts()

void CollisionDetection::getVoxelRayHitCounts	(	const helios::int3 &	ijk,
		int &	hit_before,
		int &	hit_after,
		int &	hit_inside
	)		const

Get ray classification counts for a voxel (for Beer's law calculations)

Parameters

[in]	ijk	Voxel indices (i,j,k)
[out]	hit_before	Number of rays that hit geometry BEFORE entering the voxel
[out]	hit_after	Number of rays that hit geometry AFTER entering the voxel
[out]	hit_inside	Number of rays that hit geometry INSIDE the voxel

Definition at line 3263 of file CollisionDetection.cpp.

◆ getVoxelRayPathLengths()

std::vector< float > CollisionDetection::getVoxelRayPathLengths ( const helios::int3 & ijk ) const

Get individual ray path lengths for a voxel (for Beer's law calculations)

Parameters

[in] ijk Voxel indices (i,j,k)

Returns: Vector of individual path lengths for rays that passed through the voxel

Definition at line 3287 of file CollisionDetection.cpp.

◆ getVoxelRbar()

float CollisionDetection::getVoxelRbar ( const helios::int3 & ijk ) const

Get average ray propagation distance for a voxel.

Parameters

[in] ijk Voxel indices (i,j,k)

Returns: Average ray propagation distance in meters

Definition at line 3234 of file CollisionDetection.cpp.

◆ getVoxelTransmissionProbability()

void CollisionDetection::getVoxelTransmissionProbability	(	const helios::int3 &	ijk,
		int &	P_denom,
		int &	P_trans
	)		const

Get transmission probability counts for a voxel.

Parameters

[in]	ijk	Voxel indices (i,j,k)
[out]	P_denom	Number of rays that reached this voxel
[out]	P_trans	Number of rays that were transmitted through this voxel

Definition at line 3184 of file CollisionDetection.cpp.

◆ initializeObstacleSpatialGrid()

void CollisionDetection::initializeObstacleSpatialGrid ( )

Initialize spatial grid for fast static obstacle lookups.

Definition at line 4274 of file CollisionDetection.cpp.

◆ interpolate_texture_UV_to_slice_point()

helios::vec2 CollisionDetection::interpolate_texture_UV_to_slice_point	(	const helios::vec3 &	p1,
		const helios::vec2 &	uv1,
		const helios::vec3 &	p2,
		const helios::vec2 &	uv2,
		const helios::vec3 &	ps
	)		const

Interpolate UV texture coordinates to slice point.

Parameters

[in]	p1	First edge vertex position
[in]	uv1	First edge vertex UV
[in]	p2	Second edge vertex position
[in]	uv2	Second edge vertex UV
[in]	ps	Slice point position on edge

Returns: Interpolated UV coordinates at slice point

Definition at line 49 of file CollisionDetection_Slicing.cpp.

◆ isBVHValid()

bool CollisionDetection::isBVHValid ( ) const

Check if BVH is valid and up-to-date.

Returns: True if BVH is valid, false otherwise

Definition at line 692 of file CollisionDetection.cpp.

◆ isGPUAccelerationEnabled()

bool CollisionDetection::isGPUAccelerationEnabled ( ) const

Check if GPU acceleration is enabled.

Returns: True if GPU acceleration is enabled

Definition at line 743 of file CollisionDetection.cpp.

◆ isTreeBasedBVHEnabled()

bool CollisionDetection::isTreeBasedBVHEnabled ( ) const

Check if tree-based BVH isolation is enabled.

Returns: True if tree-based BVH is enabled, false otherwise

Definition at line 4270 of file CollisionDetection.cpp.

◆ linesIntersection()

helios::vec3 CollisionDetection::linesIntersection	(	const helios::vec3 &	line1_point,
		const helios::vec3 &	line1_direction,
		const helios::vec3 &	line2_point,
		const helios::vec3 &	line2_direction
	)		const

Calculate 3D line intersection point.

Parameters

[in]	line1_point	Point on first line
[in]	line1_direction	Direction of first line
[in]	line2_point	Point on second line
[in]	line2_direction	Direction of second line

Returns: Intersection point (assumes lines intersect)

Definition at line 22 of file CollisionDetection_Slicing.cpp.

◆ optimizeLayout()

int CollisionDetection::optimizeLayout	(	const std::vector< uint > &	UUIDs,
		float	learning_rate = `0.01f`,
		int	max_iterations = `1000`
	)

Optimize layout of primitives/objects to minimize collisions.

Parameters

[in]	UUIDs	Vector of primitive/object UUIDs to optimize
[in]	learning_rate	Step size for optimization algorithm
[in]	max_iterations	Maximum number of optimization iterations

Returns: Final collision count after optimization

Definition at line 2162 of file CollisionDetection.cpp.

◆ performGridRayIntersection()

std::vector< std::vector< std::vector< std::vector< CollisionDetection::HitResult > > > > CollisionDetection::performGridRayIntersection	(	const helios::vec3 &	grid_center,
		const helios::vec3 &	grid_size,
		const helios::int3 &	grid_divisions,
		const std::vector< RayQuery > &	ray_queries
	)

Perform grid-based ray intersection for voxel operations.

Parameters

[in]	grid_center	Center point of the 3D grid
[in]	grid_size	Size of the grid in x, y, z dimensions
[in]	grid_divisions	Number of divisions in x, y, z dimensions
[in]	ray_queries	Vector of rays to intersect with the grid

Returns: 4D vector indexed as [i][j][k][hit_index] containing HitResult objects for each hit in each voxel

Definition at line 259 of file CollisionDetection_RayTracing.cpp.

◆ processRayStream()

bool CollisionDetection::processRayStream	(	RayStream &	ray_stream,
		RayTracingStats *	stats = `nullptr`
	)

Cast ray packets using streaming interface for optimal GPU utilization.

Parameters

[in]	ray_stream	Ray stream containing batched ray packets
[out]	stats	Optional ray-tracing statistics

Returns: True if all packets processed successfully

Definition at line 478 of file CollisionDetection_RayTracing.cpp.

◆ rebuildBVH()

void CollisionDetection::rebuildBVH ( )

Force a complete rebuild of the BVH.

Definition at line 485 of file CollisionDetection.cpp.

◆ registerTree()

void CollisionDetection::registerTree	(	uint	tree_object_id,
		const std::vector< uint > &	tree_primitives
	)

Register a tree object for per-tree BVH isolation.

Parameters

[in]	tree_object_id	Object ID of the tree
[in]	tree_primitives	Primitive UUIDs belonging to this tree

Associates primitives with a specific tree for isolated collision detection. Should be called before plant growth begins.

Definition at line 4323 of file CollisionDetection.cpp.

◆ selfTest()

int CollisionDetection::selfTest	(	int	argc,
		char **	argv
	)

static

Self-test routine to verify plugin functionality.

Returns: 0 if all tests pass, non-zero otherwise

Definition at line 27 of file selfTest.cpp.

◆ setBVHOptimizationMode()

void CollisionDetection::setBVHOptimizationMode ( BVHOptimizationMode mode )

Set BVH optimization mode for performance improvements.

Parameters

[in] mode Optimization mode (SOA_UNCOMPRESSED)

Definition at line 406 of file CollisionDetection_RayTracing.cpp.

◆ setMaxCollisionDistance()

void CollisionDetection::setMaxCollisionDistance ( float distance )

Set maximum distance for collision detection queries.

Parameters

[in] distance Maximum distance threshold (meters)

Definition at line 3055 of file CollisionDetection.cpp.

◆ setStaticGeometry()

void CollisionDetection::setStaticGeometry ( const std::vector< uint > & UUIDs )

Mark specific geometry as static (will be cached for efficiency)

Parameters

[in] UUIDs Vector of primitive UUIDs that represent static obstacles

Definition at line 630 of file CollisionDetection.cpp.

◆ setStaticObstacles()

void CollisionDetection::setStaticObstacles ( const std::vector< uint > & obstacle_primitives )

Set static obstacle geometry for per-tree collision detection.

Parameters

[in] obstacle_primitives Primitive UUIDs that represent static obstacles

These primitives will be included in ALL tree collision detection queries. Should include ground, buildings, and other permanent obstacles.

Definition at line 4366 of file CollisionDetection.cpp.

◆ setVoxelRbar()

void CollisionDetection::setVoxelRbar	(	float	r_bar,
		const helios::int3 &	ijk
	)

Set average ray propagation distance for a voxel.

Parameters

[in]	r_bar	Average ray propagation distance in meters
[in]	ijk	Voxel indices (i,j,k)

Definition at line 3205 of file CollisionDetection.cpp.

◆ setVoxelTransmissionProbability()

void CollisionDetection::setVoxelTransmissionProbability	(	int	P_denom,
		int	P_trans,
		const helios::int3 &	ijk
	)

Set transmission probability counts for a voxel.

Parameters

[in]	P_denom	Number of rays that reached this voxel (denominator)
[in]	P_trans	Number of rays that were transmitted through this voxel (numerator)
[in]	ijk	Voxel indices (i,j,k)

Definition at line 3165 of file CollisionDetection.cpp.

◆ slicePrimitive()

std::vector< uint > CollisionDetection::slicePrimitive	(	uint	UUID,
		const std::vector< helios::vec3 > &	voxel_face_vertices,
		helios::WarningAggregator &	warnings
	)

Slice a primitive (patch or triangle) into multiple triangles using a planar face.

Parameters

[in]	UUID	Primitive UUID to slice
[in]	voxel_face_vertices	Vector of ≥3 points defining the slicing plane
[in]	warnings	Warning aggregator for collecting non-fatal warnings

Returns: Vector of new triangle UUIDs created by slicing

Definition at line 114 of file CollisionDetection_Slicing.cpp.

◆ slicePrimitivesUsingGrid()

std::vector< uint > CollisionDetection::slicePrimitivesUsingGrid	(	const std::vector< uint > &	UUIDs,
		const helios::vec3 &	grid_center,
		const helios::vec3 &	grid_size,
		const helios::int3 &	grid_divisions
	)

Slice primitives along a regular 3D grid.

Parameters

[in]	UUIDs	Primitives to slice
[in]	grid_center	Center of voxel grid
[in]	grid_size	Grid dimensions (x, y, z)
[in]	grid_divisions	Grid cells (x, y, z)

Returns: All resulting triangle UUIDs (sliced + unmodified)

Note: Creates "cell_ID" primitive data (-1 for outside grid); Populates internal grid_cells structure

Definition at line 1234 of file CollisionDetection_Slicing.cpp.

◆ updateBVH()

void CollisionDetection::updateBVH	(	const std::vector< uint > &	UUIDs,
		bool	force_rebuild = `false`
	)

Efficiently update BVH with new geometry (avoids full rebuild when possible)

Parameters

[in]	UUIDs	Vector of UUIDs to include in BVH
[in]	force_rebuild	Force complete rebuild even if geometry hasn't changed significantly

Definition at line 576 of file CollisionDetection.cpp.

Field Documentation

◆ RAY_BATCH_SIZE

constexpr size_t CollisionDetection::RAY_BATCH_SIZE = 1024

staticconstexpr

Optimal batch size for ray processing.

Definition at line 135 of file CollisionDetection.h.

◆ WARP_SIZE

constexpr size_t CollisionDetection::WARP_SIZE = 32

staticconstexpr

Ray streaming for efficient GPU processing Processes multiple rays simultaneously for better GPU utilization.

CUDA warp size for optimal batching

Definition at line 134 of file CollisionDetection.h.

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

plugins/collisiondetection/include/CollisionDetection.h
plugins/collisiondetection/src/CollisionDetection.cpp
plugins/collisiondetection/src/CollisionDetection_RayTracing.cpp
plugins/collisiondetection/src/CollisionDetection_Slicing.cpp
plugins/collisiondetection/tests/selfTest.cpp

	1.3.64

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ BVHOptimizationMode

Constructor & Destructor Documentation

◆ CollisionDetection()

◆ ~CollisionDetection()

Member Function Documentation

◆ approxSame() [1/2]

◆ approxSame() [2/2]

◆ buildBVH()

◆ buildStaticBVH()

◆ calculateGridIntersection()

◆ calculatePrimitiveVoxelIntersection()

◆ calculateRayPathLengthsDetailed()

◆ calculateVoxelPathLengths()

◆ calculateVoxelRayPathLengths()

◆ castRay() [1/2]

◆ castRay() [2/2]

◆ castRays()

◆ castRaysOptimized()

◆ clearVoxelData()

◆ disableAutomaticBVHRebuilds()

◆ disableGPUAcceleration()

◆ disableHierarchicalBVH()

◆ disableMessages()

◆ disableTreeBasedBVH()

◆ enableAutomaticBVHRebuilds()

◆ enableGPUAcceleration()

◆ enableHierarchicalBVH()

◆ enableMessages()

◆ enableTreeBasedBVH()

◆ filterGeometryByDistance()

◆ findCollisions() [1/4]

◆ findCollisions() [2/4]

◆ findCollisions() [3/4]

◆ findCollisions() [4/4]

◆ findCollisionsWithinDistance()

◆ findNearestPrimitiveDistance()

◆ findNearestSolidObstacleInCone() [1/2]

◆ findNearestSolidObstacleInCone() [2/2]

◆ findOptimalConePath()

◆ getBVHMemoryUsage()

◆ getBVHOptimizationMode()

◆ getBVHStatistics()

◆ getGridCells()

◆ getGridIntersections()

◆ getMaxCollisionDistance()

◆ getPrimitiveCount()

◆ getRelevantGeometryForTree()

◆ getVoxelRayHitCounts()

◆ getVoxelRayPathLengths()

◆ getVoxelRbar()

◆ getVoxelTransmissionProbability()

◆ initializeObstacleSpatialGrid()

◆ interpolate_texture_UV_to_slice_point()

◆ isBVHValid()

◆ isGPUAccelerationEnabled()

◆ isTreeBasedBVHEnabled()

◆ linesIntersection()

◆ optimizeLayout()

◆ performGridRayIntersection()

◆ processRayStream()

◆ rebuildBVH()

◆ registerTree()

◆ selfTest()

◆ setBVHOptimizationMode()

◆ setMaxCollisionDistance()

◆ setStaticGeometry()

◆ setStaticObstacles()

◆ setVoxelRbar()

◆ setVoxelTransmissionProbability()

◆ slicePrimitive()

◆ slicePrimitivesUsingGrid()

◆ updateBVH()

Field Documentation