# ComtradeLib

**Repository Path**: birdman1992/comtrade-lib

## Basic Information

- **Project Name**: ComtradeLib
- **Description**: No description available
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# COMTRADE Library

一个基于 Qt/C++ 的 COMTRADE 格式读写库，用于读取和写入符合 IEEE C37.111-1999 标准的 COMTRADE 文件。

## 特性

- ✅ 支持 COMTRADE 1999 标准
- ✅ 支持 ASCII 和二进制数据格式
- ✅ 支持模拟量通道（暂不支持数字量通道）
- ✅ 自动进行原始值与物理值之间的转换
- ✅ 基于 Qt 框架，易于集成到 Qt 应用程序中
- ✅ 使用 CMake 构建系统

## 系统要求

- Qt 5 或 Qt 6
- CMake 3.16 或更高版本
- 支持 C++17 的编译器

## 构建

### Linux/macOS

```bash
mkdir build
cd build
cmake ..
cmake --build .
```

### Windows

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
```

## 安装

```bash
cmake --install . --prefix /path/to/install
```

## 使用示例

### 读取 COMTRADE 文件

```cpp
#include <comtrade/reader.h>
#include <QDebug>

// 读取 COMTRADE 文件（自动查找 .cfg 和 .dat 文件）
Comtrade::ComtradeFile file = Comtrade::Reader::read("path/to/file");

// 输出基本信息
qDebug() << "站点名称:" << file.stationName();
qDebug() << "记录设备ID:" << file.recordingDeviceId();
qDebug() << "通道数量:" << file.channelCount();
qDebug() << "采样率:" << file.samplingRate() << "Hz";
qDebug() << "采样点数:" << file.numberOfSamples();

// 遍历所有通道
for (int i = 0; i < file.channelCount(); ++i) {
    const Comtrade::Channel* channel = file.channel(i);
    if (channel) {
        qDebug() << "通道" << i << ":" << channel->id();
        qDebug() << "  相位:" << channel->phase();
        qDebug() << "  单位:" << channel->units();
        qDebug() << "  数据点数:" << channel->dataPoints().size();

        // 访问数据点
        const auto& dataPoints = channel->dataPoints();
        for (const auto& point : dataPoints) {
            qDebug() << "    时间:" << point.timestamp()
                     << "us, 值:" << point.value();
        }
    }
}
```

### 写入 COMTRADE 文件

```cpp
#include <comtrade/writer.h>
#include <comtrade/comtrade.h>
#include <comtrade/channel.h>
#include <comtrade/datapoint.h>
#include <QDateTime>
#include <QtMath>

// 创建 COMTRADE 文件对象
Comtrade::ComtradeFile file;
file.setStationName("测试站点");
file.setRecordingDeviceId("设备001");
file.setRevisionYear(1999);
file.setLineFrequency(50.0);  // 50Hz 工频
file.setSamplingRate(4000.0); // 4kHz 采样率
file.setFileType(Comtrade::FileType::ASCII);
file.setStartTime(QDateTime::currentDateTime());
file.setTriggerTime(QDateTime::currentDateTime());

// 创建通道
Comtrade::Channel channel;
channel.setNumber(1);
channel.setId("IA");
channel.setPhase("A");
channel.setUnits("kA");
channel.setMultiplier(0.001);  // 转换系数 a
channel.setOffset(0.0);        // 偏移量 b
channel.setPrimary(1.0);
channel.setSecondary(1.0);
channel.setPrimarySecondary("P");

// 添加数据点（示例：正弦波）
int numSamples = 200;
double samplingInterval = 1000000.0 / file.samplingRate(); // 微秒

for (int i = 0; i < numSamples; ++i) {
    double timestamp = i * samplingInterval;
    double value = 10.0 * qSin(2.0 * M_PI * 50.0 * timestamp / 1000000.0);
    channel.addDataPoint(Comtrade::DataPoint(timestamp, value));
}

