yw1573/A1SwapModPacker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: 为全部13个源码模块和5个测试文件添加简体中文注释

Browse Source 
- 每个文件补充模块级 docstring、类/函数 docstring、关键逻辑行内注释
- 注释风格："中文说明" 或 # 中文说明
- 代码结构和逻辑完全不变
This commit is contained in:
yw1573
2026-07-28 09:39:55 +08:00
parent b7a6f42189
commit 4ae33cbe53
18 changed files with 1528 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
a1_swap_mod_packer/gui.py
+233 -20
View File
@@ -1,3 +1,15 @@
"""
A1 SwapMod Packer 的 PySide6 图形用户界面模块。
提供完整的桌面 GUI，用于：
- 拖放/添加多个 .3mf 输入文件
- 配置换料 G-code、打包选项、输出规则
- 单个或批量构建打包的 3MF 文件
- 显示板缩略图预览、合计统计和构建日志
主入口为 ``main()`` 函数，启动 QApplication 并显示 ``MainWindow``。
"""
from __future__ import annotations
import json
@@ -10,6 +22,7 @@ from multiprocessing import freeze_support
from pathlib import Path
from typing import Any, Callable
# --- 平台适配：Windows 下使用 FreeType 字体引擎以避免字体渲染问题 ---
if sys.platform.startswith("win") and "QT_QPA_PLATFORM" not in os.environ:
os.environ["QT_QPA_PLATFORM"] = "windows:fontengine=freetype"
@@ -71,19 +84,26 @@ from .planning import (
three_mf_summary_from_mapping,
)
SUMMARY_ROLE = Qt.UserRole + 100
PATH_ROLE = Qt.UserRole + 101
# --- 自定义 Qt 数据角色，用于在表格单元格中存储摘要和路径信息 ---
SUMMARY_ROLE = Qt.UserRole + 100 # 存储 ThreeMfSummary 数据的角色
PATH_ROLE = Qt.UserRole + 101 # 存储文件绝对路径的角色
ORDER_COLUMN = 0
FILE_COLUMN = 1
COPIES_COLUMN = 2
TIME_COLUMN = 3
FILAMENT_COLUMN = 4
# --- 表格列索引常量 ---
ORDER_COLUMN = 0 # 顺序列（上移/下移按钮）
FILE_COLUMN = 1 # 文件名列
COPIES_COLUMN = 2 # 份数列
TIME_COLUMN = 3 # 预估时间列
FILAMENT_COLUMN = 4 # 耗材用量列
# --- 3MF 预览图匹配正则：Metadata/plate_N.png 或 Metadata/plate_N_small.png ---
PREVIEW_IMAGE_RE = re.compile(r"^Metadata/plate_(\d+)(?:_small)?\.png$", re.IGNORECASE)
def preview_image_sort_key(member_name: str) -> tuple[int, int, str]:
"""返回预览图排序键：(是否小图, 板号, 原始名称)。
排序规则：大图优先于小图，板号升序，同号按名称排序。
"""
match = PREVIEW_IMAGE_RE.match(member_name)
plate_number = int(match.group(1)) if match else 9999
is_small = 1 if member_name.lower().endswith("_small.png") else 0
@@ -91,6 +111,10 @@ def preview_image_sort_key(member_name: str) -> tuple[int, int, str]:
def first_preview_image_member(member_names: list[str], gcode_member: str | None = None) -> str | None:
"""从 3MF 存档成员列表中查找最佳预览图。
优先匹配与指定 gcode_member 关联的预览图，其次匹配所有 plate_N.png。
"""
available_members = set(member_names)
if gcode_member is not None:
candidates = [name for name in preview_members_for_gcode_member(gcode_member) if name in available_members]
@@ -109,10 +133,17 @@ def first_preview_image_member(member_names: list[str], gcode_member: str | None
class SuccessToast(QLabel):
FADE_MS = 1000
HOLD_MS = 5000
"""构建成功时的浮动提示条组件。
提供淡入-停留-淡出动画效果，自动居中于父窗口底部。
不会拦截鼠标事件，点击可穿透到下层控件。
"""
FADE_MS = 1000 # 淡入/淡出动画时长（毫秒）
HOLD_MS = 5000 # 停留显示时长（毫秒）
def __init__(self, parent: QWidget) -> None:
"""初始化浮动提示条，创建透明度动画和停留计时器。"""
super().__init__(parent)
self.setAlignment(Qt.AlignCenter)
self.setWordWrap(True)
@@ -132,20 +163,25 @@ class SuccessToast(QLabel):
)
self._opacity_effect = QGraphicsOpacityEffect(self)
self.setGraphicsEffect(self._opacity_effect)
# 淡入动画
self._fade_in = QPropertyAnimation(self._opacity_effect, b"opacity", self)
self._fade_in.setDuration(self.FADE_MS)
self._fade_in.setEasingCurve(QEasingCurve.InOutQuad)
# 淡出动画
self._fade_out = QPropertyAnimation(self._opacity_effect, b"opacity", self)
self._fade_out.setDuration(self.FADE_MS)
self._fade_out.setEasingCurve(QEasingCurve.InOutQuad)
self._fade_out.finished.connect(self.hide)
# 停留计时器
self._hold_timer = QTimer(self)
self._hold_timer.setSingleShot(True)
self._hold_timer.timeout.connect(self._start_fade_out)
# 监听父窗口大小变化，自动重新定位
parent.installEventFilter(self)
self.hide()
def show_message(self, message: str) -> None:
"""显示指定消息文本，启动淡入-停留-淡出动画序列。"""
self._hold_timer.stop()
self._fade_in.stop()
self._fade_out.stop()
@@ -161,12 +197,14 @@ class SuccessToast(QLabel):
self._hold_timer.start(self.FADE_MS + self.HOLD_MS)
def eventFilter(self, watched: object, event: QEvent) -> bool:
"""监听父窗口 Resize 事件，自动调整提示条尺寸和位置。"""
if watched is self.parentWidget() and event.type() == QEvent.Resize and self.isVisible():
self._fit_to_parent()
self._position()
return super().eventFilter(watched, event)
def _fit_to_parent(self) -> None:
"""根据父窗口宽度自适应提示条的最大宽度。"""
parent = self.parentWidget()
if parent is None:
return
@@ -174,6 +212,7 @@ class SuccessToast(QLabel):
self.adjustSize()
def _position(self) -> None:
"""将提示条定位到父窗口底部居中位置。"""
parent = self.parentWidget()
if parent is None:
return
@@ -183,6 +222,7 @@ class SuccessToast(QLabel):
self.move(x, y)
def _start_fade_out(self) -> None:
"""启动淡出动画，从当前透明度渐变至完全透明。"""
self._fade_out.stop()
self._fade_out.setStartValue(self._opacity_effect.opacity())
self._fade_out.setEndValue(0.0)
@@ -190,12 +230,24 @@ class SuccessToast(QLabel):
class DropTableWidget(QTableWidget):
"""支持拖放 .3mf 文件的表格控件。
允许用户将 .3mf 文件或文件夹从文件管理器拖放到表格中。
支持按 Delete 键删除选中行。
"""
def __init__(
self,
on_files_dropped: Callable[[list[Path]], None],
on_delete_pressed: Callable[[], None],
parent: QWidget | None = None,
) -> None:
"""初始化拖放表格。
参数：
on_files_dropped: 文件拖放完成时的回调，接收 Path 列表。
on_delete_pressed: 按下 Delete 键时的回调。
"""
super().__init__(parent)
self.on_files_dropped = on_files_dropped
self.on_delete_pressed = on_delete_pressed
@@ -205,6 +257,7 @@ class DropTableWidget(QTableWidget):
self.setDragDropMode(QAbstractItemView.DropOnly)
def keyPressEvent(self, event: QKeyEvent) -> None:
"""处理键盘事件：Delete 键删除选中行。"""
if event.key() == Qt.Key_Delete and self.selectedIndexes():
self.on_delete_pressed()
event.accept()
@@ -212,6 +265,7 @@ class DropTableWidget(QTableWidget):
super().keyPressEvent(event)
def eventFilter(self, watched: object, event: QEvent) -> bool:
"""过滤视口拖放事件，仅接受包含 .3mf 文件的拖放操作。"""
if watched is self.viewport():
if event.type() in {QEvent.DragEnter, QEvent.DragMove}:
drag_event = event # type: ignore[assignment]
@@ -228,18 +282,21 @@ class DropTableWidget(QTableWidget):
return super().eventFilter(watched, event)
def dragEnterEvent(self, event: QDragEnterEvent) -> None:
"""拖入事件：仅接受包含 .3mf 文件的拖放。"""
if self._has_3mf_urls(event):
event.acceptProposedAction()
return
super().dragEnterEvent(event)
def dragMoveEvent(self, event: QDragMoveEvent) -> None:
"""拖移事件：仅接受包含 .3mf 文件的拖放。"""
if self._has_3mf_urls(event):
event.acceptProposedAction()
return
super().dragMoveEvent(event)
def dropEvent(self, event: QDropEvent) -> None:
"""释放事件：提取 .3mf 文件路径并触发回调。"""
paths = self._paths_from_urls(event.mimeData().urls())
if paths:
self.on_files_dropped(paths)
@@ -248,11 +305,13 @@ class DropTableWidget(QTableWidget):
super().dropEvent(event)
def _has_3mf_urls(self, event: Any) -> bool:
"""检查拖放事件是否包含至少一个 .3mf 文件 URL。"""
if not event.mimeData().hasUrls():
return False
return bool(self._paths_from_urls(event.mimeData().urls()))
def _paths_from_urls(self, urls: list[QUrl]) -> list[Path]:
"""从 URL 列表中提取 .3mf 文件路径，支持文件和文件夹。"""
result: list[Path] = []
for url in urls:
local_path = url.toLocalFile()
@@ -267,15 +326,26 @@ class DropTableWidget(QTableWidget):
class MainWindow(QMainWindow):
"""应用程序主窗口。
职责：
- 管理 3MF 输入文件列表（添加、移除、排序、份数调整）
- 提供打包选项配置界面
- 显示缩略图预览和输出预览
- 执行单个/批量构建并显示结果日志
- 持久化用户设置到本地 JSON 文件
"""
def __init__(self) -> None:
"""初始化主窗口：创建 UI、加载设置、连接信号。"""
super().__init__()
self.setWindowTitle(APP_TITLE)
self.resize(960, 720)
self.setAcceptDrops(True)
self._updating_table = False
self._loading_settings = True
self._updating_table = False # 防重入标记：表格正在批量更新中
self._loading_settings = True # 防重入标记：正在从设置恢复 UI 状态
self._settings = self.load_settings()
self._shared_growth_enabled = False
self._shared_growth_enabled = False # 窗口高度足够时，文件区和日志区共享扩展空间
self.build_ui()
self.load_swap_gcode_to_combo()
self.restore_settings_to_ui()
@@ -284,7 +354,12 @@ class MainWindow(QMainWindow):
self.update_total_summary()
self.update_output_preview()
# =========================================================================
# 设置存取
# =========================================================================
def load_settings(self) -> dict[str, Any]:
"""从用户设置 JSON 文件加载设置，返回字典。"""
path = user_settings_path()
if path.exists():
try:
@@ -295,20 +370,38 @@ class MainWindow(QMainWindow):
return {}
def save_settings(self) -> None:
"""将当前设置字典写入用户设置 JSON 文件。"""
path = user_settings_path()
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(self._settings, indent=2), encoding="utf-8")
# =========================================================================
# UI 构建
# =========================================================================
def build_ui(self) -> None:
"""构建完整的主窗口用户界面。
布局结构（自上而下）：
1. 文件输入区（表格 + 缩略图预览 + 操作按钮）
2. 打包选项区（网格布局）
3. 输出区（目录、文件名规则、预览）
4. 日志区（只读文本框）
"""
central = QWidget(self)
root = QVBoxLayout(central)
root.setSpacing(6)
self.root_layout = root
# =====================================================================
# --- 文件输入区 ---
# =====================================================================
file_group = QGroupBox("输入 3MF 文件")
self.file_group = file_group
file_layout = QVBoxLayout(file_group)
file_body = QHBoxLayout()
# --- 文件表格 ---
table_layout = QVBoxLayout()
self.table = DropTableWidget(self.add_paths, self.remove_selected)
self.table.setColumnCount(5)
@@ -329,10 +422,12 @@ class MainWindow(QMainWindow):
self.table.itemSelectionChanged.connect(self.update_thumbnail_preview)
table_layout.addWidget(self.table)
# --- 合计统计标签 ---
self.total_summary_label = QLabel("合计：0 板 | 时间：未知 | 耗材：未知")
table_layout.addWidget(self.total_summary_label)
file_body.addLayout(table_layout, 1)
# --- 缩略图预览 ---
preview_group = QGroupBox("选中文件的缩略图")
preview_layout = QVBoxLayout(preview_group)
self.thumbnail_label = QLabel("选择一个输入文件")
@@ -356,6 +451,7 @@ class MainWindow(QMainWindow):
file_body.addWidget(preview_group)
file_layout.addLayout(file_body)
# --- 文件操作按钮栏 ---
file_buttons = QHBoxLayout()
add_button = QPushButton("添加 3MF")
remove_button = QPushButton("移除")
@@ -383,6 +479,9 @@ class MainWindow(QMainWindow):
file_layout.addLayout(file_buttons)
root.addWidget(file_group, 1)
# =====================================================================
# --- 打包选项区 ---
# =====================================================================
options_group = QGroupBox("打包选项")
grid = QGridLayout(options_group)
grid.setColumnStretch(1, 1)
@@ -391,6 +490,7 @@ class MainWindow(QMainWindow):
grid.setVerticalSpacing(6)
# ---- 控件创建 ----
# 换料 G-code 选择
self.swap_gcode_combo = QComboBox()
self.swap_gcode_combo.setMinimumWidth(260)
self.swap_gcode_combo.setMaximumWidth(440)
@@ -405,11 +505,13 @@ class MainWindow(QMainWindow):
swap_gcode_row.addWidget(refresh_button)
swap_gcode_row.addWidget(open_folder_button)
# 默认份数
self.default_copies_spin = QSpinBox()
self.default_copies_spin.setRange(1, 9999)
self.default_copies_spin.setValue(1)
self.default_copies_spin.setFixedWidth(96)
# 热床降温
self.bed_cooldown_check = QCheckBox("等待热床降温")
self.bed_cooldown_check.setChecked(True)
self.cool_bed_spin = QSpinBox()
@@ -421,18 +523,22 @@ class MainWindow(QMainWindow):
bed_row.addWidget(QLabel("°C"))
bed_row.addStretch(1)
# 弹射后等待时间
self.wait_spin = QSpinBox()
self.wait_spin.setRange(0, 3600)
self.wait_spin.setValue(45)
self.wait_spin.setSuffix(" 秒")
self.wait_spin.setFixedWidth(96)
# 剩余时间板号显示
self.show_plate_number_check = QCheckBox("在剩余时间的百位显示当前板号")
self.show_plate_number_check.setChecked(True)
# 最后换料
self.swap_final_check = QCheckBox("最后一块板后也执行换料 G-code")
self.swap_final_check.setChecked(True)
# G-code 补丁
self.patch_check = QCheckBox("应用可编辑的 G-code 补丁")
self.patch_check.setToolTip("使用 gcode_patches.ini")
self.patch_check.setChecked(True)
@@ -443,11 +549,13 @@ class MainWindow(QMainWindow):
patch_row.addWidget(open_patch_button)
patch_row.addStretch(1)
# 3MF 元数据模式
self.metadata_combo = QComboBox()
self.metadata_combo.addItem("保留原始预测和重量", "source")
self.metadata_combo.addItem("累加预测和耗材用量", "sum")
self.metadata_combo.setFixedWidth(260)
# ZIP 压缩级别
self.zip_level_combo = QComboBox()
for level in range(1, 10):
self.zip_level_combo.addItem(f"级别 {level}", level)
@@ -455,11 +563,13 @@ class MainWindow(QMainWindow):
self.zip_level_combo.setFixedWidth(120)
self.zip_level_combo.setToolTip("输出 3MF 的 zlib-ng Deflate 压缩级别。")
# 独立批处理模式
self.individual_batch_check = QCheckBox("独立批处理模式")
self.individual_batch_check.setToolTip(
"将每行输入构建为独立的输出文件，使用该行的份数。"
)
# 构建后清空 / 跳过重复
self.clear_after_build_check = QCheckBox("构建成功后清空输入列表")
self.clear_after_build_check.setChecked(False)
self.skip_duplicates_check = QCheckBox("添加输入时跳过重复文件路径")
@@ -469,44 +579,49 @@ class MainWindow(QMainWindow):
input_handling_row.addWidget(self.clear_after_build_check)
input_handling_row.addStretch(1)
# ---- 网格布局 ----
# [换料 G-code | 跨全行]
# ---- 网格布局：4 列网格，每行两个选项组 ----
# 第 0 行：[换料 G-code | 跨全行]
grid.addWidget(QLabel("换料 G-code"), 0, 0)
grid.addLayout(swap_gcode_row, 0, 1, 1, 3)
# 默认份数 | 热床降温
# 第 1 行：默认份数 | 热床降温
grid.addWidget(QLabel("新输入的默认份数"), 1, 0)
grid.addWidget(self.default_copies_spin, 1, 1)
grid.addWidget(QLabel("热床降温"), 1, 2)
grid.addLayout(bed_row, 1, 3)
# 弹射后等待 | 剩余时间板号
# 第 2 行：弹射后等待 | 剩余时间板号
grid.addWidget(QLabel("弹射后等待时间"), 2, 0)
grid.addWidget(self.wait_spin, 2, 1)
grid.addWidget(QLabel("剩余时间板号"), 2, 2)
grid.addWidget(self.show_plate_number_check, 2, 3)
# 最后换料 | G-code 补丁
# 第 3 行：最后换料 | G-code 补丁
grid.addWidget(QLabel("最后换料"), 3, 0)
grid.addWidget(self.swap_final_check, 3, 1)
grid.addWidget(QLabel("G-code 补丁"), 3, 2)
grid.addLayout(patch_row, 3, 3)
# 3MF 元数据 | ZIP 压缩
# 第 4 行：3MF 元数据 | ZIP 压缩
grid.addWidget(QLabel("3MF 元数据"), 4, 0)
grid.addWidget(self.metadata_combo, 4, 1)
grid.addWidget(QLabel("ZIP 压缩"), 4, 2)
grid.addWidget(self.zip_level_combo, 4, 3)
# 批处理模式 | 输入处理
# 第 5 行：批处理模式 | 输入处理
grid.addWidget(QLabel("批处理模式"), 5, 0)
grid.addWidget(self.individual_batch_check, 5, 1)
grid.addWidget(QLabel("输入处理"), 5, 2)
grid.addLayout(input_handling_row, 5, 3)
root.addWidget(options_group)
# =====================================================================
# --- 输出区 ---
# =====================================================================
output_group = QGroupBox("输出")
output_layout = QFormLayout(output_group)
# 输出目录
output_dir_row = QHBoxLayout()
self.output_dir_edit = QLineEdit()
self.output_dir_edit.setPlaceholderText("留空则写入输入文件所在目录")
@@ -519,6 +634,7 @@ class MainWindow(QMainWindow):
output_dir_row.addWidget(browse_output_dir_button)
output_layout.addRow("输出目录", output_dir_row)
# 输出文件名规则
self.output_name_edit = QLineEdit(DEFAULT_OUTPUT_PATTERN)
self.output_name_edit.setPlaceholderText("可使用 {source}、{sources}、{plates}、{copies}、{date}、{time} 等标记")
self.output_name_edit.setMinimumWidth(280)
@@ -532,10 +648,14 @@ class MainWindow(QMainWindow):
filename_rule_row.addWidget(output_rule_help_button)
output_layout.addRow("输出文件名规则", filename_rule_row)
# 输出预览
self.output_preview_label = QLabel("-")
output_layout.addRow("预览", self.output_preview_label)
root.addWidget(output_group)
# =====================================================================
# --- 日志区 ---
# =====================================================================
self.log = QTextEdit()
self.log.setReadOnly(True)
self.log.setMinimumHeight(100)
@@ -545,7 +665,16 @@ class MainWindow(QMainWindow):
self.success_toast = SuccessToast(central)
self.update_vertical_growth_policy()
# =========================================================================
# 窗口事件
# =========================================================================
def update_vertical_growth_policy(self) -> None:
"""根据窗口高度动态调整文件区和日志区的垂直扩展比例。
窗口高度 >= 980px 时，文件区和日志区按 4:1 共享扩展空间；
否则文件区独占扩展空间。
"""
if not hasattr(self, "root_layout") or not hasattr(self, "file_group") or not hasattr(self, "log"):
return
shared_growth = self.height() >= 980
@@ -556,11 +685,17 @@ class MainWindow(QMainWindow):
self.root_layout.setStretchFactor(self.log, 1 if shared_growth else 0)
def resizeEvent(self, event: QEvent) -> None:
"""窗口大小变化时，更新垂直扩展策略并刷新缩略图。"""
super().resizeEvent(event)
self.update_vertical_growth_policy()
self.update_thumbnail_preview()
# =========================================================================
# 设置同步
# =========================================================================
def connect_option_signals(self) -> None:
"""将所有选项控件的值变更信号连接到设置保存函数。"""
self.swap_gcode_combo.currentIndexChanged.connect(self.save_current_settings)
self.default_copies_spin.valueChanged.connect(self.save_current_settings)
self.bed_cooldown_check.stateChanged.connect(self.save_current_settings)
@@ -578,6 +713,7 @@ class MainWindow(QMainWindow):
self.output_name_edit.textChanged.connect(self.on_output_rule_changed)
def restore_settings_to_ui(self) -> None:
"""从加载的设置字典恢复所有 UI 控件的状态。"""
options = self._settings.get("packing_options", {})
if not isinstance(options, dict):
return
@@ -613,6 +749,7 @@ class MainWindow(QMainWindow):
self.swap_gcode_combo.setCurrentIndex(index)
def collect_current_settings(self) -> dict[str, Any]:
"""从 UI 控件收集当前所有打包选项，返回设置字典。"""
return {
"swap_gcode": self.swap_gcode_combo.currentData() or "",
"default_copies": self.default_copies_spin.value(),
@@ -632,6 +769,7 @@ class MainWindow(QMainWindow):
}
def save_current_settings(self) -> None:
"""将当前 UI 设置保存到本地 JSON 文件（加载阶段跳过）。"""
if self._loading_settings:
return
self._settings["packing_options"] = self.collect_current_settings()
@@ -639,10 +777,12 @@ class MainWindow(QMainWindow):
self.save_settings()
def on_output_rule_changed(self) -> None:
"""输出规则变更时：更新输出预览并保存设置。"""
self.update_output_preview()
self.save_current_settings()
def on_individual_batch_toggled(self, state: int) -> None:
"""独立批处理模式切换时：显示说明对话框，更新预览并保存。"""
self.update_output_preview()
self.save_current_settings()
if self._loading_settings:
@@ -653,13 +793,14 @@ class MainWindow(QMainWindow):
"独立批处理模式",
"独立批处理模式将每一行输入作为独立的构建任务。\n\n"
"示例：如果你添加了 20 个单板 3MF 文件并设置份数为 5，"
"点击“构建 3MF”将创建 20 个独立的打包文件。"
"点击"构建 3MF"将创建 20 个独立的打包文件。"
"每个输出文件仅包含该源文件重复 5 次的内容。\n\n"
"这个功能适用于快速将大量独立的 3MF 作业批量转换为多份数的 "
"SwapMod 包。它不会将所有输入文件合并到一个 3MF 中。",
)
def show_output_rule_help(self) -> None:
"""显示输出文件名规则的帮助对话框。"""
QMessageBox.information(
self,
"输出文件名规则",
@@ -675,7 +816,12 @@ class MainWindow(QMainWindow):
"在独立批处理模式下，这些标记会针对每行输入单独计算。",
)
# =========================================================================
# 换料 G-code 管理
# =========================================================================
def load_swap_gcode_to_combo(self) -> None:
"""扫描换料 G-code 目录，填充下拉列表，恢复上次选择。"""
current = self.swap_gcode_combo.currentData() or self._settings.get("last_swap_gcode")
options = self._settings.get("packing_options", {})
if isinstance(options, dict):
@@ -694,6 +840,7 @@ class MainWindow(QMainWindow):
self.log.append(f"在 {default_swap_gcode_dir()} 中未找到换料 G-code 文件")
def open_path(self, path: Path) -> None:
"""跨平台打开文件或文件夹（Windows/Mac/Linux）。"""
target = path if path.exists() else path.parent
target.parent.mkdir(parents=True, exist_ok=True)
if sys.platform.startswith("win"):
@@ -704,22 +851,30 @@ class MainWindow(QMainWindow):
subprocess.run(["xdg-open", str(target)], check=False)
def open_swap_gcode_folder(self) -> None:
"""在系统文件管理器中打开换料 G-code 目录。"""
folder = default_swap_gcode_dir()
folder.mkdir(parents=True, exist_ok=True)
self.open_path(folder)
def open_patch_config(self) -> None:
"""打开 G-code 补丁配置文件。"""
path = default_patch_config_path()
if not path.exists():
QMessageBox.information(self, APP_NAME, f"补丁配置文件不存在：\n{path}")
return
self.open_path(path)
# =========================================================================
# 文件输入管理（表格行操作）
# =========================================================================
def add_files(self) -> None:
"""通过文件对话框添加 3MF 文件到输入列表。"""
files, _ = QFileDialog.getOpenFileNames(self, "添加 3MF 文件", "", "3MF 文件 (*.3mf);;所有文件 (*)")
self.add_paths([Path(file_name) for file_name in files])
def create_order_widget(self, row: int) -> QWidget:
"""创建行排序控件（上移/下移按钮 + 行号标签）。"""
widget = QWidget()
layout = QHBoxLayout(widget)
layout.setContentsMargins(4, 0, 4, 0)
@@ -751,11 +906,13 @@ class MainWindow(QMainWindow):
return widget
def update_order_controls(self) -> None:
"""刷新所有行的排序控件和份数控件（行号、上下按钮状态）。"""
for row in range(self.table.rowCount()):
self.table.setCellWidget(row, ORDER_COLUMN, self.create_order_widget(row))
self.table.setCellWidget(row, COPIES_COLUMN, self.create_copies_spin(row, self.get_row_copies(row)))
def create_copies_spin(self, row: int, copies: int) -> QSpinBox:
"""创建份数微调框控件，绑定值变更信号。"""
spin = QSpinBox()
spin.setRange(1, 9999)
spin.setFixedWidth(78)
@@ -765,6 +922,7 @@ class MainWindow(QMainWindow):
return spin
def row_path(self, row: int) -> Path | None:
"""获取指定行的 3MF 文件路径。"""
item = self.table.item(row, FILE_COLUMN)
if item is None:
return None
@@ -774,6 +932,7 @@ class MainWindow(QMainWindow):
return Path(item.text())
def load_thumbnail_pixmap(self, path: Path) -> QPixmap | None:
"""从 3MF 文件中加载预览缩略图。"""
with zipfile.ZipFile(path, "r") as archive:
gcode_members = list_gcode_members(archive)
active_gcode_member = resolve_output_gcode_member(archive, gcode_members[0]) if gcode_members else None
@@ -787,6 +946,7 @@ class MainWindow(QMainWindow):
return pixmap
def update_thumbnail_preview(self) -> None:
"""更新缩略图预览：从当前选中行的 3MF 文件中提取预览图并显示。"""
if not hasattr(self, "thumbnail_label"):
return
row = self.selected_row()
@@ -812,6 +972,11 @@ class MainWindow(QMainWindow):
self.thumbnail_label.setToolTip(str(path))
def add_paths(self, paths: list[Path]) -> None:
"""批量添加 3MF 文件路径到输入表格。
支持文件和文件夹（递归添加顶层 .3mf 文件）。
根据"跳过重复"设置过滤已存在的文件。
"""
expanded: list[Path] = []
for path in paths:
if path.is_dir():
@@ -843,6 +1008,7 @@ class MainWindow(QMainWindow):
self.update_output_preview()
def add_file_row(self, file_name: str, copies: int) -> bool:
"""向表格添加单行：读取 3MF 摘要，创建表格行并填充数据。"""
path = Path(file_name)
try:
summary = read_3mf_summary(path)
@@ -879,6 +1045,7 @@ class MainWindow(QMainWindow):
return True
def summary_to_dict(self, summary: ThreeMfSummary) -> dict[str, Any]:
"""将 ThreeMfSummary 对象转换为可序列化的字典（用于 QTableWidgetItem 数据角色）。"""
return {
"source_3mf": str(summary.source_3mf),
"plate_count": summary.plate_count,
@@ -889,6 +1056,7 @@ class MainWindow(QMainWindow):
}
def base_summary_tooltip(self, summary: ThreeMfSummary) -> str:
"""生成 3MF 文件的基本摘要信息（用于工具提示）。"""
return (
f"基础板数：{summary.plate_count}\n"
f"基础时间：{format_duration(summary.prediction_seconds)}\n"
@@ -896,6 +1064,7 @@ class MainWindow(QMainWindow):
)
def get_row_copies(self, row: int) -> int:
"""获取指定行的份数值。"""
widget = self.table.cellWidget(row, COPIES_COLUMN)
if isinstance(widget, QSpinBox):
return max(1, int(widget.value()))
@@ -908,6 +1077,7 @@ class MainWindow(QMainWindow):
return 1
def set_row_copies(self, row: int, copies: int) -> None:
"""设置指定行的份数值（通过微调框或文本）。"""
value = max(1, int(copies))
widget = self.table.cellWidget(row, COPIES_COLUMN)
if isinstance(widget, QSpinBox):
@@ -918,6 +1088,7 @@ class MainWindow(QMainWindow):
item.setText(str(value))
def on_row_copies_changed(self, row: int, copies: int) -> None:
"""份数变更时：刷新该行统计、总合计和输出预览。"""
if self._updating_table:
return
self._updating_table = True
@@ -929,6 +1100,7 @@ class MainWindow(QMainWindow):
self.update_output_preview()
def update_row_stats(self, row: int) -> None:
"""根据当前份数重新计算并更新该行的时间列和耗材列。"""
path_item = self.table.item(row, FILE_COLUMN)
if path_item is None:
return
@@ -947,6 +1119,7 @@ class MainWindow(QMainWindow):
self.table.item(row, FILAMENT_COLUMN).setText(format_filament(total_weight, total_used_m))
def on_table_item_changed(self, item: QTableWidgetItem) -> None:
"""表格单元格内容变更事件：份数列手动编辑时同步更新统计。"""
if self._updating_table:
return
if item.column() == COPIES_COLUMN:
@@ -961,13 +1134,16 @@ class MainWindow(QMainWindow):
self.update_output_preview()
def selected_rows(self) -> list[int]:
"""返回当前选中行的索引列表（去重、升序）。"""
return sorted({index.row() for index in self.table.selectedIndexes()})
def selected_row(self) -> int | None:
"""返回当前选中的第一行索引，无选中时返回 None。"""
rows = self.selected_rows()
return rows[0] if rows else None
def remove_selected(self) -> None:
"""删除选中的表格行，并智能选择下一行。"""
rows = sorted(self.selected_rows(), reverse=True)
next_row = min(rows) if rows else None
for row in rows:
@@ -980,6 +1156,7 @@ class MainWindow(QMainWindow):
self.update_thumbnail_preview()
def remove_all(self) -> None:
"""清空所有输入行。"""
self.table.setRowCount(0)
self.update_order_controls()
self.update_total_summary()
@@ -987,12 +1164,14 @@ class MainWindow(QMainWindow):
self.update_thumbnail_preview()
def move_selected(self, delta: int) -> None:
"""移动选中行（delta 为正则下移，为负则上移）。"""
row = self.selected_row()
if row is None:
return
self.move_row(row, delta)
def move_row(self, row: int, delta: int) -> None:
"""将指定行移动 delta 个位置，保持份数和其他数据不变。"""
new_row = row + delta
if new_row < 0 or new_row >= self.table.rowCount():
return
@@ -1019,6 +1198,7 @@ class MainWindow(QMainWindow):
self.update_thumbnail_preview()
def apply_default_copies_to_selected(self) -> None:
"""将默认份数应用到所有选中行。"""
rows = self.selected_rows()
if not rows:
return
@@ -1032,7 +1212,12 @@ class MainWindow(QMainWindow):
self.update_total_summary()
self.update_output_preview()
# =========================================================================
# 输出配置
# =========================================================================
def choose_output_dir(self) -> None:
"""通过文件夹选择对话框设置输出目录。"""
start_dir = self.output_dir_edit.text().strip()
first_path = self.row_path(0) if self.table.rowCount() > 0 else None
if not start_dir and first_path is not None:
@@ -1042,6 +1227,7 @@ class MainWindow(QMainWindow):
self.output_dir_edit.setText(directory)
def collect_jobs(self) -> list[PlateJob]:
"""从表格中收集所有 PlateJob（文件路径 + 份数）。"""
jobs: list[PlateJob] = []
for row in range(self.table.rowCount()):
path = self.row_path(row)
@@ -1051,6 +1237,7 @@ class MainWindow(QMainWindow):
return jobs
def summary_for_path(self, path: Path) -> ThreeMfSummary:
"""根据文件路径获取 ThreeMfSummary（优先从缓存表格数据中读取）。"""
normalized = str(path)
for row in range(self.table.rowCount()):
row_path = self.row_path(row)
@@ -1064,15 +1251,18 @@ class MainWindow(QMainWindow):
return read_3mf_summary(path)
def output_naming_options(self) -> OutputNamingOptions:
"""从 UI 控件收集输出命名选项。"""
return OutputNamingOptions(
output_directory=self.output_dir_edit.text().strip(),
filename_rule=self.output_name_edit.text().strip() or DEFAULT_OUTPUT_PATTERN,
)
def current_total_summary(self) -> OutputSummary:
"""计算当前所有作业的合计摘要（板数、时间、耗材）。"""
return summarize_jobs_for_output(self.collect_jobs(), self.summary_for_path)
def update_total_summary(self) -> None:
"""刷新底部合计统计标签。"""
summary = self.current_total_summary()
self.total_summary_label.setText(
"合计："
@@ -1082,6 +1272,11 @@ class MainWindow(QMainWindow):
)
def update_output_preview(self) -> None:
"""刷新输出文件路径预览标签。
合并模式下显示单个输出路径；
独立批处理模式下显示"第一个输出路径 | N 个输出文件"。
"""
jobs = self.collect_jobs()
if not jobs:
self.output_preview_label.setText("-")
@@ -1098,7 +1293,12 @@ class MainWindow(QMainWindow):
except Exception as exc:
self.output_preview_label.setText(str(exc))
# =========================================================================
# 构建流程
# =========================================================================
def build_options_for_output(self, output_path: Path) -> BuildOptions:
"""根据当前 UI 选项构建 BuildOptions 对象。"""
swap_gcode_path = self.swap_gcode_combo.currentData()
if not swap_gcode_path:
raise ValueError("请在 swap_gcode 文件夹中放入至少一个换料 G-code 文件并选择它。")
@@ -1116,6 +1316,7 @@ class MainWindow(QMainWindow):
)
def log_build_result(self, result: Any) -> None:
"""将单次构建结果信息写入日志。"""
self.log.append(f"输出：{result.output_3mf}")
self.log.append(f"板数：{result.plate_count}")
self.log.append(f"预估源文件时间：{format_duration(result.total_prediction_seconds)}")
@@ -1123,9 +1324,11 @@ class MainWindow(QMainWindow):
self.log.append(f"G-code MD5：{result.gcode_md5}")
def show_success_toast(self, message: str) -> None:
"""显示构建成功的浮动提示条。"""
self.success_toast.show_message(message)
def build_output(self) -> None:
"""主构建入口：根据批处理模式分发到合并构建或独立构建。"""
jobs = self.collect_jobs()
if not jobs:
QMessageBox.warning(self, APP_NAME, "请至少添加一个 3MF 文件。")
@@ -1142,6 +1345,7 @@ class MainWindow(QMainWindow):
return
def build_combined_output(self, jobs: list[PlateJob]) -> None:
"""合并构建模式：将所有输入文件打包到单个输出 3MF 中。"""
output_path = resolve_output_path(jobs, self.output_naming_options(), self.summary_for_path)
options = self.build_options_for_output(output_path)
result = build_packed_3mf(jobs, options)
@@ -1151,6 +1355,7 @@ class MainWindow(QMainWindow):
self.remove_all()
def build_individual_outputs(self, jobs: list[PlateJob]) -> None:
"""独立批处理模式：每行输入构建一个独立的输出 3MF，支持并行处理。"""
used_paths: set[Path] = set()
success_count = 0
errors: list[str] = []
@@ -1192,24 +1397,32 @@ class MainWindow(QMainWindow):
if self.clear_after_build_check.isChecked():
self.remove_all()
# =========================================================================
# 窗口级拖放事件
# =========================================================================
def dragEnterEvent(self, event: QDragEnterEvent) -> None:
"""主窗口拖入事件：接受包含文件 URL 的拖放。"""
if event.mimeData().hasUrls():
event.acceptProposedAction()
return
super().dragEnterEvent(event)
def dropEvent(self, event: QDropEvent) -> None:
"""主窗口释放事件：将拖放的文件路径添加到输入列表。"""
urls: list[QUrl] = event.mimeData().urls()
paths = [Path(url.toLocalFile()) for url in urls if url.toLocalFile()]
self.add_paths(paths)
event.acceptProposedAction()
def closeEvent(self, event: Any) -> None:
"""窗口关闭前保存当前设置。"""
self.save_current_settings()
super().closeEvent(event)
def main() -> int:
"""应用程序入口：初始化 QApplication，创建并显示主窗口，进入事件循环。"""
freeze_support()
app = QApplication(sys.argv)
app.setFont(QFont("Segoe UI", 10))