【agent辅助pcb routing coding学习】实践5 kicad类按类别理解

倾心琴心2026-03-16 9:49

KiCad PCB 文件信息结构与类设计详解

概述

KiCad PCB文件包含了完整的电路板设计信息，本文档详细分析了PCB文件中9种主要信息类型在KiCad C++代码中的类表示和数据结构设计。

1. 网络定义 (Network Definitions)

核心类：NETINFO_ITEM

位置 : pcbnew/netinfo.h

类定义:

cpp 复制代码 
class NETINFO_ITEM : public BOARD_ITEM
{
private:
    int         m_netCode;         // 网络代码
    wxString    m_netname;         // 完整网络名称
    wxString    m_shortNetname;    // 简短网络名称
    wxString    m_displayNetname;  // 显示网络名称
    std::shared_ptr<NETCLASS> m_netClass;  // 网络类引用
    bool        m_isCurrent;       // 网络活跃状态
    BOARD*      m_parent;          // 父级电路板
};

关键特性:

  • 支持层次化网络名称（如/sheet/subsheet/vout）
  • 自动生成简短网络名称用于显示
  • 通过m_netClass关联网络类参数

容器类：NETINFO_LIST

位置 : pcbnew/netinfo.h

数据结构:

cpp 复制代码 
class NETINFO_LIST
{
private:
    BOARD*              m_parent;                   // 父级电路板
    NETNAMES_MAP       m_netNames;                 // 按名称索引
    NETCODES_MAP       m_netCodes;                 // 按代码索引
    int                m_newNetCode;               // 网络代码分配器
    mutable bool       m_DisplayNetnamesDirty;     // 显示名称脏标志
};

核心功能:

  • 双重索引: 同时按名称和代码索引，提高查找效率
  • 网络管理: 添加、删除、查找网络
  • 显示优化: 缓存显示网络名称，按需更新

网络连接基类：BOARD_CONNECTED_ITEM

所有需要网络连接的类（PAD、TRACK、VIA、ZONE等）都继承此类，包含：

  • NETINFO_ITEM* m_netinfo - 网络信息指针
  • int m_netCode - 网络代码
  • 网络设置和获取方法

2. 封装实例 (Footprint Instances)

核心类：FOOTPRINT

位置 : pcbnew/footprint.h

类继承 : FOOTPRINT : public BOARD_ITEM_CONTAINER, public EMBEDDED_FILES, public LIB_TREE_ITEM

核心成员变量:

cpp 复制代码 
class FOOTPRINT
{
private:
    // 定位和方向
    VECTOR2I m_pos;                 // 封装位置
    EDA_ANGLE m_orient;             // 旋转角度

    // 标识信息
    LIB_ID m_fpid;                  // 库标识符
    wxString m_libDescription;      // 库描述
    wxString m_keywords;            // 搜索关键词
    KIID m_link;                    // 逻辑链接
    KIID_PATH m_path;               // 符号路径
    wxString m_sheetname;           // 图纸名称
    wxString m_sheetfile;           // 图纸文件

    // 属性和状态
    int m_attributes;               // 属性标志位
    int m_fpStatus;                 // 自动布局状态
    int m_arflag;                   // 布线标志
    timestamp_t m_lastEditTime;     // 最后编辑时间

    // 容器成员
    std::deque<PCB_FIELD*>  m_fields;      // 字段
    std::deque<BOARD_ITEM*> m_drawings;    // 绘图项
    std::deque<PAD*>        m_pads;        // 焊盘
    std::vector<ZONE*>      m_zones;       // 区域
    std::deque<PCB_GROUP*>  m_groups;      // 组
    std::deque<PCB_POINT*>  m_points;      // 点

    // 3D模型
    std::vector<FP_3DMODEL> m_3D_Drawings; // 3D模型

    // 变体管理
    CASE_INSENSITIVE_MAP<FOOTPRINT_VARIANT> m_variants;
};

3D模型管理:

