# image-workshop

**Repository Path**: jiodg45/image-workshop

## Basic Information

- **Project Name**: image-workshop
- **Description**: 图片滤镜管道编辑应用,自定义滤镜效果确认
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-07-09
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ImageWorkshop（图像工坊）

macOS 图像处理应用：Core Image 滤镜库、图片编辑、实时拍摄、扫码识别、照片库管理，一套界面里完成「滤镜 → 编辑 → 保存 → 管理」的完整流程。

## 功能

- **滤镜**：收录 Core Image 内置滤镜（中文名展示），支持滤镜链组合、参数调节、预设保存、批量应用/导出/导入；支持 **Filter Graph JSON**（AI/用户用 JSON 描述滤镜组合，引擎自动校验并执行）
- **图片编辑**：底图 + 贴纸图层管理（选中/拖动/缩放/旋转）、涂鸦、抠图、插入图片、撤销/重做、保存替换
- **拍摄**：相机实时滤镜、道具贴纸（人脸锚点/位置配置）、视频滤镜处理
- **扫描**：二维码/条形码识别、图片文字识别（OCR）、扫描线动画
- **照片库**：相簿/相册管理（多选、合并、移动、删除、重命名）、批量导入图片或文件夹、宫格自适应布局、照片查看器
- **动画/幻灯片**：可复用动画引擎（114 项效果目录、关键帧/时间线/转场）、照片墙 7 种布局切换与批量入场、相册幻灯片（多种转场 + 每张照片可独立设置动画 + 视频导出），预览与成片同源
- **动画库**：顶部「动画」模式集中演示入场/布局/相簿/转场/蒙版/色彩/3D/手势拖拽等效果，布局实时形变、堆叠轮播、Rolodex、视差倾斜均可交互
- **我的幻灯片**：图库「幻灯片」分栏，从本地/系统相册/我的相簿导入照片，拖拽排序、框选删除、撤销重做、逐张动画 + 参数调整、Ken Burns、模板、节拍对齐、转场、背景音乐、自定义 Lottie 模板、预览与导出（含音乐、分辨率/帧率可选）
- **其他**：人脸检测与标注、RAW 处理、预编译 Metal 内核库（50 个着色器）

## 环境要求

- macOS 14.0+
- Xcode 16+（工程使用文件夹同步，新增文件无需改 pbxproj）
- iOS 17.0+（核心包与全部 App 源码均已通过 iOS 编译，AppRootView 导航壳/选择器/URL Scheme 已就位；
  待建 Xcode iOS target 即可运行，详见 [iOS 适配设计](./docs/IOS_ADAPTATION_DESIGN.md)）

## 快速开始

```bash
open ImageWorkshop.xcodeproj
```

选择 `ImageWorkshop` scheme 运行。图片页可拖入图片或从图库选择，左侧选滤镜、中间编辑、右侧调参。

命令行构建：

```bash
xcodebuild -project ImageWorkshop.xcodeproj -scheme ImageWorkshop \
  -configuration Debug -derivedDataPath .build CODE_SIGNING_ALLOWED=NO build
```

## 发布版本

- **v1.0.0**：首个正式发布，包含滤镜/编辑/拍摄/扫描/照片库/动画/幻灯片全部能力。
  GitHub Release：<https://github.com/LongXiangGuo/image-workshop/releases/tag/1.0.0>
  Gitee 同步：<https://gitee.com/jiodg45/image-workshop>

## 测试

Xcode 内 ⌘U 运行单元测试；也可用 SwiftPM 测试 harness（当前 344 通过 / 2 跳过）：

```bash
CLANG_MODULE_CACHE_PATH=/private/tmp/clang-modcache swift test \
  --package-path .build/harness \
  --scratch-path /private/tmp/iw-harness-build \
  --cache-path /private/tmp/iw-harness-cache \
  --disable-sandbox -Xswiftc -disable-sandbox
```

修改源码后需先同步到 harness 再跑：`rsync -a --delete` 对应目录到 `.build/harness`（`Sources/ImageWorkshopCore`、`Sources/ImageWorkshop`、`Tests/ImageWorkshopTests`）。

## 滤镜图（Filter Graph JSON）

滤镜组合可以用一份 JSON「施工图」描述。引擎按能力目录**自动校验并映射**：
无前缀的 `type` 走 **Core Image** 滤镜，`metal.` 前缀走**预编译 Metal 内核**（50 个），
`lut` 走 LUT 资产（16 个内置）。同一份 JSON 自动适配执行代码，不需要改任何源码。

### 示例：纯 Core Image（电影感）

```json
{
  "schemaVersion": 2,
  "name": "电影感",
  "nodes": [
    {"id": "n1", "type": "contrast", "params": {"value": 1.15}},
    {"id": "n2", "type": "bloom", "params": {"intensity": 0.4, "radius": 8}},
    {"id": "n3", "type": "vignette", "params": {"intensity": 0.5}}
  ]
}
```

### 示例：Metal 内核 + LUT（霓虹胶片）

