Metadata-Version: 2.4
Name: epd-parser-plotter
Version: 0.1.2
Summary: EPD 地球物理观测数据解析与绘图工具
Author-email: WANG Qinglin <chd_wql@qq.com>
License: MIT License
Keywords: epd,geophysics,matplotlib,parser,plotter
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Description-Content-Type: text/markdown

# EPD 数据解析与绘图工具

地球物理观测台站 `.EPD` 格式数据文件的解析与可视化工具，使用 `uv` 管理。

## 功能特性

- **多测项解析**：自动识别任意数量的测项分量
- **跨日连续绘图**：合并多天数据为连续时间序列
- **缺测标注**：自动检测 NULL 值并用红色背景高亮
- **统计信息**：每个子图右上角显示均值/最大/最小/缺测点数
- **按天输出**：`--per-day` 模式逐天生成图像
- **中文显示**：自动检测 Windows 系统中文字体

## 安装

```bash
# 克隆项目后安装
uv sync
```

## 使用方法

### 基本绘图（交互显示）
```bash
uv run epd-plot --data-dir data
```

### 指定日期范围，保存为 PNG
```bash
uv run epd-plot --data-dir data --start 20260410 --end 20260415 --output output/week.png
```

### 仅绘制某一测项
```bash
uv run epd-plot --data-dir data --channels 4312 --output output/temp.png
```

### 按天逐日输出
```bash
uv run epd-plot --data-dir data --per-day --output-dir output/daily
```

### 列出目录中所有测项代码
```bash
uv run epd-plot --data-dir data --list-channels
```

## 命令行参数

| 参数 | 说明 | 默认值 |
|---|---|---|
| `--data-dir` | EPD 数据目录 | `./data` |
| `--start` | 起始日期 YYYYMMDD | 最早文件 |
| `--end` | 结束日期 YYYYMMDD | 最晚文件 |
| `--channels` | 测项代码列表 | 全部 |
| `--output` | 输出文件路径 | 交互显示 |
| `--output-dir` | 按天输出目录 | `./output` |
| `--per-day` | 每天一张图 | — |
| `--figsize W H` | 图像尺寸（英寸） | `16 8` |
| `--dpi` | 输出分辨率 | `150` |
| `--fill-null` | 显示缺测段红色背景标注 | 默认不显示 |
| `--list-channels` | 列出测项代码 | — |
| `-v` / `--verbose` | 详细日志 | — |

## EPD 文件格式

```
[日期] [台站码] [仪器码] [采样率码] [测项数量N] [测项代码×N] [数据值×(N×样本数)]
```

示例：
```
20260410 11074 X4X1DQYQ2698 01 02 4312 4112 38.7723 1.220 38.7708 1.219 ...
```

- 采样率码 `01` = 分钟值（每天 1440 点）
- 采样率码 `02` = 秒钟值（每天 86400 点）
- `NULL` / `-NULL` = 缺测

## 已知测项代码

| 代码 | 名称 | 单位 |
|---|---|---|
| 4112 | 静水位 | m |
| 4312 | 中层水温 | ℃ |

> 测项信息由内置配置文件字典 `DEFAULT_CHANNELS` 管理。未在字典中注册的测项代码将默认使用代码本身作为显示名称。

## 配置文件字典与扩展

可通过修改 `DEFAULT_CHANNELS` 字典动态添加新测项映射：

```python
from epd_parser_plotter import DEFAULT_CHANNELS

# 动态扩展/自定义测项配置字典
DEFAULT_CHANNELS["4212"] = {"name": "深层水温", "unit": "℃"}
```

## Python API

```python
from epd_parser_plotter import parse_epd_file, load_date_range, plot_components

# 解析单个文件
result = parse_epd_file("data/X4X1DQYQ2698_20260410.EPD")
print(result.metadata)  # EpdMetadata
print(result.df.head())  # DataFrame

# 加载日期范围
df, meta = load_date_range("data", start_date="20260410", end_date="20260420")

# 绘图
plot_components(df, title="观测数据", output_path="output/plot.png")
```

