From 870057a6802b26f61df9f9354f2e441ae42e69a1 Mon Sep 17 00:00:00 2001
From: Hayodea Hekol <hayodea@protonmail.com>
Date: Tue, 21 Oct 2025 20:50:59 -0400
Subject: [PATCH] Add Stencil class for describing threshold ranges

---
 include/user/stencil.h | 83 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 include/user/stencil.h

diff --git a/include/user/stencil.h b/include/user/stencil.h
new file mode 100644
index 0000000..5c05b84
--- /dev/null
+++ b/include/user/stencil.h
@@ -0,0 +1,83 @@
+#ifndef _STENCIL_H
+#define _STENCIL_H
+
+#include <vector>
+#include <memory>
+#include <user/stimFrame.h>
+#include <mentalEntity.h>
+
+namespace smo {
+namespace cologex {
+
+/**
+ * Stencil represents range descriptions for sub-regions of sensor data frames.
+ *
+ * When a sensor yields frames with multiple values per frame, the Stencil class
+ * allows the stimbufflib driver to describe the subset of the input data that
+ * is relevant to SMO. For example:
+ *
+ * * A HSB format camera might treat brightness values above 128 as
+ *   negtrins, creating a Stencil that denotes all offsets in a
+ *   frame that exceed 128.
+ *
+ * * A lidar yielding XYZI[ntensity] might consider I values exceeding 128 to be
+ *   negtrins, creating a Stencil listing all values in the point
+ *   cloud that exceed 128.
+ *
+ * The Stencil internally represents offsets with ranges or other efficient
+ * formats to describe offsets (e.g., by row). The internal format is opaque to
+ * the stimbufflib, which describes relevant ranges by calling Stencil methods.
+ */
+class Stencil
+{
+public:
+	/**
+	 * Constructor that takes a shared_ptr to StimFrame and produces a completed
+	 * Stencil. The Stencil scans the StimFrame and efficiently allocates
+	 * internal structures to describe the stencil ranges.
+	 *
+	 * @param frame Shared pointer to the StimFrame to analyze
+	 * @param threshold The threshold value for determining relevant data
+	 */
+	Stencil(
+		const std::shared_ptr<stim_buff::StimFrame> &frame,
+		const uint32_t threshold)
+	: frame(frame), threshold(threshold)
+	{}
+	virtual ~Stencil() = default;
+
+	/**
+	 * Pure virtual method for derived classes to implement their specific
+	 * threshold analysis logic. Returns true if there are values above threshold,
+	 * false otherwise.
+	 */
+	virtual bool analyzeFrame() = 0;
+
+	/**
+	 * Stencil is constructed from a StimFrame. If the input StimFrame had no
+	 * values above threshold, then the Stencil will have no data.
+	 */
+	virtual bool hasData() const = 0;
+	operator bool() const { return hasData(); }
+	bool operator!() const { return !hasData(); }
+
+	// Return the number of relevant ranges/offsets in this Stencil.
+	virtual size_t getRelevantCount() const = 0;
+	// Return true if the offset is relevant, false otherwise
+	virtual bool isRelevant(size_t offset) const = 0;
+
+	/**
+	 * Build internal stencil metadata from the shared_ptr member to describe
+	 * the range of StimFrame values that are relevant.
+	 */
+	virtual bool buildStencilMetadata() = 0;
+
+protected:
+	uint32_t threshold;
+	std::shared_ptr<stim_buff::StimFrame> frame;
+};
+
+} // namespace cologex
+} // namespace smo
+
+#endif // _STENCIL_H