# stitch

**Repository Path**: DragonCodingPlus/stitch

## Basic Information

- **Project Name**: stitch
- **Description**: 图片合成器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图片合成器 (Stitch)

macOS / Windows 双平台原生深色风格图片合成工具，基于 Qt6 QML/C++17 构建。支持每张图片独立的视口（Viewport）缩放裁剪、自由摆放、背景设置，一键导出合成图。

## 功能总览

### 图片管理
- **添加图片** — 工具栏按钮或从文件管理器拖拽添加 PNG / JPG / WebP / BMP 图片，自动居中在画布视口放置
- **选择与排序** — 点击选中图片，按 Z 轴顺序排列，4 个层级操作按钮（置顶、上移、下移、置底）
- **右键菜单** — 在图片上右键弹出上下文菜单，支持层级调整和删除
- **删除图片** — 选中后点击右上角红色删除按钮、按 Delete 键，或通过右键菜单删除
- **拖拽移动** — 选中后在画布上自由拖动调整位置（含撤销/重做）
- **键盘快捷键** — `Ctrl+]` 上移一层、`Ctrl+[` 下移一层、`Ctrl+Shift+]` 置顶、`Ctrl+Shift+[` 置底

### 布局与变换
- **自由缩放** — 选中图片后拖拽 8 个控制点进行缩放（最小 20px，含撤销/重做）
- **双击进入裁剪模式** — 显示像素化马赛克背景，可自由平移和缩放图片视口
- **裁剪模式交互** — 滚轮缩放、拖拽平移、ESC 退出裁剪
- **尺寸编辑** — 单击右下角尺寸标签弹出编辑框，精确输入宽/高

### 背景设置
- **始终启用** — 背景始终打开，定义画布上的固定合成区域
- **透明背景** — 「透明背景」选项，画布上显示为透明区域，导出时输出透明 PNG
- **预设颜色** — 10 种预设颜色快速选择（白、黑、灰、蓝、绿、红、橙、粉、紫等）
- **系统取色器** — 「选择其他颜色...」调用操作系统原生颜色面板选取任意颜色
- **尺寸编辑** — 点击背景右下角尺寸标签弹出编辑框，精确输入宽/高
- **拖拽调整** — 背景右下角蓝色拖拽手柄，可自由调整背景区域大小
- **遮罩预览** — 背景区域外的画布部分以半透明黑色遮罩覆盖，帮助聚焦合成区域
- **画布居中** — 启动时背景矩形自动在视口中居中显示
- **实时同步** — 画布预览实时反映背景颜色/透明状态，与导出完全一致
- **自动保存** — 背景设置自动持久化到 `QSettings`（macOS: `~/Library/Preferences/`，Windows: 注册表）

### 导出
- **导出 PNG** — 将背景区域内的所有可见图片合成为 PNG
- **导出 JPEG** — 支持质量参数（默认 90%）
- **透明背景强制 PNG** — 当背景设置为透明时，自动锁定为 PNG 格式（JPEG 不支持透明通道）
- **导出尺寸** — 基于背景矩形区域，支持缩放因子

### 撤销/重做
- 支持标准 Undo / Redo 快捷键（Ctrl+Z / Ctrl+Shift+Z），覆盖图片移动和缩放操作

### 画布交互
- **滚轮缩放** — 以鼠标位置为中心缩放画布（0.1x ~ 10x）
- **拖拽平移** — 按住画布空白区域拖拽平移视口
- **重置画布** — 工具栏「重置」按钮，恢复缩放 1x、画布尺寸、居中视口
- **自动扩展** — 无背景模式下，图片拖出边界时画布自动扩展
- **拖拽锁定** — 拖拽过程中锁定 Flickable 滚动，防止图片意外跳位

