第 05 讲：阿加犀 AidCV 图像处理加速与 OpenCV 一致开发实战

一、端侧视觉处理的渲染困境

1.1 Web 桌面为什么不能直接用 OpenCV 显示

前四讲我们已经把"模型从哪来、怎么在 NPU 上跑"这条链路打通了。但还有一个绕不开的问题没解决：图像从哪来，框又画在哪？很多初学者的第一反应是用 OpenCV 那套 cv2.imshow() 把结果显示出来------在普通 Ubuntu 桌面上这没问题，但在 AidLux 上会撞墙。

原因在于 AidLux 的 Web 桌面是基于网页渲染的交互界面，而不是传统的 X11/本地桌面。OpenCV 的 imshow 依赖本地 GUI 后端（如 GTK、Qt），在网页渲染环境里根本没有这个"窗体"，调用要么报错、要么静默无效果。我在带新人时见过不止一个人卡在这里一下午：代码逻辑全对，就是看不到画面，最后发现是"显示"这步从根上就不适用。

这不是 OpenCV 的锅，而是运行环境的差异。AidLux 提供了一条专门的解法：AidCV。它既解决了"怎么显示"，也顺带解决了"怎么加速"和"怎么采相机"。

1.2 一个真实场景：实时检测怎么把框画出来

把问题说具体一点。假设你已经用第 02、04 讲跑通了一个 YOLOv5 的 QNN 模型，现在想做"相机实时检测"：相机每一帧进来 → 前处理 resize → 喂给模型推理 → 后处理得到框 → 把框画回原图 → 显示出来。最后一步"显示出来"，在 AidLux 上就必须走 AidCV 的渲染通道，否则你只能在板子上把结果存成图片、再手动下载回电脑看------那还叫什么"实时"。

所以 AidCV 解决的其实是端侧视觉工程里最不起眼、却最致命的一公里：让"处理完的图像"能实时、就地、可视地呈现出来。它和 AidLite（推理）、AidStream（视频管线，第 06 讲）共同构成工具链的视觉能力层。

1.3 AidCV 的定位：给 OpenCV 代码一个"能跑的家"

AidCV 是 AidLux 上的图像处理加速组件，它的核心卖点可以一句话概括：提供与 OpenCV 一致的 API，并扩展相机采集与 Web 桌面渲染能力。一致到什么程度？你几乎可以把已有的 OpenCV 代码原样搬过来，只改一行导入，就能在 AidLux 上跑，而且渲染能直接投到 Web 桌面。

这对开发者是巨大的减负：你不必为了换个平台去学一套全新的图像 API，也不必为了"显示"去研究网页前端。OpenCV 怎么写，AidCV 就怎么写，只是在 AidLux 环境里它帮你把底层渲染和相机接好了。

1.4 本讲目标与硬件准备

读完本讲，你应该能：第一，用 AidCV 的兼容写法写一份"和 OpenCV 几乎一样"的图像处理代码；第二，在犀牛派上打开 USB 或 MIPI 相机、实时读帧；第三，把画面渲染到 Web 桌面窗口；第四，把第 02 讲/YOLO 检测模型接进来，做出"实时画框"的最小闭环。

硬件准备：完成环境搭建的犀牛派 A1（或 X1），aid-pkg installed 能看到 aidcv。相机用 USB 摄像头最方便验证，MIPI 相机则更贴近真实产品形态（工业相机、车载相机等）。本讲以犀牛派 A1 主演示，X1 给出预期差异；代码以 Python 为主。

---

二、AidCV 与 OpenCV 的关系

2.1 什么是一致 API（compatible API）

"与 OpenCV 一致"不是宣传话术，而是工程上的"接口兼容"：AidCV 把 OpenCV 最常用的那些函数（读图、resize、色彩空间转换、画框、文字、窗口等）做了同名实现，让你的代码在导入层面几乎无感切换。你写的 cv2.imread、cv2.resize、cv2.rectangle、cv2.putText，在 AidCV 下都能用，只是底层实现换成了适配 AidLux 的那一套。

