KiCad 全局标签批量生成工具

基于Python的KiCad全局标签生成工具

基于 Python 从 Excel 读取标签名称，自动生成多列布局的 KiCad 全局标签，支持自定义坐标与分组规则，适配双侧/单侧两种布局模式。生成文件为.kicad_sch格式。

一、工具功能

1. 批量生成：从 Excel 读取标签名称，自动生成符合 KiCad 9.0+ 格式的全局标签，无需手动创建每个标签。
2. 双布局模式：
   • 双侧模式：标签按"左-右"成对分布在同一行，左侧标签180°旋转、右对齐，右侧标签0°旋转、左对齐。
   • 单侧模式：支持按指定数量分组（如20个/列），列间X坐标自动递增，适配大量标签的规整排列。
3. 高度自定义：可设置基础坐标（X/Y起始值）、行间距、列间距、字体大小等参数，灵活适配不同尺寸的原理图（如A4/A3）。
4. 智能容错：自动处理Excel中shape列的空值、不合法值，默认替换为input；参数不合法时自动修正（如列数<1时重置为1）。
5. 冲突规避：每个标签自动生成唯一UUID，避免KiCad中标签ID冲突导致的加载异常。

二、环境准备

1. Python环境：确保本地安装 Python 3.6+（推荐 3.8~3.11，兼容性最佳）。
2. 安装依赖库：打开终端/命令提示符，执行以下命令安装必备库：

   pip install pandas openpyxl numpy
   

   • pandas：核心数据处理库，用于读取和解析Excel数据。
   • openpyxl：支持读取.xlsx格式Excel文件（必装，否则无法解析Excel）。
   • numpy：辅助处理Excel中的空值（NaN），增强数据容错性。
3. KiCad版本：适配 KiCad 9.0+（测试版本：9.0.4），低版本可能存在原理图格式兼容性问题。

三、文件准备

1. Excel 数据格式

需创建 .xlsx 文件，必须包含 name 列（用于定义KiCad全局标签的名称），可选配置 shape 列（标签类型）。

1.1 基础必填格式（仅含name列）

name
MOD_VCC_3V3
MOD_GND_MAIN
MOD_SDA
MOD_SCL
MOD_RST_N
MOD_INT_N
MOD_TXD
MOD_RXD

1.2 完整可选格式（含name+shape列）

name	shape
MOD_VCC_3V3	input
MOD_GND_MAIN	input
MOD_SDA	input
MOD_SCL	input
MOD_RST_N	output
MOD_INT_N	output
MOD_TXD	output
MOD_RXD	input

• 字段说明：
  • name：必填，标签名称需符合KiCad规范（建议含模块前缀，如MOD_，避免与其他模块冲突）。
  • shape：可选，仅支持input（输入）或output（输出），空值/不合法值会自动替换为默认值input。

2. 脚本文件

将完整代码保存为 generate_optimized_kicad_sch.py（代码见文末，含示例表格注释）。

四、使用步骤

1. 配置核心参数

用记事本/VS Code等工具打开脚本，找到 if __name__ == "__main__": 代码块，根据需求修改以下参数：

if __name__ == "__main__":
    # 1. 文件路径配置（Windows路径用双反斜杠\\，macOS/Linux用正斜杠/）
    EXCEL_PATH = r"D:\PCB\project\doc\global_labels.xlsx"  # 你的Excel文件路径
    OUTPUT_SCH_PATH = r"D:\PCB\project\doc\generated_labels.kicad_sch"  # 输出的KiCad原理图路径

    # 2. 布局与坐标参数配置（根据需求选择模式并调整）
    generate_optimized_kicad_sch(
        excel_file=EXCEL_PATH,
        output_file=OUTPUT_SCH_PATH,
        layout_mode="two_side",     # 布局模式：two_side（双侧）/ one_side（单侧）
        # -------------------------- 双侧模式专属参数 --------------------------
        left_x=137,                 # 左侧标签的X坐标（双侧模式生效）
        right_x=152.24,             # 右侧标签的X坐标（双侧模式生效）
        # -------------------------- 单侧模式专属参数 --------------------------
        single_side_x=144.62,       # 单侧模式的起始X坐标（单侧模式生效）
        cols_in_one_side=20,        # 单侧模式每列显示的标签数量（如20个/列）
        col_spacing=15,             # 单侧模式下列与列的X间距（每列右移15个单位）
        # -------------------------- 通用参数 --------------------------
        start_y=15,                 # 所有标签的起始Y坐标（第一行的Y值）
        y_row_spacing=2.54,         # 同一列/同一行内标签的Y间距（默认2.54，即100mil）
        default_shape="input",      # 当shape列空/不合法时的默认值
        font_size=1.27,             # 标签字体大小（默认1.27，即50mil）
        paper_size="A4"             # 原理图图纸尺寸（支持A4/A3/A2/A1）
    )