```json
{
  "schemaVersion": 2,
  "name": "霓虹胶片",
  "nodes": [
    {"id": "n1", "type": "lut", "params": {"asset": "teal_orange"}},
    {"id": "n2", "type": "metal.chromaticAberration", "params": {"amount": 3}},
    {"id": "n3", "type": "metal.bloom", "params": {"intensity": 1.2, "threshold": 0.6}},
    {"id": "n4", "type": "metal.grain", "params": {"amount": 0.4, "seed": 42}}
  ]
}
```

导入方式：图片页工具栏「滤镜图」→ 导入 JSON（校验失败会给出稳定错误码）；也可通过外部端口（Apple Events）命令行调用：

```bash
osascript -e 'tell application "ImageWorkshop" to «event IWFTexec» "{\"input\":\"/tmp/in.jpg\",\"output\":\"/tmp/out.jpg\",\"graph\":{\"schemaVersion\":2,\"name\":\"x\",\"nodes\":[{\"id\":\"n1\",\"type\":\"exposure\",\"params\":{\"ev\":0.5}}]}}"'
```

完整的 JSON Schema、节点参考（名称/后端/属性类型/取值范围/默认值）见
[docs/FILTER_GRAPH_SCHEMA.md](./docs/FILTER_GRAPH_SCHEMA.md)（由脚本从代码生成，与引擎能力严格一致；
改动节点后运行 `bash Scripts/generate_filter_graph_docs.sh` 刷新）。

可直接导入的示例文件在 [Examples/FilterGraphs/](./Examples/FilterGraphs/)（6 个，均已通过引擎校验）：
`电影感.json`、`赛博朋克.json`、`日系胶片.json`、`黑白电影.json`、`霓虹颗粒.json`、`复古暖调.json`。

机器可读文件：
- [docs/filter-graph.schema.json](./docs/filter-graph.schema.json)：Filter Graph 协议 JSON Schema（draft-07，编辑器/CI 校验用）
- [docs/filter-capabilities.json](./docs/filter-capabilities.json)：引擎能力目录（全部节点 + 参数范围 + LUT 资产，可直接喂给 AI）

## 工程结构

```
ImageWorkshop/                # App target（Presentation 层）
  App/                        # 依赖注入组合根
  Presentation/               # 视图 + ViewModel（Editor/Camera/Scan/PhotoLibrary…）
Sources/                     # 仓库根级 SwiftPM 包（可被其它工程引用）
  ImageWorkshopDomain/        # 实体/值对象/协议（零依赖）
  ImageWorkshopCommon/        # 错误/日志/术语
  ImageWorkshopApplication/   # 用例/交互器/编排
  ImageWorkshopInfrastructure/# Core Image / Vision / 视频 / SwiftData 实现
  ImageWorkshopCore/          # 伞形目标（@_exported，保持单入口）
Package.swift                 # 根级包清单（5 个可复用产品）
ImageWorkshopTests/           # 单元测试
Scripts/                      # 测试素材生成等脚本
TestAssets/PhotoLibraries/    # 本地生成的测试图库（9 相册 × 10 张）
```

## 作为依赖被其它工程引用

本仓库根目录即 SwiftPM 包（`Package.swift` 在仓库根），其它工程可直接以仓库为依赖，
按需复用 5 个产品：

```swift
// Package.swift（其它工程）
dependencies: [
    .package(url: "https://github.com/你的账号/ImageWorkshop.git", branch: "main")
]
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "ImageWorkshopDomain", package: "ImageWorkshopCore"),   // 纯领域
            .product(name: "ImageWorkshopApplication", package: "ImageWorkshopCore"), // 用例/编排
            .product(name: "ImageWorkshopInfrastructure", package: "ImageWorkshopCore"), // CI/视频/Vision 实现
            // 或整包入口：.product(name: "ImageWorkshopCore", ...)
        ]
    )
]
```

```swift
// 代码内按需 import（推荐按模块，避免伞形全家桶）
import ImageWorkshopDomain
import ImageWorkshopApplication
```

## 文档索引

- [动画与布局引擎设计](./docs/ANIMATION_LAYOUT_DESIGN.md)：114 项动画完整评估表、架构图、视频转场/抽帧兼容、iOS/macOS 策略、阶段计划
- [我的幻灯片设计与实现](./docs/SLIDESHOW_STUDIO_DESIGN.md)：幻灯片工坊架构、GOF 映射、优化建议、Lottie 扩展设计
- [模块化架构](./docs/MODULAR_ARCHITECTURE.md)：多 SPM target 分层、依赖规则、未来场景复用矩阵
- [Filter Graph JSON 协议](./docs/FILTER_GRAPH_SCHEMA.md)：滤镜施工图 Schema、全部节点（Core Image / Metal / LUT）与参数范围
- [iOS 全面适配设计](./docs/IOS_ADAPTATION_DESIGN.md)：平台抽象层、导航/字体/手势策略、分模块适配矩阵、GoF 映射、路线图
- [Phase 10 设计](./docs/PHASE10_DESIGN.md)：照片库/道具/滤镜链/自定义滤镜库
- [工作日志 Phase 4~9](./docs/WORK_LOG_PHASE4-9.md)：含 Phase 11 动画引擎记录