Devices << VirtualDevices << MapperDevice Software Overview  |  Sitemap  |  Downloads  |  Developers  |  Forums
 Home Devices FAQs How-Tos Projects Tutorials Recipes

# Mapper Device

The Mapper Device maps an input value to another output value. Mapping can be done by mapping one set of values to another set, by using linear interpolation, or by invoking a function.

Mapping a set of values to another is done by taking a set of values, "mon, tues, wed", and when one of those values is input to the mapper, it chooses a value in the same location from another set, "red, green, blue". When the mapper sees `mon`, it outputs `red`. When it see `tues`, it outputs `green`. If the mapper sees something not in the first set, `thurs`, it leaves its output unchanged.

Mapping using linear interpolation takes two number ranges and uses them both to compute a linear mapping from the first range to the second. Even if a starting value is not in the first number range, the mapper will use linear interpolation to generate an output value. As an example of using linear interpolation, the first range is "1..5" and the second is "8..12". The value 1 maps to 8, the value 5 maps to 12, and the value 6 will map to 13. If an input is not numeric, the output of the mapper will be left unchanged.

Mapping with a function uses a function to compute an output value based on a numeric input value. If the function were "x**2" (x squared), 1 maps to 1, 2 maps to 4, and 3 maps to 9. If an input is not numeric, the output of the mapper will be left unchanged.

## Mapper Terminals

The Mapper Device has two terminals, an "in" terminal and an "out" terminal. The "in" terminal receives values, and the "out" terminal generates the mapped output values. If a Mapper Device does not recognize an input or can't generate a value, it will leave its "out" terminal unchanged.

## Creating a Mapper Device

Mapper Devices are created by running the Mapper Script. The Mapper Script takes optional input parameters. The parameters supplied determine what kind of mapping is performed.

To map one set of values to another, the parameters are as follows:

• `from : a set of values to map from. The set is a string with its elements separated by commas.`
• `to : a set of values to map to. The set is a string with its elements separated by commas. The number of elements in the "from" and "to" sets must be the same.`

To map one range of values to another using linear interpolation, the parameters are as follows:

• `from : a range of values to map from. The range is a double quoted string with two numbers separated by "..".`
• `to : a range of values to map to. The range is a double quoted string with two numbers separated by "..".`

To map an input value to an output value using a function, the parameters are as follows:

• `function : a function with a single unknown variable. A function is a string of operations enclosed in double quotes. The unknown variable in the string is the "in" terminal input value to the mapper.`

Function parameters are more fully described in the Function and Scaling Parameters section on the Scripts page.

## Examples

Running the Mapper Script with the parameters listed below will add a Mapper which maps "in" terminal values `on` and `off` to "out" terminal values `red` and `blue`:

`id: "my_mapper"`
`from: "on, off"`
`to: "red, blue"`

Running the Mapper Script with the parameters listed below will add a Mapper which maps "in" terminal values `"alarm1"` and `"alarm2"` to "out" terminal values `"This is alarm1"` and `"This is alarm2"`:

`id: "my_mapper"`
`from: "\"alarm1\", \"alarm2\""`
`to: "\"This is alarm1\", \"This is alarm2\""`

Running the Mapper Script with the parameters listed below will add a Mapper which maps "in" terminal values in Fahrenheit degrees to "out" terminal values in Celsius degrees:

`id: "my_mapper"`
`from: "32..212"`
`to: "0..100"`

Running the Mapper Script with the parameters listed below will add a Mapper which maps "in" terminal values in Fahrenheit degrees to "out" terminal values in Celsius degrees (using a function):

`id: "my_mapper"`
`function: "5/9 * (F-32)"`