GY-63_MS5611/libraries/FastMap/readme.md

FastMap

Fast mapping and constraining.

Description

FastMap is an object that pre-calculates (internal) floats to make a mapping function especially for floats. The FastMap also provides a back() function to reverse the mapping. This only works well with floats, and less with integers, so use with care.

An important difference with the traditional map() function is that both init() and map() accepts floats as parameters. This allows mapping that would be hard to achieve with the normal map() function.

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 )

• On AVR (UNO and MEGA) no gain is made mapping integers with fastMap, 130% slower = substantial.
• On AVR the gain for float is limited, 10% faster.
• On ESP32 the gain for integers and float is both in the order of 25%.

To see the actual gain in your project on your hardware you should test and compare.

FastMap is faster when mapping floats as it uses less float operations than the standard map formula does. The performance results from pre-calculating values in the init() function. An actual mapping therefore needs only one multiply and one add operation where the standard map() function uses four adds, a multiplication and a division. The pre-calculation in init() should be taken in account and if every map() call needs an init() there will be no gain, on contrary.

Precision notes

The implementation of fastMap() uses floats (typical 32 bits) which might result in more memory usage and loss of precision for mapping of larger values, especially 32 and 64 bit integers.

This is caused by the limits of the mantissa (~23 bits) of the standard 4 byte float. To solve this a FastMapDouble class is added which uses the double type for the platforms that support 8 byte floats. If your platform does not support double it will often be mapped to float, so no gain. Furthermore using double might imply a performance penalty on some platforms.

Interface

#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, although it will give less overhead if you create an fastMap object per conversion needed.
  Returns false if (out_max == out_min) or (in_max == in_min). (breaking change in 0.4.0).
• float map(float value) maps the parameter.
• float back(float value) does the inverse mapping.

Constrains

FastMap supports three versions of constraining the map function, based upon the parameters of init().

• float constrainedMap(float value); returns a value between outMin .. outMax
• float lowerConstrainedMap(float value); returns a value between outMin .. infinity, ==> no upper limit.
• float upperConstrainedMap(float value); returns a value between -infinity .. outMax ==> no lower limit.

To change the constrain values call init() with new limits, or use the standard constrain().

Note there are NO constrain-versions for back(value) function.

FastMapDouble

Version 3.0 adds fastMapDouble which has the same interface as fastMap(). This class is meant to support 8 bytes doubles in their native accuracy and precision. To display doubles one might need the sci() function of my printHelpers class. https://github.com/RobTillaart/printHelpers

Note that on most embedded platforms the performance of doubles is less than floats. See below.

boards supporting double

board	float	double
UNO	yes	no
ATMEGA	yes	no
MKR1000	yes	yes
Zero	yes	yes
Teensy	yes	?
ESP32	yes	yes
RP2040	yes	?

to elaborate table. (if someone has a good link, please let me know).

test code.

void setup() {
  Serial.begin(115200);
  Serial.print("size of double:\t");
  Serial.println(sizeof(double));
  Serial.print("size of float: \t");
  Serial.println(sizeof(float));
}
void loop() {}

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.

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

• update documentation

Should

• test performance fastMapDouble on ESP32.
  • need good test example

Could

• investigate map function for complex numbers? / coordinates?
• 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,