MojoScale Studio Docs
API Reference

mojoscale_math

Hardware-oriented math helpers for MojoScale Studio.

All modules Open Studio
Studio Docs Runtime

import mojoscale_math

The mojoscale_math module is a standalone MojoScale math library. It does not replace Berry's built-in ``math`` module; it adds MCU-friendly helpers for mapping sensor ranges, angle math, tolerances, small statistics, randomness, vectors, and quaternions. Constants: pi: Circle constant. e: Euler's number. tau: 2 * pi. inf: Positive infinity. nan: Not-a-number. DEG_TO_RAD: Multiply degrees by this value to get radians. RAD_TO_DEG: Multiply radians by this value to get degrees.

Quick example

import mojoscale_math as mm

duty = mm.map(2048, 0, 4095, 0, 100, clamp=True)
duty = mm.deadband(duty, 3)

gravity = mm.vector3(0.02, -0.04, 9.81)
tilt = gravity.angle_to(mm.vector3(0, 0, 1))

q = mm.quaternion_from_euler(0, tilt, 0)
print(q.to_euler())

importmojoscale_math

Hardware-oriented math helpers for MojoScale Studio.

The mojoscale_math module is a standalone MojoScale math library. It does not replace Berry's built-in ``math`` module; it adds MCU-friendly helpers for mapping sensor ranges, angle math, tolerances, small statistics, randomness, vectors, and quaternions. Constants: pi: Circle constant. e: Euler's number. tau: 2 * pi. inf: Positive infinity. nan: Not-a-number. DEG_TO_RAD: Multiply degrees by this value to get radians. RAD_TO_DEG: Multiply radians by this value to get degrees.

API 101 available

mojoscale_math.abs(x: int) -> float

Return the absolute value.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Absolute value as float.

mojoscale_math.min(first: any, **numbers: any) -> float

Return the smallest positional value.

Parameters
Name Type Pass as Required Description
first any positional or keyword Yes First numeric value.
*numbers any extra positional No Additional numeric values.
Returns

float Smallest value as float.

mojoscale_math.max(first: any, **numbers: any) -> float

Return the largest positional value.

Parameters
Name Type Pass as Required Description
first any positional or keyword Yes First numeric value.
*numbers any extra positional No Additional numeric values.
Returns

float Largest value as float.

mojoscale_math.floor(x: int) -> float

Round down to the nearest integer-valued float.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Floored value.

mojoscale_math.ceil(x: int) -> float

Round up to the nearest integer-valued float.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Ceiled value.

mojoscale_math.round(x: int) -> float

Round to the nearest integer-valued float.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Rounded value.

mojoscale_math.trunc(x: int) -> float

Truncate the fractional part.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Truncated value.

mojoscale_math.sqrt(x: int) -> int

Return the square root.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

int Square root. Negative input follows the platform floating-point behavior.

mojoscale_math.pow(x: int, y: int) -> float

Raise x to y.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Base value.
y int positional or keyword Yes Exponent value.
Returns

float x raised to y.

mojoscale_math.exp(x: int) -> float

Return e raised to x.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Exponential value.

mojoscale_math.log(x: int) -> float

Return the natural logarithm.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Natural logarithm.

mojoscale_math.log10(x: int) -> float

Return the base-10 logarithm.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Base-10 logarithm.

mojoscale_math.log2(x: int) -> float

Return the base-2 logarithm.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Base-2 logarithm.

mojoscale_math.sin(x: int) -> float

Return sine of an angle in radians.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Angle in radians.
Returns

float Sine value.

mojoscale_math.cos(x: int) -> float

Return cosine of an angle in radians.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Angle in radians.
Returns

float Cosine value.

mojoscale_math.tan(x: int) -> float

Return tangent of an angle in radians.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Angle in radians.
Returns

float Tangent value.

mojoscale_math.asin(x: int) -> float

Return arcsine in radians.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Angle in radians.

mojoscale_math.acos(x: int) -> float

Return arccosine in radians.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Angle in radians.

mojoscale_math.atan(x: int) -> float

Return arctangent in radians.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Angle in radians.

mojoscale_math.atan2(y: int, x: int) -> float

Return arctangent of y/x in radians.

Parameters
Name Type Pass as Required Description
y int positional or keyword Yes Y component.
x int positional or keyword Yes X component.
Returns

float Angle in radians.

mojoscale_math.sinh(x: int) -> float

Return hyperbolic sine.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Hyperbolic sine.

mojoscale_math.cosh(x: int) -> float

Return hyperbolic cosine.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Hyperbolic cosine.

mojoscale_math.tanh(x: int) -> float

Return hyperbolic tangent.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

float Hyperbolic tangent.

mojoscale_math.isfinite(x: int) -> bool

