Update multi-return for more types of return and all RGL fields. (#324)

* Add return mode and type enums. Adjust node interfaces. Update multi-return configuration on RaytraceNode.

* Add API call to set return mode on RaytraceNode.

* Update raytrace pipeline to handle multi-return.

* Fix saving non hit samples.

* Fix indexing in saving shared beam data.

* Fix isHit values being not initialized.

* Add value checkout on setting return mode.

* Remove kernel and MultiReturnPointers used in previous implementation of multi-return.

* Make adjustments in RaytraceNode definition. Remove unused code. Add minor TODOs.

* Add minor explanation to MultiReturnSamplePointers.

* Make cleanup and minor refactors in nodeKernels.

* Make cleanup in optixPrograms.

* Add TODO and explanation for nodeKernels.

* Make cleanup in RaytraceNode.

* Remove MultiReturnSwitch Node and update multi-return tests.

* Fix multi-return VLP-16 test.

* Fix multi-return test with cube in motion.

* Make last cleanup in multi-return tests.

* Add option to set cube intensity to spawnCubeOnScene helper.

* Update GraphMultiReturn test to verify also strongest return.

* Make changes based on review.

---------

Signed-off-by: Paweł Liberadzki <[email protected]>

Author: PawelLiberadzki

include/rgl/api/core.h

@@ -450,15 +450,59 @@ typedef enum : int32_t
 } rgl_field_t;
 
 /**
- * Kinds of return type for multi-return LiDAR output.
- */
-typedef enum : int32_t
+ * Bitshift and masks for coding return modes and types. Most significant byte encodes the number of returns. Return mode is
+ * encoded on 8 most significant bits (24-31) - 1 for single return mode, 2 for dual return. Remaining 24 bits are for encoding
+ * return type. First return is on 8 LEAST significant bits (0-7), and next 8 bits (8-15) are for second return. Bits 16-23 are
+ * not used at this moment - in the future e.g. the third return may be encoded there. Return type comes from rgl_return_type_t.
+ * Example: RGL_RETURN_LAST_STRONGEST would be encoded as:
+ * 		0x02000201
+ * 			02 - dual return
+ * 			00 - not used bits
+ * 			02 - second return - RGL_RETURN_TYPE_LAST
+ *			01 - first return - RGL_RETURN_TYPE_STRONGEST
+ */
+const int32_t RGL_RETURN_MODE_BIT_SHIFT = 24;
+const int32_t RGL_RETURN_MODE_SINGLE = 1 << RGL_RETURN_MODE_BIT_SHIFT;
+const int32_t RGL_RETURN_MODE_DUAL = 2 << RGL_RETURN_MODE_BIT_SHIFT;
+const int32_t RGL_RETURN_TYPE_BIT_SHIFT = 8;
+
+/**
+ * Kinds of return types for multi-return LiDAR output.
+ */
+typedef enum : uint8_t
 {
-	RGL_RETURN_TYPE_NOT_DIVERGENT = 0,
-	RGL_RETURN_TYPE_FIRST = 1,
+	RGL_RETURN_TYPE_UNKNOWN = 0,
+	RGL_RETURN_TYPE_STRONGEST = 1,
 	RGL_RETURN_TYPE_LAST = 2,
+	RGL_RETURN_TYPE_SECOND = 3,
+	RGL_RETURN_TYPE_FIRST = 4,
+	RGL_RETURN_TYPE_SECOND_STRONGEST = 5,
 } rgl_return_type_t;
 
+/**
+ * Kinds of return modes for multi-return LiDAR output.
+ */
+typedef enum : int32_t
+{
+	RGL_RETURN_UNKNOWN = RGL_RETURN_TYPE_UNKNOWN,
+	// Single return modes
+	RGL_RETURN_FIRST = RGL_RETURN_MODE_SINGLE | RGL_RETURN_TYPE_FIRST,
+	RGL_RETURN_SECOND = RGL_RETURN_MODE_SINGLE | RGL_RETURN_TYPE_SECOND,
+	RGL_RETURN_LAST = RGL_RETURN_MODE_SINGLE | RGL_RETURN_TYPE_LAST,
+	RGL_RETURN_STRONGEST = RGL_RETURN_MODE_SINGLE | RGL_RETURN_TYPE_STRONGEST,
+	// Dual return modes
+	RGL_RETURN_LAST_STRONGEST = RGL_RETURN_MODE_DUAL | (RGL_RETURN_TYPE_LAST) |
+	                            (RGL_RETURN_TYPE_STRONGEST << RGL_RETURN_TYPE_BIT_SHIFT),
+	RGL_RETURN_FIRST_LAST = RGL_RETURN_MODE_DUAL | (RGL_RETURN_TYPE_FIRST) |
+	                        (RGL_RETURN_TYPE_LAST << RGL_RETURN_TYPE_BIT_SHIFT),
+	RGL_RETURN_FIRST_STRONGEST = RGL_RETURN_MODE_DUAL | (RGL_RETURN_TYPE_FIRST) |
+	                             (RGL_RETURN_TYPE_STRONGEST << RGL_RETURN_TYPE_BIT_SHIFT),
+	RGL_RETURN_STRONGEST_SECOND_STRONGEST = RGL_RETURN_MODE_DUAL | (RGL_RETURN_TYPE_STRONGEST) |
+	                                        (RGL_RETURN_TYPE_SECOND_STRONGEST << RGL_RETURN_TYPE_BIT_SHIFT),
+	RGL_RETURN_FIRST_SECOND = RGL_RETURN_MODE_DUAL | (RGL_RETURN_TYPE_FIRST) |
+	                          (RGL_RETURN_TYPE_SECOND << RGL_RETURN_TYPE_BIT_SHIFT),
+} rgl_return_mode_t;
+
 /**
  * Helper enum for axis selection
  */