2. 运行脚本

方式1：双击运行（简单）

直接双击 generate_optimized_kicad_sch.py 文件（需确保Python已关联.py后缀，首次运行可能需选择"打开方式"为Python）。

方式2：终端运行（推荐，便于查看日志）

1. 打开终端，进入脚本所在文件夹（示例：cd D:\PCB\scripts）。
2. 执行命令：

   python generate_optimized_kicad_sch.py
   

运行成功日志示例

✅ 成功读取Excel文件: D:\PCB\project\doc\global_labels.xlsx，共8条标签记录
ℹ️ Excel缺少'shape'列，所有标签将使用默认形状: input

✅ 原理图生成成功！文件路径：
D:\PCB\project\doc\generated_labels.kicad_sch
📌 当前配置：
- 布局模式：two_side
- 坐标范围：左X=137.0000, 右X=152.2400, 起始Y=15.0000, 行间距=2.54

3. 导入KiCad原理图

无需复杂操作，直接使用生成的.kicad_sch文件即可：

1. 打开KiCad原理图编辑器（Eeschema）。
2. 点击菜单栏「File」→「Open」，选择生成的generated_labels.kicad_sch文件。
3. 标签会自动按配置的坐标排列，可手动拖动个别标签微调位置（如需调整）。

五、核心参数说明

参数名称	作用说明	适用模式	默认值	调整建议
layout_mode	布局模式：双侧（two_side）/单侧（one_side）	所有	“two_side”	标签数量≤20选双侧，＞20选单侧多列布局
left_x	双侧模式下左侧标签的X坐标	two_side	137	建议与原理图左侧边框保持5~10单位间距
right_x	双侧模式下右侧标签的X坐标	two_side	152.24	建议与原理图右侧边框保持5~10单位间距
single_side_x	单侧模式的起始X坐标（第一列X值）	one_side	144.62	从原理图左侧10~20单位开始，避免贴边
cols_in_one_side	单侧模式每列显示的标签数量	one_side	1	建议≤20（避免单列过长超出A4图纸高度）
col_spacing	单侧模式下列与列的X间距	one_side	20	根据标签名称长度调整（名称长则增大间距，避免重叠）
start_y	所有标签的起始Y坐标（第一行Y值）	所有	15	从图纸顶部15~20单位开始，避免与标题栏重叠
y_row_spacing	同一列/行内标签的Y间距	所有	2.54	字体大小1.27时用2.54（无重叠），字体大则增大
default_shape	shape列空/不合法时的默认值	所有	“input”	输入信号用input，输出信号用output
font_size	标签字体大小（单位：mm）	所有	1.27	原理图尺寸A4建议1.27，A3可增大至1.5~2.0
paper_size	原理图图纸尺寸	所有	“A4”	标签数量＞50时选A3，否则A4足够

六、常见问题与解决方法

1. Excel读取失败

• 错误提示：❌ 读取Excel失败: [Errno 2] No such file or directory
  解决：检查EXCEL_PATH路径是否正确（Windows用\\，如D:\\PCB\\labels.xlsx；确保Excel文件未被打开）。

• 错误提示：❌ Excel缺少必要列: 'name'
  解决：在Excel中添加name列，确保列名拼写正确（小写name，无空格）。

2. 标签重叠

• 双侧模式重叠：增大y_row_spacing（如从2.54调整为3.0），或调整left_x/right_x增大左右标签间距。
• 单侧模式重叠：增大col_spacing（如从15调整为20），或减少cols_in_one_side（如从20改为15）。