Check whether a value is finite.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

bool True if x is neither infinity nor NaN.

mojoscale_math.isinf(x: int) -> bool

Check whether a value is infinite.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

bool True if x is positive or negative infinity.

mojoscale_math.isnan(x: int) -> bool

Check whether a value is NaN.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

bool True if x is NaN.

mojoscale_math.sign(x: int) -> int

Return -1, 0, or 1 based on the value sign.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
Returns

int -1 for negative, 0 for zero, 1 for positive.

mojoscale_math.fmod(x: int, y: int) -> float

Return floating-point remainder.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Dividend.
y int positional or keyword Yes Divisor.
Returns

float Remainder using C fmod behavior.

mojoscale_math.hypot(x: int, y: int) -> float

Return sqrt(x*x + y*y).

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes X component.
y int positional or keyword Yes Y component.
Returns

float Euclidean hypotenuse.

mojoscale_math.clamp(value: any, minimum: any, maximum: any) -> float

Clamp a value into a range.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Input value.
minimum any positional or keyword Yes Lower bound.
maximum any positional or keyword Yes Upper bound.
Returns

float Clamped value.

mojoscale_math.map(value: any, in_min: any, in_max: any, out_min: any, out_max: any, clamp: bool = None) -> int

Map a value from one numeric range to another.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Input value.
in_min any positional or keyword Yes Input range lower bound.
in_max any positional or keyword Yes Input range upper bound.
out_min any positional or keyword Yes Output range lower bound.
out_max any positional or keyword Yes Output range upper bound.
clamp bool positional or keyword No Optional bool. True clamps the interpolation amount to 0..1.
Returns

int Mapped floating-point value.

mojoscale_math.lerp(a: any, b: any, amount: any) -> int

Linearly interpolate from a to b.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start value.
b any positional or keyword Yes End value.
amount any positional or keyword Yes Interpolation amount. 0 returns a, 1 returns b.
Returns

int Interpolated value.

mojoscale_math.inverse_lerp(a: any, b: any, value: any) -> int

Find where value sits between a and b.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start value.
b any positional or keyword Yes End value.
value any positional or keyword Yes Value to normalize.
Returns

int Interpolation amount.

mojoscale_math.normalize(value: any, minimum: any, maximum: any) -> int

Normalize a value inside a range.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Input value.
minimum any positional or keyword Yes Range lower bound.
maximum any positional or keyword Yes Range upper bound.
Returns

int Normalized interpolation amount.

mojoscale_math.radians(degrees: any) -> float

Convert degrees to radians.

Parameters
Name Type Pass as Required Description
degrees any positional or keyword Yes Angle in degrees.
Returns

float Angle in radians.

mojoscale_math.degrees(radians: any) -> float

Convert radians to degrees.

Parameters
Name Type Pass as Required Description
radians any positional or keyword Yes Angle in radians.
Returns

float Angle in degrees.

mojoscale_math.wrap_angle(angle: float, unit: str = None) -> float

Wrap an angle to 0..360 or 0..2*pi.

Parameters
Name Type Pass as Required Description
angle float positional or keyword Yes Angle value.
unit str positional or keyword No Optional unit string. Use "degrees" or "radians". Defaults to "degrees".
Returns

float Wrapped angle.

mojoscale_math.wrap_degrees(angle: float) -> float

Wrap degrees into the 0..360 range.

Parameters
Name Type Pass as Required Description
angle float positional or keyword Yes Angle in degrees.
Returns

float Wrapped angle in degrees.

mojoscale_math.wrap_radians(angle: float) -> float

Wrap radians into the 0..2*pi range.

Parameters
Name Type Pass as Required Description
angle float positional or keyword Yes Angle in radians.
Returns

float Wrapped angle in radians.

mojoscale_math.angle_difference(a: any, b: any, unit: str = None) -> float

Shortest signed difference from angle a to b.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start angle.
b any positional or keyword Yes Target angle.
unit str positional or keyword No Optional unit string. Use "degrees" or "radians". Defaults to "degrees".
Returns

float Signed shortest difference.

mojoscale_math.angle_difference_degrees(a: any, b: any) -> float

Shortest signed difference in degrees.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start angle in degrees.
b any positional or keyword Yes Target angle in degrees.
Returns

float Signed shortest difference in degrees.

mojoscale_math.angle_difference_radians(a: any, b: any) -> float

Shortest signed difference in radians.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start angle in radians.
b any positional or keyword Yes Target angle in radians.
Returns

float Signed shortest difference in radians.

mojoscale_math.lerp_angle(a: any, b: any, amount: any, unit: str = None) -> int

