JoyD/Windows/CS/Framework4.0/XCamera/使用说明.md

# 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区域数量
- 检查系统资源使用情况

## 技术支持

如有问题，请参考示例配置文件和测试程序进行调试。确保所有依赖项都已正确安装。