这样做的最大价值是迁移成本趋近于零：你在 x86 上用 OpenCV 写的算法原型，到 AidLux 上不用重写图像处理部分，只换导入方式即可。对"先笔记本验证、再上板部署"的工作流尤其友好------这正是本系列一直强调的"验证与部署解耦"在视觉层的落地。

2.2 import aidcv as cv2 的兼容写法原理

AidCV 提供了一套兼容写法，让同一份代码在"有 AidCV 的环境"和"纯 OpenCV 环境"之间自动切换：

try:
    import aidcv as cv2      # 在 AidLux 上用 AidCV（带 Web 桌面渲染+相机）
except ImportError:
    import cv2               # 在普通环境回退到原生 OpenCV

这段 try/except 是 AidCV 使用的标准起手式，它的妙处在于"一份代码，两处可跑"：在 AidLux 板子上，aidcv 存在，代码走 AidCV 分支，渲染能投 Web 桌面；在你自己的开发机（只有 OpenCV）上，aidcv 导入失败，自动回退到原生 OpenCV，本地照样能调。等你把原型在笔记本上验证好，上板几乎不改。

记住这个写法，后面所有涉及图像处理的代码我都用 cv2 这个别名，既代表原生 OpenCV，也代表 AidCV------语义统一，不纠结。

2.3 Web 桌面端口渲染：namedWindow(port=...)

AidCV 解决"网页渲染环境里怎么显示"的关键，是给 namedWindow 增加了一个 port 参数，用来指定把窗口渲染到 Web 桌面的哪个端口。大致写法是：

import aidcv as cv2
cv2.namedWindow("preview", cv2.WINDOW_NORMAL, port=12345)  # 指定 Web 桌面渲染端口
# 之后 cv2.imshow("preview", frame) 就会把画面投到 Web 桌面对应窗口

port 的存在，让"显示"这件事从"依赖本地 GUI"变成"投到网页可访问的渲染通道"。你在浏览器打开 AidLux Web 桌面时，就能看到这个实时画面。具体端口取值与 Web 桌面的映射关系，以 AidCV 当前版本的说明为准，但"用 namedWindow 的 port 参数"这套机制是固定的。

一个实用建议：给不同用途的画面分配不同窗口名和端口，方便在 Web 桌面上同时观察"原始帧""预处理后""检测画框后"多个视图，调试时能一眼看出是哪一步出了问题。

2.4 扩展能力：MIPI 相机采集与 AI 扩展

除了"渲染"，AidCV 另一大块能力是相机采集 ，尤其是 MIPI 相机------这是端侧视觉产品的主流输入（工业相机、车载环视、机器人视觉都走 MIPI）。在普通 Linux 上接 MIPI 往往要折腾 V4L2 和厂商驱动，AidCV 把这部分封装了，让你用和 OpenCV 几乎一致的 VideoCapture 接口就能采 MIPI 帧。

此外 AidCV 还带"AI 扩展"能力，可与 AidLite 推理衔接。但本讲重点放在"采集 + 预处理 + 渲染 + 画框"这条主线上；更重的视频管线（RTSP 拉流、硬件编解码、多路拼接）留给第 06 讲 AidStream。AidCV 和 AidStream 是互补关系：AidCV 偏"单帧图像处理与相机/渲染"，AidStream 偏"视频流管线与编解码"。

2.5 一致 API 的边界：哪些能照搬、哪些要当心

"与 OpenCV 一致"是强卖点，但工程师要清楚它的边界，避免踩"以为完全等价"的坑。从实践经验看：

• 能放心照搬的 ：imread/imwrite/resize/cvtColor/rectangle/putText/VideoCapture/imshow/namedWindow 这些图像处理与采集渲染的核心函数，行为高度一致，几乎不用改。
• 要当心的 ：涉及 GUI 事件循环的细节（如 waitKey 的阻塞语义、窗口生命周期）、部分高级/冷门函数、以及和"网页渲染通道"强绑定的参数（如 namedWindow 的 port）------这些在原生 OpenCV 里没有对应物，必须按 AidCV 文档的约定来。
• 建议做法：把视觉算法主体写成"只依赖 OpenCV 通用函数"的纯函数（输入 numpy、输出 numpy），渲染和相机这两件"平台相关"的事单独用 AidCV 接口包一层。这样你的算法核心在任意平台可复用，平台差异被收敛到薄薄一层适配代码里。

