Compositor 源码拆解：Mac 开源图像编辑器的图层、滤镜与像素内核

Compositor 源码拆解：Mac 开源图像编辑器的图层、滤镜与像素内核

【免费下载链接】CompositorThe Photoshop alternative for Mac项目地址: https://gitcode.com/gh_mirrors/compos/Compositor

Compositor 是一款面向 macOS 的免费开源图像编辑器，围绕图层合成与后期处理构建：图层、蒙版、选区、非破坏性变换、修复笔刷、调整层与滤镜一应俱全，快捷键按 Photoshop 习惯布局。工程以 SwiftUI 写成，按 Document（编辑逻辑）、IO（导入导出与项目存储）、Rendering（渲染管线）、UI（界面）四个目录划分，配套 50 余个测试文件，是研究大型 SwiftUI 应用的合适样本。

修图工作流：图层、选区与滤镜如何串起来

打开工程后，编辑会话集中在 Compositor/Document/：一个 EditorSession 同时持有图层树 document、撤销栈 history、视口 viewport 与当前工具 tool，levels、filterEdit 等模态面板也挂在它的状态上，UI 层观察属性变化即可驱动面板开合。

功能覆盖可以压成一张表：

能力	具体项
图层	混合模式、不透明度、复制、拖拽重排与嵌套、跨项目拖入
蒙版	绘制/填充/反相/羽化，可链接图层或单独变换，剪贴蒙版（maskSourceID）
调整层	Hue/Saturation、Levels、Curves、Exposure、Gradient Map、Grain 六种
选区	Marquee 选框、自由/多边形套索、魔棒，加减布尔与载入蒙版
变换	非破坏性移动/缩放/旋转/翻转，⌘ 拖控点自由扭曲，吸附参考线，精确数值输入
画笔修复	笔刷（Shift 画直线）、污点修复、仿制图章、模糊/涂抹/液化、渐变与形状、段落文字

一条典型链路：用 Marquee 或魔棒圈出区域，把图层像素或蒙版载入选区；按 B 补画细节，按 J 用 Spot Healing Brush 去掉污点；再按 ⌘L 做整体校正——调整层是独立图层，随时回改；收尾用 ⇧⌘E 导出 PNG 或 ⇧⌥⌘S 导出带实时预览的 JPEG。画布侧，Crop 支持 Option 对称裁剪，Canvas Size 与 Image Size 是两个独立命令。

EditorSession 状态多、耦合面大是这套方案的代价，换来的是任意两个功能——比如"选区内限制滤镜预览"——都能快速联动。

画布缩到很小时为什么不卡：渲染管线的分层设计

画布渲染不是 Core Graphics 简单叠加，而是一条分层管线，核心在 Compositor/Rendering/：LayerRenderer.swift 驱动图层合成，MetalLayerEffects.swift 处理描边与投影，SeparableBlend.swift 实现可分离混合模式；大画布由 TiledLayerRenderer.swift 分块渲染，配合 DownsampleCache.swift 的降采样缓存——图片缩到再小，原始分辨率也完整保留，放大超过 800% 时画布切到像素网格。

最密集的逐像素运算下沉到 C 内核：BrushPixels.c 管笔刷足迹与混合，HealPixels.c 做内容感知修复，WandPixels.c 跑魔棒，LevelsPixels.c、NoisePixels.c、AdjustPixels.c、LensPixels.c 各管一摊，ContentFill.c 实现能扩展画布的内容感知填充；MetalBrushCoverage.swift 则用 GPU 预算笔刷覆盖范围。

以 Levels 为例，⌘L 呼出面板后拖动滑杆，后台是 LevelsPixels.c 在算查找表，实时预览会限制在选区内：

Metal 与 C 双栈的维护成本不低，换来的是大画布帧率与逐像素精度两头都稳。

.comp 文档包存了什么，校验又卡在哪

Compositor 的项目文件是 macOS 文档包：manifest.json 记录元数据，images/ 下按图层 UUID 存放像素 .png 与蒙版 .mask.png（8 位灰度）。关键设计是像素与变换分离——PNG 只存原始像素与透明度，位置、旋转、翻转等变换写在 manifest，源照片被移动或删除后项目照样能打开。完整规范见 docs/project-format.md。

保存端用 NSFileCoordinator 加 FileWrapper.write(.atomic) 做"先写完整包、再原子替换"；加载端拒绝而不猜测：不支持的版本、无效元数据、缺失资源、用符号链接逃逸包外的路径，一律打回。格式演进到 v7：

