ww3tool 0.1.1__py3-none-any.whl

desktop/__init__.py

@@ -0,0 +1,29 @@
+"""Desktop application and view-model adapters for the src architecture."""
+
+__all__ = [
+    "ForcingStepViewModel",
+    "PipelineViewModel",
+    "PreprocessingWindow",
+    "create_window",
+    "main",
+]
+
+
+def __getattr__(name):
+    if name == "ForcingStepViewModel":
+        from .view_models.forcing_step import ForcingStepViewModel
+
+        return ForcingStepViewModel
+    if name == "PipelineViewModel":
+        from .view_models.pipeline import PipelineViewModel
+
+        return PipelineViewModel
+    if name == "PreprocessingWindow":
+        from .windows.preprocessing_window import PreprocessingWindow
+
+        return PreprocessingWindow
+    if name in {"create_window", "main"}:
+        from .application import create_window, main
+
+        return {"create_window": create_window, "main": main}[name]
+    raise AttributeError(name)

desktop/_repo_root.py

@@ -0,0 +1,38 @@
+"""仓库根目录解析（desktop 专用）。
+
+``WW3TOOL_ROOT`` 环境变量优先（pip/brew 安装形态下指向含
+meshgen/public/params.yml 的仓库），否则按仓库布局从本文件推导：
+``<仓库根>/src/desktop/``，向上 2 级即仓库根。
+
+[EN] Repo-root resolution for the desktop package: WW3TOOL_ROOT env wins
+(packaged installs); otherwise inferred from the repo layout.
+"""
+
+import os
+from pathlib import Path
+
+
+def repo_root() -> Path:
+    env_root = os.environ.get("WW3TOOL_ROOT")
+    if env_root:
+        return Path(env_root).expanduser().resolve()
+    # 仓库形态：从本文件向上找到含 params.yml 与 run.py 的仓库根
+    # [EN] Repo layout: walk up to the dir holding both params.yml and run.py.
+    _d = Path(__file__).resolve().parent
+    while True:
+        if (_d / "params.yml").is_file() and (_d / "run.py").is_file():
+            return _d
+        if _d.parent == _d:
+            break
+        _d = _d.parent
+    # 装包形态：site-packages 里的 ww3tool_resources 自带全部运行资源
+    # [EN] Packaged install: ww3tool_resources ships the runtime resources.
+    try:
+        import ww3tool_resources
+
+        pkg_root = Path(ww3tool_resources.__file__).resolve().parent
+        if (pkg_root / "params.yml").is_file():
+            return pkg_root
+    except Exception:
+        pass
+    return Path(__file__).resolve().parents[2]  # 兜底：原仓库推断

desktop/application.py