---

三、环境调研：安装与验证

3.1 aid-pkg install aidcv-sdk

犀牛派 A1/X1 预装的 AidLux SDK 通常已包含 AidCV，可跳过安装。若未预装或需更新，用包管理器安装：

sudo aid-pkg update
sudo aid-pkg install aidcv-sdk

aidcv-sdk 是 AidCV 的包名，安装后 Python 里就能 import aidcv。和第 01 讲强调的一致：装完用 aid-pkg installed 看一眼版本，确认装上了。

3.2 预装验证

验证 AidCV 是否就绪，最直观的方式是跑一段最小导入 + 渲染测试：

try:
    import aidcv as cv2
    print("AidCV 可用:", cv2.__name__)
except ImportError:
    import cv2
    print("回退原生 OpenCV:", cv2.__name__)

能打印出 AidCV 可用 说明 AidCV 分支生效。如果你在板子上看到的是"回退原生 OpenCV"，说明 aidcv 没装上或不在 Python 路径里，先回去装包。

3.3 兼容性与支持情况

根据 AidLux 官方说明，AidCV 在 Linux / AidLux OS 的 Python 环境下已提供支持；C++ 侧在规划中。所以本讲以 Python 为主，符合全系列"Python 为主、C++ 为辅"的约定。如果你后续要在 C++ 量产项目里用图像处理，需关注 AidCV C++ 的进展，或暂时用 OpenCV C++ 在 Linux 侧处理、再用 AidConnect（第 09 讲）把结果传回------不过那是后话。

---

四、操作步骤：相机采集 + Web 桌面渲染

下面以"USB 摄像头实时采集并渲染到 Web 桌面"为例，演示 AidCV 的实战流程。具体渲染端口与相机节点以你板子和 AidCV 版本为准，这里讲不变的流程逻辑。

4.1 USB / MIPI 相机接入

• USB 摄像头 ：插上后 AidLux 一般会自动识别为 /dev/videoX（X 从 0 开始）。用 ls /dev/video* 看有几个设备节点。USB 摄像头最方便验证，即插即用。
• MIPI 相机 ：接到板子的 MIPI-CSI 接口（具体排针/插槽以板型规格书为准），设备节点通常也是 /dev/videoX 形式，但索引可能与 USB 不同。MIPI 更贴近真实产品，但需要确认板子与相机模组的兼容性。

无论哪种，第一步都是确认设备节点编号------后面 VideoCapture 要填它。

4.2 打开相机读取帧

用和 OpenCV 一致的接口打开相机、循环读帧：

import aidcv as cv2

cap = cv2.VideoCapture(0)          # 0 对应 /dev/video0，按需改成你的节点
if not cap.isOpened():
    raise RuntimeError("相机打开失败，检查设备节点与权限")

while True:
    ret, frame = cap.read()
    if not ret:
        break
    # frame 就是一帧 BGR 图像，后续做预处理/推理/画框
    # cv2.imshow(...) 见 4.3

cap.read() 返回 (ret, frame)，和原生 OpenCV 完全一致------这就是"一致 API"的好处：你不用学新接口。读到的 frame 是 numpy 数组，可以直接喂给 AidLite 前处理。

4.3 在 Web 桌面开一个渲染窗口

把读到的帧实时显示出来，关键是 namedWindow 带上 port 参数，再用 imshow 投出去：

cv2.namedWindow("cam_preview", cv2.WINDOW_NORMAL, port=12345)
while True:
    ret, frame = cap.read()
    if not ret:
        break
    cv2.imshow("cam_preview", frame)   # 投到 Web 桌面对应窗口
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break
cap.release()

打开浏览器访问 AidLux Web 桌面，就能看到实时画面。第一次跑通这一步的爽感很强------你终于在板子上"看见"相机了，而不是只能存图下载。

4.4 实时预处理流水线（resize / 色彩空间 / 画框）

单纯显示还不够，真实应用要在帧上做文章。一个典型的实时预处理流水线：

