来源：AI开发日志公众号专辑「Build Your Own X With AI」
原文链接：https://mp.weixin.qq.com/s?__biz=MzUxMjg3MjE2OA==&mid=2247486022&idx=1&sn=466a3e341c3b5b86ffab9b425bd925c0&chksm=f95c91c1ce2b18d7449ecb086e61bfdec04f24a8989c3cb6c082a9e15ea7469f52a6f657565e#rd

Excel Pixel Display

一个基于 Python 的图形显示系统，使用类似 Excel 的单元格网格作为像素显示屏。通过 Python 脚本控制，可以显示图片、播放视频和创建自定义动画。

特性

🎨 灵活的网格尺寸: 支持 1x1 到 4K (3840x2160) 的网格分辨率

🖼️ 图片显示: 支持 PNG, JPG, BMP, GIF 等常见图片格式

🎬 视频播放: 支持 MP4, AVI, MOV 等视频格式，可控制帧率

🎭 自定义动画: 通过 Python 脚本创建自定义动画效果

⚡ 高性能渲染: 自适应渲染模式，针对不同分辨率优化性能

📊 性能监控: 内置性能监控工具，实时查看 FPS 和内存使用

📝 脚本编辑器: 内置代码编辑器，支持语法高亮、自动执行和单步调试

♟️ 棋盘图案: 默认显示黑白棋盘图案，便于查看网格结构

🔧 易于使用: 简洁的 API 设计，快速上手

性能表现

分辨率

平均 FPS

适用场景

100x100

~67 FPS

小型动画、交互式应用

720p (1280x720)

~104 FPS

视频播放、实时动画

1080p (1920x1080)

~49 FPS

高清视频播放

4K (3840x2160)

~12 FPS

静态图片显示

详细性能分析请参考 性能优化文档。

安装

系统要求

Python 3.8 或更高版本

至少 2GB 可用内存（4K 分辨率需要 4GB+）

支持 Tkinter 的操作系统（Windows, macOS, Linux）

安装依赖

克隆仓库

git clone 

cd excel-pixel-display

创建虚拟环境（推荐）

python -m venv .venv

source .venv/bin/activate  # Linux/macOS

或

.venv\Scripts\activate  # Windows

安装依赖

pip install -r requirements.txt

依赖包

Pillow

图片处理

opencv-python

视频处理

numpy

数值计算

psutil

性能监控

快速开始

1. 启动应用程序

python src/main.py

1. 配置网格

点击菜单栏 “配置” -> “网格设置”

选择预设分辨率或自定义行列数

点击”确定”创建网格

1. 使用脚本编辑器

点击工具栏的”脚本编辑器”按钮或菜单 “脚本” -> “脚本编辑器”

在编辑器中编写或加载 Python 脚本

使用以下功能：

▶ 运行

执行脚本

⏸ 暂停

暂停执行

⏹ 停止

停止执行

⏭ 单步

单步执行（需启用单步模式）

自动执行

启用后脚本会按设定间隔自动重复执行

语法高亮

自动高亮 Python 关键字、字符串、注释等

1. 运行示例脚本

显示图片

运行示例脚本

python examples/display_image.py

或在应用程序中：

点击”加载脚本”按钮

选择 examples/display_image.py

脚本将自动执行

播放视频

python examples/play_video.py

自定义动画

python examples/custom_animation.py

手动解码 BMP

python examples/decode_bmp_manual.py

API 文档

DisplayAPI 类

用户脚本通过 display 对象访问所有功能。

设置像素颜色

设置单个像素

display.set_pixel(x, y, r, g, b)

批量设置像素

pixels = [

(0, 0, 255, 0, 0),  # 红色

(1, 0, 0, 255, 0),  # 绿色

(2, 0, 0, 0, 255),  # 蓝色

]

display.set_pixels(pixels)

加载和显示图片

加载图片（自动缩放到网格尺寸）

display.load_image(‘path/to/image.png’)

播放视频

播放视频（使用原始帧率）

display.play_video(‘path/to/video.mp4’)

播放视频（指定帧率）

display.play_video(‘path/to/video.mp4’, fps=30)

暂停视频

display.pause_video()

恢复播放

display.resume_video()

停止视频

display.stop_video()

辅助方法

获取网格尺寸

rows, cols = display.get_grid_size()

清空显示

display.clear_display()

获取视频信息

info = display.get_video_info()

if info:

print(f”FPS: {info[‘fps’]}”)

print(f”总帧数: {info[‘total_frames’]}”)

检查视频是否正在播放

if display.is_video_playing():

print(“视频正在播放”)

示例脚本

显示图片

examples/display_image.py

import time

加载并显示图片

display.load_image(‘examples/sample_image.png’)

等待 5 秒

time.sleep(5)

清空显示

display.clear_display()

播放视频

examples/play_video.py

import time

播放视频

display.play_video(‘examples/sample_video.mp4’, fps=30)

等待 10 秒

time.sleep(10)

暂停播放

display.pause_video()

time.sleep(2)

恢复播放

display.resume_video()

time.sleep(5)

停止播放

display.stop_video()

自定义动画

examples/custom_animation.py

import time

import math

获取网格尺寸

rows, cols = display.get_grid_size()

创建渐变动画

for frame inrange(100):

pixels = []

for y inrange(rows):

for x inrange(cols):

计算颜色（基于位置和时间）

r = int(255 * (x / cols))

g = int(255 * (y / rows))

b = int(255 * math.sin(frame * 0.1))