@@ -0,0 +1,63 @@
+"""Desktop startup for the workflow-backed application."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+
+def _select_initial_work_directory(window: Any) -> bool:
+    """Prompt for a work directory on startup. Returns False if the user cancels."""
+    from .windows.work_folder_dialog import WorkFolderDialog
+
+    dialog = WorkFolderDialog(parent=window, is_startup=True)
+    if dialog.exec() != dialog.DialogCode.Accepted or not dialog.selected_folder:
+        return False
+    if hasattr(window, "set_work_directory"):
+        window.set_work_directory(dialog.selected_folder)
+    return True
+
+
+def create_window():
+    from .windows.preprocessing_window import create_preprocessing_window
+
+    return create_preprocessing_window()
+
+
+def main(argv: list[str] | None = None) -> int:
+    # [EN] Must set AA_ShareOpenGLContexts before QApplication for QWebEngineView.
+    import PyQt6.QtCore
+    PyQt6.QtCore.QCoreApplication.setAttribute(
+        PyQt6.QtCore.Qt.ApplicationAttribute.AA_ShareOpenGLContexts
+    )
+
+    try:
+        from PyQt6.QtWidgets import QApplication
+    except ImportError as exc:
+        raise SystemExit(
+            "无法启动桌面界面：请先安装 PyQt6 依赖 "
+            "(python3 -m pip install -r src/requirements.txt)"
+        ) from exc
+
+    # [EN] Validate root params.yml paths at startup (same as CLI/shell).
+    # Incompatible or non-existent paths are auto-corrected before any config is loaded.
+    try:
+        from workflows.infrastructure.runtime_config import sanitize_root_params_paths
+        sanitize_root_params_paths()
+    except Exception:
+        pass
+
+    arguments = [sys.argv[0], *(argv if argv is not None else sys.argv[1:])]
+    app = QApplication(arguments)
+    from .branding import load_logo_icon, apply_window_logo
+
+    icon = load_logo_icon()
+    if icon is not None:
+        app.setWindowIcon(icon)
+
+    window = create_window()
+    apply_window_logo(window)
+    window.show()
+    if not _select_initial_work_directory(window):
+        return 0
+    return app.exec()

desktop/background_runner.py

@@ -0,0 +1,46 @@
+"""Run workflow tasks off the UI thread and marshal results back to Qt."""
+
+from __future__ import annotations
+
+import threading
+import traceback
+import uuid
+from typing import Callable
+
+from PyQt6 import QtCore
+
+
+class _BackgroundRunnerBridge(QtCore.QObject):
+    finished = QtCore.pyqtSignal(str, object)
+
+
+class BackgroundRunner:
+    """Runs callables on daemon threads and delivers results on the UI thread."""
+
+    def __init__(self, parent: QtCore.QObject | None = None) -> None:
+        self._bridge = _BackgroundRunnerBridge(parent)
+        self._bridge.finished.connect(self._dispatch, QtCore.Qt.ConnectionType.QueuedConnection)
+        self._callbacks: dict[str, Callable[[object], None]] = {}
+
+    def run(self, task: Callable[[], object], on_done: Callable[[object], None]) -> str:
+        token = uuid.uuid4().hex
+        self._callbacks[token] = on_done
+
+        def _worker() -> None:
+            try:
+                result = task()
+            except Exception as exc:
+                traceback.print_exc()
+                result = {"success": False, "error": str(exc)}
+            self._bridge.finished.emit(token, result)
+
+        threading.Thread(target=_worker, daemon=True).start()
+        return token
+
+    def _dispatch(self, token: str, result: object) -> None:
+        callback = self._callbacks.pop(token, None)
+        if callback is not None:
+            try:
+                callback(result)
+            except Exception:
+                traceback.print_exc()

desktop/branding.py

@@ -0,0 +1,30 @@
+"""Application branding assets (window / title bar icon)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from PyQt6.QtGui import QIcon
+
+from ._repo_root import repo_root
+
+LOGO_PATH = repo_root() / "public" / "resource" / "logo.png"
+
+
+def load_logo_icon() -> QIcon | None:
+    if not LOGO_PATH.is_file():
+        return None
+    icon = QIcon(str(LOGO_PATH))
+    return icon if not icon.isNull() else None
+
+
+def apply_window_logo(window: Any) -> None:
+    """Set app logo on the window and FluentTitleBar icon label."""
+    icon = load_logo_icon()
+    if icon is None:
+        return
+    window.setWindowIcon(icon)
+    title_bar = getattr(window, "titleBar", None)
+    if title_bar is not None and hasattr(title_bar, "setIcon"):
+        title_bar.setIcon(icon)

desktop/components/__init__.py

@@ -0,0 +1,11 @@
+"""Reusable desktop presentation components."""
+
+from .combo_box import left_align_combo_text
+from .image_gallery_drawer import ImageGalleryDrawer, ImageGalleryHost, ImageGalleryPanel
+
+__all__ = [
+    "left_align_combo_text",
+    "ImageGalleryDrawer",
+    "ImageGalleryHost",
+    "ImageGalleryPanel",
+]

desktop/components/bounds_map_preview.py