3. KiCad打开文件提示"格式错误"

• 解决：1. 确认KiCad版本为9.0+；2. 重新运行脚本生成文件（可能因中断导致文件不完整）。

4. 脚本运行提示"缺少openpyxl"

• 解决：执行pip install openpyxl安装依赖（读取.xlsx文件必需）。

七、完整代码（含示例表格注释）

import pandas as pd
import uuid
import os
import numpy as np

def generate_optimized_kicad_sch(
    excel_file, 
    output_file=None, 
    layout_mode="two_side",  # 布局模式：two_side（两侧）/ one_side（单侧）
    left_x=137,             # 左侧标签X坐标（双侧模式）
    right_x=152.24,         # 右侧标签X坐标（双侧模式）
    single_side_x=144.62,   # 单侧模式起始X坐标
    start_y=15,             # 起始Y坐标
    y_row_spacing=2.54,     # 行与行之间的Y间距
    default_shape="input",  # 当shape不合法时的默认值
    font_size=1.27,         # 字体大小
    paper_size="A4",        # 图纸尺寸
    cols_in_one_side=1,     # 单侧模式下的列数（每列显示的标签数量）
    col_spacing=20          # 单侧模式下列之间的X偏移量
):
    """
    生成优化后的KiCad原理图文件(.kicad_sch)
    支持Excel中设置输入输出选项
    - 双侧模式：每2个标签在同一行左右分布（左：180°旋转+右对齐；右：0°旋转+左对齐）
    - 单侧模式：支持多列布局，可指定每列数量和列偏移

    【Excel示例表格格式】
    1. 基础必填格式（仅name列）：
    | name               |
    |--------------------|
    | MOD_VCC_3V3        |
    | MOD_GND_MAIN       |
    | MOD_SDA            |
    | MOD_SCL            |
    | MOD_RST_N          |
    | MOD_INT_N          |
    | MOD_TXD            |
    | MOD_RXD            |

    2. 完整可选格式（含shape列）：
    | name               | shape  |
    |--------------------|--------|
    | MOD_VCC_3V3        | input  |
    | MOD_GND_MAIN       | input  |
    | MOD_SDA            | input  |
    | MOD_SCL            | input  |
    | MOD_RST_N          | output |
    | MOD_INT_N          | output |
    | MOD_TXD            | output |
    | MOD_RXD            | input  |

    参数说明：
    - excel_file: Excel文件路径（.xlsx格式）
    - output_file: 输出的.kicad_sch文件路径（默认与Excel同目录、同名）
    - layout_mode: 布局模式（two_side/one_side）
    - 其他参数：见"核心参数说明"章节，根据需求调整
    """
    # 验证参数的有效性
    if cols_in_one_side < 1:
        print(f"⚠️ 列数设置不合法({cols_in_one_side})，自动调整为1")
        cols_in_one_side = 1
    
    if col_spacing <= 0:
        print(f"⚠️ 列间距设置不合法({col_spacing})，自动调整为20")
        col_spacing = 20

    # 验证默认形状是否合法
    valid_shapes = ["input", "output"]
    if default_shape not in valid_shapes:
        print(f"⚠️ 默认形状设置不合法({default_shape})，自动调整为'input'")
        default_shape = "input"

    # -------------------------- 1. 读取Excel数据 --------------------------
    try:
        # 用openpyxl引擎读取.xlsx文件，避免格式兼容问题
        df = pd.read_excel(excel_file, engine="openpyxl")
        print(f"✅ 成功读取Excel文件: {excel_file}，共{len(df)}条标签记录")
    except Exception as e:
        print(f"❌ 读取Excel失败: {str(e)}（请检查路径是否正确，文件是否未被打开）")
        return

    # 检查必要列：必须包含"name"（标签名称）
    required_col = "name"
    if required_col not in df.columns:
        print(f"❌ Excel缺少必要列: '{required_col}'（需手动添加列，填写标签名称如MOD_VCC_3V3、MOD_GND）")
        return

    # 处理shape列：确保值为input或output，否则使用默认值
    if "shape" not in df.columns:
        df["shape"] = default_shape
        print(f"ℹ️ Excel缺少'shape'列，所有标签将使用默认形状: {default_shape}")
    else:
        # 处理空值、NaN和不合法的shape值
        invalid_count = 0
        
        def process_shape(shape_value):
            nonlocal invalid_count
            # 检查空值、NaN或空白字符串
            if pd.isna(shape_value) or str(shape_value).strip() == "":
                invalid_count += 1
                return default_shape
            # 检查是否为合法值（不区分大小写）
            lower_shape = str(shape_value).lower().strip()
            if lower_shape in valid_shapes:
                return lower_shape
            else:
                invalid_count += 1
                return default_shape
        
        df["shape"] = df["shape"].apply(process_shape)
        
        if invalid_count > 0:
            print(f"⚠️ 发现{invalid_count}个不合法或空的shape值，已自动替换为默认值: {default_shape}")

    # 根据布局模式设置对齐方式和旋转角度
    if layout_mode == "two_side":
        # 双侧模式: 左侧标签right对齐, 180度旋转; 右侧标签left对齐, 0度旋转
        df["justify"] = df.index.map(lambda i: "left" if i % 2 == 1 else "right")
        df["rotation"] = df.index.map(lambda i: 0 if i % 2 == 1 else 180)
    else:  # one_side模式
        # 单侧模式: 所有标签使用相同对齐方式和旋转角度
        df["justify"] = "left"  # 统一左对齐
        df["rotation"] = 0      # 统一0度旋转

    # -------------------------- 2. 生成全局标签内容 --------------------------
    global_labels = []

    for label_idx, (_, row) in enumerate(df.iterrows()):        
        # 计算当前Y坐标和X坐标
        if layout_mode == "two_side":
            # 双侧模式: 每2个标签共享一行
            row_idx = label_idx // 2  # 行索引（0,0,1,1,2,2...）
            position_in_row = label_idx % 2  # 行内位置（0:左,1:右）
            current_y = start_y + (row_idx * y_row_spacing)
            # 确定X坐标
            current_x = right_x if position_in_row == 1 else left_x
        else:  # one_side模式
            # 单侧模式: 支持多列布局
            col_idx = label_idx // cols_in_one_side  # 列索引
            row_idx = label_idx % cols_in_one_side   # 行索引（在当前列中的位置）
            current_y = start_y + (row_idx * y_row_spacing)
            # 计算X坐标：起始X + 列索引 * 列间距
            current_x = single_side_x + (col_idx * col_spacing)

        # 计算"Intersheetrefs"属性的X坐标
        if row["justify"] == "left":
            prop_x = current_x + 8.9119  # 左对齐标签属性右移
        else:  # right
            prop_x = current_x - 8.9119  # 右对齐标签属性左移

        # 生成唯一UUID
        label_uuid = str(uuid.uuid4())

        # 构建标签格式
        label_content = f'\t(global_label "{row["name"]}"\n'
        label_content += f'\t\t(shape {row["shape"]})\n'
        label_content += f'\t\t(at {current_x:.4f} {current_y:.4f} {row["rotation"]})\n'
        label_content += f'\t\t(fields_autoplaced yes)\n'
        label_content += f'\t\t(effects\n'
        label_content += f'\t\t\t(font\n'
        label_content += f'\t\t\t\t(size {font_size} {font_size})\n'
        label_content += f'\t\t\t)\n'
        label_content += f'\t\t\t(justify {row["justify"]})\n'
        label_content += f'\t\t)\n'
        label_content += f'\t\t(uuid "{label_uuid}")\n'
        label_content += f'\t\t(property "Intersheetrefs" "${{INTERSHEET_REFS}}"\n'
        label_content += f'\t\t\t(at {prop_x:.4f} {current_y:.4f} 0)\n'
        label_content += f'\t\t\t(effects\n'
        label_content += f'\t\t\t\t(font\n'
        label_content += f'\t\t\t\t\t(size {font_size} {font_size})\n'
        label_content += f'\t\t\t\t)\n'
        label_content += f'\t\t\t\t(justify {row["justify"]})\n'
        label_content += f'\t\t\t\t(hide yes)\n'
        label_content += f'\t\t\t)\n'
        label_content += f'\t\t)\n'
        label_content += f'\t)'

        global_labels.append(label_content)

    # -------------------------- 3. 构建完整原理图结构 --------------------------
    current_date = "20250114"  # 固定版本日期，确保兼容性
    sch_uuid = str(uuid.uuid4())

    sch_content = f'(kicad_sch\n'
    sch_content += f'\t(version {current_date})\n'
    sch_content += f'\t(generator "eeschema")\n'
    sch_content += f'\t(generator_version "9.0")\n'
    sch_content += f'\t(uuid "{sch_uuid}")\n'
    sch_content += f'\t(paper "{paper_size}")\n'
    sch_content += f'\t(lib_symbols)\n'

    # 插入所有全局标签
    sch_content += "\n\n".join(global_labels) + "\n"

    # 尾部信息
    sch_content += f'\t(sheet_instances\n'
    sch_content += f'\t\t(path "/"\n'
    sch_content += f'\t\t\t(page "1")\n'
    sch_content += f'\t\t)\n'
    sch_content += f'\t)\n'
    sch_content += f'\t(embedded_fonts no)\n'
    sch_content += f')'

    # -------------------------- 4. 保存文件 --------------------------
    if output_file is None:
        excel_name = os.path.splitext(os.path.basename(excel_file))[0]
        output_file = f"{excel_name}.kicad_sch"

    try:
        with open(output_file, "w", encoding="utf-8") as f:
            f.write(sch_content)
        print(f"\n✅ 原理图生成成功！文件路径：\n{os.path.abspath(output_file)}")
        print(f"📌 当前配置：\n- 布局模式：{layout_mode}")
        if layout_mode == "two_side":
            print(f"- 坐标范围：左X={left_x:.4f}, 右X={right_x:.4f}, 起始Y={start_y:.4f}, 行间距={y_row_spacing}")
        else:
            print(f"- 坐标范围：起始X={single_side_x:.4f}, 起始Y={start_y:.4f}")
            print(f"- 列配置：列数={cols_in_one_side}, 列间距={col_spacing}, 行间距={y_row_spacing}")
    except Exception as e:
        print(f"❌ 保存文件失败: {str(e)}")
        return

