Warning
本项目是物理实验的一次性配套工具，不再额外维护，也不接受 Issue 和 Pull Request。
本实验通过电流场模拟静电场，利用导体纸上的稳恒电流场来模拟真空中的静电场分布。实验分为两部分：
- 实验一（同轴电缆）：在印有同心圆极坐标网格的图纸上，通过探针测量等势点，用黑点标记。脚本从照片中自动提取黑点坐标，换算半径与角度，绘制等势线图并进行对数线性拟合。
- 实验二（任意形状电极）：在坐标纸上记录等势点坐标，脚本通过三角剖分插值生成连续的等势线，并绘制电场线（流线）。
- 黑点自动提取 — 从极坐标图纸照片中自动识别黑色数据点，支持 Hough 圆变换定位、红墨印刷网格过滤、连通组件分析去噪
- 数据透视与聚类 — 按角度聚合测量点，将长表转换为按角度射线组织的宽表，便于查看与分析
- 等势线与电场线绘制 — 同轴电缆模型的对数线性拟合，以及任意电极的三角剖分插值 + 梯度流线生成
- 命令行即用 — 所有脚本均提供完整的 CLI 参数，默认值针对标准实验条件设定，开箱即用
# Step 1: 从照片提取黑点
python scripts/extract_black_points.py
# Step 2: 按角度透视
python scripts/pivot_black_points_by_angle.py
# Step 3: 绘制场图与拟合
python scripts/plot_coaxial_field.pypython scripts/plot_electric_field_and_equipotentials.py所有输出文件位于 output/ 目录。
- Python ≥ 3.10
- 包管理器：uv（推荐）或 pip
# Clone 仓库
git clone https://github.com/LyCecilion/StaticFlow.git
cd StaticFlow
# 使用 uv 安装依赖
uv sync
# 或者使用 pip
pip install -r <(uv pip compile pyproject.toml -o -)核心依赖：
| 包 | 用途 |
|---|---|
opencv-python |
图像读取、圆检测、形态学操作、连通组件分析 |
numpy |
数值计算、线性回归、梯度计算 |
matplotlib |
全部图表绘制 |
pillow |
辅助图像处理 |
脚本：scripts/extract_black_points.py
原理：从同轴电缆实验极坐标图纸的照片中，自动识别黑色数据点，计算每个点对应的角度和径向距离（cm）。
处理流程：
- 圆检测 — 使用 Hough 圆变换定位极坐标图的外圆，结合径向密度剖面精修外圆半径
- 红墨过滤 — 在 HSV 色彩空间分离红色印刷网格线（hue < 10 或 > 170），避免误检
- 黑点提取 — 灰度阈值（默认 < 80）+ 形态学开运算去噪
- 连通组件分析 — 面积、宽高比、位置三重过滤，排除噪点
- 坐标换算 — 像素坐标 → 极坐标（角度、半径 cm）
python scripts/extract_black_points.py \
--image example/RawDataOfCoaxialCableElectrostaticFieldExperiment.jpg \
--csv output/black_points.csv \
--debug-image output/black_points_debug.jpg \
--outer-radius-cm 6.5 \
--inner-radius-cm 1.0 \
--allowed-angle-mode experiment \
--radius-step-cm 0.2主要参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
--image |
example/...jpg |
输入照片路径 |
--csv |
output/black_points.csv |
输出 CSV 路径 |
--debug-image |
output/black_points_debug.jpg |
标注后的调试图片 |
--outer-radius-cm |
6.5 |
外圆物理半径（cm） |
--inner-radius-cm |
1.0 |
内圆物理半径（cm） |
--allowed-angle-mode |
experiment |
角度吸附模式：experiment（30°/45° 倍数）或 uniform（均匀步长） |
--angle-step-deg |
5.0 |
uniform 模式下的角度步长（°） |
--radius-step-cm |
0.2 |
半径吸附网格（cm）— 现已改为直接四舍五入到两位小数 |
--black-threshold |
80 |
黑色灰度阈值（0-255，低于此值视为黑点） |
--red-saturation-threshold |
80 |
红色饱和度阈值 |
--min-area / --max-area |
15 / 220 |
连通组件面积范围（px²） |
输出 CSV 字段：
| 字段 | 说明 |
|---|---|
index |
点序号 |
angle_deg |
真实角度（°） |
angle_deg_snapped |
吸附后的角度（°） |
radius_cm |
原始半径（cm） |
radius_cm_snapped |
四舍五入到两位小数的半径（cm） |
ring_2mm |
所在 2mm 环编号 |
radius_px |
半径（px） |
x_px, y_px |
像素坐标 |
area_px |
连通组件面积（px²） |
脚本：scripts/pivot_black_points_by_angle.py
原理：将第一步输出的长表（每个点一行）转换为宽表（每列一条角度射线，每行一个半径环上的值），方便阅读和后续处理。
处理流程：
- 角度聚类 — 按真实角度排序后，以
--cluster-gap-deg为阈值将同一条射线上的点聚合为一个 cluster - 代表角度投票 — 每个 cluster 内对 snapped 角度做多数投票
- 透视输出 — 按角度排序，输出
angle_0, angle_30, angle_60, ...列 +average列
python scripts/pivot_black_points_by_angle.py \
--input output/black_points.csv \
--output output/black_points_by_angle.csv主要参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
--input |
output/black_points.csv |
第一步输出的 CSV |
--output |
output/black_points_by_angle.csv |
透视输出路径 |
--cluster-gap-deg |
10.0 |
角度聚类阈值（°），相邻点角度差小于此值视为同一射线 |
--expected-values-per-angle |
7 |
每列期望点数（用于异常检测） |
脚本：scripts/plot_coaxial_field.py
原理：读取透视后的数据，生成两张图：
-
等势线分布图（
coaxial_field_plot.png）— 在笛卡尔坐标下绘制各等势环和电场方向箭头 -
对数半径-相对电位图（
coaxial_log_radius_plot.png）— 绘制实测$\ln r$ –$U_r$ 关系，与理论直线对比，并对实测数据进行线性拟合
理论依据：同轴电缆模型中，电势
即
python scripts/plot_coaxial_field.py \
--input output/black_points_by_angle.csv \
--inner-radius-cm 1.0 \
--outer-radius-cm 6.5主要参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
--input |
output/black_points_by_angle.csv |
透视后的 CSV |
--field-output |
output/coaxial_field_plot.png |
等势线图输出 |
--log-output |
output/coaxial_log_radius_plot.png |
对数拟合图输出 |
--inner-radius-cm |
1.0 |
内电极半径（cm） |
--outer-radius-cm |
6.5 |
外电极半径（cm） |
--angle-convention |
math |
角度约定：math（0° 指向 +x）或 chart（0° 指向下方） |
--field-line-angles-deg |
0,45,90,...,315 |
场线箭头角度 |
--dpi |
200 |
输出分辨率 |
脚本：scripts/plot_electric_field_and_equipotentials.py
原理：给定坐标纸上记录的等势点坐标，通过三角剖分插值生成连续标量场，再计算梯度得到电场方向，最终绘制等势线和电场流线。
处理流程：
- 三角剖分插值 — 对离散测量点做 Delaunay 三角剖分 + 线性插值，得到网格化的电势场
-
梯度计算 —
$\vec{E} = -\nabla V$ ，用np.gradient计算电场分量 -
等势线 —
contour按实际电压值绘制等势线并标注 -
电场流线 —
streamplot从左侧均匀起始点出发，沿电场方向绘制流线
python scripts/plot_electric_field_and_equipotentials.py \
--input example/electric_field_points.csv \
--output output/electric_field_and_equipotentials.png主要参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
--input |
example/electric_field_points.csv |
等势点坐标 CSV |
--output |
output/electric_field_and_equipotentials.png |
输出图像路径 |
--grid-size |
240 |
插值网格分辨率 |
--field-line-count |
5 |
电场流线条数 |
--stream-linewidth |
0.9 |
流线宽度 |
--stream-arrowsize |
0.8 |
流线箭头大小 |
--dpi |
200 |
输出分辨率 |
直接使用极坐标图纸的 照片（JPEG/PNG），脚本自动检测图表几何参数。
CSV 格式，包含以下列：
| 列名 | 说明 |
|---|---|
Voltage(V) |
电势值（V） |
Point_Index |
该电压等级下的点序号 |
X_Coordinate |
X 坐标 |
Y_Coordinate |
Y 坐标 |
示例（example/electric_field_points.csv）：
Voltage(V),Point_Index,X_Coordinate,Y_Coordinate
3,1,10.60,7.80
3,2,10.90,6.00
...
7,10,2.85,1.60所有脚本均通过命令行参数配置，使用 --help 查看完整参数列表。各脚本的默认值针对标准实验条件设定，可直接运行。
本项目图表使用 思源宋体（Source Han Serif SC）作为主字体，数学公式使用 Computer Modern 字体（matplotlib 内置 mathtext 渲染）。如系统未安装思源宋体，matplotlib 将自动 fallback 到微软雅黑等中文字体。
StaticFlow/
├── example/ # 示例输入数据
│ ├── RawDataOfCoaxialCableElectrostaticFieldExperiment.jpg
│ └── electric_field_points.csv
├── scripts/ # 所有脚本
│ ├── extract_black_points.py # 从照片提取黑点
│ ├── pivot_black_points_by_angle.py # 按角度透视黑点数据
│ ├── plot_coaxial_field.py # 同轴电缆场图与对数拟合
│ └── plot_electric_field_and_equipotentials.py # 电场线与等势线
├── output/ # 输出目录（gitignore）
├── pyproject.toml
├── uv.lock
└── README.md
MIT © LyCecilion