手动编程与编辑工具
=====================

本节概述自动编程完成后从标记对齐、模板审查、手动补录的完整操作讲解。

.. contents::
   :local:
   :depth: 1

标记 / 对齐 PCB
-----------------

用于检测阶段的 PCB 位置对齐。因为在检测阶段，PCB 可能存在位置偏移或轻微旋转，标记对齐可以自动将图像对齐至同一位置，确保检测的准确性。

点击“+ 标记”，框选 PCB 上固定的2个参考标记（圆形、矩形或复杂图案均可）。

框选区域应略大，以保证轻微位移仍能正确定位。确认后点击“预测中心”完成标记定义。

.. image:: images/mark_alignment.png
	:scale: 50%
	:alt: 标记对齐示例

模板编辑器
-------------

模板编辑器的左侧为自动编程生成的元件列表；若已上传 CAD，元件名称会同时显示丝印/标识。点击料号或封装即可自动分组同类别元件。

    .. image:: images/component_list.png
        :scale: 100%
        :alt: 元件列表示例  

当进入模板编辑器时，若存在不健康元件，系统会弹出警告提示：

    .. image:: images/warning.png
        :scale: 80%
        :alt: 警告示例

点击“确认”后可以继续操作。

可使用搜索栏按名称搜索，或者按评估通过/不通过、健康/不健康过滤：

    .. image:: images/search.png
        :scale: 100%
        :alt: 搜索示例

健康性核对
-----------------

训练前检查：

1. 基础信息：确认，或者按需录入 标识（丝印）、封装、料号（PN）。

    .. image:: images/edit_component_info.png
        :scale: 80%
        :alt: 组件属性填写示例

2. 全板预览：是否存在缺失、漂移、超大/超小框。
3. 局部密集区：是否重叠、是否覆盖相邻器件。
4. 不健康列表：低置信度 / CAD 未匹配 / 尺寸异常。

    - 正确但标为不健康：若位置无误可点击列表边上的 ``?`` 直接确认恢复为健康。

        .. image:: images/unhealthy.png
            :scale: 70%
            :alt: 不健康元件示例

    - CAD 中存在但未检测：若实板缺失则忽略；若实际存在则手动补录。 

        .. image:: images/missing.png
            :scale: 60%
            :alt: 缺失标记示例

    - 自动编程误检时：删除并重新手动补录。


手动编程工具栏
-------------------

右侧工具栏包含：

.. image:: images/manual_tools.png
    :scale: 120%
    :alt: 手动编程工具栏示例

1. 选择工具：左键拖拽框选多项未分组的检测框，右键唤出菜单，可以分组合并为元件；中键拖拽平移；滚轮缩放。
2. 拖拽工具：按住任意鼠标键平移视图；滚轮缩放；用于纯浏览不影响选择。
3. 3D 视图工具（仅 3D 模式）：框选后弹出局部点云，查看局部点云质量。在右上角可以看到点云颜色的选项，可以切换为绿色，伪彩色，深度等不同的显示模式，方便查看点云细节。

    .. image:: images/3d_view.png
       :scale: 70%
       :alt: 3D 视图示意

4. 本体工具：绘制主体检测框。
5. 焊料工具：绘制焊料检测框。
6. 引脚工具：绘制整排的引脚检测框，框选后，可以右键复制 / 旋转用于其它侧。
7. 文本工具：标注丝印、字符、批次 / 日期等需要 OCR 的区域。
8. 条形码工具：绘制条形码检测区域，用于 PCB 序列号追溯。

关于快捷键，参考 :ref:`编程页面快捷键` 

2D 模式下常见封装编程示例
---------------------------

电容、电阻
~~~~~~~~~~~~~~~~~~

步骤：
   1. 选择“本体工具”框出元件主体区域（紧贴真实外廓，尽量减少空白）。
   2. 选择“焊料工具”分别框出左右（或多端）焊盘/焊点区域；

质量建议：
   - 本体框贴合元件实际形状，避免包含过多空白区域；
   - 焊料框应该紧贴焊料的爬锡区域，不确定时可以使用3D视图工具来确认；
   
   .. image:: images/program_resistor.png
      :scale: 60%
      :alt: 手动编程电容、电阻示意

分组与属性：
使用“选择工具”框选主体与全部焊料框 → 右键 “分组” 生成一个元件，填写：

   - 标识（必填，建议与丝印一致）
   - （可选）料号 / 封装
   - （可选）备注或版本号

点击“创建新元件”完成。

   .. image:: images/add_component.png
      :scale: 80%
      :alt: 手动编程工具栏


QFP 封装 IC 芯片
~~~~~~~~~~~~~~~~~~~~~~~~

步骤：
   1. 选择“本体工具”框出芯片主体（紧贴封装外沿）。
   2. 选择“IC 引脚工具”框出任意一侧整排引脚（覆盖焊盘 + 焊料 + 引脚末端区域）。
   3. 右键“复制”该引脚框，拖动至对侧或其它边；必要时使用右键旋转使其与该边引脚方向一致。

质量建议：
   - 框贴合元件实际形状，避免包含过多空白区域；

        .. image:: images/program_qfc_1.png
            :scale: 50%
            :alt: QFP 封装 IC 芯片

   - (2D) IC 引脚检测需要划分 3 个区域：焊盘、焊料、引脚末端；参见 :ref:`3.2 IC 引脚检测 v2（2D，基于颜色比例）` 以了解区域划分标准。

        .. image:: images/program_qfc_2.png
            :scale: 50%
            :alt: QFP 封装 IC 芯片

