From 19d3332c02cee5dd8d49a27ee81bdd1347840ab4 Mon Sep 17 00:00:00 2001 From: Rob Tillaart Date: Tue, 31 Oct 2023 10:57:05 +0100 Subject: [PATCH] update readme.md (#17) - update readme.md (badges). - add performance test example (another). - add UNO + ESP32 test results. - minor edits. --- CHANGELOG.md | 7 ++ FastMap.cpp | 6 +- FastMap.h | 6 +- README.md | 61 +++++++++-- .../constrainedMapDemo/constrainedMapDemo.ino | 2 +- examples/fastMapDemo/fastMapDemo.ino | 10 +- examples/fastMapDemo2/fastMapDemo2.ino | 6 +- examples/fastMapDemo3/fastMapDemo3.ino | 4 +- examples/fastMapDemo4/fastMapDemo4.ino | 22 ++-- examples/fastMapDouble/fastMapDouble.ino | 10 +- .../fastMap_performance_test.ino | 100 ++++++++++++++++++ .../performance_0.4.1_ESP32.txt | 13 +++ .../performance_0.4.1_UNO.txt | 14 +++ library.json | 4 +- library.properties | 4 +- 15 files changed, 225 insertions(+), 44 deletions(-) create mode 100644 examples/fastMap_performance_test/fastMap_performance_test.ino create mode 100644 examples/fastMap_performance_test/performance_0.4.1_ESP32.txt create mode 100644 examples/fastMap_performance_test/performance_0.4.1_UNO.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index 912044d..4f653d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). +## [0.4.1] - 2023-10-30 +- update readme.md (badges). +- add performance test example (another). + - add UNO + ESP32 test results. +- minor edits. + + ## [0.4.0] - 2022-11-02 - add changelog.md - add rp2040 to build-CI diff --git a/FastMap.cpp b/FastMap.cpp index 6f9c509..61a7055 100644 --- a/FastMap.cpp +++ b/FastMap.cpp @@ -1,11 +1,9 @@ // // FILE: FastMap.cpp // AUTHOR: Rob Tillaart -// VERSION: 0.4.0 +// VERSION: 0.4.1 // PURPOSE: class with fast map function - library for Arduino // URL: https://github.com/RobTillaart/FastMap -// -// HISTORY: see changelog.md #include "FastMap.h" @@ -115,5 +113,5 @@ double FastMapDouble::upperConstrainedMap(double value) } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/FastMap.h b/FastMap.h index f69aa7f..535113c 100644 --- a/FastMap.h +++ b/FastMap.h @@ -2,14 +2,14 @@ // // FILE: FastMap.h // AUTHOR: Rob Tillaart -// VERSION: 0.4.0 +// VERSION: 0.4.1 // PURPOSE: class with fast map function - library for Arduino // URL: https://github.com/RobTillaart/FastMap #include "Arduino.h" -#define FASTMAP_LIB_VERSION (F("0.4.0")) +#define FASTMAP_LIB_VERSION (F("0.4.1")) class FastMap @@ -53,5 +53,5 @@ class FastMapDouble }; -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/README.md b/README.md index 91b6f72..3597f60 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,11 @@ [![Arduino CI](https://github.com/RobTillaart/FastMap/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci) [![Arduino-lint](https://github.com/RobTillaart/FastMap/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/FastMap/actions/workflows/arduino-lint.yml) [![JSON check](https://github.com/RobTillaart/FastMap/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/FastMap/actions/workflows/jsoncheck.yml) +[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/FastMap.svg)](https://github.com/RobTillaart/FastMap/issues) + [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/FastMap/blob/master/LICENSE) [![GitHub release](https://img.shields.io/github/release/RobTillaart/FastMap.svg?maxAge=3600)](https://github.com/RobTillaart/FastMap/releases) +[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/FastMap.svg)](https://registry.platformio.org/libraries/robtillaart/FastMap) # FastMap @@ -23,6 +26,7 @@ This allows mapping that would be hard to achieve with the normal **map()** func Since 0.4.0 the **init()** function will not accept zero range defining input or output parameters. + ## Performance notes (based upon tests https://github.com/RobTillaart/FastMap/issues/4 ) @@ -54,6 +58,13 @@ Furthermore using double might imply a performance penalty on some platforms. ## Interface +```cpp +#include "FastMap.h" +``` + +### Base + +- **FastMap()** Constructor - **bool init(float in_min, float in_max, float out_min, float out_max)** defines the linear mapping parameters. The **init()** function calculates all needed values for the **map()**, the **back()** call and the **constrainXX()** functions. The **init()** function can be called again with new values when needed to do other mapping, @@ -84,6 +95,8 @@ To display doubles one might need the **sci()** function of my **printHelpers** https://github.com/RobTillaart/printHelpers Note that on most embedded platforms the performance of doubles is less than floats. +See below. + #### boards supporting double @@ -112,22 +125,58 @@ void loop() {} ``` -## Usage +## Performance + +Tested version 0.4.1 with **fastMap_performance_test.ino** + +| | MAP | FASTMAP | FASTMAP dbl | Notes | +|:--------|:--------:|:---------:|:-------------:|:-------:| +| UNO | 496072 | 211888 | 211888 | float == double +| ESP32 | 1814 | 627 | 6924 | + + +UNO scores factor 2.34 +ESP32 scores factor 2.89 + +Note: the 8 byte double (ESP32) is ~11 x slower than the float version, +and ~4 x slower than the default map function. +So unless the precision of 8 bytes double is required one better +uses the float version. -See examples. +Note: always do your own performance measurements! + +If you have additional performance figures for other boards, +please let me know (report via an issue). ## Future -#### must +#### Must -#### should - update documentation + +#### Should + - test performance fastMapDouble on ESP32. + - need good test example + +#### Could -#### could - investigate map function for complex numbers? / coordinates? -- can fastMap and fastMapDouble be in a class hierarchy? gain? - Template class? +#### Wont + +- can fastMap and fastMapDouble be in a class hierarchy? limited gain? + + +## Support + +If you appreciate my libraries, you can support the development and maintenance. +Improve the quality of the libraries by providing issues and Pull Requests, or +donate through PayPal or GitHub sponsors. + +Thank you, + + diff --git a/examples/constrainedMapDemo/constrainedMapDemo.ino b/examples/constrainedMapDemo/constrainedMapDemo.ino index 935c167..3d16fc8 100644 --- a/examples/constrainedMapDemo/constrainedMapDemo.ino +++ b/examples/constrainedMapDemo/constrainedMapDemo.ino @@ -46,5 +46,5 @@ void loop() } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/examples/fastMapDemo/fastMapDemo.ino b/examples/fastMapDemo/fastMapDemo.ino index f14f174..08dfffa 100644 --- a/examples/fastMapDemo/fastMapDemo.ino +++ b/examples/fastMapDemo/fastMapDemo.ino @@ -25,10 +25,10 @@ void setup() Serial.println(FASTMAP_LIB_VERSION); Serial.println(); - // Get a non optimizable value; + // Get a non optimizable value; int z = analogRead(A0); - // REFERENCE + // REFERENCE start = micros(); for (int i = 0; i < 10000; i++) { @@ -42,7 +42,7 @@ void setup() Serial.println(x); Serial.println(); - // FASTMAP + // FASTMAP mapper.init(0, 1023, yy, zz); start = micros(); for (int i = 0; i < 10000; i++) @@ -55,7 +55,7 @@ void setup() Serial.print(" -> "); Serial.println(x); - // GAIN + // GAIN Serial.print("Performance factor: "); Serial.println(reference/(stop-start)); } @@ -66,5 +66,5 @@ void loop() } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/examples/fastMapDemo2/fastMapDemo2.ino b/examples/fastMapDemo2/fastMapDemo2.ino index 2fab5c0..edc560d 100644 --- a/examples/fastMapDemo2/fastMapDemo2.ino +++ b/examples/fastMapDemo2/fastMapDemo2.ino @@ -8,8 +8,8 @@ #include "FastMap.h" -FastMap CtoF; -FastMap FtoC; +FastMap CtoF; // Celsius to Fahrenheit +FastMap FtoC; // Fahrenheit to Celsius void setup() @@ -39,5 +39,5 @@ void loop() } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/examples/fastMapDemo3/fastMapDemo3.ino b/examples/fastMapDemo3/fastMapDemo3.ino index 7c68074..fe18c97 100644 --- a/examples/fastMapDemo3/fastMapDemo3.ino +++ b/examples/fastMapDemo3/fastMapDemo3.ino @@ -8,7 +8,7 @@ #include "FastMap.h" -FastMap CtoF; +FastMap CtoF; // Celsius to Fahrenheit void setup() @@ -46,5 +46,5 @@ void loop() } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/examples/fastMapDemo4/fastMapDemo4.ino b/examples/fastMapDemo4/fastMapDemo4.ino index f58feb9..73ecc31 100644 --- a/examples/fastMapDemo4/fastMapDemo4.ino +++ b/examples/fastMapDemo4/fastMapDemo4.ino @@ -25,10 +25,10 @@ void setup() Serial.println(FASTMAP_LIB_VERSION); Serial.println(); - // Get a non optimizable value; + // Get a non optimizable value; int z = analogRead(A0); - // REFERENCE + // REFERENCE start = micros(); for (int i = 0; i < 10000; i++) { @@ -43,7 +43,7 @@ void setup() Serial.println(x); Serial.println(); - // FASTMAP + // FASTMAP mapper.init(0, 1023, yy, zz); start = micros(); for (int i = 0; i < 10000; i++) @@ -57,12 +57,12 @@ void setup() Serial.print(" -> "); Serial.println(x); - // GAIN + // GAIN Serial.print("Performance factor: "); Serial.println((float)reference/(stop-start)); Serial.println(); - // constrainedMap + // constrainedMap mapper.init(0, 1023, yy, zz); start = micros(); for (int i = 0; i < 10000; i++) @@ -76,12 +76,12 @@ void setup() Serial.print(" -> "); Serial.println(x); - // GAIN + // GAIN Serial.print("Performance factor: "); Serial.println((float)reference/(stop-start)); Serial.println(); - // lowerConstrainedMap + // lowerConstrainedMap mapper.init(0, 1023, yy, zz); start = micros(); for (int i = 0; i < 10000; i++) @@ -95,12 +95,12 @@ void setup() Serial.print(" -> "); Serial.println(x); - // GAIN + // GAIN Serial.print("Performance factor: "); Serial.println((float)reference/(stop-start)); Serial.println(); - // upperConstrainedMap + // upperConstrainedMap mapper.init(0, 1023, yy, zz); start = micros(); for (int i = 0; i < 10000; i++) @@ -114,7 +114,7 @@ void setup() Serial.print(" -> "); Serial.println(x); - // GAIN + // GAIN Serial.print("Performance factor: "); Serial.println((float)reference/(stop-start)); Serial.println(); @@ -128,5 +128,5 @@ void loop() } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/examples/fastMapDouble/fastMapDouble.ino b/examples/fastMapDouble/fastMapDouble.ino index 5683f06..70b04c1 100644 --- a/examples/fastMapDouble/fastMapDouble.ino +++ b/examples/fastMapDouble/fastMapDouble.ino @@ -11,7 +11,7 @@ #include "FastMap.h" -#include "printHelpers.h" // https://github.com/RobTillaart/printHelpers +#include "printHelpers.h" // https://github.com/RobTillaart/printHelpers uint32_t start, stop; volatile double x; @@ -27,11 +27,11 @@ void setup() Serial.println(FASTMAP_LIB_VERSION); Serial.println(); - // Get a non optimizable value; + // Get a non optimizable value; volatile double pie = PI; - // FASTMAP - // map 0 .. 100% to lightspeed in km/hr + // FASTMAP + // map 0 .. 100% to lightspeed in km/hr mapper.init(0, 100, 0, 1.0792528488E+12); start = micros(); for (int i = 0; i < 10000; i++) @@ -65,5 +65,5 @@ void loop() } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/examples/fastMap_performance_test/fastMap_performance_test.ino b/examples/fastMap_performance_test/fastMap_performance_test.ino new file mode 100644 index 0000000..0e8898a --- /dev/null +++ b/examples/fastMap_performance_test/fastMap_performance_test.ino @@ -0,0 +1,100 @@ +// +// FILE: fastMap_performance_test.ino +// AUTHOR: Rob Tillaart +// PURPOSE: demo of FastMap class ==> a faster map function +// DATE: 2014-11-02 +// URL: https://github.com/RobTillaart/FastMap + + +#include "FastMap.h" + +uint32_t start; +uint32_t stop; +uint32_t reference; + +volatile long zz = 3000, yy = 20000; +volatile float x; +volatile int z; + +FastMap mapper; +FastMapDouble mapperD; + + +void setup() +{ + Serial.begin(115200); + Serial.println(); + Serial.println(__FILE__); + Serial.print("FASTMAP_LIB_VERSION: "); + Serial.println(FASTMAP_LIB_VERSION); + Serial.println(); + delay(100); + + // Get a non optimizable value; + z = analogRead(A0); + + + // REFERENCE + start = micros(); + for (int i = 0; i < 10000; i++) + { + x = map(z, 0, 1023, yy, zz); + } + stop = micros(); + reference = stop - start; + Serial.print("MAP:\t"); + Serial.println(reference); + Serial.print(z); + Serial.print(" -> "); + Serial.println(x); + Serial.println(); + delay(100); + + + + // FASTMAP + mapper.init(0, 1023, yy, zz); + start = micros(); + for (int i = 0; i < 10000; i++) + { + x = mapper.map(z); + } + stop = micros(); + Serial.print("FASTMAP:\t"); + Serial.println(stop - start); + Serial.print(z); + Serial.print(" -> "); + Serial.println(x); + Serial.print("Performance factor: "); + Serial.println(1.0 * reference / (stop - start)); + Serial.println(); + delay(100); + + + + // FASTMAPDOUBLE + mapperD.init(0, 1023, yy, zz); + start = micros(); + for (int i = 0; i < 10000; i++) + { + x = mapperD.map(z); + } + stop = micros(); + Serial.print("FASTMAPD:\t"); + Serial.println(stop - start); + Serial.print(z); + Serial.print(" -> "); + Serial.println(x); + Serial.print("Performance factor: "); + Serial.println(1.0 * reference / (stop - start)); + Serial.println(); + +} + + +void loop() +{ +} + + +// -- END OF FILE -- diff --git a/examples/fastMap_performance_test/performance_0.4.1_ESP32.txt b/examples/fastMap_performance_test/performance_0.4.1_ESP32.txt new file mode 100644 index 0000000..6c3177f --- /dev/null +++ b/examples/fastMap_performance_test/performance_0.4.1_ESP32.txt @@ -0,0 +1,13 @@ +fastMap_performance_test.ino +FASTMAP_LIB_VERSION: 0.4.1 + +MAP: 1814 +0 -> 20000.00 + +FASTMAP: 627 +0 -> 20000.00 +Performance factor: 2.89 + +FASTMAPD: 6924 +0 -> 20000.00 +Performance factor: 0.26 diff --git a/examples/fastMap_performance_test/performance_0.4.1_UNO.txt b/examples/fastMap_performance_test/performance_0.4.1_UNO.txt new file mode 100644 index 0000000..a54fe65 --- /dev/null +++ b/examples/fastMap_performance_test/performance_0.4.1_UNO.txt @@ -0,0 +1,14 @@ + +fastMap_performance_test.ino +FASTMAP_LIB_VERSION: 0.4.1 + +MAP: 496072 +1023 -> 3000.00 + +FASTMAP: 211888 +1023 -> 3000.00 +Performance factor: 2.34 + +FASTMAPD: 211888 +1023 -> 3000.00 +Performance factor: 2.34 diff --git a/library.json b/library.json index 48eb1e3..2ebb59c 100644 --- a/library.json +++ b/library.json @@ -15,9 +15,9 @@ "type": "git", "url": "https://github.com/RobTillaart/FastMap" }, - "version": "0.4.0", + "version": "0.4.1", "license": "MIT", - "frameworks": "arduino", + "frameworks": "*", "platforms": "*", "headers": "FastMap.h" } diff --git a/library.properties b/library.properties index 3893888..2403942 100644 --- a/library.properties +++ b/library.properties @@ -1,8 +1,8 @@ name=FastMap -version=0.4.0 +version=0.4.1 author=Rob Tillaart maintainer=Rob Tillaart -sentence=Library with fast map function for Arduino. +sentence=Library with fast map function for Arduino. paragraph= category=Data Processing url=https://github.com/RobTillaart/FastMap