GY-63_MS5611/libraries/moduloMap/README.md

moduloMap

Arduino library for the moduloMap class.

Description

The moduloMap is an experimental library that optimizes modular mapping.

How do I define modular mapping?

Imagine the mapping of all real numbers on a subset in a modular way. Imagine the real number line rolled around a defined circle with a minimum and maximum value. After one rotation the numbers mapped to start over again.

E.g. moduloMap(7, 13) maps all the real numbers to the interval [7; 13> modulo 6.

So the numbers 7..13 do not change as they are already within the range 7-13. The number 6 is mapped on 12, 5 on 11, 4 on 10, .. 1 on 7, 0 on 12 -1 on 11 etc. Similar the numbers in between e.g 5.5 is mapped on 11.5

Note: there is no scaling.

Other name might be circular mapping, although it might be any shape. (for now circles is complex enough)

Applications

• modular mapping of rotations to angles.
  This can be on 0-360 degrees or 0-2PI radians or -180-180 degrees or even -90..270 degrees.
• hoist math
  Imagine a hoist, that needs to roll up / roll off a long rope around a cylinder.
• wire cutter
  Determine the length of a wire for a wire cutter by moving it between two wheels with known circumference.
• math fun

Interface

• moduloMap() constructor.
• bool begin(float minimum, float maximum) define the range the numbers should be mapped to. Returns true if minimum < maximum, false otherwise.
• float map(float value) actual mapping of a value to a number within the range.
• float rotations(float value) how many ranges (maximum - minimum) fit in a given length.
  Think of it as how many rotations must a hoist must make to "free" a rope of given length. Or how many rotations a hoist has to make to roll up a rope of given length. This includes the minimum that already has rolled off / should stay rolled off.

Get internal parameters (for debug)

• float getMinimum() idem.
• float getMaximum() idem.
• float getRange() idem.

Performance

Tested with moduloMap_performance.ino on AVR.

version	1000 x map
0.1.0	44120 us
0.1.1	36340 us

Operation

The examples show the basic working of the functions.

Future

must

• elaborate documentation
• add examples

should

• move code to .cpp file

could

• are there other than circular modulos
  • triangular, square, pentagram, fractal?
  • increasing length per rotation (complex)
• add link to related libraries
  • angles + fastmap?
• add begin(float radius)
  • assumes circle from 0..max

wont