def preprocess(frame, size=320):
    img = cv2.resize(frame, (size, size))   # 缩放到模型输入
    img = img.astype("float32") / 255.0     # 归一化
    return np.expand_dims(img, axis=0)       # NHWC

def draw_boxes(frame, boxes):
    for (x1, y1, x2, y2, score, cls) in boxes:
        cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
        cv2.putText(frame, f"{cls}:{score:.2f}", (x1, y1 - 6),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1)
    return frame

resize、rectangle、putText 都是 OpenCV 同名函数，AidCV 直接可用。注意 rectangle 的颜色在 BGR 顺序下是 (B, G, R)，绿框是 (0, 255, 0)------这个细节和原生 OpenCV 完全一致，不用特别记。

4.5 帧率预算：实时系统该怎么看"卡不卡"

"实时"不是一句空话，它背后是一条帧率预算：一帧从进来到显示，经历的相机采集、预处理、推理、渲染四段时间之和，必须小于等于 1 / 目标帧率。超出，就卡。所以判断"卡不卡"，不能靠感觉，要把每一段单独计时拆开看：

import time
def profile_frame(cap, interp, preprocess, infer, render):
    ret, frame = cap.read(); t0 = time.perf_counter()
    inp = preprocess(frame);                 t1 = time.perf_counter()
    out = infer(interp, inp);                t2 = time.perf_counter()
    disp = render(frame, out);               t3 = time.perf_counter()
    cv2.imshow("p", disp);                   t4 = time.perf_counter()
    print(f"采:{t1-t0:.1f} 预处理:{t2-t1:.1f} 推理:{t3-t2:.1f} 渲染:{t4-t3:.1f} ms")

一旦某一段（通常是推理或 CPU 预处理）占比过高，你就有明确方向去优化它。另一个实时系统的关键决策是丢帧策略：当某一帧推理来不及，是"排队等它算完"还是"直接跳过这一帧、保延迟"？多数实时检测选后者------宁可偶发少检一帧，也不要让延迟累积。把这套预算和策略想清楚，你的实时应用才立得住。

---

五、关键代码：AidCV 与 AidLite 串联

5.1 兼容导入写法（贯穿全讲）

所有图像相关代码，统一以这段起手：

try:
    import aidcv as cv2      # AidLux 上走 AidCV（渲染+相机）
except ImportError:
    import cv2               # 开发机回退原生 OpenCV
import numpy as np

后面凡是用到 cv2.xxx，都按"可能是 AidCV、也可能是 OpenCV"来理解，不再区分。这保证了你的一份视觉代码，在笔记本和板子上都能跑。

5.2 相机回调采集

除了 cap.read() 的阻塞式循环，AidCV 也适合做"边采边处理"的流式循环（严格说仍是主循环里读帧，但逻辑上等价于回调式流水线）。核心是把"读一帧 → 处理一帧 → 显示一帧"压进一个紧凑循环：

cap = cv2.VideoCapture(0)
cv2.namedWindow("detect", cv2.WINDOW_NORMAL, port=12345)
while True:
    ret, frame = cap.read()
    if not ret:
        continue
    # 下面接 5.4 的推理与画框
    disp = process_frame(frame)     # 处理 + 画框
    cv2.imshow("detect", disp)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break
cap.release()

这个循环就是实时视觉应用的骨架。它的瓶颈通常不在"读帧"或"显示"，而在"推理"------所以后面要把模型推理做成高效的 AidLite 调用，且尽量复用同一个 interpreter，避免每帧重建。

5.3 预处理：resize / 色彩 / 画框

前处理要把相机帧变成模型要的输入。注意两点：一是 色彩空间 ，相机读出来是 BGR，很多模型训练用的是 RGB，必要时 cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)；二是 布局 ，AidLite 默认 NHWC（第 02 讲 3.7 强调过），前处理最后要扩成 [1,H,W,3]。

def to_model_input(frame, size=320):
    img = cv2.resize(frame, (size, size))
    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) if USE_RGB else img
    img = img.astype("float32") / 255.0
    return np.expand_dims(img, axis=0)   # NHWC