@@ -848,6 +892,18 @@ RGL_API rgl_status_t rgl_node_raytrace_configure_beam_divergence(rgl_node_t node
  */
 RGL_API rgl_status_t rgl_node_raytrace_configure_default_intensity(rgl_node_t node, float default_intensity);
 
+/**
+ * Modifies RaytraceNode to set return mode.
+ * Point return types (RGL_FIELD_RETURN_TYPE_U8) will be set to corresponding rgl_return_type_t values, e.g. return mode
+ * RGL_RETURN_FIRST_LAST will result in point return types to be set to RGL_RETURN_TYPE_FIRST or RGL_RETURN_TYPE_LAST,
+ * interchangeably.
+ * Default return mode on RaytraceNode is RGL_RETURN_FIRST.
+ * Passing RGL_RETURN_UNKNOWN is an invalid operation and will fail - user can not set RGL_RETURN_UNKNOWN as return mode.
+ * @param node RaytraceNode to modify.
+ * @param return_mode Return mode to set.
+ */
+RGL_API rgl_status_t rgl_node_raytrace_configure_return_mode(rgl_node_t node, rgl_return_mode_t return_mode);
+
 /**
  * Creates or modifies FormatPointsNode.
  * The Node converts internal representation into a binary format defined by the `fields` array.
@@ -886,7 +942,10 @@ RGL_API rgl_status_t rgl_node_points_compact_by_field(rgl_node_t* node, rgl_fiel
 /**
  * Creates or modifies SpatialMergePointsNode.
  * The Node merges point clouds spatially (e.g., multiple lidars outputs into one point cloud).
- * Only provided fields are merged (RGL_FIELD_DYNAMIC_FORMAT is not supported).
+ * Only provided fields are merged (RGL_FIELD_DYNAMIC_FORMAT is not supported). This Node do not resolve point return types
+ * (RGL_FIELD_RETURN_TYPE_U8) in any way - output return mode is always assumed to be RGL_RETURN_UNKNOWN and respective
+ * cloud points keep their return types. This may results in a case, where output point cloud contain points e.g. from
+ * four or more return types (rgl_return_type_t).
  * Input point clouds must be unorganized (height == 1).
  * Any modification to the Node's parameters clears accumulated data.
  * Graph input: point cloud(s)
@@ -913,7 +972,9 @@ RGL_API rgl_status_t rgl_node_points_temporal_merge(rgl_node_t* node, const rgl_
 
 /**
  * Creates or modifies FromArrayPointsNode.
- * The Node provides initial points for its children Nodes.
+ * The Node provides initial points for its children Nodes. This Node does not handle return mode - it is assumed that
+ * return mode is always RGL_RETURN_UNKNOWN. RGL_FIELD_RETURN_TYPE_U8 field values are still set according to data
+ * passed by user.
  * Input: none
  * Output: point cloud
  * @param node If (*node) == nullptr, a new Node will be created. Otherwise, (*node) will be modified.
@@ -1059,17 +1120,6 @@ RGL_API rgl_status_t rgl_node_gaussian_noise_angular_hitpoint(rgl_node_t* node,
 RGL_API rgl_status_t rgl_node_gaussian_noise_distance(rgl_node_t* node, float mean, float st_dev_base,
                                                       float st_dev_rise_per_meter);
 
-/**
- * Creates or modifies MultiReturnSwitchNode
- * This is a special node which does not modify the data but acts as an adapter to the multi-return feature.
- * Thanks to this node, user can attach unchanged pipelines to work with specific return type from multi-return raytracing.
- * Graph input: point cloud (with multi-return fields)
- * Graph output: point cloud (with a selected field from parent's multi-return point cloud)
- * @param node If (*node) == nullptr, a new Node will be created. Otherwise, (*node) will be modified.
- * @param return_type Return type to select from multi-return point cloud.
- */
-RGL_API rgl_status_t rgl_node_multi_return_switch(rgl_node_t* node, rgl_return_type_t);
-
 /**
  * Assigns value true to out_alive if the given node is known and has not been destroyed,
  * assigns value false otherwise.

src/api/apiCore.cpp

@@ -1066,6 +1066,27 @@ void TapeCore::tape_node_raytrace_configure_default_intensity(const YAML::Node&
 	rgl_node_raytrace_configure_default_intensity(node, yamlNode[1].as<float>());
 }
 
+RGL_API rgl_status_t rgl_node_raytrace_configure_return_mode(rgl_node_t node, rgl_return_mode_t return_mode)
+{
+	auto status = rglSafeCall([&]() {
+		RGL_API_LOG("rgl_node_raytrace_configure_return_mode(node={}, return_mode={})", repr(node), return_mode);
+		CHECK_ARG(node != nullptr);
+		CHECK_ARG(return_mode != RGL_RETURN_UNKNOWN);
+		RaytraceNode::Ptr raytraceNode = Node::validatePtr<RaytraceNode>(node);
+		raytraceNode->setReturnMode(return_mode);
+	});
+	TAPE_HOOK(node, return_mode);
+	return status;
+}
+
+void TapeCore::tape_node_raytrace_configure_return_mode(const YAML::Node& yamlNode, PlaybackState& state)
+{
+	auto nodeId = yamlNode[0].as<TapeAPIObjectID>();
+	auto returnMode = static_cast<rgl_return_mode_t>(yamlNode[1].as<int>());
+	rgl_node_t node = state.nodes.contains(nodeId) ? state.nodes.at(nodeId) : nullptr;
+	rgl_node_raytrace_configure_return_mode(node, returnMode);
+}
+
 RGL_API rgl_status_t rgl_node_points_format(rgl_node_t* node, const rgl_field_t* fields, int32_t field_count)
 {
 	auto status = rglSafeCall([&]() {
@@ -1422,27 +1443,6 @@ void TapeCore::tape_node_gaussian_noise_distance(const YAML::Node& yamlNode, Pla
 	state.nodes.insert({nodeId, node});
 }
 
-RGL_API rgl_status_t rgl_node_multi_return_switch(rgl_node_t* node, rgl_return_type_t return_type)
-{
-	auto status = rglSafeCall([&]() {
-		RGL_API_LOG("rgl_node_multi_return_switch(node={}, return_type={})", repr(node), return_type);
-		CHECK_ARG(node != nullptr);
-
-		createOrUpdateNode<MultiReturnSwitchNode>(node, return_type);
-	});
-	TAPE_HOOK(node, return_type);
-	return status;
-}
-
-void TapeCore::tape_node_multi_return_switch(const YAML::Node& yamlNode, PlaybackState& state)
-{
-	auto nodeId = yamlNode[0].as<TapeAPIObjectID>();
-	auto return_type = static_cast<rgl_return_type_t>(yamlNode[1].as<int>());
-	rgl_node_t node = state.nodes.contains(nodeId) ? state.nodes.at(nodeId) : nullptr;
-	rgl_node_multi_return_switch(&node, return_type);
-	state.nodes.insert({nodeId, node});
-}
-
 rgl_status_t rgl_node_is_alive(rgl_node_t node, bool* out_alive)
 {
 	auto status = rglSafeCall([&]() {

src/gpu/MultiReturn.hpp

@@ -20,9 +20,18 @@
 #define MULTI_RETURN_BEAM_LAYERS 3
 #define MULTI_RETURN_BEAM_SAMPLES (1 + (MULTI_RETURN_BEAM_VERTICES * MULTI_RETURN_BEAM_LAYERS))
 
-struct MultiReturnPointers
+struct MultiReturnSamplesPointers
 {
+	// XYZ is not stored for samples, because we calculate it alongside center ray direction. For this reason, only distance
+	// is necessary.
 	Field<IS_HIT_I32>::type* isHit;
-	Field<XYZ_VEC3_F32>::type* xyz;
 	Field<DISTANCE_F32>::type* distance;
+	Field<INTENSITY_F32>::type* intensity;
+	Field<LASER_RETRO_F32>::type* laserRetro;
+	Field<ENTITY_ID_I32>::type* entityId;
+	Field<ABSOLUTE_VELOCITY_VEC3_F32>::type* absVelocity;
+	Field<RELATIVE_VELOCITY_VEC3_F32>::type* relVelocity;
+	Field<RADIAL_SPEED_F32>::type* radialSpeed;
+	Field<NORMAL_VEC3_F32>::type* normal;
+	Field<INCIDENT_ANGLE_F32>::type* incidentAngle;
 };

src/gpu/RaytraceRequestContext.hpp

@@ -54,6 +54,7 @@ struct RaytraceRequestContext
 	Field<IS_HIT_I32>::type* isHit;
 	Field<RAY_IDX_U32>::type* rayIdx;
 	Field<RING_ID_U16>::type* ringIdx;
+	Field<RETURN_TYPE_U8>::type* returnType;
 	Field<DISTANCE_F32>::type* distance;
 	Field<INTENSITY_F32>::type* intensityF32;
 	Field<INTENSITY_U8>::type* intensityU8;
@@ -70,8 +71,9 @@ struct RaytraceRequestContext
 	Field<INCIDENT_ANGLE_F32>::type* incidentAngle;
 
 	// Multi-Return
+	MultiReturnSamplesPointers mrSamples;
+	int returnCount;
 	float hBeamHalfDivergenceRad;
 	float vBeamHalfDivergenceRad;
-	MultiReturnPointers mrSamples;
 };
 static_assert(std::is_trivially_copyable<RaytraceRequestContext>::value);