AFT二次开发教程（16）：外部数据面集成——PCF / CAESAR II Neutral / EPANET / GIS 与第三方衔接
版本与事实声明
- 产品与版本：AFT Fathom 15 / AFT Impulse 12（当前）；本篇菜单项与格式引用官方Fathom 13帮助页
File Menu及其链接页正文，当前版以官方文档为准。- 语言/环境：Python 3.x（标准库）。
- 本文目标：读完能说清 AFT 与配管/应力/供水/地理工具之间哪条通道传什么，并管理好导入件的清点与命名。
- 所有文件名为示例性，不代表任何真实项目。
一句话结论：AFT 的外部资产交换由 File 菜单的Import Piping Layout From（Piping Component File.pcf/ CAESAR II Neutral File.cii/ GIS Shapefile.shp/ EPANET File.inp）与Export Piping Layout To（EPANET.inp）承担，另有Merge（Workspace Only）把另一模型文件并入当前模型；注意.inp有双语义（EPANET 文件 与Export Model Data的 Preformatted Report 都可能叫.inp），必须按来源动作而非扩展名区分。
〇、本篇要解决的认知问题
- Q1：AFT 与外部工具交换的是"数据"还是"资产"？为什么这里要专门讲一次？
- Q2：
Import Piping Layout From支持哪四类格式？各自来自哪个专业、传什么？ - Q3：为什么只有 EPANET 能"导出"？这说明了 AFT 在管网生态里的位置是什么？
- Q4：
.inp双语义陷阱是什么？怎么避免？ - Q5：
Merge与"导入格式"有什么本质不同？
一、机制解析
16.1 两种"对外"，别混为一谈
本系列到目前讲了两类"对外"：
| 类型 | 通道 | 传什么 | 例子 |
|---|---|---|---|
| 数据面（前几篇） | Excel / Batch File / Force File | 参数与结果（数值） | AFT Transfer、Excel 导出件、Force File |
| 资产面（本篇） | Import Piping Layout From等 | 管网的几何与拓扑 | PCF、CII、SHP、EPANET |
为什么必须分开：数值数据面解决"批量算与批量取"；资产面解决"建出来的模型从哪来、算完的模型往哪去"。一个管网模型的"出生"往往是配管专业的 PCF/CII；它的"去处"可能是应力专业的载荷文件、或供水管网分析工具的 EPANET 文件。自动化流水线要覆盖模型的全生命周期，就不能只管数值不管资产。
16.2 四类导入格式：来自谁、传什么
官方File Menu的Import Piping Layout From列出四类：
| 格式 | 官方扩展名 | 来源专业/工具 | 传什么 |
|---|---|---|---|
| Piping Component File (PCF) | .pcf | 配管/三维设计工具导出的管件清单 | 管线元件与连接关系 |
| CAESAR II Neutral File (CII) | .cii | 管系应力分析（CAESAR II 的中性文件格式） | 管线几何与拓扑（中性格式，被多方支持） |
| GIS Shapefile | .shp | 地理信息系统 | 地理图形（geospatial maps），常对应管网走向/位置 |
| EPANET File | .inp | 供水管网分析生态 | 供水管网模型 |
工程解读：
- PCF与CII都是"从配管/应力侧拿几何"——现实中你的管网拓扑往往已经在三维设计里存在了，没必要在 AFT 里重画一遍；导入后补水力参数（管径细节、粗糙度、泵曲线、边界条件）。
- GIS Shapefile是"从地图拿走向"——城市/园区管网常以 GIS 形式存在；导入
.shp把地理走向带进来。 - EPANET是"从供水分析生态拿模型"——这是 AFT 与市政/供水领域互通的接口。
共同点（也是最重要的工程事实）：导入的是"管网骨架"，不是"能算的模型"。导入后你要做的是补全水力定义（流体、边界、泵特性、规格）——这一步正是前面 15 篇所有功夫的用武之地：导入骨架 → 用AFT Transfer批量补参数 → 批跑 → 取数。
这就构成一条完整流水线：
配管/应力/供水/地图 → 导入骨架(.pcf/.cii/.shp/.inp) → 批量补水力参数(AFT Transfer) → 批跑 → 取数/交付 (外部专业) (本篇, 官方导入) (第05/09/15篇) (第10篇) (第11/14/19篇)16.3 为什么只有 EPANET 能导出
官方Export Piping Layout To只列了一项：EPANET File (.inp)。
这说明了 AFT 在生态里的位置：
- 进得多、出得少——AFT 乐于当"水力分析的大脑"，从各种上游拿几何；
- 出只出 EPANET——因为供水领域需要"把 AFT 算好的管网交回供水生态"；
- 应力载荷不走"布局导出"，而走
Export Force File（第 14 篇）——力和几何是两条不同的出口。
工程师要记住：想"把 AFT 模型导回三维设计"，没有官方布局导出通道（除了 EPANET）。这不是缺陷，而是分工——几何的真相源在三维设计，AFT 只做水力。
16.4.inp双语义陷阱
第 04 篇提过一次，这里说清：
- EPANET File：
.inp，供水管网模型格式； Export Model Data的 Preformatted Report：也会生成.inp，官方明确提示"which is not to be confused with EPANET files that have the same file extension"。
两者的用处完全不同：
同名.inp | 生成动作 | 用途 |
|---|---|---|
| EPANET 文件 | 由 EPANET 生态产生 / AFT 的 EPANET 导出产生 | 供水管网模型交换 |
| Preformatted Report | Export Model Data→ 选 Preformatted Report | 模型数据文本快照，可用于文本 diff 找差异（官方说作用类似 Scenario Comparison Tool） |
避免方法：永远按下"生成动作"归档，而不是按扩展名。目录命名与清单里写清"这是 EPANET 还是 Report"（本篇代码 16-1 的用途分类就是干这个）。
附带收获：Preformatted Report 的.inp是一条无 GUI 的模型差异对比路径——适合放进自动化回归测试（第 20 篇），每次改模型后diff两个.inp快照，就知道输入到底变了什么。
16.5Merge：另一种"合并"
官方Merge - (Workspace Only)：打开一个 Merge 对话框，把另一个模型文件合并进当前模型。
与"导入格式"的本质区别：
Import Piping Layout From：导入的是外部格式的几何，需要在 AFT 里重新生成对象；Merge：合并的是另一个 AFT 模型文件（.fth/.imp等），对象本来就是 AFT 对象。
工程用途：把"分专业/分区段建的多个 AFT 模型"合成一个完整模型（如"厂区东侧 + 西侧"两个模型合成全网），或把"某师傅做好的泵站子模型"并入主模型。合并后同样必须复核对象编号冲突（不同文件里可能有同名/同编号对象）。
16.6 资产面的三个工程纪律
资产面（导入几何、合并模型）比数据面更容易出"大错"——因为它动的是拓扑，不是数值。三条纪律：
纪律一：导入后先清点，再补水。导入 PCF/CII/SHP 后，先跑一次对象清点（第 04 篇object_inventory.py），把"进来了多少管、多少结点、有哪些类型"记下来；然后再补水力参数。顺序反了，你会不知道"某个参数为什么改不上"（因为对象根本没进来）。
纪律二：合并前必查编号冲突。AFT 的管与结点是两套独立编号空间（第 04 篇），合并两个模型时"管 3"和"管 3"会撞车（merge_guard.py就是干这个）。冲突必须先重编号，再合并——合并后再改会牵动一大片连接关系。
纪律三：几何的真相源不在 AFT。AFT 只做水力，不回写三维几何（官方Export Piping Layout To只支持 EPANET）。所以别指望"在 AFT 里改了几何再导回设计"——几何改动要回到上游工具做，AFT 侧重新导入。认清这条，能省下大量"为什么导不回去"的困惑。
二、完整代码与逐行剖析
代码 16-1：layout_in.py（导入件清点 + 用途分类 + 命名标准化）
# -*- coding: utf-8 -*-""" layout_in.py —— 外部导入件清点与命名标准化 按"来源动作/格式"分类，避免 .inp 双语义混淆；输出清点 JSON 供流水线引用。 运行： python layout_in.py --selftest python layout_in.py incoming/ --out incoming_inventory.json """importargparseimportjsonimportosimportreimportsys# 官方支持的四类导入格式LAYOUT_EXT={".pcf":"PCF",".cii":"CAESAR II Neutral",".shp":"GIS Shapefile",".inp":"EPANET-or-Report"}MODEL_EXT={".fth":"AFT Fathom",".imp":"AFT Impulse",".aro":"AFT Arrow",".xtr":"AFT xStream"}defclassify_inp(name:str)->str:"""区分 .inp 双语义：文件名/同目录标记含 report/export 视为模型报告，否则按 EPANET。"""low=name.lower()ifre.search(r"(report|preformat|model_data)",low):return"Model Data Preformatted Report (.inp)"return"EPANET File (.inp)"definventory(root:str)->dict:items,ext_counts=[],{}fordirpath,_dirs,filesinos.walk(root):forfninfiles:ext=os.path.splitext(fn)[1].lower()ifextinLAYOUT_EXT:kind=classify_inp(fn)ifext==".inp"elseLAYOUT_EXT[ext]elifextinMODEL_EXT:kind=MODEL_EXT[ext]+" 模型文件"else:continueext_counts[ext]=ext_counts.get(ext,0)+1items.append({"file":os.path.relpath(os.path.join(dirpath,fn),root),"ext":ext,"kind":kind})return{"root":root,"total":len(items),"by_ext":ext_counts,"items":sorted(items,key=lambdax:x["file"])}defselftest():demo=["layout_01.pcf","stress_neutral.cii","water.epanet.inp","model_data_report.inp","plant_west.fth","notes.txt"]kinds={}forfnindemo:ext=os.path.splitext(fn)[1].lower()ifextinLAYOUT_EXT:kinds[fn]=classify_inp(fn)ifext==".inp"elseLAYOUT_EXT[ext]assertkinds["water.epanet.inp"].startswith("EPANET"),kindsassert"Report"inkinds["model_data_report.inp"],kinds# 双语义被区分assert"notes.txt"notinkindsandlen(kinds)==4,kindsprint("SELFTEST OK：4 个导入件被正确分类，两种 .inp 语义被区分，.txt 被忽略。")print(json.dumps(kinds,ensure_ascii=False,indent=2))defmain():ap=argparse.ArgumentParser()ap.add_argument("root",nargs="?",default=".")ap.add_argument("--out",default="incoming_inventory.json")ap.add_argument("--selftest",action="store_true")a=ap.parse_args()ifa.selftest:selftest()return0inv=inventory(a.root)withopen(a.out,"w",encoding="utf-8")asf:json.dump(inv,f,ensure_ascii=False,indent=2)print(f"清点{inv['total']}个外部件：{inv['by_ext']}→{a.out}")return0if__name__=="__main__":sys.exit(main())逐行剖析：
LAYOUT_EXT与MODEL_EXT分开：外部格式（需要导入转换）与AFT 模型文件（可直接 Open/Merge）是两回事，混在一起会让人误以为.fth也是"导入格式"。.inp的"EPANET-or-Report"占位 +classify_inp()按"文件命名/同目录标记"区分双语义：这是用命名纪律弥补格式歧义的实际手法。它不完美（依赖命名），但比"只看扩展名"强得多——并把不确定性显式记录在用途字段里。inventory()只收已知格式，其余静默忽略（notes.txt不会被当导入件）。这在真实项目里能过滤掉一堆无关文件。by_ext计数让"这次收了多少件"一目了然——导入前先清点，是资产面流水线的第一步（尤其当上游一次性甩来几十个.pcf时）。selftest()断言两种.inp被区分、notes.txt被忽略——这两条正是本篇最容易出错的知识点。
代码 16-2：merge_guard.py（合并前对象编号冲突预检）
# -*- coding: utf-8 -*-""" merge_guard.py —— Merge 前对象编号冲突预检 输入：各模型的对象清点（第04篇 object_inventory.py 产物，含编号列表） 输出：编号交叉冲突清单 运行：python merge_guard.py --selftest """importsysdefcheck(model_a:dict,model_b:dict)->list:"""model_*: {"pipes": {num,...}, "junctions": {num,...}}"""problems=[]forkindin("pipes","junctions"):dup=set(model_a.get(kind,()))&set(model_b.get(kind,()))ifdup:problems.append(f"{kind}编号冲突{sorted(dup)}—— Merge 后需重编号")returnproblemsdefselftest():a={"pipes":{1,2,3},"junctions":{1,2}}b={"pipes":{3,4},"junctions":{5}}probs=check(a,b)assertany("pipes"inpforpinprobs),probsassertnotany("junctions"inpforpinprobs),probs# junction 无冲突print("SELFTEST OK：识别出 pipes 编号 3 冲突，junctions 无冲突。")if__name__=="__main__":if"--selftest"insys.argv:selftest()逐行剖析：
- 冲突预检按"管"与"结点"两类分别做交集——因为 AFT 里管与结点是两套编号空间（第 04 篇），管 3 与结点 3 可以共存，不算冲突。
- 返回的是冲突编号本身（不是布尔）：你要的是"具体哪些号要重编"，好去做批量重编号。
selftest()刻意构造"管有冲突、结点无冲突"，验证脚本不会把两类混为一谈。
三、常见报错与排查
报错 16-1：把Export Model Data生成的.inp当 EPANET 文件导入，失败。
现象：EPANET 导入报错或反了。根因：.inp双语义——Preformatted Report 与 EPANET 同扩展名。解法：按生成动作归档；导入 EPANET 明确走Import Piping Layout From > EPANET File（代码 16-1 的用途分类）。
报错 16-2：导入 PCF/.cii后模型"能看不能算"。
现象：骨架有了，跑不了。根因：导入的是几何骨架，不是完整水力模型——缺流体、边界、泵特性、规格。解法：导入后按流水线批量补水力参数（AFT Transfer）；补完再跑。
报错 16-3：想"把 AFT 模型导回三维设计"，找不到导出项。
现象：只看到 EPANET 导出。根因：官方Export Piping Layout To只支持 EPANET；应力载荷走Export Force File（第 14 篇），几何真相源在三维设计。解法：接受分工——AFT 不负责回写三维几何；需要载荷就用 Force File。
报错 16-4：Merge 后出现重复编号/对象错乱。
现象：合并后模型异常。根因：两个模型里管或结点的编号空间重叠。解法：合并前用merge_guard.py预检冲突，先重编号再 Merge；合并后做对象清点复核（第 04 篇）。
报错 16-5：GIS Shapefile 导入后"位置对、连接不对"。
现象：地理走向有了，但拓扑连接缺失/错乱。根因：GIS 传的是地理图形，不保证拓扑完整。解法：导入后核对连接关系（Node/Element 连通性），用Export Model Data清点对象并补连线。
报错 16-6：导入后参数改不上，怀疑是变更表写错。
现象：变更表看着没问题，导入却失败。根因：对象根本没进来——导入件只带来了部分元件，某对象不在模型里。解法：按纪律一，先清点对象、再补水；变更表的对象编号必须取自清点结果（第 04/07 篇）。
四、动手练习
- 练习 1（清点自检）：跑
python layout_in.py --selftest。判定：输出SELFTEST OK；两种.inp用途被区分；.txt被忽略。 - 练习 2（真实清点）：把一个含多种外部件的目录用
layout_in.py incoming/ --out inv.json清点。判定：by_ext计数与目录里实际件数一致；.inp条目的kind都明确（无EPANET-or-Report残留）。 - 练习 3（导入—补参闭环）：用一个
.pcf（或示例件）导入生成骨架，然后用AFT Transfer批量补 5 个水力参数，跑一次。判定：模型能跑出结果；列出你补了哪 5 个参数。 - 练习 4（合并预检）：用
merge_guard.py对两个模型的对象编号做冲突预检（编号可从Export Model Data清点得到）。判定：若报冲突，给出重编号方案；若无冲突，写出"管/结点两套编号空间"的解释。 - 练习 5（序号规范）：为导入件建立一套命名规范（含来源、日期、版本），并写进清点清单。判定：清单里每个导入件的
kind与文件名都能对应；任取一个文件，仅凭文件名就能说出"它来自谁、什么时候、哪个版本"。
五、小结与下一篇预告
本篇划清了"资产面"：AFT 从PCF / CAESAR II Neutral（.cii）/ GIS Shapefile / EPANET导入管网骨架，只向EPANET导出布局；Merge用于合并AFT 模型文件（性质不同于格式导入）；.inp双语义必须按生成动作区分；导入骨架后要靠AFT Transfer 批量补水力参数才算能算的模型。至此，五条通道全部讲完——17 篇起进入综合实战。
第 17 篇《实战一：管网水力批量分析端到端项目》：我们把 05/09/10/11/12 全部串起来，做一个可断点续跑的 CLI——工况矩阵 → 变更表 → 批跑 → 取数 → 落库 → 出报告，并给出完整的账本与目录规范。
FAQ（与第〇节一一对应）
Q1：AFT 与外部工具交换的是数据还是资产？
A：两类都有但本文专讲资产面——数据面（Excel、Batch File、Force File）传参数与结果数值，资产面（Import Piping Layout From 等）传管网的几何与拓扑；模型生命周期要求同时覆盖两者。
Q2：Import Piping Layout From 支持哪四类格式？
A：Piping Component File（.pcf）、CAESAR II Neutral File（.cii）、GIS Shapefile（.shp）、EPANET File（.inp）；分别来自配管/三维设计、管系应力分析、地理信息系统与供水管网生态，传的都是管网骨架而非完整水力模型。
Q3：为什么只有 EPANET 能导出，这说明了什么？
A：官方 Export Piping Layout To 只支持 EPANET File（.inp），说明 AFT 在生态里定位为水力分析大脑、进多出少；应力载荷另走 Export Force File，几何真相源在三维设计，AFT 不负责回写几何。
Q4：.inp 双语义陷阱是什么，怎么避免？
A：EPANET 文件与 Export Model Data 的 Preformatted Report 都使用 .inp 扩展名（官方明确提示不要混淆），前者用于供水管网模型交换、后者是模型数据文本快照可用于文本 diff；避免方法是按生成动作归档而非按扩展名判断，并在清单里记录用途分类。
Q5：Merge 与导入格式有什么本质不同？
A：Import Piping Layout From 导入的是外部格式的几何，需在 AFT 里重新生成对象；Merge 合并的是另一个 AFT 模型文件（对象本来就是 AFT 对象），常用于把分区段或分专业建的多个 AFT 模型合成一个完整模型，合并前须做编号冲突预检。
