颜色效果
概述
颜色效果 API 提供生成动态灯光效果的实用函数，如彩虹、呼吸、闪烁等基于时间和相位偏移的颜色调制效果。通过 ColorEffects 访问这些函数。
Python 颜色效果 API 实现位于 Applications/Python/PikaPython/MatrixOS_ColorEffects.py，类型提示位于 Applications/Python/PikaPython/_MatrixOS_ColorEffects.pyi。
颜色生成效果
ColorEffects.Rainbow
def Rainbow(period: int = 1000, offset: int = 0) -> Color
生成彩虹色效果，在指定周期内循环遍历色相光谱。
参数：
period(int, 可选)：完整颜色循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整起始色相的偏移量，默认为0
返回值：
Color：彩虹循环中的当前颜色
示例：
# 基础彩虹效果
rainbow_color = ColorEffects.Rainbow()
MatrixOS.LED.Fill(rainbow_color)
MatrixOS.LED.Update()
# 更快的彩虹，带偏移
fast_rainbow = ColorEffects.Rainbow(500, 100)
MatrixOS.LED.SetColor(Point(0, 0), fast_rainbow)
亮度调制效果
ColorEffects.Breath
def Breath(period: int = 1000, offset: int = 0) -> int
生成以正弦波模式平滑过渡的亮度值（呼吸效果）。
参数：
period(int, 可选)：呼吸循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整呼吸相位的偏移量，默认为0
返回值：
int：亮度值（0-255）
示例：
# 创建呼吸效果
brightness = ColorEffects.Breath(2000) # 2秒循环
MatrixOS.LED.Fill(Color(255, 0, 0), brightness)
MatrixOS.LED.Update(brightness)
ColorEffects.BreathLowBound
def BreathLowBound(low_bound: int = 64, period: int = 1000, offset: int = 0) -> int
生成具有最低亮度值的呼吸效果。
参数：
low_bound(int, 可选)：最低亮度值，默认为64period(int, 可选)：呼吸循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整呼吸相位的偏移量，默认为0
返回值：
int：亮度值（low_bound 到 255）
示例：
# 永远不会完全变暗的呼吸效果
brightness = ColorEffects.BreathLowBound(100, 1500)
MatrixOS.LED.Fill(Color(0, 255, 0), brightness)
ColorEffects.Strobe
def Strobe(period: int = 1000, offset: int = 0) -> int
通过在满亮度和关闭状态之间交替来生成闪烁效果。
参数：
period(int, 可选)：一个闪烁循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整闪烁相位的偏移量，默认为0
返回值：
int：亮度值（0 或 255）
示例：
# 快速闪烁效果
brightness = ColorEffects.Strobe(200) # 200ms 循环
MatrixOS.LED.Fill(Color(255, 255, 255), brightness)
ColorEffects.Saw
def Saw(period: int = 1000, offset: int = 0) -> int
生成用于亮度的锯齿波形，从 0 到 255 线性循环。
参数：
period(int, 可选)：一个锯齿循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整相位的偏移量，默认为0
返回值：
int：亮度值（0-255）
示例：
# 锯齿亮度渐变
brightness = ColorEffects.Saw(3000) # 3秒渐亮
MatrixOS.LED.Fill(Color(0, 0, 255), brightness)
ColorEffects.Triangle
def Triangle(period: int = 1000, offset: int = 0) -> int
生成用于亮度的三角波形，在 0 和 255 之间上下循环。
参数：
period(int, 可选)：一个三角循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整相位的偏移量，默认为0
返回值：
int：亮度值（0-255）
示例：
# 三角波亮度
brightness = ColorEffects.Triangle(2000)
MatrixOS.LED.Fill(Color(255, 255, 0), brightness)
颜色调制效果
ColorEffects.ColorBreath
def ColorBreath(color: Color, period: int = 1000, offset: int = 0) -> Color
通过调制亮度为特定颜色应用呼吸效果。
参数：
color(Color)：基础颜色period(int, 可选)：呼吸循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整呼吸相位的偏移量，默认为0
返回值：
Color：应用呼吸效果后的调制颜色
示例：
base_color = Color(255, 0, 0) # 红色
breathing_red = ColorEffects.ColorBreath(base_color, 1500)
MatrixOS.LED.Fill(breathing_red)
ColorEffects.ColorBreathLowBound
def ColorBreathLowBound(color: Color, low_bound: int = 64, period: int = 1000, offset: int = 0) -> Color
为颜色应用呼吸效果，确保最低亮度值。
参数：
color(Color)：基础颜色low_bound(int, 可选)：最低亮度值，默认为64period(int, 可选)：呼吸循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整呼吸相位的偏移量，默认为0
返回值：
Color：应用呼吸效果后的调制颜色
示例：
base_color = Color(0, 255, 255) # 青色
subtle_breath = ColorEffects.ColorBreathLowBound(base_color, 128, 2000)
MatrixOS.LED.Fill(subtle_breath)
ColorEffects.ColorStrobe
def ColorStrobe(color: Color, period: int = 1000, offset: int = 0) -> Color
为特定颜色应用闪烁效果。
参数：
color(Color)：基础颜色period(int, 可选)：一个闪烁循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整闪烁相位的偏移量， 默认为0
返回值：
Color：应用闪烁效果后的调制颜色
示例：
base_color = Color(255, 0, 255) # 洋红色
strobe_magenta = ColorEffects.ColorStrobe(base_color, 300)
MatrixOS.LED.Fill(strobe_magenta)
ColorEffects.ColorSaw
def ColorSaw(color: Color, period: int = 1000, offset: int = 0) -> Color
为特定颜色的亮度应用锯齿波形。
参数：
color(Color)：基础颜色period(int, 可选)：一个锯齿循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整相位的偏移量，默认为0
返回值：
Color：应用锯齿效果后的调制颜色
示例：
base_color = Color(255, 255, 0) # 黄色
saw_yellow = ColorEffects.ColorSaw(base_color, 2500)
MatrixOS.LED.Fill(saw_yellow)
ColorEffects.ColorTriangle
def ColorTriangle(color: Color, period: int = 1000, offset: int = 0) -> Color
为特定颜色的亮度应用三角波形。
参数：
color(Color)：基础颜色period(int, 可选)：一个三角循环的持续时间（毫秒），默认为1000msoffset(int, 可选)：调整相位的偏移量，默认为0
返回值：
Color：应用三角效果后的调制颜色
示例：
base_color = Color(0, 255, 0) # 绿色
triangle_green = ColorEffects.ColorTriangle(base_color, 1800)
MatrixOS.LED.Fill(triangle_green)
使用示例
动态彩虹网格
def rainbow_grid():
"""在 LED 网格上创建彩虹效果"""
while True:
for x in range(8):
for y in range(8):
# 根据位置创建相位偏移
offset = (x + y) * 125 # 每步 125ms 偏移
rainbow_color = ColorEffects.Rainbow(2000, offset)
MatrixOS.LED.SetColor(Point(x, y), rainbow_color)
MatrixOS.LED.Update()
MatrixOS.SYS.DelayMs(50)
rainbow_grid()
多效果组合
def combined_effects():
"""组合多种颜色效果"""
base_colors = [
Color(255, 0, 0), # 红色
Color(0, 255, 0), # 绿色
Color(0, 0, 255), # 蓝色
Color(255, 255, 0) # 黄色
]
while True:
for i, base_color in enumerate(base_colors):
row = i * 2 # 每种颜色使用两行
# 第 1 行：呼吸效果
breath_color = ColorEffects.ColorBreath(base_color, 3000, i * 750)
for x in range(8):
MatrixOS.LED.SetColor(Point(x, row), breath_color)
# 第 2 行：闪烁效果
if row + 1 < 8:
strobe_color = ColorEffects.ColorStrobe(base_color, 1000, i * 250)
for x in range(8):
MatrixOS.LED.SetColor(Point(x, row + 1), strobe_color)
MatrixOS.LED.Update()
MatrixOS.SYS.DelayMs(50)
combined_effects()
音乐响应效果
def music_visualizer():
"""使用效果的简单音乐响应灯光"""
# 模拟音频强度（在实际应用中，这将来自音频输入）
import random
base_color = Color(255, 100, 0) # 橙色
while True:
# 模拟不同的音频级别
audio_level = random.randint(0, 100)
if audio_level > 80:
# 高能量 - 快速闪烁
effect_color = ColorEffects.ColorStrobe(base_color, 100)
elif audio_level > 50:
# 中等能量 - 呼吸
effect_color = ColorEffects.ColorBreath(base_color, 500)
elif audio_level > 20:
# 低能量 - 缓慢三角波
effect_color = ColorEffects.ColorTriangle(base_color, 2000)
else:
# 静音 - 暗淡呼吸
effect_color = ColorEffects.ColorBreathLowBound(base_color, 32, 4000)
MatrixOS.LED.Fill(effect_color)
MatrixOS.LED.Update()
MatrixOS.SYS.DelayMs(50)
music_visualizer()
基于时间的颜色区域
def time_zones():
"""不同网格区域的不同效果"""
while True:
current_time = MatrixOS.SYS.Millis()
# 顶部区域：彩虹
for x in range(8):
for y in range(2):
offset = x * 100
rainbow = ColorEffects.Rainbow(4000, offset)
MatrixOS.LED.SetColor(Point(x, y), rainbow)
# 中间区域：呼吸颜色
colors = [Color(255, 0, 0), Color(0, 255, 0), Color(0, 0, 255)]
for x in range(8):
for y in range(2, 6):
color_idx = (x + y) % len(colors)
base_color = colors[color_idx]
breath_color = ColorEffects.ColorBreath(base_color, 2000, x * 200)
MatrixOS.LED.SetColor(Point(x, y), breath_color)
# 底部区域：锯齿白色
for x in range(8):
for y in range(6, 8):
brightness = ColorEffects.Saw(3000, x * 100)
white_color = Color(255, 255, 255).Scale(brightness / 255.0)
MatrixOS.LED.SetColor(Point(x, y), white_color)
MatrixOS.LED.Update()
MatrixOS.SYS.DelayMs(50)
time_zones()
Comments