Utilities » Math utilities

Math utilities

In this page:

Round
Modulate
Math utilities example

Round

Utils.round() will convert any number to an integer (whole number), or to a decimal with a specified number of digits after the point.

Utils.round value, decimals

value — Any number (or variable containing a number).
decimals — Number of digits after the decimal point. (Optional)

print Utils.round 100.12345
» 100

print Utils.round 100.12345, 2
» 100.12

print Utils.round 100.12345, 4
» 100.1234

Here are a few more parameters for when you want more control:

Utils.round value, decimals, increment, min, max

increment — The increment to round to. (Optional)
min — The minimum value to return. (Optional)
max — The maximum value to return. (Optional)

print Utils.round 100.123, 2
» 100.12

# setting an increment value
print Utils.round 100.123, 2, 0.2
» 100.2

With ‘min’ and ‘max’ you can set a minimum and/or maximum value that should be returned.

print Utils.round 1.123, 2
» 1.12

# returned value should be 1.14 or higher
print Utils.round 1.123, 2, 0, 1.14
» 1.14

# returned value should be 1.11 or lower
print Utils.round 1.123, 2, 0, 0, 1.11
» 1.11

Example

In the Math utilities example, we round the slider’s value to a number with only one decimal.

burgerQuantity = Utils.round slider.value, 1

Modulate

You can send a numeric value to Utils.modulate(), and it will return that value mapped on a different scale.

You provide these source and destination scales as arrays, each with a minimum and maximum value.

Utils.modulate value, [a, a], [b, b], limit

Arguments

value — The input value.
[a, a] — The scale to interpolate from.
[b, b] — The scale to interpolate to.
limit — Whether to limit the output values. (no by default)

Say you’re converting Celsius to Fahrenheit:

-20° Celsius is -4° Fahrenheit
and 40° Celsius is 104° Fahrenheit

This means that your ‘from’ array will be [-20, 40] (the range for Celsius) and the ‘to’ array will be [-4, 104] (the range for Fahrenheit).

tempInCelsius = 20
tempInFahrenheit = Utils.modulate tempInCelsius, [-20, 40], [-4, 104]
print tempInFahrenheit
» 68

But even if you give the function an input value outside of this [-20, 40] range you will still get a correct result:

tempInCelsius = -22
tempInFahrenheit = Utils.modulate tempInCelsius, [-20, 40], [-4, 104]
print tempInFahrenheit
» -7,6

Although when you enable ‘limit’, the output value will be capped:

tempInCelsius = -22
tempInFahrenheit = Utils.modulate tempInCelsius, [-20, 40], [-4, 104], yes
print tempInFahrenheit
» -4

You can use Modulate to create a parallax effect (when multiple layers move, but at different speeds), or have a layer fade out when you’re scrolling.

Math utilities example

In this example project, we map the number of cheeseburgers (0 to 10) to the width of the layer that makes them visible (0 to 600 points).

# burgers: 0 to 10
# width of the masking layer: 0 to 600 points
burgersMask.width = Utils.modulate burgerQuantity, [0,10], [0,600], yes

We use Round to make sure the ‘burger quantity’ is a value with only one decimal.

burgerQuantity = Utils.round slider.value, 1