开发工具CLI硬件开发【免费下载链接】WireVizEasily document cables and wiring harnesses.项目地址https://gitcode.com/gh_mirrors/wi/WireViz点击查看免费下载本篇技术指南以 WireViz 仓库中 examples/readme.mdExample Gallery为主体逐例解读仓库自带 14 个示例的 YAML 源文件与其自动生成的 BOM物料清单并结合 build_examples.py 说明示例产物的生成机制。读完本文你将掌握 WireViz 中模板复用、颜色编码、线规换算、屏蔽、菊花链、交叉线、线束捆绑、端子压接、接头配对接合与图片嵌入等核心实战能力可直接复刻到自己的线束文档项目中。一、示例画廊是什么仓库自带的 14 个可运行样本WireViz 是一个以纯文本 YAML 文件为输入、借助 GraphViz 输出 SVG/PNG 等精美图形、并自动生成 BOM 的线缆与线束文档化工具。examples/readme.md正是它的示例画廊集中列出了examples/目录下的 14 个示例每个示例都由三部分构成渲染结果图如ex01.png等矢量/位图输出YAML 源文件如ex01.yml即 WireViz 的输入描述BOM 表格如ex01.bom.tsv由 WireViz 自动生成的物料清单制表符分隔的 TSV。示例源文件BOM主题Example 01ex01.ymlex01.bom.tsv屏蔽串口线 IEC 颜色编码 交叉线Example 02ex02.ymlex02.bom.tsvYAML 锚点模板复用电源线Example 03ex03.ymlex03.bom.tsv线束 bundle 与颜色循环Example 04ex04.ymlex04.bom.tsv压接端子Crimp ferruleExample 05ex05.ymlex05.bom.tsv菊花链 variant 1 顶层模板Example 06ex06.ymlex06.bom.tsv菊花链 variant 26 连接器Example 07ex07.ymlex07.bom.tsv隐藏未连接引脚Example 08ex08.ymlex08.bom.tsv图片嵌入3.5 mm TRS 耳机插头Example 09ex09.ymlex09.bom.tsv大引脚数自定义引脚名Example 10ex10.ymlex10.bom.tsvCAT5e 交叉线T568AExample 11ex11.ymlex11.bom.tsv裸线 端子 单向接线Example 12ex12.ymlex12.bom.tsv端子排双向跨接Example 13ex13.ymlex13.bom.tsv多实例自动编号X.X1语法Example 14ex14.ymlex14.bom.tsv拼接、压接与对接的综合大示例注examples/readme.md中图片链接如均指代examples/目录下对应同名 PNG即 ex01.png、ex02.png 等渲染结果图读者可直接打开这些图片查看每个示例的实际输出效果。二、示例产物从哪来build_examples.py 的自动生成机制画廊中每一张图与每一份 BOM 都不是手绘的而是由 src/wireviz/build_examples.py 批量驱动 WireViz 生成的。从脚本源码可以看到其分组逻辑groups { examples: {path: dir / examples, prefix: ex, readme: [], title: Example Gallery}, tutorial: {path: dir / tutorial, prefix: tutorial, readme: [md, yml], title: f{APP_NAME} Tutorial}, demos: {path: dir / examples, prefix: demo}, }即examples/目录同时承载两组产物前缀ex的 14 个示例与前缀demo的 2 个演示demo01/demo02。脚本还定义了输入扩展名与输出产物的类别input_extensions [.yml] extensions_not_containing_graphviz_output [.gv, .bom.tsv] extensions_containing_graphviz_output [.png, .svg, .html]这说明每个.yml输入会派生出一组文件.gvGraphViz 中间输出、.bom.tsv物料清单、.png/.svg图形、.html内嵌图形与 BOM 的网页。要复现或重建这些示例可参考仓库 docs/buildscript.md 对build_examples.py的说明来运行该脚本。以 Example 01 自动生成的 ex01.bom.tsv 为例其 BOM 结构如下制表符分隔含表头Id / Description / Qty / Unit / DesignatorsId Description Qty Unit Designators 1 Cable, Serial, 4 x 0.25 mm² shielded 0.2 m W1 2 Connector, Molex KK 254, female, 4 pins 2 X1, X2可见 BOM 会自动汇总同类物料两个相同连接器合并为一项、数量 2、设计符 X1/X2并正确体现“4 芯、0.25 mm²、屏蔽、长度 0.2 m”等线缆属性。三、Example 01屏蔽线、颜色编码与交叉线ex01.yml 是画廊的基础范本涵盖 WireViz 最常用的配置项connectors: X1: type: Molex KK 254 subtype: female pinlabels: [GND, VCC, RX, TX] # pincount is implicit in pinout X2: type: Molex KK 254 subtype: female pinlabels: [GND, VCC, RX, TX] cables: W1: color_code: IEC # auto-color wires based on a standard wirecount: 4 # need to specify number of wires explicitly when using a color code gauge: 0.25 mm2 # also accepts AWG as unit show_equiv: true # auto-calculate AWG equivalent from metric gauge length: 0.2 # length in m shield: true type: Serial connections: - - X1: [1-4] - W1: [1-4] - X2: [1,2,4,3] # crossover - # connection from connector pin to wire shielding - X1: 1 - W1: s关键点引脚数由 pinlabels 隐式推导X1/X2 均未写pincountWireViz 从pinlabels列表长度自动得出 4 引脚。颜色编码color_code: IEC按 IEC 60757 标准BN/RD/OR/YE/GN/BU/VT/GY/WT/BK自动分配线色。使用color_code时必须显式指定wirecount。线规与等效换算gauge: 0.25 mm2使用公制单位show_equiv: true让 WireViz 自动换算并显示对应的 AWG 等效值gauge同样接受 AWG 写法如20 AWG。屏蔽shield: true为线缆加屏蔽层connections中第二组连接X1: 1 → W1: s把 X1 的 1 号引脚接到屏蔽层s即 shield。交叉线第三项X2: [1,2,4,3]表示 X2 的 1/2/3/4 号引脚分别接 W1 的 1/2/4/3 号线实现 RX/TX 交叉。四、Example 02 与 03YAML 锚点模板与 bundle 线束Example 02ex02.yml示范了用 YAML 原生锚点anchor与合并键merge key批量定义重复结构connectors: X1: boo type: Molex Micro-Fit subtype: male pinlabels: [GND, VCC] X2: con_power_f # define template type: Molex Micro-Fit subtype: female pinlabels: [GND, VCC] X3: : *con_power_f # create from template X4: : *con_power_f cables: W1: wire_power # define template colors: [BK, RD] # number of wires implicit in color list gauge: 0.25 # assume mm2 if no gauge unit is specified show_equiv: true length: 0.2 W2: : *wire_power W3: : *wire_power gauge: 20 awg # override template value connections: - - X1: [1-2] - W1: [1-2] - X2: [1-2] - - X1: [1-2] - W2: [1-2] - X3: [1-2] - - X1: [1-2] - W3: [1-2] - X4: [1-2]要点con_power_f定义模板: *con_power_f生成新的同构连接器 X3/X4W1 定义线缆模板W2/W3 从模板生成。颜色列表隐式决定线数colors: [BK, RD]只有两个颜色WireViz 据此推导 W1 为 2 芯线无需wirecount。单位省略时的默认值gauge: 0.25未写单位WireViz 默认按 mm² 处理。模板可覆写W3 在继承模板后把gauge覆写为20 awg展示了一处覆盖一处生效的灵活用法。Example 03ex03.yml在同一套连接器模板之上引入bundle 线束与颜色循环cables: W1: category: bundle # bundles are routed together, but more loosely than normal cables wirecount: 6 colors: [BK, RD] # if number of items in color list is less than wirecount, loop colors gauge: 0.25 mm2 show_equiv: true length: 0.2要点category: bundle表示将 6 根线作为一束松散地一起布线与普通线缆的紧密捆扎区分。颜色列表少于 wirecount 时自动循环只有 BK、RD 两个颜色却要 6 根线WireViz 会按 BK→RD→BK→RD… 循环着色。三个连接段分别把 X1 的 1-2 引脚接到 X2、X3、X4演示一根 bundle 同时服务三个目标连接器。五、Example 04压接端子Crimp Ferruleex04.yml 演示最简端子用法——用一个style: simple的端子连接一根 6 芯 bundle 的两端cables: W1: gauge: 0.25 mm2 show_equiv: true length: 0.2 color_code: IEC wirecount: 6 category: bundle connectors: F: style: simple type: Crimp ferrule connections: - - F. - W1: [1-6] - F.要点端子用style: simple以简化符号绘制如压接管不显示引脚细节。F.点号语法F.表示按连接上下文自动生成一个 F 的新实例并分配设计符两端各放一个F.即每根线两端各压接一个端子。这里 W1 有 6 根线、但只需一对端子说明F.的实例数量取决于连接上下文。六、Example 05 与 06菊花链Daisy Chain两种实现菊花链指多个连接器沿同一总线依次串接。Example 05ex05.yml用顶层templates:键统一存放模板并演示在type中直接嵌入 HTML 超链接templates: - template_con type: a hrefhttps://www.molex.com/molex/products/family/kk_254_rpc_connector_systemMolex KK 254/a subtype: female pinlabels: [GND, VCC, SCL, SDA] - template_wire gauge: 0.25 mm2 length: 0.2 colors: [PK, TQ, YE, VT] category: bundle type: I2C connectors: X1: {: *template_con} X2: {: *template_con} X3: {: *template_con} cables: W1: {: *template_wire} W2: {: *template_wire} connections: - - X1: [1-4] - W1: [1-4] - X2: [1-4] - - X2: [1-4] - W2: [1-4] - X3: [1-4]要点顶层templates:键模板定义可集中放在文件头部供 connectors/cables 引用。type 中可写 HTML把连接器型号包进a href...链接最终 SVG/PNG 会呈现可点击的型号文字依赖 GraphViz HTML 标签渲染。菊花链 variant 1X1→W1→X2→W2→X3 依次串接W1、W2 均从模板生成、带type: I2C总线类型标注。Example 06ex06.yml把链扩展到 6 个连接器、5 段线缆形成 X1-W1-X2、X3-W2-X2、X3-W3-X4、X5-W4-X4、X5-W5-X6 的树状/双链结构展示大规模重复结构下模板 合并键带来的极简写法整个文件仅靠两组模板便声明了 6 个同构连接器与 5 段同构线缆。七、Example 07隐藏未连接引脚ex07.yml 针对“连接器引脚很多、但实际只用几个”的场景社区贡献示例connectors: X1: type: TE 776164-1 subtype: female hide_disconnected_pins: True pincount: 35 notes: Unconnected pins are not shown X2: type: D-Sub subtype: female pincount: 9 hide_disconnected_pins: True cables: C1: wirecount: 2 gauge: 20 AWG colors: [YE, GN] length: 1 connections: - - X1: [5,6] - C1: [1,2] - X2: [7,2]要点hide_disconnected_pins: True让未参与任何连接的引脚不在图中显示35 引脚连接器只呈现实际用到的 5、6 号引脚图纸大为简化。notes字段可附加说明文字直接显示在连接器旁。两根线YE/GN20 AWG长 1 m把 X1 的 5/6 接到 X2 的 7/2展示任意引脚映射。八、Example 08在连接器与线缆中嵌入图片ex08.yml 演示 WireViz 的图片嵌入能力社区贡献并扩展在image:子键下指定src、caption与缩放高度把实物照片放进图中辅助理解物理结构connectors: Key: type: Phone Connector subtype: male 3.5 pins: [T, R, S] # custom pin names pinlabels: [Dot, Dash, Ground] show_pincount: false image: src: resources/stereo-phone-plug-TRS.png caption: Tip, Ring, and Sleeve cables: W1: gauge: 24 AWG length: 0.2 color: BK # Cable jacket color color_code: DIN wirecount: 3 shield: SN # Matching the shield color in the image image: src: resources/cable-WHBNGNshield.png height: 70 # Scale the image size slightly down caption: Cross-section connections: - - Key: [S,R,T] - W1: [WH,BN,GN] - - Key: S - W1: s要点pins:自定义引脚名3.5 mm 耳机插头用 TTip、RRing、SSleeve命名引脚与pinlabels的 Dot/Dash/Ground 语义标签解耦。show_pincount: false隐藏引脚数量标注。线缆图片与屏蔽颜色shield: SN银色与图片中屏蔽层颜色一致color: BK是线缆外皮颜色注意与内部芯线颜色color_code: DIN相互独立。image.height缩放按像素高度缩放图片避免图片过大。按颜色名接线连接段W1: [WH,BN,GN]直接用 DIN 颜色缩写引用芯线无需关心内部编号。关于图片嵌入的更多细节如相对路径解析、HTML 输出中的内联处理可参阅仓库 docs/advanced_image_usage.md。九、Example 09大引脚数连接器与 48 引脚阵列ex09.yml 展示高引脚数场景25 引脚的 D-Sub 与 48 引脚的 F48 对连通过pins:显式列出引脚名不必连续编号connectors: X1: type: D-Sub subtype: male pincount: 25 pins: [1,14,3,16,5,18,7,20,9,22,11,24,13] pinlabels: [SENSE_P_1, SENSE_N_1, ..., GND] X2: type: F48 subtype: female pincount: 48 pins: [z2,b2,d2,z4,b4,d4, ..., z32,b32,d32] cables: W1: gauge: 0.25 mm2 length: 0.2 color_code: DIN wirecount: 12 shield: true connections: - - X1: [1,14,3,16,5,18,7,20,9,22,11,24] - W1: [2,1,4,3,6,5,8,7,10,9,12,11] - X2: [d4,z2,d10,z8,d16,z14,d20,z18,d26,z24,d32,z30] - - X1: 13 - W1: s要点pins:只显示列出的引脚48 引脚连接器仅显示pins列表中声明的 24 个引脚名图纸可控。任意交错映射12 根 DIN 标准色线把 D-Sub 的 12 个引脚按特定顺序映射到 F48 的 12 个引脚接线关系一目了然。屏蔽接 GND第二连接段把 X1 的 13 号引脚GND接到 W1 屏蔽层。十、Example 10CAT5e 交叉线T568A 颜色编码ex10.yml 是网络工程中最常见的场景之一——RJ45 交叉线crossover cableconnectors: X1: type: Stewart Connector SS-37000-002 subtype: male pinlabels: [DA,DA-,DB,DC,DC-,DB-,DD,DD-] X2: type: Stewart Connector SS-37000-002 subtype: male pinlabels: [DB,DB-,DA,DD,DD-,DA-,DC,DC-] cables: W1: color_code: T568A # auto-color wires based on a standard wirecount: 8 gauge: 24 AWG length: 1 shield: false type: CAT5e connections: - - X1: [1-8] - W1: [1-8] - X2: [3,6,1,7,8,2,4,5] # crossover要点color_code: T568A除 IEC、DIN 外WireViz 还内置 TIA/EIA 568 A/B 及 25-Pair 等网线配色标准见仓库 docs/README.md 功能列表配合wirecount: 8得到标准 8 芯网线配色。交叉映射X1 按 1-8 顺序接入 W1X2 侧以[3,6,1,7,8,2,4,5]重排正是 10/100BASE-T 交叉线的 1↔3、2↔6 互换图中同时包含 4/5↔7/8 的全交叉。线缆类型标注type: CAT5e把型号信息写到图中线缆上。十一、Example 11 与 12裸线直连、单向/双向端子排Example 11ex11.yml不依赖外部线缆用连接器自带裸线 端子 单向接线箭头--完成供电connectors: X1: X type: Screw connector subtype: male color: GN pincount: 4 pinlabels: [A, B, C, D] F: style: simple type: Ferrule color: GY cables: W: color: BK colors: [BK, WH, BU, BN] connections: - # ferrules connector X1 - W.W1: [1-4] - F. - -- - X1: [1-4]要点无 gauge/wirecount 的裸线cables.W只给出colors4 根线直接挂在连接器 X1 上。--单向接线箭头明确表示“从线缆经端子压接后插入螺钉端子”图形上呈现方向性。W.W1点号语法自动为 W 生成实例 W1F.则按上下文自动压接端子。Example 12ex12.yml与之对称使用表示双向跨接端子排connectors: X1: dupont type: Dupont 2.54mm subtype: male pincount: 5 color: BK X2: : *dupont subtype: female cables: W: category: bundle colors: [RD, BK, BU, GN] length: 0.2 connections: - - W.W1: [1-4] - X1: [1-4] - - X2: [1-4] - W.W2: [1-4]要点一根 4 芯 bundle 的两段W1 公头侧、W2 母头侧经跨接端子排贯通红色/黑色/蓝色/绿色四色一一对应演示“公头—端子排—母头”的中间转接形态。十二、Example 13多实例自动编号X.X1 语法ex13.yml 解决“同型连接器/线缆出现多次、逐个命名繁琐”的问题演示实例自动生成与已生成实例复用connectors: X: pincount: 4 pinlabels: [A, B, C, D] F: style: simple type: ferrule cables: C: wirecount: 4 color_code: DIN connections: - - X.X1: [1-4] # auto-generate instance X1 of X - C.C1: [1-4] - [F.F1, F.F2, F.F3, F.F4] # generate new instances of F and assign designators - C.C2: [1-4] - X.X2: [1-4] - - [F1, F2, F3, F4] # reuse previously assigned designators - C.C3: [1-4] - X.X3: [1-4]要点X.X1点号自动生成为连接器 X 生成新实例 X1同理C.C1、C.C2生成线缆实例。方括号批量实例[F.F1, F.F2, F.F3, F.F4]一次生成 4 个端子实例并显式命名。已命名实例直接复用第二连接段用[F1, F2, F3, F4]引用第一段生成的端子无需再次声明。整体呈现 X1—C1—F1..F4—C2—X2 的端子排转接以及 F1..F4—C3—X3 的续接链路。十三、Example 14拼接Splice、压接与对接的综合大示例ex14.yml 是画廊中语法最丰富的综合示例把模板、自动实例、拼接、压接、对接mate与方向箭头全部串联connectors: JSTMALE: JST_SM type: JST SM subtype: male pincount: 4 pinlabels: [A, B, C, D] JSTFEMALE: : *JST_SM subtype: female X4: type: Screw terminal connector pincount: 4 color: GN pinlabels: [W, X, Y, Z] S: style: simple type: Splice color: CU F: style: simple type: Ferrule color: GY cables: CABLE: wirecount: 4 color_code: DIN length: 0.1 WIRE: wirecount: 1 colors: [BK] length: 0.1 connections: - - JSTMALE.X1: [4-1] # . syntax to generate a new instance of JSTMALE, named X1 - CABLE.W1: [1-4] - [S., S., S.S1, S.] # splice W1 and W2 together; only wire #3 needs a user-defined designator - CABLE.W2: [1-4] - S. # test shorthand, auto-get required number of ferrules from context - CABLE.W21: [1-4] - JSTFEMALE.X2: [1-4] - # mate X2 and X3 - JSTMALE.X3: [1-4] - CABLE.W3: [1-4] - [F., F., F., F.] - -- # insert ferrules into screw terminal connector - X4: [2,1,4,3] - - S1: [1] # reuse previously generated splice - WIRE.: [1] # auto-generate a simple wire instance - X2: [4]要点模板 反向接线JSTMALE.X1: [4-1]既自动生成 X1 实例又用反向列表[4-1]表示 4→3→2→1 的倒序接线。拼接 Splice[S., S., S.S1, S.]声明拼接点其中第 3 号拼接显式命名为 S1其余自动生成随后- S1: [1]直接复用该拼接。对接符号表示 X2 与 X3 公母对插mate图形呈现插接关系。压接与插入[F., F., F., F.]按 4 根线自动生成 4 个端子--表示压接端子插入 X4 螺钉端子排引脚顺序[2,1,4,3]交叉。混合实例语法X4 只使用一次因此直接用固定设计符而 JST 连接器、CABLE、WIRE 均通过.语法按需生成体现了 WireViz 设计符管理的三种方式固定命名、自动生成、显式批量生成。十四、从画廊到实战把示例迁移到自己的线束文档看完 14 个示例可以总结出一条清晰的实战迁移路径起步复制 ex01.yml 的骨架connectors / cables / connections 三段式替换为自己的连接器型号、引脚标签与线缆规格。减少重复凡出现“多个同型连接器或线缆”立即采用 YAML 锚点 合并键模板参考 ex02/ex05/ex06/ex14配合X.X1、F.点号自动实例语法ex13/ex14。规范配色根据线缆用途选择color_codeIEC / DIN / T568A / 25-Pair并在多色场景善用colors列表自动循环ex01/ex03/ex10。特殊结构多线一束用category: bundleex03端子用style: simple--/方向接线ex04/ex11/ex12拼接用 Splice 与[S., S., ...]语法ex14公母对接用ex14。图纸瘦身大引脚连接器用hide_disconnected_pins: Trueex07、pins:精选引脚ex09、show_pincount: falseex08。可视化增强用image:嵌入实物照片并配captionex08用notes添加说明ex07用type:标注线缆/总线类型ex01/ex05/ex10。交付物运行wireviz 你的文件.yml生成.gv/.svg/.png/.bom.tsv/.html全套产物见仓库 docs/README.md 的 Usage 一节需要批量重建时参考 docs/buildscript.md 运行 build_examples.py。十五、配套学习资源语法手册docs/syntax.md 是 WireViz 全部语法特性的权威参考画廊中每个示例的写法都能在其中找到对应说明。入门教程tutorial/readme.md 提供从零开始的 8 讲教程tutorial01–tutorial08与本文的示例画廊互为补充。演示文件demo01.yml 与 demo02.yml 是更完整的端到端演示含 BOM 与 HTML 输出。图片嵌入进阶docs/advanced_image_usage.md 详解image:配置的更多用法。构建脚本说明docs/buildscript.md 介绍build_examples.py的参数与重建流程。变更记录docs/CHANGELOG.md 记录了语法与功能的历史演进。将上述 14 个示例逐一跑通、对照 exXX.yml 与 exXX.bom.tsv 理解输入与产物之间的对应关系你就能把 WireViz 无缝应用到自己的线束与线缆文档化工作中。赞分享开发工具CLI硬件开发【免费下载链接】WireVizEasily document cables and wiring harnesses.项目地址https://gitcode.com/gh_mirrors/wi/WireViz点击查看免费下载相关推荐WatchYourLAN 网络 IP 扫描器部署完整指南从一条命令启动到 VLAN 扫描与监控接入WatchYourLAN 网络 IP 扫描器部署完整指南从一条命令启动到 VLAN 扫描与监控接入 WatchYourLAN 是一款 Go 语言编写的轻量网络运维网络PDF补丁丁免安装PDF工具箱修书签、统一页面尺寸、合并拆分一次搞定PDF补丁丁免安装PDF工具箱修书签、统一页面尺寸、合并拆分一次搞定 刚下手的扫描版电子书没有目录翻页全靠拖进度条想打印一份资料阅读器却弹出禁止打印桌面应用文档Gensim 文档示例画廊Sphinx Gallery机制全解析从脚本到 HTML 与 Notebook 的自动化文档流水线Gensim 文档示例画廊Sphinx Gallery机制全解析从脚本到 HTML 与 Notebook 的自动化文档流水线 本文以 docs/src/g人工智能NLP机器学习深度学习上一篇gogcli 数据验证清理实战深入解析 gog sheets validation clear 命令与表格下拉列降级机制下一篇dlt 集成 DuckLake 目标基于 DuckDB 引擎与 SQL Catalog 的湖仓式数据加载实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考