夜雨聆风适用于 MATLAB 读取 Excel 配置、自动生成 gprMax 输入文件、预览模型与批量参数扫描
项目 | 说明 |
文档用途 | 说明 Excel 模板、MATLAB 读取代码、cfg 数据结构、.in 生成逻辑与后续扩展方法 |
适用对象 | gprMax 入门仿真、GPR 钢筋/空洞/脱空/含水区模型构建、批量仿真数据集生成 |
核心思想 | 用 Excel 管理模型参数，用 MATLAB 转换为 gprMax 命令，降低手写 .in 文件的工作量 |
建议版本 | MATLAB R2020a 及以上；Excel .xlsx；gprMax v3.x |
1. 设计目标与总体思路
本工具的目标是将 gprMax 输入文件的手写过程转变为“Excel 配置—MATLAB 解析—自动生成 .in 文件”的流程。用户主要在 Excel 中填写模型尺寸、材料参数、几何目标、天线与扫描参数，MATLAB 负责读取配置、检查参数、估算仿真次数、输出 gprMax 输入文件和模型预览图。
该设计保留底层代码的可扩展性，同时降低日常仿真建模的使用门槛。对于单根钢筋、圆形空洞、水平脱空、矩形含水区等常见二维 GPR 模型，用户无需逐行书写 #box、#cylinder、#material 等命令，只需要在表格中启用相应对象并填写坐标。
图1从 Excel 配置到 gprMax 仿真的推荐工作流
2. 总体架构
系统可分为五个层次：Excel 配置层、读取解析层、计算校验层、输出生成层和 gprMax 运行层。Excel 配置层面向用户，读取解析层将 Excel 中的 key/value 表和对象表转换为 MATLAB 结构体 cfg，计算校验层负责仿真次数估算和关键参数检查，输出生成层负责写入 .in 文件和绘制模型预览图，最终由 gprMax 运行仿真。
图2Excel 配置生成 gprMax .in 文件的代码架构
3. 文件组成与模块职责
文件名 | 类型 | 主要职责 |
gprmax_excel_config_template.xlsx | Excel 模板 | 集中配置模型尺寸、材料库、几何对象、天线扫描和批量案例 |
demo_build_from_excel.m | 示例脚本 | 给出单模型生成流程，调用主入口函数并打印结果 |
gprmax_build_from_excel.m | 主入口 | 读取 Excel、估算 nrun、导出 .in、生成预览图、打印运行命令 |
gprmax_read_excel_config.m | 读取解析 | 读取 Global、Materials、Objects、AntennaScan，形成 cfg 结构体 |
gprmax_estimate_nrun_cfg.m | 计算函数 | 根据模型长度、天线初始位置、扫描步距和安全边距自动估算仿真次数 |
gprmax_write_in_from_cfg.m | 写入函数 | 将 cfg 转换为 gprMax 命令并写入 UTF-8 编码的 .in 文件 |
gprmax_preview_cfg.m | 预览函数 | 根据 cfg 绘制 x-z 剖面模型图，用于检查目标位置和材料分布 |
gprmax_build_batch_from_excel.m | 批量函数 | 读取 BatchCases 工作表，批量生成单根钢筋等模板模型 |
4. Excel 模板设计
Excel 模板采用“配置表 + 对象表 + 批量表”的方式组织。Global 和 AntennaScan 使用 key/value 形式，适合管理全局参数；Materials 和 Objects 使用结构化表格，适合逐行启用、禁用、添加材料和目标；BatchCases 用于批量生成参数化样本。
4.1 Global 工作表
Global 用于配置模型基本尺寸、网格尺寸、时间窗、背景材料、安全边距和 geometry 输出开关。该表的 key 将被读取为 cfg.domain、cfg.grid、cfg.time_window_ns、cfg.background_material 等字段。
key | 含义 | 对应 gprMax 命令或 cfg 字段 |
title | 模型标题 | cfg.global.title，同时作为输出文件名基础 |
Lx, Ly, Lz | 模型 x/y/z 尺寸 | #domain: Lx Ly Lz |
dx, dy, dz | 网格尺寸 | #dx_dy_dz: dx dy dz |
time_window_ns | 仿真时间窗，单位 ns | #time_window: time_window_ns × 1e-9 |
background_material | 背景材料名称 | #box: 0 0 0 Lx Ly Lz background_material |
margin | 右侧安全边距 | 用于 nrun 自动估算 |
output_geometry | 是否输出 geometry.vti | 控制是否写入 #geometry_view |
geometry_name | geometry 输出文件名前缀 | #geometry_view 的 filename base |
4.2 Materials 工作表
Materials 是材料库，enabled=1 的材料会写入 .in 文件。gprMax 内置材料如 pec 和 free_space 不需要重新定义；用户在 Objects 表中引用材料时，材料名称应与 Materials 表中 name 一致，或使用 gprMax 内置材料。
列名 | 说明 | 示例 |
enabled | 是否启用，1 为写入 .in | 1 |
name | 材料名称，后续 Objects 按名称引用 | concrete / air / water_like |
eps_r | 相对介电常数 | 7 |
sigma | 电导率 S/m | 0.01 |
mu_r | 相对磁导率，通常取 1 | 1 |
sigma_star | 磁损耗项，通常取 0 | 0 |
note | 说明信息，不写入 .in | 混凝土背景 |
4.3 Objects 工作表
Objects 是几何目标表，是最常用的配置区域。每一行代表一个几何对象，enabled=1 的对象会被写入 .in 文件。对象通过 type 字段区分钢筋、圆形空洞、水平脱空、矩形区域和通用圆柱。priority 用于控制写入顺序，通常背景先写入，病害和目标后写入，以保证后写入对象覆盖先写入对象。
列名 | 说明 | 适用对象 |
enabled | 是否启用 | 全部 |
id | 对象编号，便于调试 | 全部 |
type | 对象类型：rebar、void_circle、delamination、box、cylinder_y | 全部 |
x1,z1 | 目标中心或矩形左上角坐标 | 全部 |
x2,z2 | 矩形目标另一角或脱空终点 | box、delamination |
radius | 圆形目标半径 | rebar、void_circle、cylinder_y |
thickness | 脱空厚度 | delamination |
material | 目标材料名称 | 全部 |
priority | 写入顺序，数值越小越先写 | 全部 |
note | 说明信息 | 全部 |
图3Objects 表到 gprMax 几何命令的映射关系
4.4 AntennaScan 工作表
AntennaScan 用于配置激励源、接收器、扫描步距和输出分量。对于二维 TMy 模型，当 Ly=dy 即 y 方向只有一个网格时，Hertzian dipole 的极化方向建议设置为 y，输出分量优先查看 Ey。
key | 含义 | 对应 gprMax 命令 |
waveform_type | 波形类型，目前主要使用 ricker | #waveform: ricker ... |
amplitude | 波形幅值系数 | #waveform 第二个参数 |
freq_GHz | 中心频率，单位 GHz | 写入时转换为 Hz |
waveform_name | 波形名称 | 供 #hertzian_dipole 引用 |
polarisation | 源极化方向，二维 TMy 建议 y | #hertzian_dipole 第一个参数 |
src_x, rx_x | 源和接收器初始 x 坐标 | |
antenna_z | 源和接收器 z 坐标 | |
src_step_x, rx_step_x | 源和接收器每次移动步距 | |
output_component | 绘制 B-scan 的输出分量 | plot_Bscan 参数 |
nrun_override | 手动覆盖仿真次数 | 若有效则优先使用 |
4.5 BatchCases 工作表
BatchCases 用于批量参数扫描。当前批量接口先支持 single_rebar 模板，可通过 rebar_x、rebar_depth、rebar_diameter、freq_GHz、eps_r、sigma 等字段批量生成不同埋深、直径、频率和介质参数的钢筋模型。后续可扩展 void、delamination、water_damage 等模板。
5. cfg 数据结构设计
MATLAB 读取 Excel 后统一转换为 cfg 结构体。cfg 是后续所有函数之间的数据接口，避免各函数直接读取 Excel，便于后续接入 App Designer 或其他配置来源。
cfg.global.title
cfg.domain.Lx / Ly / Lz
cfg.grid.dx / dy / dz
cfg.time_window_ns
cfg.background_material
cfg.margin
cfg.output_geometry
cfg.geometry_name
cfg.materials(i).name / eps_r / sigma / mu_r / sigma_star
cfg.objects(i).type / x1 / z1 / x2 / z2 / radius / thickness / material / priority
cfg.antenna.waveform_type / freq_GHz / polarisation / src_x / rx_x / antenna_z
cfg.antenna.src_step_x / rx_step_x / output_component / nrun_override
cfg.run.nrun
6. MATLAB 主流程说明
6.1 单模型生成入口 gprmax_build_from_excel
单模型生成入口负责串联读取、计算、写入和预览。该函数是日常使用的主要接口，用户只需要传入 Excel 文件路径和输出目录即可。
result = gprmax_build_from_excel(configFile, outDir);
% 内部流程：
% 1. cfg = gprmax_read_excel_config(configFile);
% 2. nrun = gprmax_estimate_nrun_cfg(cfg);
% 3. gprmax_write_in_from_cfg(cfg, inFile);
% 4. gprmax_preview_cfg(cfg, previewPng);
% 5. 打印 gprMax 运行、合并与绘图命令。
6.2 Excel 读取函数 gprmax_read_excel_config
该函数将 Excel 中不同工作表转换为统一 cfg 结构体。Global 与 AntennaScan 使用 key/value 读取方式；Materials、Objects 使用 readtable 读取。读取后进行基本校验，包括模型尺寸、网格尺寸、时间窗和扫描步距等。
• key/value 表适合存放全局单值参数，例如 Lx、dx、freq_GHz。
• 结构表适合存放可变数量的材料和目标，例如 Materials 和 Objects。
• 读取后统一转换为 cfg，后续写入 .in、预览、批量生成均不再依赖 Excel。
6.3 仿真次数估算函数 gprmax_estimate_nrun_cfg
仿真次数 nrun 本质上是 B-scan 道数。源和接收器每运行一次分别按照 #src_steps 和 #rx_steps 移动。为了避免天线移动到右侧边界或 PML 区域，需要保留安全边距 margin。
第 n 次仿真时，源和接收器位置分别为：xs(n)=xs0+(n-1)·ds，xr(n)=xr0+(n-1)·dr。应满足 xs(n)≤Lx−margin，xr(n)≤Lx−margin。因此可分别计算源和接收器允许的最大次数，再取二者较小值。
ns = floor((Lx - margin - xs0) / src_step_x) + 1;
nr = floor((Lx - margin - xr0) / rx_step_x) + 1;
nrun = min(ns, nr);
% 若 Excel 中 nrun_override 填写了正数，则优先使用 nrun_override。
6.4 .in 写入函数 gprmax_write_in_from_cfg
该函数是核心输出模块，负责将 cfg 中的模型参数写入 gprMax 输入命令。文件以 UTF-8 编码写入，避免中文注释导致 UnicodeDecodeError。写入顺序为：文件头、基本模型设置、材料定义、背景区域、几何对象、天线、扫描步距和 geometry 输出。
写入阶段 | gprMax 命令 | 说明 |
基本模型 | 定义模型名称、尺寸、网格和时间窗 | |
材料 | 写入 Materials 中 enabled=1 的材料，pec 等内置材料跳过 | |
背景 | 用 background_material 填充整个计算域 | |
钢筋/圆柱 | 沿 y 方向贯穿模型厚度，适合二维剖面模型 | |
空洞 | 圆形空洞用 cylinder，矩形空洞用 box | |
脱空 | 用薄矩形区域表示层间空鼓或脱空 | |
天线 | 写入源、接收器和波形 | |
扫描 | 控制 B-scan 多道采集 | |
几何预览 | #geometry_view | 调试时打开，正式批量仿真建议关闭 |
6.5 模型预览函数 gprmax_preview_cfg
预览函数用于在正式运行 gprMax 前检查模型几何是否合理，包括模型范围、目标位置、钢筋深度、空洞和脱空范围、源和接收器位置。预览图不参与 gprMax 仿真，但对调试非常重要。后续建议将 gprmax_preview_cfg 与 gprmax_preview_model 的绘图风格统一，采用语义颜色图例：钢筋黑色、空洞浅蓝、脱空橙红、含水区蓝色、混凝土浅灰。
7. Excel 表到 .in 命令的转换规则
Excel 配置 | MATLAB cfg 字段 | gprMax 命令示例 |
Global: Lx=4, Ly=0.002, Lz=1.2 | cfg.domain.Lx/Ly/Lz | #domain: 4 0.002 1.2 |
Global: dx=0.004, dy=0.002, dz=0.004 | cfg.grid.dx/dy/dz | #dx_dy_dz: 0.004 0.002 0.004 |
Materials: concrete, 7, 0.01 | cfg.materials | #material: 7 0.01 1 0 concrete |
Objects: rebar, x1=2, z1=0.35, radius=0.015, material=pec | cfg.objects | #cylinder: 2 0 0.35 2 Ly 0.35 0.015 pec |
Objects: delamination, x1=1.2, x2=2.6, z1=0.3, thickness=0.02 | cfg.objects | #box: 1.2 0 0.3 2.6 Ly 0.32 air |
AntennaScan: freq_GHz=1.6 | cfg.antenna.freq_GHz | #waveform: ricker 1 1.6e9 src |
AntennaScan: polarisation=y, src_x=0.3, antenna_z=0.05 | cfg.antenna | #hertzian_dipole: y 0.3 Ly/2 0.05 src |
AntennaScan: rx_x=0.36, antenna_z=0.05 | cfg.antenna | #rx: 0.36 Ly/2 0.05 |
AntennaScan: src_step_x=0.02, rx_step_x=0.02 | cfg.antenna |
8. 推荐使用流程
单模型调试时，建议先启用 output_geometry=1，仅运行 1 道，检查 geometry.vti 和预览图；确认模型几何正确后，再将 output_geometry 设为 0 并运行 -n 多道仿真。这样可以避免生成大量重复的 geometry*.vti 文件。
% MATLAB 中生成 .in
result = gprmax_build_from_excel('gprmax_excel_config_template.xlsx');
% Anaconda Prompt 中运行仿真
cd "生成的 .in 文件所在目录"
python -m gprMax "single_rebar_from_excel.in" -n 178
python -m tools.outputfiles_merge single_rebar_from_excel
python -m tools.plot_Bscan single_rebar_from_excel_merged.out Ey
9. 常见问题与调试建议
问题 | 原因 | 建议 |
No module named gprMax | 当前 conda 环境未安装 gprMax 或使用了错误环境 | 检查 where python；切换到已安装 gprMax 的环境，或在源码根目录 pip install -e . |
polarisation must be y in 2D TMy mode | Ly=dy 时模型为二维 TMy，但源极化写成 z | AntennaScan 中 polarisation 设为 y |
UnicodeDecodeError | 手写 .in 文件不是 UTF-8，或中文注释编码错误 | MATLAB fopen 使用 UTF-8；普通注释使用 ## |
生成大量 geometry*.vti | 多道仿真时 output_geometry=1 | 正式批量仿真前将 output_geometry 设为 0 |
材料未生效 | Objects 中 material 名称与 Materials 不一致 | 检查拼写；pec 是内置材料可直接使用 |
B-scan 看不到目标 | 目标过深、时间窗过短、频率或网格不合适 | 增加 time_window_ns；检查目标 z 坐标；查看 geometry 预览图 |
数值色散警告 | 网格相对高频波长偏粗 | 减小 dx/dz 或降低中心频率，入门调试可先接受小警告 |
10. 后续扩展设计
10.1 新增对象类型
若需要新增斜裂缝、不规则空洞、钢筋网或多层结构，应按三步扩展：第一，在 Objects 表中新增 type 约定和必要字段；第二，在 gprmax_write_in_from_cfg 中增加对应 case 分支；第三，在 gprmax_preview_cfg 或统一预览函数中增加绘图逻辑。
switch type
case 'new_object_type'
% 1. 读取 x1,z1,x2,z2 或其他字段
% 2. 写入 gprMax 对应命令
% 3. 在预览函数中定义颜色和图形表达
end
10.2 新增批量模板
BatchCases 当前支持 single_rebar。后续可增加 void_circle、delamination、rebar_void、multi_rebar 等模板。扩展时建议保持 BatchCases 的 template 字段作为模板类型标识，每种模板在 gprmax_build_batch_from_excel 中单独生成 cfg.objects。
10.3 集成到 MATLAB App Designer
当前 Excel 模板本质上已经定义了 App 的数据模型。后续做 App Designer 时，可以将 Global、Materials、Objects、AntennaScan 分别做成参数面板和表格控件。用户在 App 中修改表格后，仍然调用 gprmax_write_in_from_cfg 写入 .in 文件。这样既能保留 Excel 批量配置能力，也能逐步升级为图形化建模工具。
App 模块 | 对应 Excel/代码 | 说明 |
模型参数面板 | Global | 配置尺寸、网格、时间窗、背景材料 |
材料库表格 | Materials | 添加、删除、启用材料 |
几何对象表格 | Objects | 添加钢筋、空洞、脱空、含水区等目标 |
天线扫描面板 | AntennaScan | 设置频率、源/接收器位置和扫描步距 |
模型预览窗口 | gprmax_preview_cfg / gprmax_preview_model | 显示 x-z 模型图和语义图例 |
导出按钮 | gprmax_write_in_from_cfg | 生成 .in 文件 |
运行按钮 | gprMax 命令调用 | 可后续集成 system() 调用 Anaconda 环境 |
11. 维护建议
建议将 Excel 模板、读取函数、写入函数、预览函数和批量函数作为一个独立工具包维护。每次新增对象类型或修改字段时，应同步更新 Excel 模板、读取函数、写入函数、预览函数和本设计说明书，避免表格字段和代码分支不一致。
• 对外使用入口尽量保持简单，例如 result = gprmax_build_from_excel(configFile)。
• 底层函数保持单一职责：读取只负责读取，写入只负责生成 .in，预览只负责绘图。
• 每个对象类型应有明确的字段要求和 gprMax 命令映射。
• 批量仿真时建议关闭 geometry 输出，避免产生大量重复 .vti 文件。
附录： csdn 搜 jaz 资源库下载
gprmax_excel_config_matlab_tools/
├── gprmax_excel_config_template.xlsx
├── demo_build_from_excel.m
├── gprmax_build_from_excel.m
├── gprmax_read_excel_config.m
├── gprmax_estimate_nrun_cfg.m
├── gprmax_write_in_from_cfg.m
├── gprmax_preview_cfg.m
├── gprmax_build_batch_from_excel.m
└── README.md
excel设置即可：
.rtcContent { padding: 30px; } .lineNode {font-size: 10pt; font-family: Menlo, Monaco, Consolas, "Courier New", monospace; font-style: normal; font-weight: normal; }%% demo_build_from_excel% 通过 Excel 配置文件生成 gprMax .in 文件。% 建议流程：% 1. 修改 gprmax_excel_config_template.xlsx 中的 Global / Materials / Objects / AntennaScan% 2. 运行本脚本% 3. 检查生成的 .in 文件和预览图% 4. 在 Anaconda Prompt 中运行打印出的 gprMax 命令clc;clear;close all;%% 1. Excel 配置文件路径configFile = 'gprmax_excel_config_template.xlsx';% 如果模板不在当前目录，可写完整路径，例如：% configFile = 'D:\Work\GPR\gprMax-master\gprMax-master\Work\gprmax_excel_config_template.xlsx';workDir = 'D:\Work\GPR\gprMax-master\gprMax-master\Work';if ~exist(workDir, 'dir')workDir = pwd;end%% 2. 输出目录outDir = fullfile(pwd, 'generated_in');%% 3. 生成 .in 文件、预览图，并打印运行命令result = gprmax_build_from_excel(configFile, outDir);fprintf('\n生成完成。\n');fprintf('IN 文件：%s\n', result.inFile);fprintf('预览图：%s\n', result.previewPng);fprintf('推荐仿真次数 nrun = %d\n', result.nrun);