file.addChannel(channel);
file.setAnalogChannelCount(1);
file.setDigitalChannelCount(0);
file.setTotalChannels(1);
file.setNumberOfSamples(numSamples);

// 写入文件
if (Comtrade::Writer::write(file, "output/test")) {
    qDebug() << "COMTRADE 文件写入成功";
} else {
    qDebug() << "COMTRADE 文件写入失败";
}
```

## COMTRADE 格式说明

COMTRADE (Common Format for Transient Data Exchange) 是 IEEE C37.111 标准定义的电力系统暂态数据交换格式。该格式广泛应用于电力系统的故障录波、保护装置测试等领域。

COMTRADE 文件由两个主要文件组成：
- **.cfg 文件**：配置文件，包含通道信息、采样率、时间等元数据
- **.dat 文件**：数据文件，包含实际的采样数据（支持 ASCII 和二进制格式）

本库实现了 COMTRADE 1999 标准，支持模拟量通道的读写。

### 数据转换

COMTRADE 文件中存储的是原始值（raw value），需要通过转换公式转换为物理值：

```
物理值 = a × 原始值 + b
```

其中：
- `a` 是乘数（multiplier）
- `b` 是偏移量（offset）

本库自动处理这种转换，`DataPoint` 中存储的是转换后的物理值。

## API 参考

### 主要类

#### `Comtrade::ComtradeFile`
表示一个完整的 COMTRADE 文件，包含所有元数据和通道数据。

主要方法：
- `addChannel(const Channel& channel)` - 添加通道
- `channel(int index)` - 获取指定索引的通道
- `channelCount()` - 获取通道数量
- 各种 getter/setter 方法用于访问元数据

#### `Comtrade::Channel`
表示一个模拟量通道，包含通道元数据和数据点。

主要方法：
- `addDataPoint(const DataPoint& point)` - 添加数据点
- `dataPoints()` - 获取所有数据点
- `rawToPhysical(double raw)` - 原始值转物理值
- `physicalToRaw(double physical)` - 物理值转原始值

#### `Comtrade::DataPoint`
表示一个数据点（时间-数值对）。

成员：
- `timestamp()` - 时间戳（微秒）
- `value()` - 物理值

#### `Comtrade::Reader`
用于读取 COMTRADE 文件的静态类。

主要方法：
- `static ComtradeFile read(const QString& basePath)` - 读取文件
- `static ComtradeFile readFromFiles(const QString& cfgPath, const QString& datPath)` - 从指定路径读取

#### `Comtrade::Writer`
用于写入 COMTRADE 文件的静态类。

主要方法：
- `static bool write(const ComtradeFile& file, const QString& basePath)` - 写入文件
- `static bool writeToFiles(const ComtradeFile& file, const QString& cfgPath, const QString& datPath)` - 写入到指定路径

## 在 CMake 项目中使用

安装库后，在你的 CMake 项目中添加：

```cmake
find_package(comtrade REQUIRED)
target_link_libraries(your_target PRIVATE comtrade::comtrade)
```

## 项目结构

```
comtrade-lib/
├── CMakeLists.txt          # CMake 配置文件
├── README.md               # 本文件
├── LICENSE                 # 许可证文件
├── cmake/                  # CMake 配置模块
│   └── comtradeConfig.cmake.in
├── include/                # 头文件目录
│   └── comtrade/
│       ├── types.h         # 类型定义
│       ├── datapoint.h     # 数据点类
│       ├── channel.h       # 通道类
│       ├── comtrade.h      # COMTRADE 文件类
│       ├── reader.h        # 读取器类
│       └── writer.h        # 写入器类
└── src/                    # 源文件目录
    ├── datapoint.cpp
    ├── channel.cpp
    ├── comtrade.cpp
    ├── reader.cpp
    └── writer.cpp
```

## 许可证

请参阅 LICENSE 文件。

## 贡献

欢迎提交问题报告和拉取请求。