### 视觉与交互
- macOS / Windows 统一深色风格（#252526 背景、SF / Segoe UI 字体、圆形控制点）
- 选中蓝色边框（#007AFF）带外发光效果
- 裁剪模式橙色边框（#FF9F0A）
- 暗色棋盘格画布背景
- 选中图片右下角实时显示尺寸（宽 × 高）
- 背景矩形白色半透明边框、右下角显示尺寸
- 状态栏显示图片数量、选中状态、操作提示

---

## 系统要求

| 项目 | macOS | Windows |
|------|-------|---------|
| 操作系统 | macOS 11.0+ | Windows 10 21H2+ |
| Qt | 6.10.1 | 6.10.1 |
| 编译器 | AppleClang (Xcode 16+) | MSVC 2022 |
| 构建系统 | CMake 3.16+ / Ninja | CMake 3.16+ / Ninja |
| 架构 | arm64 (Apple Silicon) | x86_64 |

---

## 项目结构

```
Stitch/
├── CMakeLists.txt              # CMake 构建配置（macOS + Windows）
├── pack.sh                     # 发布打包脚本 (macOS DMG)
├── pack.bat                    # 发布打包脚本 (Windows)
├── README.md                   # 本文件
├── src/
│   ├── main.cpp                # 入口（含 macOS AppKit / Windows 适配）
│   ├── resources/
│   │   ├── AppIcon.icns        # macOS 应用图标
│   │   ├── app_icon.rc         # Windows 应用图标资源
│   │   └── Info.plist.in       # macOS Bundle Info.plist 模板
│   ├── core/                   # C++ 核心数据模型
│   │   ├── ViewportItem.h/.cpp     # 单张图片的数据对象
│   │   ├── ViewportModel.h/.cpp    # 图片列表模型 + 背景设置 + QSettings 持久化
│   │   └── UndoCommands.h/.cpp     # 撤销/重做命令
│   ├── engine/                 # C++ 合成引擎
│   │   └── CompositionEngine.h/.cpp # PNG/JPEG 导出合成
│   └── qml/                    # QML UI 层
│       ├── Main.qml            # 窗口 + 布局 + 对话框 + 快捷键
│       └── ui/
│           ├── ToolBar.qml         # 顶部工具栏（添加/背景/重置/Z-order/导出）
│           ├── CanvasView.qml      # 画布 (Flickable + 背景 + 遮罩 + 拖放)
│           ├── ViewportDelegate.qml # 图片项 (选中框 + 裁剪 + 右键菜单)
│           └── StatusBar.qml       # 底部状态栏
├── docs/
│   ├── ARCHITECTURE.md         # 架构文档
│   └── superpowers/
│       ├── specs/              # 需求规格文档
│       └── plans/              # 实现计划
└── build/                      # 构建输出
```

---

## 构建与运行

### macOS 调试构建

```bash
cmake -S . -B build-debug -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_PREFIX_PATH=$HOME/Qt/6.10.1/macos \
  -DCMAKE_MAKE_PROGRAM=$HOME/Qt/Tools/Ninja/ninja

cmake --build build-debug --parallel
open build-debug/appStitch.app
```

### Windows 调试构建

```powershell
# 使用 Qt 提供的命令提示符（x64 Native Tools for VS 2022 + Qt环境）
cmake -S . -B build-debug -G Ninja ^
  -DCMAKE_BUILD_TYPE=Debug ^
  -DCMAKE_PREFIX_PATH=C:\Qt\6.10.1\msvc2022_64 ^
  -DCMAKE_MAKE_PROGRAM=C:\Qt\Tools\Ninja\ninja

cmake --build build-debug --parallel
.\build-debug\appStitch.exe
```

### macOS 发布打包

```bash
bash pack.sh
```

打包脚本执行：
1. 配置 & 编译 Release
2. Qt CMake Deployment API — 按需打包依赖（仅 38 个框架 vs macdeployqt 的 62 个）
3. Ad-hoc 重签名
4. 创建 DMG（约 56MB）

---

## 架构概述

### 三层架构

