【电赛学习笔记】MaxiCAM 图像基础操作
前言
本文仅是对MaxiPy官方文档的整理与总结，自学请看官方文档，侵权即删MaixCAM MaixPy 快速开始 - MaixPy
下面给出「整段速查脚本」的逐行、逐参数超详细中文解释，方便你随时 Ctrl+F 定位查阅。
# -*- coding: utf-8 -*-
"""
MaixCAM MaixPy 图像基础速查
1. 创建/加载/保存
2. 颜色空间与格式转换
3. 几何变换
4. 绘图与文字
5. 与外部数据（bytes、OpenCV、文件）互转
"""-
整个文件是 UTF-8 编码的 Python 脚本，顶部 docstring 仅作说明，不会被 Python 执行。
from maix import image, display, app, time-
image：MaixPy 的图像核心模块，负责创建、绘图、格式转换等。 -
display：屏幕显示模块，可把 Image 对象刷到 LCD。 -
app：提供need_exit()检测按键/IDE 停止事件。 -
time：提供sleep_ms、ticks_ms等时间函数。
1. 创建图像
img = image.Image(320, 240, image.Format.FMT_RGB888)-
新建一张 320×240 的空白图。
-
image.Format.FMT_RGB888：24-bit RGB，每像素 3 字节（R,G,B 连续）。 -
若省略第三个参数，默认就是
FMT_RGB888。
# img = image.load("/root/test.jpg")
# img = image.load("/root/test.png")-
如果板子里已有
/root/test.jpg，取消注释即可把文件解码成 Image 对象。 -
支持 JPG、PNG；失败会返回
None，建议判断后再用。
# img.save("/root/out.jpg")-
把内存里的 Image 以 JPEG 编码保存到指定路径。
-
路径必须可写（SD 卡或
/root等）。
2. 摄像头实时流（已注释）
# cam = camera.Camera(640, 480, fps=60)
# img = cam.read()-
如想实时采集，取消注释即可：
-
640, 480：分辨率。 -
fps=60：强制 60 帧；省略则按内部规则自动选择。
-
-
cam.read()返回一帧图像的 Image 对象。
3. 基本属性
w, h, fmt = img.width(), img.height(), img.format()
print(f"{w}×{h} fmt={fmt}")-
width()、height()取宽高，单位像素。 -
format()返回枚举值，如FMT_RGB888、FMT_GRAYSCALE等。
4. 内部格式转换
gray = img.to_format(image.Format.FMT_GRAYSCALE)-
把原图转换成 8-bit 灰度图；返回新对象，原图不变。
jpeg = img.to_format(image.Format.FMT_JPEG)-
把原图压缩成 JPEG 内存块（用于网络或文件保存）；返回新 Image 对象。
5. 与 bytes 互转
b = img.to_bytes()-
把图像数据 完整拷贝 成
bytes对象，大小=width*height*像素字节数。 -
适合需要把图像发到 PC 或做协议打包。
img2 = image.from_bytes(w, h, fmt, b)-
反向操作：从 bytes 重建一张 独立 的 Image。
-
注意：
w, h, fmt必须与原始数据一致，否则会花屏。
6. 几何变换
resized = img.resize(160, 120)-
等比/非等比缩放；返回新对象。
-
也可传
keep_aspect_ratio=True保持宽高比。
cropped = img.crop(50, 50, 100, 100)-
从原图 (50,50) 开始，截取 100×100 区域；返回新对象。
rotated = img.rotate(90)-
顺时针旋转 90°；可选
rotate(180)、rotate(270)。 -
旋转后宽高会互换。
copied = img.copy()-
深拷贝，生成与原图完全相同但内存独立的新对象，防止后续绘图污染原图。
warp = img.affine([(0,0),(w,0),(0,h)], [(20,20),(w-20,20),(20,h-20)])-
三点映射三点，做仿射变换（旋转+缩放+平移）。
-
列表 1：原图三点坐标；列表 2：目标图三点坐标。
-
内部自动计算 2×3 仿射矩阵并输出新图像。
7. 绘图
7.1 颜色对象
red = image.Color.from_rgb(255, 0, 0)
green = image.Color.from_rgb(0, 255, 0)
blue = image.Color.from_rgb(0, 0, 255)
white = image.Color.from_rgb(255, 255, 255)-
from_rgb(r,g,b)生成 24-bit 颜色。 -
还有
from_rgba(r,g,b,a)带透明度。
7.2 画矩形
img.draw_rect(10, 10, 100, 80, red)-
(10,10) 左上角，宽 100，高 80，红色边框，线宽默认 1。
img.draw_rect(120, 10, 100, 80, red, thickness=-1)-
thickness=-1→ 实心填充。
7.3 画圆
img.draw_circle(200, 60, 30, green)-
圆心 (200,60)，半径 30，绿色边框。
7.4 画线
img.draw_line(10, 120, 100, 180, blue, thickness=2)-
起点 (10,120)，终点 (100,180)，蓝色，线宽 2。
7.5 画十字
img.draw_cross(150, 150, white, size=10)-
十字中心 (150,150)，
size=10→ 横竖各伸出 10 像素，线宽 1。
8. 文字
img.draw_string(10, 210, "Hello MaixPy", white, scale=2)-
(10,210) 左上角；
scale=2字体放大 2×2；white颜色。 -
字体默认内置英文 8×16；如需中文请看下两行注释。
8.1 中文/自定义字体（注释示例）
# image.load_font("sourcehansans", "/maixapp/share/font/SourceHanSansCN-Regular.otf", size=32)
# image.set_default_font("sourcehansans")-
从文件加载
.otf字体，注册名为"sourcehansans"，字号 32。 -
set_default_font让后续所有draw_string默认走该字体；也可单个调用传font=参数。
# img.draw_string(10, 180, "你好世界", white, font="sourcehansans")-
单独指定字体。
8.2 文字尺寸测量
# w, h = image.string_size("Hello MaixPy", scale=2)-
返回该字符串在当前字体/缩放下的像素宽高，用于居中、对齐。
9. 绘图叠加（贴图）
icon = image.Image(50, 50, image.Format.FMT_RGB888)
icon.draw_rect(0, 0, 50, 50, green, thickness=-1)
img.draw_image(260, 10, icon)-
先创建 50×50 绿色方块
icon。 -
draw_image(x,y,src)把icon贴到img的 (260,10) 位置。
10. 关键点 & 箭头
10.1 关键点
kpts = [50, 50, 150, 50, 100, 150]
img.draw_keypoints(kpts, red, size=8, thickness=1, fill=False)-
列表中每两个数字为一组坐标：[(50,50),(150,50),(100,150)]。
-
在每个坐标画小圆点；
size决定直径，thickness线宽，fill=False空心。
10.2 箭头
img.draw_arrow(100, 200, 200, 200, blue, thickness=2)-
起点 (100,200)，终点 (200,200)，蓝色箭头，线宽 2。
11. 显示到屏幕
disp = display.Display()
disp.show(img)-
Display()自动识别板载 LCD 分辨率并初始化。 -
show(img)立刻把整幅图刷到屏幕。
12. 主循环（可选）
# while not app.need_exit():
# time.sleep(1)-
在 MaixVision 或板子上按 Home/IDE 停止时，
app.need_exit()变为 True，循环退出。 -
如果只想静态图，可省略；若做实时视频，则放
cam.read()后面不断show()。
MaixPy 图像基础操作「一页通」
（把上面 24 个知识点浓缩成可直接 copy-paste 的「常用代码模板」+ 注释）
# -*- coding: utf-8 -*-
"""
MaixCAM MaixPy 图像基础速查
1. 创建/加载/保存
2. 颜色空间与格式转换
3. 几何变换
4. 绘图与文字
5. 与外部数据（bytes、OpenCV、文件）互转
"""
from maix import image, display, app, time
# ---------- 1. 创建图像 ----------
# 1.1 空白图
img = image.Image(320, 240, image.Format.FMT_RGB888) # RGB888 默认
# 1.2 从文件
# img = image.load("/root/test.jpg") or image.load("/root/test.png")
# 1.3 保存
# img.save("/root/out.jpg")
# ---------- 2. 摄像头实时流 ----------
# cam = camera.Camera(640, 480, fps=60)
# img = cam.read()
# ---------- 3. 基本属性 ----------
w, h, fmt = img.width(), img.height(), img.format()
print(f"{w}×{h} fmt={fmt}")
# ---------- 4. 格式转换 ----------
# 4.1 内部互转
gray = img.to_format(image.Format.FMT_GRAYSCALE)
jpeg = img.to_format(image.Format.FMT_JPEG)
# 4.2 与 bytes
b = img.to_bytes()
img2 = image.from_bytes(w, h, fmt, b) # 重新生成独立副本
# ---------- 5. 几何变换 ----------
resized = img.resize(160, 120) # 缩放
cropped = img.crop(50, 50, 100, 100) # 裁剪
rotated = img.rotate(90) # 顺时针 90°
copied = img.copy() # 深拷贝
# 仿射：三点对应三点
warp = img.affine([(0,0),(w,0),(0,h)], [(20,20),(w-20,20),(20,h-20)])
# ---------- 6. 绘图 ----------
# 6.1 颜色
red = image.Color.from_rgb(255, 0, 0)
green = image.Color.from_rgb(0, 255, 0)
blue = image.Color.from_rgb(0, 0, 255)
white = image.Color.from_rgb(255, 255, 255)
# 6.2 图形
img.draw_rect(10, 10, 100, 80, red) # 空心框
img.draw_rect(120, 10, 100, 80, red, thickness=-1) # 实心框
img.draw_circle(200, 60, 30, green)
img.draw_line(10, 120, 100, 180, blue, thickness=2)
img.draw_cross(150, 150, white, size=10)
# 6.3 文字
# 6.3.1 英文/默认字体
img.draw_string(10, 210, "Hello MaixPy", white, scale=2)
# 6.3.2 中文/自定义字体
# image.load_font("sourcehansans", "/maixapp/share/font/SourceHanSansCN-Regular.otf", size=32)
# image.set_default_font("sourcehansans")
# img.draw_string(10, 180, "你好世界", white, font="sourcehansans")
# ---------- 7. 绘图叠加 ----------
icon = image.Image(50, 50, image.Format.FMT_RGB888)
icon.draw_rect(0, 0, 50, 50, green, thickness=-1)
img.draw_image(260, 10, icon) # 把 icon 贴到 img 上
# ---------- 8. 关键点 ----------
kpts = [50, 50, 150, 50, 100, 150]
img.draw_keypoints(kpts, red, size=8, thickness=1, fill=False)
# ---------- 9. 箭头 ----------
img.draw_arrow(100, 200, 200, 200, blue, thickness=2)
# ---------- 10. 显示 ----------
disp = display.Display()
disp.show(img)
# ---------- 11. 主循环（可选，保持窗口） ----------
# while not app.need_exit():
# time.sleep(1)使用说明
-
把需要试的代码段取消注释即可运行。
-
所有绘图函数均返回新的 Image 对象（或原地修改），可按需
copy()保留原图。 -
大分辨率或高频调用时，避免频繁
to_bytes()，防止内存拷贝开销。