露天爆破设计（blasting）总览
dimine_python_sdk.lib.blasting 是露天深孔台阶爆破设计的纯 Python 业务域：从爆破区域出发，依次完成
布孔 → 装药 → 起爆网络 → 分析 → DMO 炮孔数据库落盘，全程不依赖 DmPyBindInterface、
无需启动 Dimine GUI，也不要求 DIMINE_HOME（离线也能跑设计计算）。
本模块与 lib.io.dmo_file 深度配合：设计算法产出的是类型化记录（装药分段、连线、炮孔），
最后由 build_dmo 装配成 DmoFile 交给 lib.io 落盘为 .dmo。
自动化工作流：若需要「一键出图 + 出报告」的完整流程（等时线 / 起爆时间柱状图 / 模拟动画 / Excel 爆破设计说明书 / 逐阶段 DMO 快照），见仓库根目录的
open-pit-blasting-designskill（.claude/skills/open-pit-blasting-design/）。 该 skill 的数值核心就是本包；matplotlib 出图与 Excel 报告 不在本包内。
模块定位与边界
| 对象 | 归属 | 说明 |
|---|---|---|
布孔 layout_holes |
lib.blasting.hole_layout |
多边形内按孔网/安全距离排孔，逐孔解析标高 |
装药（直算）design_charge / min_stemming_length |
lib.blasting.charge_design |
按单耗或最小填塞计算装药量/结构 |
装药（模板套用）adapt_charge_template / design_charge_from_template |
lib.blasting.template_adapt |
把固定装药模板适配到每个真实孔深 |
起爆网络 build_network |
lib.blasting.network |
按 V 型/斜线型连线并赋设计延时 |
纯计算分析 flyrock_range / throw_direction / blast_bounds |
lib.blasting.analysis |
飞石 / 抛掷方向 / 包围盒（不依赖 matplotlib） |
DMO 装配 build_dmo / resolve_schedule |
lib.blasting.dmo_export |
设计结果 → DmoFile 与权威地表起爆时间 |
全局配置库 HoleParam / ExplosiveDB / ChargeTemplateDB |
lib.blasting.{hole_param,explosive_db,charge_template} |
读写 Dimine 全局参数文件（.xml / .dmt） |
默认值加载 load_layout_params / load_explosives |
lib.blasting.defaults |
从全局配置读入设计参数，失败返 None（离线回退内置默认） |
| 设计参数/结果模型 | lib.blasting.models |
Pydantic 参数模型、结果模型与枚举 |
| 记录类型（装药/连线/炮孔） | lib.io.dmo_file |
ChargeSegment/ChargeResult/BlastLine/DmoHole/DmoNetwork，随 .dmo 读写（本包 re-export） |
.dmo 文件读写 |
lib.io（DmoFile） |
底层落盘，见 DMO 炮孔数据库 |
约定：本包只做数值计算与模型装配。等时线/柱状图/动画（matplotlib）与 Excel 爆破设计说明书（openpyxl/pandas）均属
open-pit-blasting-designskill，不在此包。
快速上手
from dimine_python_sdk.lib.blasting import (
BlastRegion, HoleLayoutParams, ChargeParams, Explosive,
NetworkParams, DetonatorType, layout_holes, design_charge,
build_network, resolve_schedule, build_dmo,
)
# 1. 爆破区域（多边形 + 前排方向 + 孔口/孔底标高）
region = BlastRegion(
name="M01",
polygon=[(0, 0), (30, 0), (30, 25), (0, 25)],
front_azimuth=90.0, # °，0=正北
mouth={"mode": "z", "value": 765.0}, # 孔口标高 765m
bottom={"mode": "depth", "value": 15.0}, # 孔底=孔口−15m
)
# 2. 布孔 → 装药 → 起爆网络
holes = layout_holes(region, HoleLayoutParams())
charges = design_charge(
holes, ChargeParams(), explosives=[Explosive(name="乳化炸药", line_density=6.0)],
burden=4.0, # 最小抵抗线 W (m)
)
net = build_network(holes, NetworkParams(), init_delay=100.0, charge_results=charges)
# 3. 权威地表起爆时间（与 .dmo 落盘同口径），并装配为内存 DmoFile
surface = resolve_schedule(holes, charges, net, region, burn_velocity=2000.0,
detonator=DetonatorType.NONEL)
net.delays = surface # 回写，供分析/报告消费
dmo = build_dmo(holes, charges, net, region, burn_velocity=2000.0)
dmo.save("blast_result.dmo", burn_velocity=2000.0) # 落盘（需 Dimine 原生运行环境）
上面五步的完整逐段说明见 爆破设计流程。
公共 API 一览
lib.blasting 的 __init__.py 聚合了全部公共符号，统一从包名导入即可：
from dimine_python_sdk.lib.blasting import (
# 设计算法
layout_holes, design_charge, min_stemming_length,
build_network, flyrock_range, throw_direction, blast_bounds,
build_dmo, resolve_schedule,
# 装药模板套用与适配
adapt_charge_template, design_charge_from_template, TemplateAdaptation,
# 参数 / 结果模型与枚举
BlastRegion, Hole, HoleLayoutParams, ChargeParams, NetworkParams,
FlyrockParams, NetworkResult, Explosive,
LayoutPattern, ChargeMode, AdjustRule, DetonatorType,
ConnectionType, BlastType, ElevationMode, ElevationSpec,
ChargeSegment, ChargeResult,
# 记录类型（re-export 自 lib.io.dmo_file）
BlastLine, DmoHole, DmoNetwork, first_explosive_relay, DmoChargeStructureError,
# 全局配置库（布孔参数 / 炸药库 / 装药模板库）
HoleParam, hole_param_conn, hole_param_path,
HoleParamError, HoleParamPathError, HoleParamFormatError,
ExplosiveDB, explosive_db_conn, explosivedb_path,
ExplosiveDBError, ExplosiveDBPathError, ExplosiveDBFormatError,
ChargeTemplateDB, charge_template_conn, charge_template_path,
ChargeTemplateError, ChargeTemplatePathError, ChargeTemplateFormatError,
# 从 Dimine 全局配置读默认
load_layout_params, load_explosives,
)
说明：
ChargeSegment/ChargeResult真实定义在lib.io.dmo_file（随.dmo装药结构列读写）， 本包 re-export 同一对象；BlastLine/DmoHole/DmoNetwork/first_explosive_relay亦然。 用from dimine_python_sdk.lib.blasting import ChargeSegment与直接从lib.io.dmo_file导入等价。Explosive定义在lib.blasting.models，由ExplosiveDB库读写。- 配置库的细粒度用法见 全局配置库与参数来源，装药模板套用见 装药模板套用与适配。
核心数据模型
所有参数/结果模型均为 Pydantic 模型（统一继承 ParamModel），构造时校验边界、可序列化为 dict。
枚举
| 枚举 | 成员 = 值 | 语义 |
|---|---|---|
LayoutPattern 布孔方式 |
SQUARE="方形" / STAGGERED="梅花形" / TRIANGLE="三角形" / CUSTOM="自定义" |
网格错位方式 |
ChargeMode 装药模式 |
MIN_STEMMING="优先最小填塞和炸药" / BY_SPECIFIC_CHARGE="优先按单耗计算" / STEMMING_SPACER="优先填塞和间隔器" |
模板适配优先级（见 charge_from_template） |
AdjustRule 调整规则 |
PROPORTIONAL="按比例" / MOUTH_FIRST="优先孔口装药" / BOTTOM_FIRST="优先孔底装药" |
压缩时哪段「保底」（正向/反向起爆） |
DetonatorType 雷管类型 |
DIGITAL="数码电子雷管" / NONEL="导爆管雷管" |
影响连线燃烧时长是否计入 |
ConnectionType 连线类型 |
V_TYPE="V型" / DIAGONAL="斜线型" |
起爆网络拓扑 |
BlastType 爆破类型 |
DEEP_HOLE="深孔" / SHALLOW_HOLE="浅孔/二次破碎" |
飞石规范下限用 |
标高策略 ElevationSpec
孔口 / 孔底 Z 的来源方式。mode 取下列字符串（ElevationMode 为类型别名，非枚举）：
| mode | 含义 | 必填 |
|---|---|---|
"z" |
指定标高（value） |
否（缺省延迟到布孔时校验） |
"depth" |
指定孔深（value m），孔底=孔口−孔深；仅用于孔底 |
value |
"surface_file" |
表面文件：interp_fn: (x, y) -> z |
interp_fn |
"bottom_file" |
底面文件：interp_fn: (x, y) -> z |
interp_fn |
"slope" |
底面坡度（value° 斜坡面）；仅用于孔底 |
value |
from dimine_python_sdk.lib.blasting import BlastRegion, ElevationSpec
# 两种等价写法：dict 或 ElevationSpec
BlastRegion(name="M01", polygon=[(0, 0), (30, 0), (30, 25), (0, 25)],
mouth={"mode": "z", "value": 765.0},
bottom={"mode": "depth", "value": 15.0})
BlastRegion(name="M01", polygon=[(0, 0), (30, 0), (30, 25), (0, 25)],
mouth=ElevationSpec(mode="z", value=765.0),
bottom=ElevationSpec(mode="depth", value=15.0))
爆破区域 BlastRegion
| 字段 | 类型/默认 | 说明 |
|---|---|---|
name |
str（必填） |
爆区名称 / 编号（如 M01） |
polygon |
(N,2)/(N,3) 顶点列表（必填） |
接受 np.ndarray / 嵌套 list；仅取 X/Y |
front_azimuth |
float=0.0，[0,360) |
前排方向角（自由面法向）；0=正北(+Y)、90=正东(+X) |
mouth |
ElevationSpec(mode="z") |
孔口标高策略 |
bottom |
ElevationSpec(mode="depth", value=15.0) |
孔底标高策略 |
参数模型
HoleLayoutParams 布孔参数
| 分组 | 字段 | 默认 | 约束 | 说明 |
|---|---|---|---|---|
| 孔网 | hole_spacing |
5.0 |
>0 |
孔间距 m |
row_spacing |
3.0 |
>0 |
排间距 m | |
pattern |
SQUARE |
— | 布孔方式 | |
front_distance |
4.0 |
>=0 |
前排安全距离（第一排孔距自由面）m | |
back_distance |
2.0 |
>=0 |
后冲距离 m | |
left_distance / right_distance |
2.0 / 2.0 |
>=0 |
侧向冲距离 m | |
rotation_angle |
0.0 |
— | 孔网整体旋转角度° | |
| 钻孔 | diameter |
220.0 |
>0 |
孔径 mm |
azimuth |
0.0 |
[0,360) |
方位角°（0=正北） | |
inclination |
-90.0 |
[-180,0] |
倾角°（负=向下；垂直=-90） | |
| 超深 | front_overdrill |
2.0 |
>=0 |
前排超深 m |
back_overdrill |
1.0 |
>=0 |
后排超深 m | |
| 其他 | bench_height |
15.0 |
>0 |
平均回采高度 / 台阶高度 m |
detonator |
DIGITAL |
— | 雷管类型 | |
detonation_velocity |
2000.0 |
>0 |
导爆管燃速 m/s | |
init_delay |
100.0 |
>=0 |
起爆点延时 ms | |
isochrone_interval |
10.0 |
>0 |
等时线间隔 ms | |
tolerance |
1.0 |
>=0 |
布孔容差 m |
ChargeParams 装药参数
| 字段 | 默认 | 约束 | 说明 |
|---|---|---|---|
min_stemming |
2.0 |
>=0 |
最小填塞长度 m |
spacer_length |
2.0 |
>=0 |
间隔器默认长度 m |
charge_mode |
BY_SPECIFIC_CHARGE |
— | 装药模式（模板适配语义见下） |
adjust_rule |
PROPORTIONAL |
— | 调整规则（正向/反向起爆取舍） |
specific_charge |
0.4 |
>=0 |
单耗 q kg/m³ |
k |
1.15 |
>=1.0 |
后排药量增大系数（1.1~1.2） |
template |
"连续装药" |
— | 内置模板：连续装药 / 间隔装药 |
in_hole_delay |
350.0 |
>0 |
孔内雷管延时基值 ms（连续=唯一炸药段；间隔=最靠孔口炸药段） |
deck_delay_step |
30.0 |
>=0 |
间隔装药逐段延时递增 ms（350→380→410） |
segments |
None |
>=1 或 None |
分段数；None=按孔深自动（>8m 分段） |
NetworkParams 起爆网络参数
| 字段 | 默认 | 约束 | 说明 |
|---|---|---|---|
connection_type |
V_TYPE |
— | V 型 / 斜线型 |
hole_delay |
25.0 |
>=0 |
孔间延时 ms |
row_delay_min / row_delay_max |
42.0 / 65.0 |
>=0 |
排间延时上下限 ms |
capture_range |
1.0 |
>=0 |
捕捉范围 m |
first_row_delay |
9.0 |
>=0 |
首排延时 ms |
last_row_delay |
42.0 |
>=0 |
末排延时 ms |
incremental |
False |
— | 基于已有连线解算（增量延拓） |
FlyrockParams 飞石参数（GB 6722-2014）
| 字段 | 类型/默认 | 说明 |
|---|---|---|
W |
float（必填，>0） |
最小抵抗线 m |
n |
float（必填，>0） |
炸药作用系数 |
Kf |
float（必填，>0） |
安全系数 |
blast_type |
DEEP_HOLE |
爆破类型（决定规范下限） |
downhill |
False |
是否下坡方向（影响范围 ×1.5） |
结果模型
| 模型 | 说明 | 关键字段 |
|---|---|---|
Hole 炮孔 |
布孔结果（单孔） | number(如 A-01)、region、mouth_* / bottom_* 坐标、diameter mm、depth m、azimuth/inclination°、row(0=前排)/col、overdrill、is_initiating；属性 bench_height = 孔深−超深 |
ChargeResult 单孔装药结果 |
装药设计结果（随 .dmo 装药列写回） |
hole_number、depth、charge_length/charge_weight/stemming_length/spacer_length、segments: List[ChargeSegment]（孔口→孔底）、specific_charge_area(负担面积)、warnings(红色警告) |
ChargeSegment 装药分段 |
一段填塞/炸药/间隔器/空气/起爆药包 | fill_type、length m、weight kg（惰性=0）、delay ms（惰性 -1，起爆 >=0） |
NetworkResult 网络结果 |
起爆网络拓扑与延时 | nodes(孔号)、edges[(from,to)]、delays(孔号→地表起爆时间 ms，设计增量不含连线燃速)、initiating_hole、relays[(a,b)]=设计延时雷管 ms（非时间差）、segment_charges(时刻→单段药量) |
Explosive 炸药 |
炸药信息 | name、line_density kg/m、unit_price 元/kg |
TemplateAdaptation 适配结果 |
单孔模板适配结果（不绑孔对象） | ok、fail_code(A/B/C 或 None)、fail_reason、segments、charge_length/charge_weight/stemming_length/spacer_length |
segments语义：自孔口→孔底有序；segments[0]恒为孔口填塞段。惰性段 （填塞物 / 间隔器 / 空气）delay=-1不参与起爆，起爆段delay>=0（含 0=同段即发）。
单位与坐标约定
| 量 | 单位 | 备注 |
|---|---|---|
| 长度（孔深/孔距/填塞…） | m | 仅 diameter 为 mm，装药计算内部自动换算 |
| 角度 | ° | front_azimuth/azimuth：0=正北(+Y)、90=正东(+X)；inclination 负=向下（垂直=-90） |
| 重量 / 线密度 | kg / (kg/m) | Explosive.line_density 即「体重」列 |
| 延时 | ms | 雷管段别不在本包；一律用数值延时 ms |
| 燃速 | m/s | 导爆管燃速，缺省 2000 |
| 单耗 | kg/m³ | specific_charge q |
| 价格 | 元/kg | unit_price |
异常与离线降级
- 设计算法（布孔/装药/网络/分析/DMO）：非法输入抛
ValueError（或pydantic.ValidationError）； 孔深不足等「失败孔」不抛异常——模板适配会以ok=False/warnings="原因A/B/C"形式返回。 - 配置库管理器 各自由三件套异常组成（均不继承
RuntimeError，继承自Exception）：
| 库 | 基类 | 子类 |
|---|---|---|
HoleParam |
HoleParamError |
HoleParamPathError（找不到文件） / HoleParamFormatError（XML 结构不符） |
ExplosiveDB |
ExplosiveDBError |
ExplosiveDBPathError / ExplosiveDBFormatError |
ChargeTemplateDB |
ChargeTemplateError |
ChargeTemplatePathError / ChargeTemplateFormatError |
- 默认值加载：
load_layout_params()/load_explosives()在无DIMINE_HOME、文件缺失或解析失败时 返回None而非抛异常——业务侧回退到内置默认（离线可用）。 .dmo记录/落盘相关异常（DmoError等）见 DMO 炮孔数据库。
章节导航
相关链接：
lib.io.dmo_file类型化.dmo读写见 DMO 炮孔数据库； API 参考（mkdocs 构建时自动生成）见reference/lib/blasting/。