Interpolate along the shortest angle path.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start angle.
b any positional or keyword Yes Target angle.
amount any positional or keyword Yes Interpolation amount.
unit str positional or keyword No Optional unit string. Use "degrees" or "radians". Defaults to "degrees".
Returns

int Interpolated wrapped angle.

mojoscale_math.lerp_angle_degrees(a: any, b: any, amount: any) -> int

Interpolate degrees along the shortest angle path.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start angle in degrees.
b any positional or keyword Yes Target angle in degrees.
amount any positional or keyword Yes Interpolation amount.
Returns

int Interpolated wrapped degrees.

mojoscale_math.lerp_angle_radians(a: any, b: any, amount: any) -> int

Interpolate radians along the shortest angle path.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start angle in radians.
b any positional or keyword Yes Target angle in radians.
amount any positional or keyword Yes Interpolation amount.
Returns

int Interpolated wrapped radians.

mojoscale_math.isclose(a: any, b: any, rel_tol: any = None, abs_tol: any = None) -> bool

Compare floats with relative and absolute tolerance.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes First value.
b any positional or keyword Yes Second value.
rel_tol any positional or keyword No Optional relative tolerance. Defaults to 1e-6.
abs_tol any positional or keyword No Optional absolute tolerance. Defaults to 1e-9.
Returns

bool True when the values are close.

mojoscale_math.near_zero(x: int, tolerance: any = None) -> bool

Check whether a value is close to zero.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Numeric value.
tolerance any positional or keyword No Optional absolute tolerance. Defaults to 1e-6.
Returns

bool True when abs(x) <= tolerance.

mojoscale_math.deadband(value: any, threshold: float) -> float

Suppress small values around zero.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Input value.
threshold float positional or keyword Yes Deadband threshold.
Returns

float 0 when abs(value) < threshold, otherwise value.

mojoscale_math.smoothstep(edge0: any, edge1: any, value: any) -> float

Smoothly interpolate from 0 to 1 between two edges.

Parameters
Name Type Pass as Required Description
edge0 any positional or keyword Yes Lower edge.
edge1 any positional or keyword Yes Upper edge.
value any positional or keyword Yes Input value.
Returns

float Smoothstep value from 0 to 1.

mojoscale_math.move_towards(current: float, target: any, maximum_change: any) -> float

Move a value toward a target by no more than maximum_change.

Parameters
Name Type Pass as Required Description
current float positional or keyword Yes Current value.
target any positional or keyword Yes Target value.
maximum_change any positional or keyword Yes Maximum absolute change.
Returns

float Updated value.

mojoscale_math.sum(values: list) -> float

Return the sum of numeric list values.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
Returns

float Numeric sum.

mojoscale_math.mean(values: list) -> float

Return the mean of numeric list values.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
Returns

float Mean value.

mojoscale_math.median(values: list) -> float

Return the median of numeric list values.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
Returns

float Median value.

mojoscale_math.variance(values: list, sample: bool = None) -> float

Return population or sample variance.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
sample bool positional or keyword No Optional bool. True uses sample variance, False uses population variance.
Returns

float Variance.

mojoscale_math.stddev(values: list, sample: bool = None) -> float

Return population or sample standard deviation.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
sample bool positional or keyword No Optional bool. True uses sample standard deviation.
Returns

float Standard deviation.

mojoscale_math.minimum(values: list) -> list

Return the smallest value in a numeric list.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
Returns

list Minimum list value.

mojoscale_math.maximum(values: list) -> list

Return the largest value in a numeric list.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
Returns

list Maximum list value.

mojoscale_math.range(values: list) -> float

Return maximum(values) - minimum(values).

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
Returns

float Numeric range.

mojoscale_math.rms(values: list) -> float

Return root-mean-square of numeric list values.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes List of numbers.
Returns

float RMS value.

mojoscale_math.seed(value: any) -> bool

Seed the pseudo-random generator.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Integer seed.
Returns

bool True.

mojoscale_math.random() -> float

Return pseudo-random float from 0.0 inclusive to 1.0 exclusive.

Returns

float Random float. Not cryptographically secure.

mojoscale_math.randint(minimum: any, maximum: any) -> int

Return pseudo-random integer in an inclusive range.

Parameters
Name Type Pass as Required Description
minimum any positional or keyword Yes Inclusive lower bound.
maximum any positional or keyword Yes Inclusive upper bound.
Returns

int Random integer. Not cryptographically secure.

mojoscale_math.uniform(minimum: any, maximum: any) -> float

Return pseudo-random float in a range.

Parameters
Name Type Pass as Required Description
minimum any positional or keyword Yes Lower bound.
maximum any positional or keyword Yes Upper bound.
Returns

float Random float. Not cryptographically secure.

mojoscale_math.choice(values: list) -> list

Return one pseudo-random value from a list.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes Non-empty list.
Returns