pixels.append((x, y, r, g, b))

批量更新像素

display.set_pixels(pixels)

控制帧率

time.sleep(1/30)  # 30 FPS

手动解码 BMP

examples/decode_bmp_manual.py

完全手动解析 BMP 文件格式，不使用 PIL 等图像库

展示如何从底层读取 BMP 文件头、信息头和像素数据

classBMPDecoder:

defdecode(self, filepath):

读取文件头（14 字节）

读取 DIB 信息头（40 字节）

读取像素数据（BGR 格式，从底部到顶部）

返回 RGB 像素数据

pass

解码并显示 BMP 文件

decoder = BMPDecoder(‘image.bmp’)

width, height, pixel_data = decoder.decode()

显示像素

pixels = [(x, y, r, g, b) for y inrange(height)

for x inrange(width)]

display.set_pixels(pixels)

项目结构

excel-pixel-display/

├── src/

│   ├── core/              # 核心模块

│   │   ├── cell_grid.py           # 单元格网格

│   │   ├── display_controller.py  # 显示控制器

│   │   ├── color_mapper.py        # 颜色映射

│   │   └── performance_monitor.py # 性能监控

│   ├── media/             # 媒体处理

│   │   ├── image_loader.py        # 图片加载

│   │   └── video_player.py        # 视频播放

│   ├── script/            # 脚本引擎

│   │   ├── engine.py              # 脚本引擎

│   │   └── api.py                 # 用户 API

│   ├── ui/                # 用户界面

│   │   ├── main_window.py         # 主窗口

│   │   └── config_dialog.py       # 配置对话框

│   └── main.py            # 程序入口

├── tests/                 # 测试

│   ├── test_cell_grid.py

│   ├── test_display_controller.py

│   ├── test_image_loader.py

│   ├── test_video_player.py

│   ├── test_script_engine.py

│   └── test_performance.py

├── examples/              # 示例脚本

│   ├── display_image.py

│   ├── play_video.py

│   ├── custom_animation.py

│   └── benchmark_performance.py

├── docs/                  # 文档

│   ├── PERFORMANCE_OPTIMIZATION.md

│   ├── ERROR_HANDLING.md

│   └── ERROR_HANDLING_SUMMARY.md

├── requirements.txt       # 依赖列表

└── README.md             # 本文件

性能优化

自适应渲染模式

系统会根据网格尺寸自动选择最优的渲染模式：

图像模式

用于大网格（≥100x100），使用 PIL Image 直接操作像素

矩形模式

用于小网格（<100x100），使用 Tkinter Canvas 绘制矩形

批量更新优化

使用批量更新 API 可以显著提升性能：

不推荐：逐个更新（慢）

for x inrange(width):

for y inrange(height):

display.set_pixel(x, y, r, g, b)

推荐：批量更新（快）

pixels = [(x, y, r, g, b) for x inrange(width) for y inrange(height)]

display.set_pixels(pixels)

性能监控

使用内置的性能监控工具：

from src.core.performance_monitor import PerformanceMonitor

monitor = PerformanceMonitor()

for frame in frames:

monitor.start_frame()

渲染帧

display.update_frame(frame)

monitor.end_frame()

打印统计信息

print(monitor.get_stats_summary())

详细信息请参考 性能优化文档。

测试

运行所有测试

运行所有单元测试

python -m pytest tests/ -v

运行性能测试

python -m pytest tests/test_performance.py -v

运行基准测试

python examples/benchmark_performance.py

测试覆盖率

项目包含以下测试：

✅ 单元格网格测试

✅ 显示控制器测试

✅ 图片加载器测试

✅ 视频播放器测试

✅ 脚本引擎测试

✅ 性能测试

✅ 内存泄漏检测

错误处理

系统提供了完善的错误处理机制：

文件加载错误

友好的错误提示，说明可能的原因

脚本执行错误

显示详细的错误信息和堆栈跟踪

性能警告

当 FPS 过低或内存使用过高时发出警告

详细信息请参考 错误处理文档。

常见问题

Q: 为什么 4K 分辨率下帧率很低？

A: 4K 分辨率包含 830 万像素，渲染需要大量计算。系统已经过优化，可以达到约 12 FPS，适合静态图片显示。如需播放视频，建议使用 720p 或 1080p 分辨率。

Q: 如何提高视频播放性能？

A:

降低目标分辨率（推荐 720p）

降低视频帧率（如 24 或 30 FPS）

关闭其他高负载应用

使用批量更新 API

Q: 内存使用过高怎么办？

A:

降低网格分辨率

避免长时间运行

定期清空显示：display.clear_display()

使用性能监控工具检测内存泄漏

Q: 如何创建自己的脚本？

A:

创建一个 .py 文件

使用 display 对象调用 API

在应用程序中加载脚本

参考 examples/ 目录中的示例

贡献

欢迎贡献代码、报告问题或提出建议！

开发指南

Fork 本仓库

创建特性分支：git checkout -b feature/your-feature

提交更改：git commit -am ‘Add some feature’

推送到分支：git push origin feature/your-feature

提交 Pull Request

代码规范

遵循 PEP 8 代码风格

添加必要的注释和文档字符串

编写单元测试

确保所有测试通过

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

致谢

Pillow: 强大的图片处理库

OpenCV: 优秀的计算机视觉库

Tkinter: Python 内置的 GUI 框架

联系方式

如有问题或建议，请通过以下方式联系：

提交 Issue

发送 Pull Request

享受像素艺术的乐趣！ 🎨✨