fix(math): Fix range mapper deadband logic (#423)

* Fix issue in range mapper which could occur if the center and range deadzones overlapped
* More explicitly allow uni-directional output mappings when min==center or max==center
* Flesh out test cases for floating point precision issues and values around the deadbands

It was found that the output could be discontinuous if the center deadzone overlapped with one of the range deadzones. The solution was to better handle the case that there are unidirectional output distributions (e.g. where center==min or center==max) and to better handle how the deadbands are calculated.

Build and run `math/example` on QtPy ESP32s3 and ensure the output of `rm4` matches what we expect.

Author: finger563

components/math/example/main/math_example.cpp

@@ -183,18 +183,49 @@ extern "C" void app_main(void) {
     // You can even invert the ouput distribution, and add a deadband around the
     // min/max values
     espp::FloatRangeMapper rm4({
-        .center = center,
-        .center_deadband = deadband,
+        .center = max,                      // test uni-directional mapping
+        .center_deadband = deadband / 2.0f, // test different deadband around center / range
         .minimum = min,
         .maximum = max,
         .range_deadband = deadband,
         .invert_output = true,
     });
     // make a vector of float values min - 10 to max + 10 in increments of 5
     std::vector<float> vals;
-    for (float v = min - 10; v <= max + 10; v += 5) {
+    static constexpr float increment = deadband / 3.0f;
+    static constexpr float oob_range = deadband * 3.0f;
+    for (float v = min - oob_range; v <= max + oob_range; v += increment) {
       vals.push_back(v);
     }
+    // ensure that very small values around center, max, and min are mapped to
+    // 0, 1, and -1 respectively
+    vals.push_back(center - 0.0001f);
+    vals.push_back(center - 0.00001f);
+    vals.push_back(center - 0.000001f);
+    vals.push_back(center - std::numeric_limits<float>::epsilon());
+    vals.push_back(center + 0.0001f);
+    vals.push_back(center + 0.00001f);
+    vals.push_back(center + 0.000001f);
+    vals.push_back(center + std::numeric_limits<float>::epsilon());
+    vals.push_back(max - 0.0001f);
+    vals.push_back(max - 0.00001f);
+    vals.push_back(max - 0.000001f);
+    vals.push_back(max - std::numeric_limits<float>::epsilon());
+    vals.push_back(max + 0.0001f);
+    vals.push_back(max + 0.00001f);
+    vals.push_back(max + 0.000001f);
+    vals.push_back(max + std::numeric_limits<float>::epsilon());
+    vals.push_back(min - 0.0001f);
+    vals.push_back(min - 0.00001f);
+    vals.push_back(min - 0.000001f);
+    vals.push_back(min - std::numeric_limits<float>::epsilon());
+    vals.push_back(min + 0.0001f);
+    vals.push_back(min + 0.00001f);
+    vals.push_back(min + 0.000001f);
+    vals.push_back(min + std::numeric_limits<float>::epsilon());
+
+    std::sort(vals.begin(), vals.end());
+
     // test the mapping and unmapping
     fmt::print(
         "% value, mapped [0;255] to [-1;1], unmapped [-1;1] to [0;255], mapped [0;255] to "

components/math/include/range_mapper.hpp

@@ -194,21 +194,24 @@ template <typename T> class RangeMapper {
     T calibrated{0};
     // compare against center
     calibrated = clamped - center_;
-    bool positive_input = calibrated >= 0;
+    bool min_eq_center = minimum_ == center_;
+    bool max_eq_center = maximum_ == center_;
     bool within_center_deadband = std::abs(calibrated) < center_deadband_;
-    bool within_range_deadband =
-        clamped >= maximum_ - range_deadband_ || clamped <= minimum_ + range_deadband_;
+    // Ensure we handle the case that the center is equal to the min or max,
+    // which may happen if the user wants a uni-directional output (e.g. [0,1]
+    // instead of [-1,1]). In this case, we only apply the center deadband, not
+    // the range deadband.
+    bool within_max_deadband = !max_eq_center && clamped >= (maximum_ - range_deadband_);
+    bool within_min_deadband = !min_eq_center && clamped <= (minimum_ + range_deadband_);
     if (within_center_deadband) {
-      // if it's within the center deadband, return the output center
       return output_center_;
-    } else if (within_range_deadband) {
-      // if it's within the range deadband around the min/max, return the output
-      // min/max, taking into account the output inversion
-      return positive_input   ? invert_output_ ? output_min_ : output_max_
-             : invert_output_ ? output_max_
-                              : output_min_;
+    } else if (within_min_deadband) {
+      return invert_output_ ? output_max_ : output_min_;
+    } else if (within_max_deadband) {
+      return invert_output_ ? output_min_ : output_max_;
     }
 
+    bool positive_input = calibrated >= 0;
     // remove the deadband from the calibrated value
     calibrated = positive_input ? calibrated - center_deadband_ : calibrated + center_deadband_;