画框则在推理之后，把检测框映射回原始帧分辨率再画，否则框会落在缩放后的小图上、对不上原画面。坐标映射是实时检测最容易写错的一步：模型输出的是基于输入尺寸（如 320×320）的框，要等比放大回相机帧的真实尺寸。

5.4 对接第 02 讲检测模型做实时画框

把前面几讲的积木拼起来：用第 03 讲的可参数化 build_interpreter 建好 YOLO 的 QNN interpreter，在每帧里做"前处理 → set_input → invoke → 取输出 → 后处理解码 → 画框 → 渲染"。最小拼接示意：

from infer_core import build_interpreter   # 第03讲封装
import numpy as np, time

interp = build_interpreter("yolov5s_int8.amf", backend="qnn",
                           input_shapes=[[1, 320, 320, 3]],
                           output_shapes=[[1, 10, 10, 255],
                                          [1, 20, 20, 255],
                                          [1, 40, 40, 255]])

def process_frame(frame):
    h, w = frame.shape[:2]
    inp = to_model_input(frame, 320)
    interp.set_input_tensor(0, inp)
    interp.invoke()
    outs = [interp.get_output_tensor(i) for i in range(3)]
    boxes = decode_yolo(outs, orig_w=w, orig_h=h)   # 解码+NMS，坐标映射回原图
    return draw_boxes(frame, boxes)

注意 decode_yolo 里的坐标必须映射回 (w, h) 原图尺寸------这是 5.3 强调的坑。整套串起来，你就得到了一个"相机实时检测画框"的最小闭环：感知真正闭环了。

5.5 完整最小工程（循环 + 推理 + 渲染）

