Map Functions

Map functions are used to expand, contract, or offset data values. They convert a numeric value from one range to another.

For example, mapping the value 0 from the range 0..100 to the range 10..20 results in 10:

Notice how 0 is the leftmost value in its range, as is 10.

Similarly, mapping 50 from the range 0..100 to the range 10..20 results in 15:

Again, notice how 50 is in the middle of its range, and so is 15.

So, map functions maintain the relative position of a value.

Map functions are included in the music library, so, in order to use them, you need the following in your program:

Function Description
mapValue(value, minValue, maxValue, minResult, maxResult) Takes a number within one range and returns its equivalent within another range. The arguments are:

  • value – the number to be mapped
  • minValue – the lowest possible number to be mapped (inclusive)
  • maxValue – the highest possible number to be mapped (inclusive)
  • minResult – the lowest value of the destination range (inclusive)
  • maxResult – the highest value of the destination range (inclusive)
mapScale(value, minValue, maxValue, minResult, maxResult, scale) Takes a number (i.e., MIDI pitch) within one range and returns a its equivalent within another range, quantized to the pitch class value in scale. The arguments are:

  • value – the number to be mapped
  • minValue – the lowest possible number to be mapped (inclusive)
  • maxValue – the highest possible number to be mapped (inclusive)
  • minResult – the lowest value of the destination range (inclusive)
  • maxResult – the highest value of the destination range (inclusive)
  • scale – (optional) the musical scale (a list of pitch classes between 0 and 11) to be applied to the destination range (here are common scales).  If omitted, mapScale() works like mapValue().