cpp 复制代码 
class FP_3DMODEL
{
public:
    VECTOR3D m_Scale;       // 缩放因子
    VECTOR3D m_Rotation;    // 旋转角度
    VECTOR3D m_Offset;      // 偏移量
    double   m_Opacity;     // 不透明度
    wxString m_Filename;    // 模型文件名
    bool     m_Show;        // 显示标志
};

封装变体:

cpp 复制代码 
class FOOTPRINT_VARIANT
{
public:
    wxString                     m_name;                    // 变体名称
    bool                         m_dnp;                     // 不装配标志
    bool                         m_excludedFromBOM;         // 排出BOM标志
    bool                         m_excludedFromPosFiles;    // 排出位置文件标志
    std::map<wxString, wxString> m_fields;                  // 字段值覆盖
};

3. 焊盘 (Pads)

核心类：PAD

位置 : pcbnew/pad.h

类继承 : PAD : public BOARD_CONNECTED_ITEM

核心成员变量:

cpp 复制代码 
class PAD
{
private:
    // 基本属性
    wxString m_number;              // 焊盘编号
    wxString m_pinFunction;         // 引脚功能
    wxString m_pinType;             // 引脚电气类型
    VECTOR2I m_pos;                 // 焊盘位置

    // 几何属性
    PADSTACK m_padStack;            // 焊盘堆栈
    PAD_ATTRIB m_attribute;         // 焊盘属性
    PAD_PROP m_property;            // 制造属性

    // 电气参数
    int m_lengthPadToDie;           // 焊盘到芯片长度
    int m_delayPadToDie;            // 传播延迟
    int m_subRatsnest;              // 子网编号

    // 缓存
    mutable std::mutex m_dataMutex;
    mutable BOX2I m_effectiveBoundingBox;
    mutable LAYER_SHAPE_MAP m_effectiveShapes;
    mutable LAYER_POLYGON_MAP m_effectivePolygons;
};

焊盘堆栈：PADSTACK

位置 : pcbnew/padstack.h

核心结构:

cpp 复制代码 
class PADSTACK
{
public:
    enum class MODE {
        NORMAL,           // 所有层形状相同
        FRONT_INNER_BACK, // 最多三种形状
        CUSTOM            // 自定义层形状
    };

    struct SHAPE_PROPS {
        PAD_SHAPE shape;           // 形状类型
        VECTOR2I size;            // 尺寸
        VECTOR2I offset;          // 偏移
        double round_rect_radius_ratio;
        double chamfered_rect_ratio;
        VECTOR2I trapezoid_delta_size;
    };

    struct COPPER_LAYER_PROPS {
        SHAPE_PROPS shape;
        std::optional<ZONE_CONNECTION> zone_connection;
        std::optional<int> thermal_spoke_width;
        std::optional<int> thermal_gap;
        std::optional<int> clearance;
    };

    struct DRILL_PROPS {
        VECTOR2I size;              // 钻孔尺寸
        PAD_DRILL_SHAPE shape;      // 钻孔形状
        PCB_LAYER_ID start;         // 起始层
        PCB_LAYER_ID end;           // 结束层
        std::optional<bool> is_filled;
        std::optional<bool> is_capped;
    };
};

焊盘形状枚举

cpp 复制代码 
enum class PAD_SHAPE {
    CIRCLE,          // 圆形
    RECTANGLE,       // 矩形
    OVAL,           // 椭圆形
    TRAPEZOID,      // 梯形
    ROUNDRECT,      // 圆角矩形
    CHAMFERED_RECT, // 倒角矩形
    CUSTOM          // 自定义形状
};

enum class PAD_ATTRIB {
    PTH,        // 镀通孔
    SMD,        // 表面贴装
    CONN,       // 连接器
    NPTH        // 非镀通孔
};

4. 轨道段 (Track Segments)

核心类：PCB_TRACK

位置 : pcbnew/pcb_track.h

类继承 : PCB_TRACK : public BOARD_CONNECTED_ITEM

核心成员变量:

cpp 复制代码 
class PCB_TRACK
{
protected:
    VECTOR2I m_Start;           // 起点
    VECTOR2I m_End;             // 终点
    int m_width;                // 宽度
    bool m_hasSolderMask;       // 阻焊层标志
    std::optional<int> m_solderMaskMargin;  // 阻焊边距
};

关键方法:

  • GetLength(): 计算轨道长度
  • GetDelay(): 计算时间延迟
  • HitTest(): 碰撞检测
  • GetEffectiveShape(): 获取几何形状

弧形轨道：PCB_ARC

类继承 : PCB_ARC : public PCB_TRACK

特殊成员:

cpp 复制代码 
class PCB_ARC : public PCB_TRACK
{
private:
    VECTOR2I m_Mid;    // 弧形中点
};

几何计算:

  • 三点定义：起点、中点、终点
  • GetRadius(): 计算半径
  • GetAngle(): 获取弧形角度
  • IsCCW(): 判断是否为逆时针弧形

5. 过孔 (Vias)

核心类：PCB_VIA

位置 : pcbnew/pcb_track.h

类继承 : PCB_VIA : public PCB_TRACK

特殊成员变量:

cpp 复制代码 
class PCB_VIA : public PCB_TRACK
{
private:
    VIATYPE m_viaType;              // 过孔类型
    PADSTACK m_padStack;            // 焊盘堆栈
    bool m_isFree;                  // 自由过孔标志
};

过孔类型枚举

cpp 复制代码 
enum class VIATYPE : int {
    THROUGH = 4,      // 通孔 - 贯穿所有层
    BURIED = 3,       // 埋孔 - 内部层连接
    BLIND = 2,        // 盲孔 - 表层到内层
    MICROVIA = 1,     // 微过孔 - 高密度板用
    NOT_DEFINED = 0   // 未定义
};

层对管理:

  • SetLayerPair(): 设置层对
  • TopLayer() / BottomLayer(): 获取顶层/底层
  • HasValidLayerPair(): 验证层对有效性

6. 填充区域 (Fill Zones)

核心类：ZONE

位置 : pcbnew/zone.h

类继承 : ZONE : public BOARD_CONNECTED_ITEM

核心成员变量:

cpp 复制代码 
class ZONE
{
protected:
    // 几何属性
    SHAPE_POLY_SET* m_Poly;              // 区域轮廓
    int m_cornerSmoothingType;           // 角点平滑类型
    unsigned int m_cornerRadius;         // 圆角半径

    // 层和优先级
    LSET m_layerSet;                     // 层集合
    unsigned m_priority;                 // 优先级

    // 网络连接
    ZONE_CONNECTION m_padConnection;     // 焊盘连接模式
    int m_thermalReliefGap;              // 热焊盘间隙
    int m_thermalReliefSpokeWidth;       // 热焊盘辐条宽度

    // 特殊功能
    bool m_isRuleArea;                   // 规则区域标志
    TEARDROP_TYPE m_teardropType;        // 泪滴类型
    wxString m_zoneName;                 // 区域名称

    // 缓存
    mutable std::mutex m_layerSetMutex;
    std::map<PCB_LAYER_ID, std::shared_ptr<SHAPE_POLY_SET>> m_FilledPolysList;
};

区域连接枚举

cpp 复制代码 
enum class ZONE_CONNECTION {
    INHERITED = -1,     // 继承默认设置
    NONE,               // 不覆盖焊盘
    THERMAL,            // 热焊盘连接
    FULL,               // 完全覆盖焊盘
    THT_THERMAL         // 仅THT焊盘热焊盘
};

区域填充器：ZONE_FILLER

核心功能:

cpp 复制代码 
class ZONE_FILLER
{
private:
    bool fillCopperZone( const ZONE* aZone, PCB_LAYER_ID aLayer,
                         SHAPE_POLY_SET& aFillPolys );

    void connect_nearby_polys( SHAPE_POLY_SET& aPolys, double aDistance );

    void buildThermalSpokes( const ZONE* aZone, PCB_LAYER_ID aLayer,
                            const std::vector<BOARD_ITEM*>& aPadsList,
                            std::deque<SHAPE_LINE_CHAIN>& aSpokes );
};