版本	新增
v2	图层分组（parentID/isGroup），拒绝循环与超过 64 层的嵌套
v3	每层不透明度与 9 种混合模式（Normal 至 Color Burn）
v4	图层蒙版（maskFile/maskEnabled，白显黑隐）
v5	maskSourceID 实时蒙版，即剪贴蒙版的底层表示，链长上限 256
v6	组（文件夹）可携带蒙版
v7	调整层元数据

ProjectStore.swift 的 validate 与 checkSize 给出硬性上限：画布单边 ≤ 30,000 像素、全部源像素 ≤ 1 亿、蒙版像素额外 ≤ 1 亿、图层 ≤ 10,000 层、manifest ≤ 4 MiB、单个编码资源 ≤ 512 MiB、分辨率 1–9600 PPI（缺省 72）。撤销历史与视口状态只属于会话，不写进文件；旧版本应用遇到更高版本会明确拒绝打开，而不是错误渲染。

宁可报错也不猜测，是文档格式里最值得学的一条原则。

快捷键：Photoshop 习惯的完整复刻与自定义

工具键基本沿用 Photoshop 布局：V 移动、B 笔刷、E 橡皮擦、J 污点修复、S 仿制图章、T 文字、G 渐变、U 形状、I 吸管、M 选框、W 魔棒、L 套索、R 模糊/涂抹/液化、C 裁剪；[ ] 调笔刷大小，⇧[ ⇧] 调硬度，数字键 0–9 连续输入可精确设定不透明度，方向键按 1px/10px 步进微调。

菜单级命令同样齐全：⌘Z/⇧⌘Z 撤销重做、⌘S/⇧⌘S 保存与另存、⇧⌘E 导出 PNG、⇧⌥⌘S 导出 JPEG、⌘J 复制图层、⌘E 合并、⌘G/⌥⌘G 分组与剪贴蒙版、⌘L/⌘M/⌘U 呼出 Levels、Curves、Hue/Saturation、⌘D 取消选择、⇧⌘I 反选、⌥⌘A 选择主体。

比复刻更值得注意的是可自定义：ShortcutSettings 把重映射存进 UserDefaults（键 keyboardShortcuts.v1），保存前用 problem(in:) 校验——必须单键、修饰键位合法、不与 ⌘Q、⌘,、⌥⌘M 冲突、不允许重复指派，实现见 KeyboardShortcuts.swift。对"替代品"定位来说，快捷键是成本最低、感知最强的迁移入口，把校验做严谨，自定义才不会把布局改乱。

从源码构建到发布 DMG：一条完整的交付链路

构建要求 macOS 26 与 Xcode 26：打开 Compositor.xcodeproj 运行 Compositor scheme 即可。应用入口是 CompositorApp.swift，主窗口默认 1180×780，CompositorApplicationDelegate 持有全局 EditorSession 与项目控制器 projects；Info.plist 里除了 Sparkle 自动更新（SUFeedURL 与 SUPublicEDKey），还注册了 JPEG/PNG/HEIC/TIFF 的查看器声明与 .comp 的 Owner handler。

scripts/release.sh 把发布串成一条流水线：

1. xcodebuild -showBuildSettings 提取 MARKETING_VERSION 与 CURRENT_PROJECT_VERSION
2. CODE_SIGN_STYLE=Manual、Developer ID 证书、TEAM 3E4X3B9Z9T 执行 archive，按 scripts/ExportOptions.plist 导出后 codesign --verify --deep --strict 验签
3. 压缩后 xcrun notarytool submit 公证、stapler staple 装订，再用 create-dmg 打带背景图的 DMG（tiffutil -cathidpicheck 合成 Retina 背景）
4. 对 DMG 重复签名、公证、装订，spctl --assess 验证 Gatekeeper

质量侧，CompositorTests/ 有 50 余个测试文件，覆盖图层分组、蒙版、选区羽化、笔刷性能、变换、历史记录与导入导出，性能基准另存于 docs/brush-performance.md。证书与公证凭据全部放在仓库之外，仓库保持干净可构建——代价是新环境跑一次完整发布需要额外准备，换来的是任何人都能直接拿源码构建和跑测试。

【免费下载链接】CompositorThe Photoshop alternative for Mac项目地址: https://gitcode.com/gh_mirrors/compos/Compositor