0.1.1 version

Author: RobTillaart

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Rob Tillaart
+Copyright (c) 2011-2020 Rob Tillaart
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MultiMap.h

@@ -0,0 +1,83 @@
+#pragma once
+//
+//    FILE: multimap.h
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.1
+// PURPOSE: Arduino library for fast non-linear mapping or interpolation of values
+//     URL: https://github.com/RobTillaart/MultiMap
+//     URL: http://playground.arduino.cc/Main/MultiMap
+//
+// HISTORY: see playground article
+//
+
+#define MULTIMAP_LIB_VERSION "0.1.1"
+
+#include <Arduino.h>
+
+// note: the in array should have increasing values
+template<typename T>
+T multiMap(T val, T* _in, T* _out, uint8_t size)
+{
+    // take care the value is within range
+    // val = constrain(val, _in[0], _in[size-1]);
+    if (val <= _in[0]) return _out[0];
+    if (val >= _in[size-1]) return _out[size-1];
+
+    // search right interval
+    uint8_t pos = 1;  // _in[0] allready tested
+    while(val > _in[pos]) pos++;
+
+    // this will handle all exact "points" in the _in array
+    if (val == _in[pos]) return _out[pos];
+
+    // interpolate in the right segment for the rest
+    return (val - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
+}
+
+
+/*
+ * speed optimized version if inputs do not change often e.g.  2 2 2 2 2 3 3 3 3 5 5 5 5 5 5 8 8 8 8 5 5 5 5 5 
+ * 
+// note: the in array should have increasing values
+template<typename T>
+T multiMap(T val, T* _in, T* _out, uint8_t size)
+{
+    
+    static T lastvalue = -1;
+    static T cache = -1;	
+	
+	if (val == lastvalue) return cache;
+	lastvalue = val;
+
+    // take care the value is within range
+    // val = constrain(val, _in[0], _in[size-1]);
+    if (val <= _in[0])
+	{
+		cache = _out[0];
+	}
+    else if (val >= _in[size-1])
+	{
+		cache = _out[size-1];
+	}
+    else
+	{
+        // search right interval; index 0 _in[0] already tested
+        uint8_t pos = 1;  
+        while(val > _in[pos]) pos++;
+	    
+        // this will handle all exact "points" in the _in array
+        if (val == _in[pos]) 
+        {
+		    cache = _out[pos];
+        }
+		else
+		{
+		    // interpolate in the right segment for the rest
+            cache = (val - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
+		}
+	}
+	return cache;
+}
+*/
+
+// -- END OF FILE --

README.md

@@ -1,2 +1,40 @@
 # MultiMap
-Arduino library for non-linear mapping or interpolation of values
+
+Arduino library for fast non-linear mapping or interpolation of values
+
+## Description
+
+In Arduino applications often the value of a sensor is mapped upon a more
+usable value. E.g. the value of analogRead() is mapped onto 0 .. 5.0 Volt.
+This is done by the map function which does a linear interpolation. This means
+```
+    output = C1 + input * C2
+```
+As C1 and C2 are to be calculated Arduino has the **map()** that calculates the 
+two variables runtime from two given mappings.
+```
+    output = map(input, I1, I2, O1, O2):
+```
+
+In many cases when there is no linear mapping possible, as the 'points' are not on a single line,
+one needs non-linear math to calculate the output. **Multimap()** just does that.
+
+**Multimap()** needs two equal sized arrays of 'points', **input\[\]** and **output\[\]**, it looks up the 
+input value in the input\[\] array and if needed it linear interpolates between two
+points of the output\[\] array. 
+
+The **input\[\]** array must have increasing values,
+there is no such restriction for the **output\[\]** array.
+
+**Multimap()** automatically constrains the output to the first and last 
+value in the **output\[\]** array.
+
+## Operation
+
+See examples
+
+Please note the fail example as this shows that in the intern math overflow can happen.
+
+## TODO
+
+Investigate class implementation for performance.

examples/multimap_NTC/multimap_NTC.ino

@@ -0,0 +1,83 @@
+//
+//    FILE: multimap_NTC.ino
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+// PURPOSE: demo
+//    DATE: 2020-04-09
+//    (c) : MIT
+//
+
+#include "multimap.h"
+
+uint32_t start;
+uint32_t stop;
+
+volatile float x, y, z;
+
+// Note this is a bit an extreme example,
+// normally you only make a multimap of the working range
+
+float in[] = {
+  0, 1, 3, 8, 13,  20, 25, 32, 50, 60,  72, 85, 100, 145, 200,  250, 300, 400, 500, 600,  650, 700, 753, 800, 830,  870, 900, 936, 964, 985,  1000, 1017, 1023
+};
+float out[] = {
+  -273.15, -71.65, -60.69, -49.81, -43.97, -38.50, -35.54, -32.16, -25.72, -22.95, -20.08, -17.37, -14.62, -7.90, -1.43, 3.57,
+  8.08, 16.34, 24.30, 32.64, 37.17, 42.13, 48.05, 54.19, 58.75, 66.03, 72.87, 83.85, 96.51, 111.46, 129.49, 182.82, 301.82
+};
+
+int sz = 33;
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.println();
+  delay(10);  // make sure print has ended
+
+  start = micros();
+  x = val(z);
+  stop = micros();
+  Serial.println(stop - start);
+  delay(10);  // make sure print has ended
+
+  start = micros();
+  x = multiMap<float>(z, in, out, sz);
+  stop = micros();
+  Serial.println(stop - start);
+  delay(10);  // make sure print has ended
+
+  for (int i = 0; i < 1024; i++)
+  {
+    x = val(i);
+    y = multiMap<float>(i, in, out, sz);
+    z = abs(x - y);
+
+    Serial.print(i);
+    Serial.print('\t');
+    Serial.print(x);
+    Serial.print('\t');
+    Serial.print(y);
+    Serial.print('\t');
+    Serial.print(z);
+    Serial.println();
+  }
+
+}
+
+void loop()
+{
+}
+
+// NTC formula
+float val(int sensorValueA1)
+{
+  int   R10k_ntc = 9870;
+  float U10k_ntc = sensorValueA1 * (5.0 / 1024.0);
+  float Untc = 5.0 - U10k_ntc;
+  float Rntc = (R10k_ntc * Untc) / U10k_ntc;
+  float Temp = (298.15 / (1 - (298.15 / 4300.0) * log(10000.0 / Rntc))) - (273.15 + 0);
+
+  return Temp;
+}
+
+// -- END OF FILE --

