Map Functions

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

from music import *

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:

>>> mapValue(0, 0, 100, 10, 20)
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:

>>> mapValue(50, 0, 100, 10, 20)
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.

NOTE:  If you use float numbers, mapValue() will return a float value that is properly scaled (preserving accuracy):

>>> mapValue(49 , 0, 100, 10, 20)
14
>>> mapValue(49 , 0, 100, 10.0, 20.0)
14.9

Notice how in the second example, 49 was mapped to 14.9, since the destination range was float.

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().