Lg1: Implement both light|darkAmbience stimBuffs & their production

We now produce both light and dark ambience stimframes into
stimbuffs for the LivoxGen1 lidar devices.

stimBuffApis/livoxGen1/pcloudAmbienceQualeIfaceApi.h

@@ -1,12 +1,15 @@
 #ifndef _LIVOX_GEN1_PCLOUD_AMBIENCE_QUALE_IFACE_API_H
 #define _LIVOX_GEN1_PCLOUD_AMBIENCE_QUALE_IFACE_API_H
 
+#include <algorithm>
 #include <cstdint>
 #include <memory>
-#include <optional>
 #include <stdexcept>
 #include <string>
+#include <string_view>
 #include <user/deviceAttachmentSpec.h>
+#include <user/intrin.h>
+#include <user/intrinThresholdParams.h>
 
 namespace smo {
 namespace stim_buff {
@@ -36,45 +39,110 @@ struct ParamComparator
 	}
 };
 
-struct PcloudAmbiencePassbandComparators
+inline bool paramsContain(
+	const std::vector<std::pair<std::string, std::string>>& params,
+	const std::string& name)
 {
-	std::optional<ParamComparator> lt;
-	std::optional<ParamComparator> gt;
-};
+	return std::any_of(
+		params.begin(), params.end(),
+		[&name](const auto& p) { return p.first == name; });
+}
 
-/* Both `passband-count-lt-val` and `passband-count-gt-val` are permitted
- * simultaneously on a pcloudAmbience qualeIfaceApi: the lt comparator
- * typically feeds a postrin(...) segment (triggering on unusually low
- * counts), and the gt comparator typically feeds a negtrin(...) segment
- * (triggering on unusually high counts).
+/* pcloudLightAmbience requires exactly one `passband-count-gt-val` on its
+ * qualeIfaceApi params; `passband-count-lt-val` is a hard error. Feeds a
+ * negtrin(...) segment (scene is "unbearably much, get away").
  */
-inline PcloudAmbiencePassbandComparators parsePcloudAmbiencePassbandComparators(
+inline ParamComparator parsePcloudLightAmbienceGtComparator(
 	const std::shared_ptr<device::DeviceAttachmentSpec>& deviceAttachmentSpec)
 {
 	const auto& params = deviceAttachmentSpec->qualeIfaceApiParams;
+
+	if (paramsContain(params, "passband-count-lt-val"))
+	{
+		throw std::runtime_error(
+			"pcloudLightAmbience qualeIfaceApi does not accept "
+			"'passband-count-lt-val'; use pcloudDarkAmbience for lt-val "
+			"pipelines.");
+	}
+
 	constexpr int kParamNotSpecified = -1;
 	const int gtVal = device::DeviceAttachmentSpec::parseOptionalParamAsInt(
 		params, "passband-count-gt-val", kParamNotSpecified);
+
+	if (gtVal == kParamNotSpecified)
+	{
+		throw std::runtime_error(
+			"pcloudLightAmbience qualeIfaceApi requires "
+			"'passband-count-gt-val' on its params.");
+	}
+
+	return ParamComparator{
+		.op = OP_CMP_GT,
+		.value = static_cast<uint32_t>(gtVal),
+	};
+}
+
+/* pcloudDarkAmbience requires exactly one `passband-count-lt-val` on its
+ * qualeIfaceApi params; `passband-count-gt-val` is a hard error. Feeds a
+ * postrin(...) segment (scene is "too good, stay here").
+ */
+inline ParamComparator parsePcloudDarkAmbienceLtComparator(
+	const std::shared_ptr<device::DeviceAttachmentSpec>& deviceAttachmentSpec)
+{
+	const auto& params = deviceAttachmentSpec->qualeIfaceApiParams;
+
+	if (paramsContain(params, "passband-count-gt-val"))
+	{
+		throw std::runtime_error(
+			"pcloudDarkAmbience qualeIfaceApi does not accept "
+			"'passband-count-gt-val'; use pcloudLightAmbience for gt-val "
+			"pipelines.");
+	}
+
+	constexpr int kParamNotSpecified = -1;
 	const int ltVal = device::DeviceAttachmentSpec::parseOptionalParamAsInt(
 		params, "passband-count-lt-val", kParamNotSpecified);
 
-	PcloudAmbiencePassbandComparators out;
-	if (gtVal != kParamNotSpecified)
+	if (ltVal == kParamNotSpecified)
 	{
-		out.gt = ParamComparator{
-			.op = OP_CMP_GT,
-			.value = static_cast<uint32_t>(gtVal),
-		};
-	}
-	if (ltVal != kParamNotSpecified)
-	{
-		out.lt = ParamComparator{
-			.op = OP_CMP_LT,
-			.value = static_cast<uint32_t>(ltVal),
-		};
+		throw std::runtime_error(
+			"pcloudDarkAmbience qualeIfaceApi requires "
+			"'passband-count-lt-val' on its params.");
 	}
 
-	return out;
+	return ParamComparator{
+		.op = OP_CMP_LT,
+		.value = static_cast<uint32_t>(ltVal),
+	};
+}
+
+/* Shared parser used by both pcloudLightAmbience and pcloudDarkAmbience
+ * stimbuffs to decode a postrin(...) / negtrin(...) segment's threshold
+ * params into an IntrinConfig. Kept with the qualeIfaceApi helpers because
+ * it's ambience-specific (nDgramsPerFrame is the percentage base).
+ */
+inline intrin::IntrinConfig parseAmbienceIntrinConfigFromParams(
+	std::string_view intrinKind,
+	const std::vector<std::pair<std::string, std::string>>& params,
+	size_t nDgramsPerFrame)
+{
+	intrin::validateIntrinSegmentParams(intrinKind, params);
+
+	const auto threshold = intrin::parseOptionalThresholdParam(
+		params,
+		intrin::kIntrinInterestPcNames,
+		intrin::kIntrinInterestThrNames,
+		/*defaultValue=*/0,
+		/*defaultUnit=*/intrin::ThresholdUnit::Absolute);
+
+	return intrin::IntrinConfig{
+		.percentage =
+			threshold.unit == intrin::ThresholdUnit::Percentage
+				? static_cast<uint32_t>(threshold.value)
+				: 0U,
+		.threshold = intrin::resolveThresholdValue(
+			threshold, nDgramsPerFrame),
+	};
 }
 
 } // namespace stim_buff