@@ -0,0 +1,252 @@
+"""Reusable inline map preview for editable geographic bounds."""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+from PyQt6.QtCore import pyqtSignal, QRectF, QTimer, QUrl, QUrlQuery
+from PyQt6.QtGui import QColor, QPainterPath, QRegion
+from PyQt6.QtWebEngineCore import QWebEngineSettings
+from PyQt6.QtWidgets import QSizePolicy
+
+from .._repo_root import repo_root
+from .globe_picker_dialog import MapWebEngineView, current_map_language, current_map_type
+
+
+class BoundsMapPreview(MapWebEngineView):
+    """Show a blue outline for four bound fields without map editing controls."""
+
+    expand_requested = pyqtSignal()
+
+    def __init__(self, parent=None) -> None:
+        super().__init__(parent)
+        self._page_loaded = False
+        self._regions: list[dict[str, object]] = []
+        self._field_regions: list[dict[str, object]] = []
+        self._field_connections: list[tuple[object, object]] = []
+        self._applying_web_move = False
+        self._move_poll_in_flight = False
+        self._update_timer = QTimer(self)
+        self._update_timer.setSingleShot(True)
+        self._update_timer.setInterval(180)
+        self._update_timer.timeout.connect(self._update_from_bound_fields)
+        self._move_poll_timer = QTimer(self)
+        self._move_poll_timer.setInterval(120)
+        self._move_poll_timer.timeout.connect(self._poll_preview_move)
+
+        self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Fixed)
+        self.setFixedHeight(210)
+        self.setZoomFactor(1.0)
+        page = self.page()
+        page.setBackgroundColor(QColor("#ffffff"))
+        settings = page.settings()
+        settings.setAttribute(QWebEngineSettings.WebAttribute.LocalContentCanAccessRemoteUrls, True)
+        settings.setAttribute(QWebEngineSettings.WebAttribute.WebGLEnabled, True)
+        page.loadFinished.connect(self._on_page_loaded)
+
+        html_path = repo_root() / "public" / "globe_picker" / "globe_picker.html"
+        url = QUrl.fromLocalFile(str(html_path.resolve()))
+        query = QUrlQuery()
+        query.addQueryItem("mode", "preview")
+        query.addQueryItem("lang", current_map_language())
+        query.addQueryItem("mapType", current_map_type())
+        url.setQuery(query)
+        self.load(url)
+
+    def bind_fields(
+        self, *, west, east, south, north, color: str = "#1677d2", label: str = ""
+    ) -> None:
+        self._clear_field_bindings()
+        self.add_bound_fields(
+            west=west, east=east, south=south, north=north, color=color, label=label
+        )
+
+    def add_bound_fields(
+        self, *, west, east, south, north, color: str = "#1677d2", label: str = ""
+    ) -> None:
+        fields = (west, east, south, north)
+        self._field_regions.append({"fields": fields, "color": color, "label": label})
+        for field in fields:
+            slot = lambda *_: self._schedule_field_update()
+            field.textChanged.connect(slot)
+            self._field_connections.append((field, slot))
+        self._update_timer.start()
+
+    def replace_bound_fields(self, bindings: list[dict[str, object]]) -> None:
+        """Replace all live field bindings, for example after nested levels change."""
+        self._clear_field_bindings()
+        for binding in bindings:
+            self.add_bound_fields(**binding)
+        if not bindings:
+            self.clear_bounds()
+        # 立即同步 regions，确保 regions() 返回最新数据
+        self._update_from_bound_fields()
+
+    def _clear_field_bindings(self) -> None:
+        self._update_timer.stop()
+        for field, slot in self._field_connections:
+            try:
+                field.textChanged.disconnect(slot)
+            except (RuntimeError, TypeError):
+                pass
+        self._field_connections.clear()
+        self._field_regions.clear()
+
+    def set_bounds(self, west: float, east: float, south: float, north: float) -> None:
+        self.set_regions([{"west": west, "east": east, "south": south, "north": north}])
+
+    def set_regions(self, regions: list[dict[str, object]]) -> None:
+        self._regions = [dict(region) for region in regions]
+        self._sync_regions()
+
+    def clear_bounds(self) -> None:
+        self.set_regions([])
+
+    def refresh(self) -> None:
+        self._update_timer.stop()
+        self._update_from_bound_fields()
+
+    def regions(self) -> list[dict[str, object]]:
+        return [dict(region) for region in self._regions]
+
+    def reload_map_type(self) -> None:
+        url = self.url()
+        query = QUrlQuery(url)
+        query.removeAllQueryItems("mapType")
+        query.addQueryItem("mapType", current_map_type())
+        url.setQuery(query)
+        self._page_loaded = False
+        self.load(url)
+
+    def resizeEvent(self, event) -> None:
+        super().resizeEvent(event)
+        path = QPainterPath()
+        path.addRoundedRect(QRectF(self.rect()), 8.0, 8.0)
+        self.setMask(QRegion(path.toFillPolygon().toPolygon()))
+
+    def showEvent(self, event) -> None:
+        super().showEvent(event)
+        if self._page_loaded:
+            self._move_poll_timer.start()
+        self._restore_host_frameless()
+
+    def hideEvent(self, event) -> None:
+        self._move_poll_timer.stop()
+        super().hideEvent(event)
+
+    def _on_page_loaded(self, ok: bool) -> None:
+        self._page_loaded = ok
+        if ok:
+            self._sync_regions()
+            if self.isVisible():
+                self._move_poll_timer.start()
+            self._restore_host_frameless()
+            QTimer.singleShot(0, self._restore_host_frameless)
+            QTimer.singleShot(100, self._restore_host_frameless)
+
+    def _schedule_field_update(self) -> None:
+        if not self._applying_web_move:
+            self._update_timer.start()
+
+    def _poll_preview_move(self) -> None:
+        if not self._page_loaded or self._move_poll_in_flight:
+            return
+        self._move_poll_in_flight = True
+        self.page().runJavaScript(
+            "(function(){"
+            "var r=window.__previewMoveResult||null;"
+            "window.__previewMoveResult=null;"
+            "var x=window.__expandRequested||false;"
+            "window.__expandRequested=false;"
+            "if(x)return {_expand:true};"
+            "return r;"
+            "})()",
+            self._on_preview_move,
+        )
+
+    def _on_preview_move(self, result: object) -> None:
+        self._move_poll_in_flight = False
+        if not isinstance(result, dict):
+            return
+        if result.get("_expand"):
+            QTimer.singleShot(0, self.expand_requested.emit)
+            return
+        try:
+            index = int(result["index"])
+            bounds = tuple(float(result[key]) for key in ("west", "east", "south", "north"))
+        except (KeyError, TypeError, ValueError):
+            return
+        if index < 0 or index >= len(self._field_regions):
+            return
+        west, east, south, north = bounds
+        if not all(math.isfinite(value) for value in bounds):
+            return
+        if south >= north or south < -90 or north > 90 or east <= west or east - west > 360:
+            return
+
+        fields = self._field_regions[index]["fields"]
+        self._applying_web_move = True
+        try:
+            for field, value in zip(fields, bounds):
+                field.setText(f"{value:.4f}")
+        finally:
+            self._applying_web_move = False
+
+        for region in self._regions:
+            if int(region.get("fieldIndex", -1)) == index:
+                region.update({"west": west, "east": east, "south": south, "north": north})
+                break
+
+    def _update_from_bound_fields(self) -> None:
+        if not self._field_regions:
+            return
+        regions: list[dict[str, object]] = []
+        for field_index, binding in enumerate(self._field_regions):
+            fields = binding["fields"]
+            try:
+                west, east, south, north = (
+                    float(field.text().strip()) for field in fields
+                )
+            except ValueError:
+                continue
+            if not all(math.isfinite(value) for value in (west, east, south, north)):
+                continue
+            while east <= west:
+                east += 360
+            if south >= north or south < -90 or north > 90 or east - west > 360:
+                continue
+            regions.append(
+                {
+                    "west": west,
+                    "east": east,
+                    "south": south,
+                    "north": north,
+                    "color": binding["color"],
+                    "label": binding["label"],
+                    "width": 1.5,
+                    "fieldIndex": field_index,
+                }
+            )
+        self.set_regions(regions)
+
+    def _restore_host_frameless(self) -> None:
+        host = self.window()
+        if host is self:
+            return
+        update_frameless = getattr(host, "updateFrameless", None)
+        if callable(update_frameless):
+            update_frameless()
+        set_system_buttons = getattr(host, "setSystemTitleBarButtonVisible", None)
+        if callable(set_system_buttons):
+            set_system_buttons(False)
+        title_bar = getattr(host, "titleBar", None)
+        if title_bar is not None:
+            title_bar.raise_()
+
+    def _sync_regions(self) -> None:
+        if not self._page_loaded:
+            return
+        payload = json.dumps(self._regions, separators=(",", ":"))
+        self.page().runJavaScript(f"window.__setPreviewRegions({payload})")