# -------------------------- 运行入口 --------------------------
if __name__ == "__main__":
    # 1. 文件路径配置（Windows路径用双反斜杠\\，macOS/Linux用正斜杠/）
    EXCEL_PATH = r"D:\PCB\project\doc\global_labels.xlsx"  # 你的Excel文件路径
    OUTPUT_SCH_PATH = r"D:\PCB\project\doc\generated_labels.kicad_sch"  # 输出的KiCad原理图路径

    # 2. 布局与坐标参数配置（根据需求选择模式并调整）
    generate_optimized_kicad_sch(
        excel_file=EXCEL_PATH,
        output_file=OUTPUT_SCH_PATH,
        layout_mode="two_side",     # 布局模式：two_side（双侧）/ one_side（单侧）
        # -------------------------- 双侧模式专属参数 --------------------------
        left_x=137,                 # 左侧标签的X坐标（双侧模式生效）
        right_x=152.24,             # 右侧标签的X坐标（双侧模式生效）
        # -------------------------- 单侧模式专属参数 --------------------------
        single_side_x=144.62,       # 单侧模式的起始X坐标（单侧模式生效）
        cols_in_one_side=20,        # 单侧模式每列显示的标签数量（如20个/列）
        col_spacing=15,             # 单侧模式下列与列的X间距（每列右移15个单位）
        # -------------------------- 通用参数 --------------------------
        start_y=15,                 # 所有标签的起始Y坐标（第一行的Y值）
        y_row_spacing=2.54,         # 同一列/同一行内标签的Y间距（默认2.54，即100mil）
        default_shape="input",      # 当shape列空/不合法时的默认值
        font_size=1.27,             # 标签字体大小（默认1.27，即50mil）
        paper_size="A4"             # 原理图图纸尺寸（支持A4/A3/A2/A1）
    )