```
┌─────────────────────────────────────┐
│            QML UI Layer              │
│  Main.qml  ToolBar  CanvasView  ... │
├─────────────────────────────────────┤
│         C++ Object Layer             │
│  ViewportModel  ViewportItem         │
│  CompositionEngine  QUndoStack       │
├─────────────────────────────────────┤
│          Qt6 Runtime                 │
│  QtQuick  QtGui  QtWidgets  AppKit   │
│  (macOS) or Win32 API (Windows)      │
└─────────────────────────────────────┘
```

### 数据流

1. 用户在 QML 中拖拽/缩放图片 → 修改 `ViewportItem` 的属性
2. `ViewportItem` 通过 Qt 属性系统 (`Q_PROPERTY`) 发出信号
3. `ViewportModel` 监听到变化后发出 `contentChanged()` 信号
4. QML 层响应信号更新 UI 渲染
5. 导出时 `CompositionEngine` 从 `ViewportModel` 读取所有 `ViewportItem`，按 backgroundRect / boundingRect 渲染到 QImage

---

## 关键技术点

| 技术 | 实现 |
|------|------|
| 深色标题栏 | `main.cpp` 中 `#ifdef Q_OS_MACOS` 调用 `[NSApp setAppearance:]`，链接 `-framework AppKit` |
| 跨平台字体 | `#ifdef Q_OS_WIN` → `Segoe UI`，`#else` → `.AppleSystemUIFont` |
| 最小化依赖打包 | CMake `qt_generate_deploy_qml_app_script()` + `codesign --deep --sign -`（macOS） |
| 图片裁剪视口 | `viewportRect`（归一化 0-1）+ `zoom`（倍率）+ 像素级平移计算，QPainter 按公式重现 |
| 画布缩放 | `zoomCanvasAtPoint()` — 以鼠标在画布上的位置为中心缩放，保持该点静止 |
| 拖拽锁定 | `_dragLocked` 配合 `_lockCW/CH/CX/CY` 冻结 Flickable contentWidth/Height/scroll |
| 背景区域遮罩 | 4 个 `_big: 99999` 超大矩形覆盖区域外（上/下/左/右），半透明黑色 |
| 背景边框抗闪烁 | `antialiasing: false` + `border.width: Math.max(1, 1/canvasZoom)` |
| 弹窗失焦关闭 | `Qt.Dialog \| Qt.FramelessWindowHint` + `show(); raise(); requestActivate()` + `onActiveChanged` 检测失焦 |
| 透明背景持久化 | `QSettings("com.stitch.app", "Stitch")` 读写 `background/transparent` |
| 合成渲染 | `QPainter` 逐图片加载 → 按 `frameRect` 定位 → `viewportRect` 裁剪 → 按 zOrder 绘制到 backgroundRect 区域内 |
| 撤销/重做 | `QUndoStack` + `MoveFrameCommand` 记录移动/缩放的 `frameRect` 变更 |
| 本地化 | 全部 UI 字符串为中文，`Info.plist` 包含 `CFBundleDisplayName = "图片合成器"` |

---

## 下载

| 平台 | 下载 |
|------|------|
| macOS (Intel / Apple Silicon) | [图片合成器.dmg](https://gitee.com/DragonCodingPlus/stitch/releases/download/V1.0/%E5%9B%BE%E7%89%87%E5%90%88%E6%88%90%E5%99%A8.dmg) |
| Windows (x86_64) | [Stitch.zip](https://gitee.com/DragonCodingPlus/stitch/releases/download/V1.0/Stitch.zip) |

**微信公众号**

![公众号二维码](qrcode-wechat.jpg)

扫码关注，获取最新版本动态和使用技巧。

### 相关链接

- [作品主页](http://mjlong123.top/products/stitch)
- [作者主页](http://mjlong123.top)

---

## 许可证

仅供个人学习使用。项目名 Stitch，Bundle ID: `com.stitch.app`。