Skip to main content
Version: Matrix OS 3.2

ColorEffects

Preview notice​

The MatrixOS Python API is in preview and is subject to change; it may contain errors.

Overview​

The ColorEffects API provides utility functions for generating dynamic lighting effects such as rainbow, breathing, strobe, and other color modulation effects based on time and phase offsets. Access these functions through ColorEffects.

The Python ColorEffects API is implemented in Applications/Python/PikaPython/MatrixOS_ColorEffects.py with type hints in Applications/Python/PikaPython/_MatrixOS_ColorEffects.pyi.

Color Generation Effects​

ColorEffects.Rainbow​

def Rainbow(period: int = 1000, offset: int = 0) -> Color

Generates a rainbow color effect that cycles through the hue spectrum over the specified period.

Parameters:

  • period (int, optional): Duration of the full color cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the starting hue. Defaults to 0

Returns:

  • Color: The current color in the rainbow cycle

Brightness Modulation Effects​

ColorEffects.Breath​

def Breath(period: int = 1000, offset: int = 0) -> int

Generates a brightness value that smoothly transitions in a sinusoidal pattern (breathing effect).

Parameters:

  • period (int, optional): Duration of the breathing cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the breathing phase. Defaults to 0

Returns:

  • int: The brightness value (0-255)

ColorEffects.BreathLowBound​

def BreathLowBound(low_bound: int = 64, period: int = 1000, offset: int = 0) -> int

Generates a breathing effect with a minimum brightness value.

Parameters:

  • low_bound (int, optional): Minimum brightness value. Defaults to 64
  • period (int, optional): Duration of the breathing cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the breathing phase. Defaults to 0

Returns:

  • int: The brightness value (low_bound to 255)

ColorEffects.Strobe​

def Strobe(period: int = 1000, offset: int = 0) -> int

Generates a strobe effect by alternating between full brightness and off states.

Parameters:

  • period (int, optional): Duration of one strobe cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the strobe phase. Defaults to 0

Returns:

  • int: The brightness value (0 or 255)

ColorEffects.Saw​

def Saw(period: int = 1000, offset: int = 0) -> int

Generates a sawtooth waveform for brightness, cycling from 0 to 255 linearly.

Parameters:

  • period (int, optional): Duration of one sawtooth cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the phase. Defaults to 0

Returns:

  • int: The brightness value (0-255)

ColorEffects.Triangle​

def Triangle(period: int = 1000, offset: int = 0) -> int

Generates a triangle waveform for brightness, cycling up and down between 0 and 255.

Parameters:

  • period (int, optional): Duration of one triangle cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the phase. Defaults to 0

Returns:

  • int: The brightness value (0-255)

Color Modulation Effects​

ColorEffects.ColorBreath​

def ColorBreath(color: Color, period: int = 1000, offset: int = 0) -> Color

Applies a breathing effect to a specific color by modulating its brightness.

Parameters:

  • color (Color): The base color
  • period (int, optional): Duration of the breathing cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the breathing phase. Defaults to 0

Returns:

  • Color: The modulated color with the breathing effect applied

ColorEffects.ColorBreathLowBound​

def ColorBreathLowBound(color: Color, low_bound: int = 64, period: int = 1000, offset: int = 0) -> Color

Applies a breathing effect to a color, ensuring a minimum brightness value.

Parameters:

  • color (Color): The base color
  • low_bound (int, optional): Minimum brightness value. Defaults to 64
  • period (int, optional): Duration of the breathing cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the breathing phase. Defaults to 0

Returns:

  • Color: The modulated color with the breathing effect applied

ColorEffects.ColorStrobe​

def ColorStrobe(color: Color, period: int = 1000, offset: int = 0) -> Color

Applies a strobe effect to a specific color.

Parameters:

  • color (Color): The base color
  • period (int, optional): Duration of one strobe cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the strobe phase. Defaults to 0

Returns:

  • Color: The modulated color with the strobe effect applied

ColorEffects.ColorSaw​

def ColorSaw(color: Color, period: int = 1000, offset: int = 0) -> Color

Applies a sawtooth waveform to the brightness of a specific color.

Parameters:

  • color (Color): The base color
  • period (int, optional): Duration of one sawtooth cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the phase. Defaults to 0

Returns:

  • Color: The modulated color with the sawtooth effect applied

ColorEffects.ColorTriangle​

def ColorTriangle(color: Color, period: int = 1000, offset: int = 0) -> Color

Applies a triangle waveform to the brightness of a specific color.

Parameters:

  • color (Color): The base color
  • period (int, optional): Duration of one triangle cycle in milliseconds. Defaults to 1000ms
  • offset (int, optional): Offset to adjust the phase. Defaults to 0

Returns:

  • Color: The modulated color with the triangle effect applied

Comments