填充流程:

  1. 轮廓平滑处理
  2. 清除区域计算
  3. 热焊盘连接生成
  4. 最终填充多边形生成

7. 层定义 (Layer Definitions)

层管理系统

位置 : include/layer_ids.h

层分类:

cpp 复制代码 
// 铜层 (最多32层)
PCB_LAYER_ID F_Cu;           // 顶层
PCB_LAYER_ID In1_Cu;         // 内层1
// ... In2_Cu 到 In30_Cu
PCB_LAYER_ID B_Cu;           // 底层

// 技术层
PCB_LAYER_ID F_Mask, B_Mask;        // 阻焊层
PCB_LAYER_ID F_SilkS, B_SilkS;      // 丝印层
PCB_LAYER_ID F_Paste, B_Paste;      // 锡膏层

// 用户层
PCB_LAYER_ID Dwgs_User;             // 绘图层
PCB_LAYER_ID Cmts_User;             // 注释层
PCB_LAYER_ID Edge_Cuts;             // 边缘层
PCB_LAYER_ID User_1 到 User_45;     // 用户定义层

层集合：LSET

位置 : include/lset.h

类继承 : LSET : public BASE_SET

核心功能:

cpp 复制代码 
class LSET
{
    // 预设掩码
    static LSET AllCuMask( int aCuLayerCount );
    static LSET ExternalCuMask();
    static LSET FrontTechMask();
    static LSET BackTechMask();

    // 层序列生成
    LSEQ CuStack();           // 铜层堆叠序列
    LSEQ UIOrder();           // UI显示序列
};

特性:

  • 基于位集合的高效实现
  • 支持快速包含检查
  • 提供多种预设掩码
  • 支持层序列遍历

层属性管理

  • 固定名称: 用于文件格式兼容性
  • 显示名称: 支持本地化
  • 可见性控制: 通过GAL层系统
  • 颜色管理: 每层独立颜色设置

8. 设置和层叠 (Settings and Stackup)

设计规则：BOARD_DESIGN_SETTINGS

位置 : include/board_design_settings.h

核心参数:

cpp 复制代码 
class BOARD_DESIGN_SETTINGS
{
private:
    // 走线和过孔尺寸
    std::vector<int> m_TrackWidthList;
    std::vector<VIA_DIMENSION> m_ViasDimensionsList;
    std::vector<DIFF_PAIR_DIMENSION> m_DiffPairDimensionsList;

    // 设计规则
    int m_MinClearance;              // 最小间距
    int m_TrackMinWidth;            // 最小走线宽度
    int m_ViasMinSize;              // 最小过孔尺寸
    int m_CopperEdgeClearance;      // 铜到边缘间距
    int m_SolderMaskExpansion;      // 阻焊扩展

    // 层管理
    int m_copperLayerCount;         // 铜层数量
    LSET m_enabledLayers;           // 启用层掩码
    BOARD_STACKUP m_stackup;        // 层叠管理
};

层叠管理：BOARD_STACKUP

位置 : pcbnew/board_stackup_manager/board_stackup.h

层叠项目类型:

cpp 复制代码 
enum BOARD_STACKUP_ITEM_TYPE {
    BS_ITEM_TYPE_COPPER,        // 铜层
    BS_ITEM_TYPE_DIELECTRIC,    // 介质层
    BS_ITEM_TYPE_SOLDERPASTE,   // 锡膏层
    BS_ITEM_TYPE_SOLDERMASK,    // 阻焊层
    BS_ITEM_TYPE_SILKSCREEN,    // 丝印层
};

介质层参数:

cpp 复制代码 
class DIELECTRIC_PRMS {
    wxString m_Material;         // 材料类型
    int m_Thickness;             // 厚度
    double m_EpsilonR;           // 介电常数
    double m_LossTangent;       // 损耗tangent
    wxString m_Color;            // 颜色
};

绘图参数：PCB_PLOT_PARAMS

位置 : pcbnew/pcb_plot_params.h

主要设置:

cpp 复制代码 
class PCB_PLOT_PARAMS
{
private:
    PLOT_FORMAT m_format;           // 绘图格式
    LSET m_layerSelection;          // 层选择
    DRILL_MARKS m_drillMarks;      // 钻孔标记

    // Gerber特定设置
    bool m_useGerberX2format;
    bool m_includeGerberNetlistInfo;
    int m_gerberPrecision;
};

网络类：NETCLASS

位置 : include/netclass.h

网络类参数:

cpp 复制代码 
class NETCLASS
{
private:
    std::optional<int> m_Clearance;     // 间距
    std::optional<int> m_TrackWidth;    // 走线宽度
    std::optional<int> m_ViaDia;       // 过孔直径
    std::optional<int> m_ViaDrill;     // 过孔钻孔
    std::optional<int> m_diffPairWidth; // 差分对宽度
    std::optional<int> m_diffPairGap;   // 差分对间距
    COLOR4D m_pcbColor;                // PCB颜色
};

9. 图形对象 (Graphical Objects)

图形形状：PCB_SHAPE

位置 : pcbnew/pcb_shape.h

类继承 : PCB_SHAPE : public BOARD_CONNECTED_ITEM, public EDA_SHAPE

支持的形状类型:

cpp 复制代码 
enum SHAPE_T {
    SEGMENT,     // 线段
    RECTANGLE,   // 矩形
    ARC,         // 弧形
    CIRCLE,      // 圆形
    POLY,        // 多边形
    BEZIER       // 贝塞尔曲线
};

核心属性:

cpp 复制代码 
class PCB_SHAPE
{
private:
    SHAPE_T m_shape;                // 形状类型
    STROKE_PARAMS m_stroke;         // 描边参数
    FILL_T m_fill;                  // 填充模式
    COLOR4D m_fillColor;            // 填充颜色
    VECTOR2I m_start, m_end;        // 起点和终点
    SHAPE_POLY_SET m_poly;          // 多边形形状
};

文本对象：PCB_TEXT

位置 : pcbnew/pcb_text.h

类继承 : PCB_TEXT : public BOARD_ITEM, public EDA_TEXT

核心功能:

  • 文本属性：字体、大小、颜色、样式
  • 位置变换：位置、旋转、直立保持
  • 变量处理：GetShownText() 处理文本变量
  • 多边形转换：TransformTextToPolySet()

尺寸标注：PCB_DIMENSION_BASE

位置 : pcbnew/pcb_dimension.h

支持的标注类型:

  • PCB_DIM_ALIGNED - 对齐尺寸
  • PCB_DIM_ORTHOGONAL - 正交尺寸
  • PCB_DIM_RADIAL - 径向尺寸
  • PCB_DIM_LEADER - 引导线尺寸
  • PCB_DIM_CENTER - 中心标记

核心属性:

cpp 复制代码 
class PCB_DIMENSION_BASE : public PCB_TEXT
{
private:
    DIM_UNITS_FORMAT m_unitsFormat;    // 单位格式
    DIM_PRECISION m_precision;         // 精度
    DIM_TEXT_POSITION m_textPosition;  // 文本位置
    int m_lineThickness;               // 线条粗细
    int m_arrowLength;                 // 箭头长度
};

其他图形对象

PCB_TARGET（目标标记）
cpp 复制代码 
class PCB_TARGET
{
private:
    int m_shape;        // 形状（0=+, 1=X）
    int m_size;         // 大小
    int m_lineWidth;    // 线宽
    VECTOR2I m_pos;     // 位置
};
PCB_MARKER（错误标记）
cpp 复制代码 
class PCB_MARKER : public BOARD_ITEM, public MARKER_BASE
{
private:
    std::vector<SHAPE*> m_pathShapes;  // 路径形状
};
PCB_TEXTBOX（文本框）
cpp 复制代码 
class PCB_TEXTBOX : public PCB_SHAPE, public EDA_TEXT
{
private:
    int m_marginLeft, m_marginTop;     // 边距
    int m_marginRight, m_marginBottom;
};