examples/multimap_NTC_int_FAIL/multimap_NTC_int_FAIL.ino

@@ -0,0 +1,89 @@
+//
+//    FILE: multimap_NTC_int_FAIL.ino
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+// PURPOSE: demo of faulty optimizing 
+//    DATE: 2020-04-09
+//    (c) : MIT
+//
+
+// NOTE:
+// use integers instead of floats to minimize RAM. uses ~320 bytes PROGMEM ~120 bytes RAM less on UNO than float version
+//
+// this example is added to show how to reduce memory but  also how it can FAIL due to math overflow
+// E.g. see around 196-200; 340-400
+// to prevent this one must have more values which increases the memory usage again.
+// 
+
+
+#include "multimap.h"
+
+uint32_t start;
+uint32_t stop;
+
+volatile float x, y, z;
+
+int in[] = {
+  0, 1, 3, 8, 13,  20, 25, 32, 50, 60,  72, 85, 100, 145, 200,  250, 300, 400, 500, 600,  650, 700, 753, 800, 830,  870, 900, 936, 964, 985,  1000, 1017, 1023
+};
+int out[] = {
+  -27315, -7165, -6069, -4981, -4397,    -3850, -3554, -3216, -2572, -2295,    -2008, -1737, -1462, -790, -143,    357, 808, 1634, 2430, 3264, 
+  3717, 4213, 4805, 5419, 5875,    6603, 7287, 8385, 9651, 11146,    12949, 18282, 30182
+};
+
+int sz = 33;
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.println();
+  delay(10);  // make sure print has ended
+
+  start = micros();
+  x = val(z);
+  stop = micros();
+  Serial.println(stop - start);
+  delay(10);  // make sure print has ended
+
+  start = micros();
+  x = 0.01 * multiMap<int>(z, in, out, sz);
+  stop = micros();
+  Serial.println(stop - start);
+  delay(10);  // make sure print has ended
+
+  for (int i = 0; i < 1024; i++)
+  {
+    x = val(i);
+    y = 0.01 * multiMap<int>(i, in, out, sz);
+    z = abs(x - y);
+
+    Serial.print(i);
+    Serial.print('\t');
+    Serial.print(x);
+    Serial.print('\t');
+    Serial.print(y);
+    Serial.print('\t');
+    Serial.print(z);
+    Serial.println();
+  }
+
+}
+
+void loop()
+{
+}
+
+// NTC formula
+float val(int sensorValueA1)
+{
+  int   R10k_ntc = 9870;
+  float U10k_ntc = sensorValueA1 * (5.0 / 1024.0);
+  float Untc = 5.0 - U10k_ntc;
+  float Rntc = (R10k_ntc * Untc) / U10k_ntc;
+  float Temp = (298.15 / (1 - (298.15 / 4300.0) * log(10000.0 / Rntc))) - (273.15 + 0);
+
+  return Temp;
+}
+
+// -- END OF FILE --

examples/multimap_distance/multimap_distance.ino

@@ -0,0 +1,47 @@
+
+//
+//    FILE: multimap_distance.ino
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+// PURPOSE: demo
+//    DATE: 2020-04-09
+//
+
+#include "multimap.h"
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.println();
+
+  for (int i = 80; i < 512; i++)
+  {
+    float distance = sharp2cm(i);
+//    Serial.print('\t');
+//    Serial.print(i);
+//    Serial.print('\t');
+    Serial.println(distance, 1);
+  }
+  Serial.println("Done...");
+}
+
+void loop()
+{
+}
+
+
+// for a sharp distance range finder
+float sharp2cm(int val)
+{
+  // out[] holds the distances in cm
+  float out[] = {150, 140, 130, 120, 110, 100, 90, 80, 70, 60, 50, 40, 30, 20};
+
+  // in[] holds the measured analogRead() values for that distance
+  float in[]  = { 90, 97, 105, 113, 124, 134, 147, 164, 185, 218, 255, 317, 408, 506};
+
+  float dist = multiMap<float>(val, in, out, 14);
+  return dist;
+}
+
+// -- END OF FILE --