把上面的片段组织成一个可运行的最小工程（前后处理按你模型约定补齐）：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
AidCV + AidLite 实时检测画框最小工程（犀牛派 A1 / X1 通用）
流程：相机采集 -> 前处理 -> QNN 推理 -> 解码画框 -> Web 桌面渲染
"""
try:
    import aidcv as cv2
except ImportError:
    import cv2
import numpy as np
from infer_core import build_interpreter

CAM_ID   = 0
WIN_PORT = 12345
MODEL    = "yolov5s_int8.amf"

def main():
    interp = build_interpreter(MODEL, backend="qnn",
                              input_shapes=[[1, 320, 320, 3]],
                              output_shapes=[[1, 10, 10, 255],
                                             [1, 20, 20, 255],
                                             [1, 40, 40, 255]])
    cap = cv2.VideoCapture(CAM_ID)
    cv2.namedWindow("realtime_detect", cv2.WINDOW_NORMAL, port=WIN_PORT)
    print("按 q 退出")
    while True:
        ret, frame = cap.read()
        if not ret:
            continue
        disp = process_frame(interp, frame)   # 见 5.3 / 5.4
        cv2.imshow("realtime_detect", disp)
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break
    cap.release()
    interp.destroy()

if __name__ == "__main__":
    main()

把它放到 /home/aidlux/demo/，配合你的模型和 infer_core.py（第 03 讲模板），即可在 Web 桌面看到实时检测画面。这个工程同时是后面第 06 讲（AidStream 视频管线）和第 11 讲（综合实战）的视觉底座。

5.6 把预处理也交给硬件加速

讲到这里要提一个性能点：上面 to_model_input 里的 resize、cvtColor 都跑在 CPU 上。当相机帧率高、分辨率大时，CPU 预处理可能成为瓶颈，拖慢整体帧率。这也是 AidLux 工具链把"硬件加速预处理"当成重点的原因------AidCV 自身、以及第 06 讲 AidStream 的 GStreamer 插件（qtivtransform 等），都提供把 resize/色彩转换下沉到硬件的能力。

实际项目里，如果该段成为瓶颈（用第 02 讲 8.4 的基准循环分别计时即可定位），可以考虑把预处理挪到 AidStream 的硬件加速节点，或在 AidCV 支持的加速路径下调用。先把功能跑通、再按需把热点下沉到硬件，是性价比最高的优化顺序。

5.7 坐标映射的数学：为什么框会"飘"

5.3 提到"把框映射回原图"，这里把它的数学讲透，因为这是实时画框最经典的错位根因。假设模型输入是正方形 320×320，而相机原始帧是 W×H（比如 1280×720）。前处理把 W×H 缩放成 320×320，推理得到的框坐标 (x, y, w, h) 都是基于 320 这个尺度的。要画回原图，必须等比放大：

sx = W / 320.0      # 宽度方向缩放因子
sy = H / 320.0      # 高度方向缩放因子
x_o, y_o = int(x * sx), int(y * sy)
w_o, h_o = int(w * sx), int(h * sy)
cv2.rectangle(frame, (x_o, y_o), (x_o + w_o, y_o + h_o), (0, 255, 0), 2)

两个常见坑：第一，如果前处理用的是非等比 resize （直接把 W×H 拉成 320×320 而不变比例），那 sx 和 sy 不相等，框会被拉伸变形------要么用等比缩放并在短边补黑边（letterbox），要么分别用 sx、sy 映射；第二，如果用的是 letterbox 等比缩放，还要减去黑边偏移量，否则框整体偏移。把这套映射写成一个纯函数、单测几组坐标，能省掉大量"框飘来飘去"的调试时间。它和 5.3 的"画框在原始分辨率"是同一件事的两面：一处讲为什么，一处讲怎么做。

---

六、坑点

6.1 渲染端口被占用（port 冲突）

namedWindow(port=...) 的端口若被别的窗口或服务占用，渲染可能失败或画面打不开。对策：换一个未占用的端口，或先停掉占用该端口的进程；给不同窗口规划好端口号，避免随手填导致冲突。

6.2 设备节点 /dev/videoX 选错

插了多个相机（USB + MIPI，或多个 USB）时，/dev/videoX 的编号不一定符合直觉。现象是 VideoCapture(0) 打开的是错误的设备，或干脆打不开。对策：用 ls /dev/video* 列出所有节点，逐一尝试编号，或在代码里打印 cap.get(cv2.CAP_PROP_...) 确认分辨率等属性是否匹配预期设备。

6.3 Web 桌面权限与跨域

渲染到 Web 桌面涉及网页通道，偶尔会遇到权限或跨域相关的问题，导致画面不显示。对策：确认 AidCV 与 AidLux Web 桌面版本匹配，必要时重启 Web 桌面服务；权限问题参考官方 AidCV 文档的渲染通道说明。

6.4 与 OpenCV 的行为差异（部分函数不支持）

AidCV 追求"与 OpenCV 一致"，但不是 100% 函数级完全等价------个别冷门函数或参数在 AidCV 下可能未实现或行为略有差异。对策：核心的图像处理（imread/resize/cvtColor/rectangle/putText/VideoCapture/imshow）都很稳；若用到非常用函数报错，查 AidCV 文档确认支持范围，或把那一步用原生 OpenCV 思路改写。

---

七、验证：相机实时画面 + 检测画框

7.1 本地相机画面验证

先不接模型，单独跑"相机采集 + 渲染"（4.3 的循环），在 Web 桌面确认能看到流畅实时画面、无卡顿无黑屏。这一步排除了相机节点、端口、权限的问题，是后续接推理的前提。如果画面卡顿，先用这个最小循环定位是"采不全"还是"显示慢"。

7.2 检测画框验证

接上第 5.5 的完整工程，对着相机放几个能被模型识别的物体，确认：画面里出现绿色检测框、类别与置信度标注正确、框位置贴合物体、随物体移动实时更新。若框错位，优先查 5.3/5.4 提到的"坐标映射回原图"和"NHWC 布局"；若完全无框，先确认模型加载与推理在单图上已通（回到第 02、04 讲验证）。

7.3 A1 与 X1 上的差异

指标	犀牛派 A1（QCS6490）	犀牛派 X1（QCS8550）
单路相机实时检测帧率	可满足单路（以实测为准）	更高，从容（以实测为准）
多路相机/高分辨率	受限	更优
代码改动	零	零

同一份 AidCV + AidLite 工程，在两板间几乎免改；差异体现在 NPU 推理水位带来的帧率余量。具体帧率以你的真机实测为准，不要拿标称算力估算。

---

八、FAQ

Q1：AidCV 和 OpenCV 能混用吗？

推荐统一：在 AidLux 上就用 import aidcv as cv2 这一个入口，避免混用两套实现导致渲染/相机行为不一致。开发机回退原生 OpenCV 即可。

Q2：没有相机能用吗？

能用视频文件或图片代替 cap.read() 来验证渲染与推理链路；真机相机验证建议至少用一次 USB 摄像头确认节点与端口。

Q3：namedWindow 的 port 随便填吗？

不要随便填，避免与已有窗口/服务冲突（见 6.1）。规划好端口号，不同窗口用不同端口。

Q4：MIPI 相机和 USB 相机代码有区别吗？

采集接口都是 VideoCapture，区别主要在设备节点编号和硬件兼容性；MIPI 需确认板子与相机模组匹配。

Q5：为什么我的画面不显示？

按顺序查：AidCV 是否导入成功、namedWindow 的 port 是否被占用、相机节点是否正确、Web 桌面服务是否正常。多数情况是 port 或节点问题。

Q6：实时检测很卡，怎么优化？

先分别计时定位瓶颈：是相机读取、CPU 预处理，还是 NPU 推理。预处理瓶颈可下沉到硬件加速（5.6）；推理瓶颈可优化模型或参考第 12 讲调优。

Q7：AidCV 能做视频文件读写吗？

可以用一致的 VideoCapture/VideoWriter 思路处理视频文件；更重的视频管线（RTSP、硬件编解码）建议用第 06 讲 AidStream。

Q8：C++ 能用 AidCV 吗？

根据官方说明，AidCV 当前以 Linux/AidLux 的 Python 支持为主，C++ 规划中。C++ 量产项目可关注进展或暂用 OpenCV C++。

Q9：画面颜色和训练时不一致怎么办？

检查 BGR/RGB 转换：相机是 BGR，模型若用 RGB 要 cvtColor(COLOR_BGR2RGB)。颜色错会导致检测精度明显下降。

Q10：AidCV 和 AidStream 怎么选？

单帧图像处理、相机采集、Web 桌面渲染用 AidCV；视频流管线、RTSP、硬件编解码、多路拼接用 AidStream。两者互补，第 06 讲展开。

---

九、结论

本讲我们填上了端侧视觉工程的"最后一公里"：用 AidCV 的兼容写法，把 OpenCV 风格的代码无缝搬到了 AidLux 上，解决了 Web 桌面无法用 OpenCV 渲染的痛点，并能直接采集 USB/MIPI 相机、把画面实时投到 Web 桌面。更重要的是，我们把第 02、04 讲跑通的 YOLO 模型接了进来，做出了"相机实时检测画框"的最小闭环------感知，第一次在板子上真正闭环了。

AidCV 的价值，不在于它发明了多少新 API，而在于它"几乎没有新 API"：你用 OpenCV 的肌肉记忆就能写 AidLux 视觉代码，一份代码在笔记本和板子两端可跑。这种"低迁移成本"正是 AidLux 工具链一以贯之的设计哲学------让开发者把精力放在算法和业务上，而不是和平台差异搏斗。

下一讲我们离开"单帧"，进入"视频流"：用 AidStream 搭建带硬件编解码的视觉流水线，把 RTSP 拉流、NPU 检测、画框、推流串成一条生产级管线，并顺带解决多路视频这类进阶场景。那才是视觉能力真正走向产品化的台阶。

---

十、官方资源导航

资源	地址	用途
模型广场 Model Farm	https://aiot.aidlux.com/zh/models	下载已适配高通平台的模型
AidLux 开发者文档中心	https://docs.aidlux.com	SDK 接口与指南
AidLux 软件总览	https://developer.aidlux.com/software/aidlite	工具链组件总览
技术论坛	https://forum.aidlux.com	社区问答、案例
官网	https://www.aidlux.com	产品与方案
技术支持	support@aidlux.com	FAE 支持

本文 AidCV 的兼容写法、namedWindow 端口渲染、相机采集能力、支持情况等均来自 AidLux 官方文档；跨板帧率参考高通公开资料，精确值以真机实测为准。