desktop/components/combo_box.py

@@ -0,0 +1,98 @@
+"""Presentation helpers shared by desktop combo boxes."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from PyQt6.QtCore import Qt, QTimer
+from PyQt6.QtWidgets import QWidget
+from qfluentwidgets import ComboBox
+
+from workflows.domain.parameter_catalog import canonical_file_split
+from workflows.support.translations import tr
+
+
+def add_labeled_combo_items(combo: ComboBox, items: Iterable[tuple[str, str]]) -> None:
+    """qfluentwidgets ``addItem(text, icon, userData)`` 第二参是 icon，枚举值必须用 ``userData=``。
+
+    [EN] In qfluentwidgets, ``addItem(text, icon, userData)`` treats the second
+    parameter as icon; enum values must be passed with ``userData=``.
+    """
+    for label, value in items:
+        combo.addItem(label, userData=value)
+
+
+def combo_selected_user_data(combo: ComboBox) -> str:
+    """读取当前项 ``userData``；缺失时回退 ``currentText``。
+
+    [EN] Read the current item's ``userData``; fall back to ``currentText`` when missing.
+    """
+    data = combo.itemData(combo.currentIndex())
+    if data is not None and str(data).strip():
+        return str(data).strip()
+    return combo.currentText().strip()
+
+
+def file_split_combo_items() -> list[tuple[str, str]]:
+    """``ww3.file_split`` 下拉项：展示文案 + 规范枚举值。
+
+    [EN] Drop-down items for ``ww3.file_split``: display text + canonical enum value.
+    """
+    return [
+        (tr("file_split_single", "单文件"), "single"),
+        (tr("file_split_hour", "小时"), "hour"),
+        (tr("file_split_day", "天"), "day"),
+        (tr("file_split_month", "月"), "month"),
+        (tr("file_split_year", "年"), "year"),
+    ]
+
+
+def current_file_split_from_combo(combo: ComboBox, *, default: str = "year") -> str:
+    """从下拉框读出规范的 ``ww3.file_split`` 枚举值。
+
+    [EN] Read the canonical ``ww3.file_split`` enum value from the combo box.
+    """
+    return canonical_file_split(combo_selected_user_data(combo), default=default)
+
+
+def select_file_split_combo(combo: ComboBox, value: object, *, default: str = "year") -> None:
+    """按规范值选中 file_split 项；兼容旧值 ``none`` 与误存的展示文案。
+
+    [EN] Select the file_split item by canonical value; compatible with the legacy
+    value ``none`` and mistakenly stored display text.
+    """
+    selected = canonical_file_split(value, default=default)
+    for index in range(combo.count()):
+        data = combo.itemData(index)
+        if str(data or "").strip().lower() == selected:
+            combo.setCurrentIndex(index)
+            return
+    label_by_value = {item_value: item_label for item_label, item_value in file_split_combo_items()}
+    target_label = label_by_value.get(selected)
+    if target_label:
+        for index in range(combo.count()):
+            if combo.itemText(index) == target_label:
+                combo.setCurrentIndex(index)
+                return
+    if combo.count():
+        combo.setCurrentIndex(0)
+
+
+def left_align_combo_text(combo: QWidget) -> None:
+    """Keep combo display text aligned with the left-side form fields."""
+
+    def apply_alignment() -> None:
+        line_edit_factory = getattr(combo, "lineEdit", None)
+        if callable(line_edit_factory):
+            line_edit = line_edit_factory()
+            if line_edit is not None:
+                line_edit.setAlignment(Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter)
+
+        if "text-align: left" not in combo.styleSheet():
+            combo.setStyleSheet(
+                f"{combo.styleSheet()}\n"
+                "QComboBox, ComboBox, EditableComboBox { text-align: left; }\n"
+            )
+
+    apply_alignment()
+    QTimer.singleShot(0, apply_alignment)

desktop/components/forcing_progress_dialog.py

@@ -0,0 +1,84 @@
+"""Progress feedback displayed while forcing files are prepared."""
+
+from __future__ import annotations
+
+from PyQt6 import QtCore, QtGui, QtWidgets
+from PyQt6.QtCore import Qt
+from qfluentwidgets import MessageBoxBase, themeColor
+from workflows.support.translations import tr
+
+
+class _RotatingSpinner(QtWidgets.QWidget):
+    def __init__(self, parent=None, diameter: int = 52) -> None:
+        super().__init__(parent)
+        self._angle = 0
+        self._thickness = 5
+        self.setFixedSize(diameter, diameter)
+        self._timer = QtCore.QTimer(self)
+        self._timer.setInterval(16)
+        self._timer.timeout.connect(self._advance)
+        self._timer.start()
+
+    def _advance(self) -> None:
+        self._angle = (self._angle + 12) % 360
+        self.update()
+
+    def paintEvent(self, event) -> None:
+        _ = event
+        rect = self.rect().adjusted(6, 6, -6, -6)
+        painter = QtGui.QPainter(self)
+        painter.setRenderHint(QtGui.QPainter.RenderHint.Antialiasing)
+
+        track_pen = QtGui.QPen(QtGui.QColor(220, 224, 230), self._thickness)
+        track_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+        painter.setPen(track_pen)
+        painter.drawArc(rect, 0, 360 * 16)
+
+        accent = themeColor()
+        if not accent or not accent.isValid():
+            accent = self.palette().color(QtGui.QPalette.ColorRole.Highlight)
+        arc_pen = QtGui.QPen(accent, self._thickness)
+        arc_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+        painter.setPen(arc_pen)
+        painter.drawArc(rect, int(-self._angle * 16), int(110 * 16))
+
+
+class ForcingProgressDialog(MessageBoxBase):
+    """Legacy-aligned wait dialog for Step 2 file preparation."""
+
+    def __init__(self, parent, message: str | None = None) -> None:
+        super().__init__(parent)
+        message = message or tr("please_wait", "请稍候...")
+        self.setWindowTitle("")
+        self.hideYesButton()
+        self.hideCancelButton()
+        self.buttonLayout.parent().setVisible(False)
+        if hasattr(self, "setClosableOnMaskClicked"):
+            self.setClosableOnMaskClicked(True)
+
+        container = QtWidgets.QWidget(self)
+        layout = QtWidgets.QVBoxLayout(container)
+        layout.setContentsMargins(24, 16, 24, 16)
+        layout.setSpacing(14)
+        layout.setAlignment(Qt.AlignmentFlag.AlignCenter)
+
+        layout.addWidget(_RotatingSpinner(container, diameter=56), alignment=Qt.AlignmentFlag.AlignCenter)
+
+        title = QtWidgets.QLabel(tr("forcing_progress_title", "正在处理强迫场文件..."))
+        title.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        title.setStyleSheet("font-size: 18px; font-weight: 600;")
+        layout.addWidget(title)
+
+        self._message_label = QtWidgets.QLabel(message)
+        self._message_label.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self._message_label.setWordWrap(True)
+        self._message_label.setStyleSheet("font-size: 13px;")
+        layout.addWidget(self._message_label)
+
+        self.viewLayout.addWidget(container, 1)
+        self.setMinimumWidth(420)
+        self.setMinimumHeight(220)
+        self.setWindowModality(QtCore.Qt.WindowModality.WindowModal)
+
+    def set_message(self, message: str) -> None:
+        self._message_label.setText(message)