283 lines
7.9 KiB
Markdown
283 lines
7.9 KiB
Markdown
# XCamera库使用说明
|
||
|
||
## 项目结构
|
||
```
|
||
XCamera/
|
||
├── XCamera.sln # Visual Studio解决方案文件
|
||
├── XCamera.csproj # 项目文件
|
||
├── README.md # 项目说明文档
|
||
├── build.bat # 编译脚本（批处理）
|
||
├── build.ps1 # 编译脚本（PowerShell）
|
||
├── src/ # 源代码目录
|
||
│ ├── XCamera.cs # 主类，提供静态API
|
||
│ ├── XCameraManager.cs # 核心管理器
|
||
│ ├── Core/ # 核心功能
|
||
│ │ ├── ConfigurationManager.cs # 配置管理
|
||
│ │ ├── CameraConnectionManager.cs # 摄像头连接管理
|
||
│ │ ├── XCloudSdkWrapper.cs # SDK P/Invoke封装
|
||
│ │ └── XCloudSdkEnums.cs # SDK枚举定义
|
||
│ ├── Models/ # 数据模型
|
||
│ │ ├── LedColor.cs # LED颜色枚举
|
||
│ │ ├── LedState.cs # LED状态枚举
|
||
│ │ ├── LedRegion.cs # LED区域定义
|
||
│ │ ├── CameraConfig.cs # 摄像头配置
|
||
│ │ └── LedStatus.cs # LED状态信息
|
||
│ ├── Vision/ # 图像处理和LED检测
|
||
│ │ ├── ImageProcessor.cs # 图像处理器
|
||
│ │ └── LedDetector.cs # LED检测器
|
||
│ └── UI/ # 用户界面
|
||
│ └── RegionEditorForm.cs # 区域编辑器
|
||
├── config/ # 配置文件
|
||
│ └── sample_config.json # 示例配置文件
|
||
├── lib/ # 依赖库
|
||
│ └── XCloudSDK/ # XCloudSDK
|
||
│ ├── XCloudSDK.dll # SDK动态库
|
||
│ ├── XCloudSDK.lib # SDK静态库
|
||
│ └── include/ # SDK头文件
|
||
└── test/ # 测试程序
|
||
└── Program.cs # 控制台测试程序
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 编译项目
|
||
```bash
|
||
# 使用PowerShell脚本编译
|
||
powershell -ExecutionPolicy Bypass -File build.ps1
|
||
|
||
# 或使用批处理脚本
|
||
build.bat
|
||
```
|
||
|
||
### 2. 基本使用示例
|
||
```csharp
|
||
using System;
|
||
using XCamera;
|
||
|
||
class Program
|
||
{
|
||
static void Main()
|
||
{
|
||
// 1. 初始化
|
||
if (!XCamera.Initialize("config.json"))
|
||
{
|
||
Console.WriteLine("初始化失败");
|
||
return;
|
||
}
|
||
|
||
// 2. 启动摄像头
|
||
if (XCamera.StartCamera())
|
||
{
|
||
Console.WriteLine("摄像头启动成功");
|
||
|
||
// 3. 开始捕获图像（自动检测LED）
|
||
if (XCamera.StartCapture(1000)) // 1秒间隔
|
||
{
|
||
Console.WriteLine("开始捕获图像...");
|
||
|
||
// 4. 等待用户输入
|
||
Console.WriteLine("按任意键停止...");
|
||
Console.ReadKey();
|
||
|
||
// 5. 停止捕获
|
||
XCamera.StopCapture();
|
||
}
|
||
|
||
// 6. 停止摄像头
|
||
XCamera.StopCamera();
|
||
}
|
||
|
||
// 7. 关闭资源
|
||
XCamera.Shutdown();
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 事件驱动使用示例
|
||
```csharp
|
||
using System;
|
||
using XCamera;
|
||
|
||
class Program
|
||
{
|
||
static void Main()
|
||
{
|
||
// 订阅LED状态更新事件
|
||
XCamera.LedStatusUpdated += OnLedStatusUpdated;
|
||
XCamera.ConnectionStateChanged += OnConnectionStateChanged;
|
||
XCamera.ErrorOccurred += OnErrorOccurred;
|
||
|
||
// 初始化并启动
|
||
if (XCamera.Initialize("config.json"))
|
||
{
|
||
if (XCamera.StartCamera())
|
||
{
|
||
XCamera.StartCapture(1000);
|
||
|
||
// 运行10秒后停止
|
||
Thread.Sleep(10000);
|
||
|
||
XCamera.StopCapture();
|
||
XCamera.StopCamera();
|
||
}
|
||
}
|
||
|
||
XCamera.Shutdown();
|
||
}
|
||
|
||
static void OnLedStatusUpdated(object sender, List<LedStatus> statuses)
|
||
{
|
||
Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] LED状态更新:");
|
||
foreach (var status in statuses)
|
||
{
|
||
Console.WriteLine($" {status.RegionName}: {status.DetectedColor} {status.State} " +
|
||
$"{(status.IsBlinking ? "闪烁" : "")} 亮度:{status.Brightness} 置信度:{status.Confidence}%");
|
||
}
|
||
}
|
||
|
||
static void OnConnectionStateChanged(object sender, bool connected)
|
||
{
|
||
Console.WriteLine($"摄像头连接状态: {(connected ? "已连接" : "已断开")}");
|
||
}
|
||
|
||
static void OnErrorOccurred(object sender, string error)
|
||
{
|
||
Console.WriteLine($"错误: {error}");
|
||
}
|
||
}
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
配置文件使用JSON格式，包含摄像头连接信息和LED区域定义：
|
||
|
||
```json
|
||
{
|
||
"IpAddress": "192.168.100.10",
|
||
"TcpPort": 34567,
|
||
"HttpPort": 8888,
|
||
"OnvifPort": 8899,
|
||
"Username": "admin",
|
||
"Password": "",
|
||
"Channel": 1,
|
||
"LedRegions": [
|
||
{
|
||
"Id": "power_led",
|
||
"Name": "电源指示灯",
|
||
"X": 100,
|
||
"Y": 50,
|
||
"Width": 20,
|
||
"Height": 20,
|
||
"ExpectedColor": "Red",
|
||
"ColorTolerance": 30,
|
||
"MinBrightness": 100
|
||
},
|
||
{
|
||
"Id": "status_led",
|
||
"Name": "状态指示灯",
|
||
"X": 150,
|
||
"Y": 50,
|
||
"Width": 20,
|
||
"Height": 20,
|
||
"ExpectedColor": "Green",
|
||
"ColorTolerance": 30,
|
||
"MinBrightness": 100
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## API参考
|
||
|
||
### 主要方法
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `Initialize(configFilePath)` | 初始化库 |
|
||
| `SetConfigFile(configFilePath)` | 设置配置文件路径 |
|
||
| `StartCamera()` | 启动摄像头连接 |
|
||
| `StartCapture(intervalMs)` | 开始循环捕获图像 |
|
||
| `DetectLeds()` | 手动检测LED状态 |
|
||
| `GetLedStatuses()` | 获取LED状态 |
|
||
| `ShowRegionEditor()` | 显示区域编辑器 |
|
||
| `StopCapture()` | 停止捕获 |
|
||
| `StopCamera()` | 停止摄像头 |
|
||
| `Shutdown()` | 关闭并释放资源 |
|
||
|
||
### 事件
|
||
|
||
| 事件 | 描述 |
|
||
|------|------|
|
||
| `LedStatusUpdated` | LED状态更新事件 |
|
||
| `ConnectionStateChanged` | 连接状态变更事件 |
|
||
| `CaptureStateChanged` | 捕获状态变更事件 |
|
||
| `ErrorOccurred` | 错误事件 |
|
||
|
||
### LED状态信息
|
||
|
||
`LedStatus`类包含以下属性：
|
||
- `RegionId`: 区域ID
|
||
- `RegionName`: 区域名称
|
||
- `DetectedColor`: 检测到的颜色（Red/Yellow/Blue/Green/Unknown）
|
||
- `State`: LED状态（On/Off/Blinking/Unknown）
|
||
- `IsBlinking`: 是否闪烁
|
||
- `Brightness`: 亮度值（0-255）
|
||
- `Confidence`: 置信度（0-100%）
|
||
- `LastUpdateTime`: 最后更新时间
|
||
|
||
## 测试程序
|
||
|
||
运行测试程序来验证库的功能：
|
||
|
||
```bash
|
||
cd test
|
||
dotnet run
|
||
```
|
||
|
||
测试程序提供交互式菜单，可以测试所有功能：
|
||
|
||
```
|
||
功能菜单:
|
||
1. 初始化
|
||
2. 设置配置文件路径
|
||
3. 启动摄像头
|
||
4. 开始捕获图像
|
||
5. 检测LED灯状态
|
||
6. 查询灯的状态
|
||
7. 显示区域编辑器
|
||
8. 停止捕获
|
||
9. 停止摄像头
|
||
10. 更新IP地址
|
||
11. 保存配置
|
||
12. 显示状态
|
||
0. 退出
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **网络配置**: 确保摄像头IP地址正确，网络连接正常
|
||
2. **权限**: 确保有足够的权限访问摄像头
|
||
3. **配置文件**: LED区域坐标需要根据实际图像调整
|
||
4. **性能**: 建议捕获间隔不要设置得太短（建议≥500ms）
|
||
5. **资源释放**: 使用完毕后务必调用`Shutdown()`释放资源
|
||
|
||
## 故障排除
|
||
|
||
### 连接失败
|
||
- 检查IP地址和端口配置
|
||
- 确认摄像头网络连接正常
|
||
- 验证用户名和密码
|
||
|
||
### LED检测不准确
|
||
- 调整LED区域的坐标和大小
|
||
- 调整亮度阈值和颜色容差
|
||
- 确保图像质量良好
|
||
|
||
### 性能问题
|
||
- 增加捕获间隔时间
|
||
- 减少LED区域数量
|
||
- 检查系统资源使用情况
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请参考示例配置文件和测试程序进行调试。确保所有依赖项都已正确安装。 |