数据结构设计特点

1. 继承层次设计

复制代码 
EDA_ITEM (基础类)
    ↓
BOARD_ITEM (PCB项目基类)
    ↓
BOARD_CONNECTED_ITEM (有网络连接的项目)
    ↓
具体项目类 (PAD, TRACK, VIA, ZONE等)

2. 容器模式

  • BOARD: 顶层容器，包含所有PCB项目
  • FOOTPRINT: 封装容器，包含焊盘和图形
  • BOARD_ITEM_CONTAINER: 容器接口类

3. 缓存优化

  • 几何形状缓存：m_effectiveShapes
  • 边界框缓存：m_cachedBoundingBox
  • 多边形缓存：m_FilledPolysList
  • 文本缓存：m_knockout_cache

4. 智能指针使用

  • std::shared_ptr<NETCLASS>: 网络类管理
  • std::shared_ptr<SHAPE_POLY_SET>: 多边形共享
  • std::optional<T>: 可选属性管理

5. 线程安全

  • std::mutex: 互斥锁保护
  • mutable std::mutex: 缓存保护
  • 原子操作和锁分离

6. 现代C++特性

  • 强类型枚举：enum class
  • 右值引用和移动语义
  • 模板和泛型编程
  • RAII资源管理

性能优化策略

1. 内存管理

  • 对象池复用
  • 延迟加载
  • 智能指针生命周期管理

2. 渲染优化

  • LOD（细节层次）控制
  • 视口裁剪
  • 批量渲染

3. 计算缓存

  • 几何计算结果缓存
  • 脏标志机制
  • 按需计算

4. 并发处理

  • 多线程区域填充
  • 读写锁分离
  • 无锁数据结构

扩展性设计

1. 插件系统

  • 外部插件接口
  • 自定义对象支持
  • 脚本扩展能力

2. 自定义层

  • 用户定义层支持
  • 层属性自定义
  • 层显示配置

3. 网络类扩展

  • 模式匹配分配
  • 聚合网络类
  • 参数继承机制

4. 文本变量系统

  • 动态文本变量
  • 表式计算
  • 条件显示

总结

KiCad的PCB文件信息结构设计体现了现代EDA软件的复杂性和专业性：

  1. 完整性: 涵盖了PCB设计的所有方面，从网络定义到图形标注
  2. 层次性: 清晰的继承层次和容器关系
  3. 性能: 大量缓存和优化机制确保高效操作
  4. 扩展性: 支持自定义和扩展，适应不同需求
  5. 现代化: 采用现代C++特性和设计模式

这种设计使KiCad能够处理从简单的双面板到复杂的多层高速板设计的各种需求，同时保持良好的性能和用户体验。

相关推荐
Frostnova丶2 小时前
LeetCode 50. Pow(x, n)
算法·leetcode
lierenvip2 小时前
【语义分割】12个主流算法架构介绍、数据集推荐、总结、挑战和未来发展
算法·架构
三块可乐两块冰2 小时前
机器学习笔记一
笔记·算法·机器学习
海兰2 小时前
OpenClaw安全保命指南：Skill 插件投毒风险全解析及应对措施
人工智能·安全·agent·openclaw
凤年徐2 小时前
优选算法——滑动窗口2
数据结构·c++·算法
安之若素.re2 小时前
827. 最大人工岛
算法·深度优先
吴佳浩2 小时前
大模型垂直领域微调系列（二）：ms-swift 框架全景
算法
哈里谢顿2 小时前
人工智能公开课学习目录
agent
DeepModel2 小时前
【概率分布】泊松分布的原理、推导与实战应用
python·算法·概率论
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04OpenClaw macOS 完整安装与本地模型配置教程（实战版）05本地部署 OpenClaw + DeepSeek-R1 完全指南06UV安装并设置国内源07Openclow安装保姆级教程08OpenClaw 飞书机器人不回复消息？3 小时踩坑总结09OpenClaw Control UI安全上下文访问配置10在 Windows 上配置 Claude Code从安装到解决网络问题