list One list element.

mojoscale_math.vector2(x: int, y: int) -> vector2

Create a 2D vector.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes X component.
y int positional or keyword Yes Y component.
Returns

vector2 vector2 object.

mojoscale_math.vector2().length() -> float

Return vector magnitude.

mojoscale_math.vector2().length_squared() -> float

Return squared magnitude.

mojoscale_math.vector2().normalized() -> vector2

Return a unit vector.

mojoscale_math.vector2().dot(other) -> float

Dot product with another vector2.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector2().distance_to(other) -> float

Distance to another vector2.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector2().angle_to(other) -> float

Angle to another vector2 in radians.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector2().add(other) -> vector2

Component-wise addition.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector2().sub(other) -> vector2

Component-wise subtraction.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector2().scale(value) -> vector2

Multiply by scalar.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Required value.

mojoscale_math.vector2().div(value) -> vector2

Divide by scalar.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Required value.

mojoscale_math.vector2().to_map() -> dict: Return {"x": x, "y"

y}.

mojoscale_math.vector3(x: int, y: int, z: any) -> vector3

Create a 3D vector.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes X component.
y int positional or keyword Yes Y component.
z any positional or keyword Yes Z component.
Returns

vector3 vector3 object.

mojoscale_math.vector3().length() -> float

Return vector magnitude.

mojoscale_math.vector3().length_squared() -> float

Return squared magnitude.

mojoscale_math.vector3().normalized() -> vector3

Return a unit vector.

mojoscale_math.vector3().dot(other) -> float

Dot product with another vector3.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector3().cross(other) -> vector3

Cross product with another vector3.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector3().distance_to(other) -> float

Distance to another vector3.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector3().angle_to(other) -> float

Angle to another vector3 in radians.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector3().add(other) -> vector3

Component-wise addition.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector3().sub(other) -> vector3

Component-wise subtraction.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.vector3().scale(value) -> vector3

Multiply by scalar.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Required value.

mojoscale_math.vector3().div(value) -> vector3

Divide by scalar.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Required value.

mojoscale_math.vector3().to_map() -> dict: Return {"x": x, "y": y, "z"

z}.

mojoscale_math.quaternion(w: any, x: int, y: int, z: any) -> quaternion

Create a quaternion using w, x, y, z ordering.

Parameters
Name Type Pass as Required Description
w any positional or keyword Yes Real component.
x int positional or keyword Yes X imaginary component.
y int positional or keyword Yes Y imaginary component.
z any positional or keyword Yes Z imaginary component.
Returns

quaternion quaternion object.

mojoscale_math.quaternion().normalized() -> quaternion

Return a unit quaternion.

mojoscale_math.quaternion().conjugate() -> quaternion

Return the conjugate.

mojoscale_math.quaternion().inverse() -> quaternion

Return the inverse.

mojoscale_math.quaternion().multiply(other) -> quaternion

Hamilton product with another quaternion.

Parameters
Name Type Pass as Required Description
other any positional or keyword Yes Required value.

mojoscale_math.quaternion().rotate(vector) -> vector3

Rotate a vector3 by this quaternion.

Parameters
Name Type Pass as Required Description
vector any positional or keyword Yes Required value.

mojoscale_math.quaternion().to_euler() -> dict

Return roll, pitch, and yaw in radians.

mojoscale_math.quaternion().to_matrix() -> list

Return a 3x3 rotation matrix as nested lists.

mojoscale_math.quaternion().to_map() -> dict: Return {"w": w, "x": x, "y": y, "z"

z}.

mojoscale_math.quaternion_from_euler(roll: any, pitch: any, yaw: any) -> quaternion

Create a quaternion from roll, pitch, yaw radians.

Parameters
Name Type Pass as Required Description
roll any positional or keyword Yes Roll angle in radians.
pitch any positional or keyword Yes Pitch angle in radians.
yaw any positional or keyword Yes Yaw angle in radians.
Returns

quaternion quaternion object.

mojoscale_math.quaternion_from_axis_angle(axis: any, angle: float) -> quaternion

Create a quaternion from an axis vector and angle.

Parameters
Name Type Pass as Required Description
axis any positional or keyword Yes vector3 rotation axis.
angle float positional or keyword Yes Rotation angle in radians.
Returns

quaternion quaternion object.

mojoscale_math.quaternion_slerp(a: any, b: any, amount: any) -> quaternion

Spherically interpolate between two quaternions.

Parameters
Name Type Pass as Required Description
a any positional or keyword Yes Start quaternion.
b any positional or keyword Yes End quaternion.
amount any positional or keyword Yes Interpolation amount from 0 to 1.
Returns

quaternion quaternion object.