车辆智能监测系统 - 技术文档1. 系统概述1.1 项目背景本系统是一套基于海康威视SDK和RKNN模型的车辆智能监测系统主要用于车辆年检场景中的黑烟检测和车牌识别。1.2 核心功能功能模块说明状态车牌识别通过海康SDK接收车牌抓拍报警✅ 已实现黑烟检测使用RKNN模型进行实时黑烟检测✅ 已实现预警记录检测到黑烟时保存预警信息和图片✅ 已实现配置管理Web前端配置摄像头参数和检测阈值✅ 已实现检测区域框选支持自定义黑烟检测区域✅ 已实现2. 技术架构2.1 系统架构图┌─────────────────────────────────────────────────────────────────┐ │ 前端页面 (HTML/JS) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ 摄像头配置 │ │ 检测参数配置 │ │ 预警记录展示 │ │ │ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │ └──────────┼─────────────────┼───────────────────┼───────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ FastAPI 后端服务 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ /config │ │ /start │ │ /alerts │ │ │ │ /set_roi │ │ /stop │ │ /plate │ │ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ └──────────┬─────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 核心业务模块 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ 海康SDK │ │ RKNN检测器 │ │ 视频流处理 │ │ │ │ 车牌识别 │ │ 黑烟检测 │ │ 帧读取/分析 │ │ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────────┘2.2 核心模块说明2.2.1 海康SDK模块功能通过SDK连接摄像头接收车牌识别报警信息关键APINET_DVR_Init()- 初始化SDKNET_DVR_Login_V40()- 设备登录NET_DVR_SetDVRMessageCallBack_V30()- 设置回调函数NET_DVR_StartListen_V30()- 启动监听2.2.2 RKNN黑烟检测器功能使用RKNN模型进行实时黑烟检测关键流程模型初始化 (SmokeDetector.init())图像预处理 (preprocess())模型推理 (rknn.inference())后处理与NMS (postprocess())2.2.3 视频流处理功能读取RTSP流每秒处理一帧优化策略设置缓冲大小为1帧固定帧率为1fps分辨率设置为640×4803. 配置说明3.1 默认配置# 摄像头配置cam1_ipxxx# 车牌识别摄像头cam2_ipXXX# 黑烟检测摄像头cam1_usernameadmincam1_passwordqXXXcam2_usernameadmincam2_passwordXXX# 检测参数smoke_confidence0.1# 黑烟检测置信度阈值model_namesmoke_0520.rknn# RKNN模型文件名# 检测区域默认画面中下部分占宽度80%高度40%roi_x164roi_y1192roi_x2576roi_y23843.2 配置文件管理配置文件路径camera_config.json{cam1_ip:192.168.40.210,cam1_username:admin,cam1_password:qaz135$,cam2_ip:192.168.40.211,cam2_username:admin,cam2_password:qaz135$,smoke_confidence:0.1,model_name:smoke_0520.rknn,roi_x1:64,roi_y1:192,roi_x2:576,roi_y2:384}4. 常见问题与解决方案4.1 SDK加载失败问题描述OSError: cannot open shared object file: No such file or directory原因分析LD_LIBRARY_PATH环境变量未正确设置SDK文件路径配置错误缺少HCNetSDKCom目录解决方案# 设置环境变量LinuxexportLD_LIBRARY_PATH/path/to/HCNetSDKV6.1.11.5:/path/to/HCNetSDKV6.1.11.5/HCNetSDKCom:$LD_LIBRARY_PATH代码层面处理ifsys.platform.startswith(linux):sdk_path./HCNetSDKV6.1.11.5_build20251204_ArmLinux64_ZH_20260320152158sdk_com_pathos.path.join(sdk_path,HCNetSDKCom)current_ld_pathos.environ.get(LD_LIBRARY_PATH,)new_ld_pathsdk_path:sdk_com_path:current_ld_path os.environ[LD_LIBRARY_PATH]new_ld_path4.2 登录异常问题描述int object is not subscriptable原因分析SDK登录函数返回值处理不当结构体初始化不完整解决方案# 正确初始化登录结构体login_infoNET_DVR_USER_LOGIN_INFO()ctypes.memset(ctypes.byref(login_info),0,ctypes.sizeof(login_info))login_info.sDeviceAddressc_char_p(ip.encode(gbk))login_info.sUserNamec_char_p(username.encode(gbk))login_info.sPasswordc_char_p(password.encode(gbk))login_info.wPortport# 正确处理返回值lUserIDHCNetSDK.NET_DVR_Login_V40(ctypes.byref(login_info),ctypes.byref(device_info))iflUserID0:error_codeHCNetSDK.NET_DVR_GetLastError()print(f登录失败错误码:{error_code})4.3 视频卡顿问题描述实时画面显示卡顿检测处理延迟严重原因分析RTSP缓冲过大帧率设置过高分辨率过高画面显示占用资源解决方案# 优化RTSP连接配置capcv2.VideoCapture(rtsp_url)cap.set(cv2.CAP_PROP_BUFFERSIZE,1)# 设置缓冲为1帧cap.set(cv2.CAP_PROP_FPS,1)# 设置帧率为1fps# 生产环境禁用画面显示parser.add_argument(--no-display,actionstore_true,help禁用画面显示)优化效果优化项优化前优化后效果缓冲大小默认1帧减少延迟帧率原始1fps降低CPU占用画面显示启用可选禁用减少内存占用4.4 置信度设置问题问题描述设置置信度为0.05仍无预警设置置信度为0.05出现大量误检原因分析置信度阈值设置过低导致误检模型后处理NMS阈值不合适解决方案场景推荐置信度说明严格检测0.3-0.5减少误检可能漏检平衡模式0.15-0.25兼顾检测率和准确率宽松检测0.05-0.1检测率高误检较多代码配置CONF_THRESH0.13# 黑烟检测置信度NMS_THRESH0.45# NMS非极大值抑制阈值4.5 模型文件路径问题问题描述模型文件不存在best_0513.rknn原因分析模型文件未放置在正确路径配置中的模型名称与实际文件名不一致配置文件未正确保存解决方案确保模型文件存在ls-la*.rknn# 确保输出中包含你要使用的模型文件正确操作流程前端输入模型名称 → 点击保存配置 → 点击启动系统检查配置保存# 后端会打印配置更新日志print(f[配置更新] 模型名称已更新为:{current_config[model_name]})# 启动时检查模型文件model_pathos.path.join(os.getcwd(),model_name)ifos.path.exists(model_path):print(f✅ 模型文件存在:{model_path})else:print(f⚠️ 警告模型文件不存在:{model_path})4.6 预警记录前端显示问题问题描述终端显示预警已保存前端页面未显示预警记录原因分析预警回调条件限制仅在有车牌时记录前端轮询接口异常数据格式不匹配解决方案# 修改预警回调逻辑无车牌也记录ifalert_callback:plate_numplate_snap[plate_num]ifplate_snap[plate_num]else无车牌alert_callback(plate_num,time.strftime(%Y-%m-%d %H:%M:%S))前端轮询逻辑// 每2秒轮询一次预警记录setInterval(async(){try{constresponseawaitfetch(/alerts);constdataawaitresponse.json();constalertListdocument.getElementById(alert-list);if(data.length0){alertList.innerHTMLdata.map(alertdiv classalert-item span classplate[预警]${alert.plate}/span span classtime${alert.time}/span /div).join();}else{alertList.innerHTMLdiv styletext-align:center; color:#999;暂无预警记录/div;}}catch(error){console.error(获取预警失败:,error);}},2000);4.7 检测框位置不正确问题描述配置的检测区域与实际画面不匹配检测框位置偏移原因分析摄像头分辨率与默认分辨率不一致坐标未进行缩放处理解决方案# 获取实际帧分辨率actual_height,actual_widthframe2.shape[:2]# 默认分辨率前端设置的基准分辨率default_width640default_height480# 计算缩放比例scale_xactual_width/default_width scale_yactual_height/default_height# 将ROI坐标缩放到实际分辨率x1_roi_scaledint(x1_roi*scale_x)y1_roi_scaledint(y1_roi*scale_y)x2_roi_scaledint(x2_roi*scale_x)y2_roi_scaledint(y2_roi*scale_y)# 确保坐标在有效范围内x1_roi_scaledmax(0,x1_roi_scaled)y1_roi_scaledmax(0,y1_roi_scaled)x2_roi_scaledmin(actual_width-1,x2_roi_scaled)y2_roi_scaledmin(actual_height-1,y2_roi_scaled)5. API接口说明5.1 配置管理接口方法说明/configGET获取当前配置/configPOST更新配置POST /config 请求体{cam1_ip:192.168.40.210,cam1_username:admin,cam1_password:qaz135$,cam2_ip:192.168.40.211,cam2_username:admin,cam2_password:qaz135$,smoke_confidence:0.1,model_name:smoke_0520.rknn}5.2 系统控制接口方法说明/startPOST启动系统/stopPOST停止系统/statusGET获取系统状态5.3 数据查询接口方法说明/plateGET获取最新车牌信息/alertsGET获取预警记录列表/set_roiPOST设置检测区域POST /set_roi 请求体{x1:64,y1:192,x2:576,y2:384}6. 部署说明6.1 环境要求项目要求操作系统Linux (RK3588)Python版本3.8依赖库opencv-python, rknn-toolkit2, fastapi, uvicornSDK版本HCNetSDKV6.1.11.5 (ARM Linux)6.2 依赖安装# 安装基础依赖pipinstallopencv-python numpy requests# 安装FastAPIpipinstallfastapi uvicorn# 安装RKNN Toolkit根据平台选择# RK3588平台pipinstallrknn-toolkit26.3 启动命令# 开发模式python app.py# 生产模式禁用调试uvicorn app:app--host0.0.0.0--port8000--workers16.4 项目结构./ ├── app.py # FastAPI主应用 ├── vehicle_inspection_sdk.py # 核心业务逻辑 ├── camera_config.json # 配置文件运行后生成 ├── HCNetSDKV6.1.11.5_.../ # 海康SDK目录 │ ├── libhcnetsdk.so │ └── HCNetSDKCom/ ├── templates/ │ └── index.html # 前端页面 ├── alerts/ # 预警图片保存目录 └── smoke_0520.rknn # RKNN模型文件7. 日志说明7.1 日志级别级别标识说明信息[I]正常运行信息警告[W]需要注意的情况错误[E]错误信息调试[DEBUG]详细调试信息7.2 关键日志示例[I] SDK初始化成功 [I] 登录设备 192.168.40.210 成功 [I] 已连接 1 个摄像头用于车牌抓拍 [I] 当前配置的模型名称: smoke_0520.rknn [I] ✅ 模型文件存在: /path/to/smoke_0520.rknn [I] 系统启动成功无显示模式黑烟置信度: 0.13 [黑烟检测] 检测区域内发现 2 个目标, 置信度: [0.85, 0.72] [I] ✅ 预警已保存: alerts/smoke_京A12345_20260520_112236.jpg8. 故障排查流程┌─────────────────────────────────────────────────────────────────┐ │ 故障排查流程图 │ ├─────────────────────────────────────────────────────────────────┤ │ 问题现象 │ │ │ │ │ ▼ │ │ 检查日志 │ │ │ │ │ ├── [E] 模型文件不存在 → 检查模型文件路径和名称 │ │ │ │ │ ├── [E] SDK加载失败 → 检查LD_LIBRARY_PATH │ │ │ │ │ ├── [E] 登录失败 → 检查摄像头IP/用户名/密码 │ │ │ │ │ └── [W] 黑烟检测器初始化失败 → 检查RKNN环境 │ │ │ │ 检查网络连接 │ │ │ │ │ ├── ping 摄像头IP → 网络连通性 │ │ └── 检查RTSP端口(554) → 端口是否开放 │ │ │ │ 检查配置文件 │ │ │ │ │ └── camera_config.json 是否存在且内容正确 │ │ │ │ 检查资源占用 │ │ │ │ │ ├── CPU占用 → top命令 │ │ └── 内存占用 → free命令 │ └─────────────────────────────────────────────────────────────────┘9. 版本历史版本日期变更说明V1.02026-05-10初始版本基础功能实现V1.12026-05-15添加SDK支持优化视频流处理V1.22026-05-20添加检测区域框选修复预警显示问题文档版本V1.0创建日期2026-05-21适用系统车辆智能监测系统