分组与属性：
   使用“选择工具”框选主体与全部焊料框 → 右键 “分组” 生成一个元件，填写：

   - 标识（必填，建议与丝印一致）
   - （可选）料号 / 封装
   - （可选）备注或版本号

点击“创建新元件”完成。

   .. image:: images/add_component.png
      :scale: 80%
      :alt: 手动编程工具栏

SOP/TSSOP 封装的存储芯片或驱动芯片
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

与 QFP 类似：本体工具框主体 → IC 引脚工具框一侧引脚后复制到另一侧 → 分组创建元件。

   .. image:: images/program_sop.png
      :scale: 80%
      :alt: SOP/TSSOP 封装示例


3D 模式下常见封装编程示例
---------------------------

电容、电阻
~~~~~~~~~~~~~~~~~~

步骤：
   1. 选择“本体工具”框出元件主体区域（紧贴真实外廓，尽量减少空白）。
   2. 选择“焊料工具”分别框出左右（或多端）焊盘/焊点区域；


质量建议：

    - 主体框应贴合元件实际形状，避免包含过多空白区域；
   
        .. image:: images/program_resistor_3d.png
            :scale: 60%
            :alt: 手动编程电容、电阻示意
    
    - 焊料框应该紧贴焊料的爬锡区域，虚线部分延展ROI一边延展到基板上，一边延展到元件表面上，不确定时可以使用3D视图工具来确认。

        .. image:: images/program_resistor_solder_3d.png
            :scale: 60%
            :alt: 手动编程电容、电阻焊料示意
        
        .. image:: images/program_resistor_solder_3d_pointcloud.png
            :scale: 60%
            :alt: 手动编程电容、电阻焊料示意

分组与属性：
使用“选择工具”框选主体与全部焊料框 → 右键 “分组” 生成一个元件，填写：

   - 标识（必填，建议与丝印一致）
   - （可选）料号 / 封装
   - （可选）备注或版本号

点击“创建新元件”完成。

   .. image:: images/add_component.png
      :scale: 80%
      :alt: 手动编程工具栏


QFP 封装 IC 芯片
~~~~~~~~~~~~~~~~~~~~~~~~

步骤：
   1. 选择“本体工具”框出芯片主体（紧贴封装外沿）。
   2. 选择“IC 引脚工具”框出任意一侧整排引脚（覆盖焊盘 + 焊料 + 引脚末端区域）。
   3. 右键“复制”该引脚框，拖动至对侧或其它边；必要时使用右键旋转使其与该边引脚方向一致。

质量建议：
   - 本体框贴合元件实际形状，避免包含过多空白区域；

        .. image:: images/program_qfc_3d.png
            :scale: 80%
            :alt: QFP 封装 IC 芯片
   
   - (3D) IC 引脚检测需要定义在爬锡区域部分，然后延展ROI延展至部分基板上

        .. image:: images/program_qfc_1_3d.png
            :scale: 80%
            :alt: QFP 封装 IC 芯片

        .. image:: images/program_qfc_2_3d.png
            :scale: 50%
            :alt: QFP 封装 IC 芯片

分组与属性：
   使用“选择工具”框选主体与全部焊料框 → 右键 “分组” 生成一个元件，填写：

   - 标识（必填，建议与丝印一致）
   - （可选）料号 / 封装
   - （可选）备注或版本号

点击“创建新元件”完成。

   .. image:: images/add_component.png
      :scale: 80%
      :alt: 手动编程工具栏

SOP/TSSOP 封装的存储芯片或驱动芯片
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

与 QFP 类似：本体工具框主体 → IC 引脚工具框一侧引脚后复制到另一侧 → 分组创建元件。

   .. image:: images/program_sop_3d.png
      :scale: 80%
      :alt: SOP/TSSOP 封装示例

   .. image:: images/program_sop_3d_2.png
      :scale: 80%
      :alt: SOP/TSSOP 封装示例

私有库
~~~~~~~~~~~~~~~~~~

编程好的元件可以添加至私有库，方便后续在其它产品中复用。

步骤：
    1. 选择已编程好的元件，右键唤出菜单，点击“添加到私有库”。

        .. image:: images/add_private_library.png
            :scale: 80%
            :alt: 私有库示意

    2. 在弹出的对话框中填写元件的封装、料号，点击“添加到私有库”完成添加。
        .. image:: images/add_private_library2.png
            :scale: 80%
            :alt: 私有库示意

    3. 在“私有库”页面可以选择元件模板, 点击 ``使用此模板`` 来添加到视图，或者删除库里的元件。

        .. image:: images/add_from_private_library.png
            :scale: 80%
            :alt: 私有库示意


训练与评估
~~~~~~~~~~~~~~~

确认全部元件后点击 ``训练`` ，耗时 ~1 分钟；完成后点击 ``自动生成检测参数`` 来基于所有元件的训练集数据分布生成检测参数。

.. image:: images/train.png
	:scale: 50%
	:alt: 训练示意

点击下方的“评估全部”按钮，对所有元件进行评估，（绿=模型预测正确 / 红=模型预测与实际不符）。

.. image:: images/eval_result.png
	:scale: 50%
	:alt: 训练示意


后续：不健康项可参考 :ref:`检测参数` 章节按需微调；修改或补录后重新训练+评估即可迭代。