# 自动合成印花服饰效果图工具 PRD ## 1. 背景 本项目是一款 Windows 本地桌面软件，用于把印花图片叠加到衣服底图上，生成服饰印花效果图。参考旧版工具已经具备衣服图、印花图加载，模板合成，自定义位置、尺寸、旋转，单张合成和批量合成等能力。 新版需要复刻旧版核心工作流，并增强可视化编辑能力，让用户可以直接在预览区拖动、缩放、旋转印花图片。 ## 2. 产品目标 - 用户可以快速加载衣服底图和印花图。 - 用户可以通过模板或手动编辑决定印花在衣服上的位置、尺寸和角度。 - 用户可以在预览区直观看到合成效果。 - 用户可以导出单张效果图。 - 用户可以批量生成多张效果图。 - 用户可以保存并复用常用合成模板。 - 软件可以在无 Python 环境的 Windows 电脑上运行。 ## 3. 目标用户 - 服饰定制、印花和打样工作人员。 - 需要批量生成服饰效果图的设计、运营或生产支持人员。 - 在局域网多台电脑上共同使用工具的小团队。 ## 4. 使用场景 ### 4.1 单张效果图制作 用户选择一张衣服底图和一张印花图，在预览区拖动、缩放和旋转印花，确认效果后导出一张合成图。 ### 4.2 批量效果图制作 用户导入一个衣服图片文件夹和一个印花图片文件夹，选择模板或当前编辑参数，批量生成合成图。 ### 4.3 模板复用 用户把常用的印花位置、尺寸和旋转角度保存为模板，下次直接选择模板完成同类衣服的合成。 ### 4.4 多人本地使用 多台 Windows 电脑安装同一工具。不同电脑可以使用相同或不同版本，但主程序本身应保持本地可运行，不依赖公网服务。 ## 5. 核心概念 ### 5.1 衣服底图 衣服底图是合成画布的基础图片。印花图会叠加到衣服底图之上。 要求： - 支持常见图片格式：PNG、JPG、JPEG、WEBP。 - 支持批量从文件夹加载。 - 保留原图尺寸作为默认导出尺寸。 ### 5.2 印花图 印花图是需要叠加到衣服底图上的图案。 要求： - 支持透明 PNG。 - 支持缩放、拖动和旋转。 - 支持批量从文件夹加载。 - 合成时保持透明区域正确。 ### 5.3 模板 模板是一组可复用的合成参数。 模板使用**比例坐标**存储，以适配任意尺寸的衣服底图（字段为相对衣服宽高的比例 `x_ratio` / `y_ratio` / `width_ratio` / `height_ratio` 及 `rotation`），应用时再换算为像素： ```json { "name": "左胸小号模板", "x_ratio": 0.50, "y_ratio": 0.22, "width_ratio": 0.16, "height_ratio": 0.16, "rotation": 0 } ``` 其中 `width_ratio` / `height_ratio` 表示目标框，而非印花最终尺寸；印花在框内按原始宽高比 contain 适配（详见 6.6）。 ## 6. 功能需求 ### 6.1 图片加载 用户可以分别选择衣服图片文件夹和印花图片文件夹。 要求： - 选择文件夹后，导入该文件夹及其所有子文件夹中的支持格式图片。 - 加载后在对应列表中显示图片文件。 - 支持全选、取消全选。 - 支持单独选中或取消选中某张衣服图片。 - 支持单独选中或取消选中某张印花图片。 - 支持选择当前预览使用的衣服图和印花图。 - **记住上次选择的衣服文件夹和印花文件夹**：分别持久化，下次打开「打开文件夹」对话框时定位到上次的位置；目录已不存在时回退到系统默认位置。 - 加载失败时显示可理解的错误信息。 - 忽略不支持的文件格式，并在日志中记录。 ### 6.2 预览区 预览区用于显示当前衣服底图和印花叠加效果。 要求： - 衣服底图按比例适配预览区域。 - 印花图显示在衣服底图之上。 - 预览区操作不应改变原始素材文件。 - 用户切换衣服图或印花图时，预览区及时刷新。 - 预览效果应尽量接近最终导出效果。 ### 6.3 拖动印花 用户可以用鼠标拖动印花图改变位置。 要求： - 拖动过程中实时更新预览。 - 拖动结束后更新 X/Y 坐标输入框。 - 坐标以衣服底图原始像素坐标为准。 - 不强制限制印花必须完全位于衣服底图内，但导出时只保留画布范围内内容。 ### 6.4 缩放印花 用户可以调整印花尺寸。 要求： - 支持通过宽度、高度输入框设置尺寸。 - 支持在预览区通过交互方式缩放。 - 默认保持宽高比例。 - 可以提供解除宽高比例锁定的选项。 - 缩放结束后更新宽度和高度输入框。 ### 6.5 旋转印花 用户可以旋转印花。 要求： - 支持角度输入。 - 支持向左旋转和向右旋转。 - 支持在预览区通过交互方式旋转。 - 角度单位为度。 - 旋转后导出结果与预览一致。 ### 6.6 模板选择 系统提供常用预设模板。 第一批内置模板： - 正方形模板。 - 纵向长方形模板。 - 横向长方形模板。 - 左胸小号模板。 要求： - 用户点击模板后，印花位置、尺寸、旋转参数立即应用到当前预览。 - 模板参数应基于衣服底图尺寸计算，避免只适配单一图片分辨率。 - 模板的 `width_ratio` / `height_ratio` 定义衣服上的**目标框**，而非强制拉伸尺寸。已知印花原始尺寸时，印花按自身宽高比缩放后 contain 进目标框并居中，不被拉伸变形；未知印花尺寸时退化为铺满目标框。 - 内置模板尺寸以贴近真实印花占比为准（例如正方形模板约为衣服宽度的 1/6，居中偏下），避免印花占据过大面积。 - 选中的模板是**粘性**的：在预览区切换衣服、切换印花，或在合成队列中选中一个**未微调**的任务时，印花不应丢失，应按当前选中模板基于该任务的衣服/印花尺寸重新计算落位，而非回退到画布的写死默认值。已手动微调的项不受影响，仍使用其自身参数。 - **记住上次选择的模板**：程序退出前持久化当前选中的模板，下次启动自动恢复选中该模板。若该模板为自定义模板且已被删除，则回退到第一个内置模板。 - 提供 `位置` / `尺寸` / `旋转` **三项独立的重置**，分别只把对应参数还原为当前选中模板的值（位置→模板居中位置；尺寸→模板目标框内适配的大小；旋转→模板角度，通常为 0），三者互不影响。 - 另在参数栏底部提供 `位置尺寸旋转重置为当前模板`，一次性把位置、尺寸、旋转整体还原为模板，作为三项分项重置的「全部」入口。该按钮归属「调整参数」，放在参数栏（紧挨它操作的参数），不放在模板管理区域。 - 未选模板或未加载衣服/印花时，以上所有重置不可用。 ### 6.7 自定义模板 用户可以保存当前参数为自定义模板。 要求： - 支持新增模板。 - 支持重命名模板。 - 支持删除自定义模板。 - 支持把模板保存到本地配置文件。 - 自定义模板在下次启动后仍可使用。 ### 6.8 单张合成导出 用户可以导出当前预览图。 要求： - 输出图片尺寸默认与衣服底图一致。 - 支持选择输出目录。 - 支持 JPG、PNG 输出。 - 支持输出质量设置。 - 文件名应避免覆盖已有文件，除非用户确认。 - 输出按「运行时间戳 → 印花」两级分组：每次导出运行先在输出目录下新建一个时间戳文件夹，其内再按印花分子文件夹，文件名为 `<衣服文件名>_<印花文件名>`，即 `输出目录/<时间戳>/<印花文件名>/<衣服文件名>_<印花文件名>.<扩展名>`（例如印花 `TY030`、衣服 `1` → `.../TY030/1_TY030.png`；单张导出与批量导出一致）。 - 一次导出运行（一次批量，或一次单张）共用同一个时间戳，避免重复生成时互相覆盖或混在一起。 ### 6.9 批量合成导出 用户可以批量生成合成效果图。 批量规则需要支持四种模式： - 多衣服 × 单印花：多个衣服图片使用同一个印花图片合成。 - 单衣服 × 多印花：一个衣服图片轮流使用多个印花图片合成。 - 一一匹配：第 1 张衣服图配第 1 张印花图，第 2 张衣服图配第 2 张印花图。 - 全组合：每张衣服图分别与每张印花图合成。 要求： - 用户可以选择批量模式。 - **记住上次选择的批量模式**：程序退出前持久化当前批量模式，下次启动自动恢复；持久化值非法时回退到默认模式（全组合）。 - 批量导出使用当前模板或当前编辑参数。 - 显示合成进度。 - 支持取消批量任务。 - 单个文件失败不应中断整个批量任务。 - 批量结束后显示成功数量和失败数量。 - 失败原因写入日志。 ### 6.10 低对比组合筛选 用户在实际使用中可能遇到衣服颜色和印花颜色接近的问题，导致合成后印花效果不明显。软件应支持在不导出合成图的情况下，先筛选出这类低可见度组合。 要求： - 支持对衣服和印花组合进行可见度分析。 - 分析应基于当前模板或当前 `TransformState` 对应的印花覆盖区域。 - 衣服颜色分析应优先使用印花将要覆盖的衣服区域，而不是整张衣服图。 - 印花颜色分析应优先使用透明 PNG 中 alpha 有效的像素区域。 - 系统应将组合标记为 `正常`、`偏低` 或 `不明显`。 - 用户可以筛选出 `偏低` 和 `不明显` 的组合。 - 用户可以选择跳过低对比组合，不参与批量导出。 - 低对比筛选不得修改原始衣服图片和原始印花图片。 - 低对比筛选不得直接替用户删除队列项，应由用户确认跳过或保留。 ### 6.11 日志 软件应记录运行日志。 要求： - 记录程序启动、图片加载、模板加载、导出开始、导出完成、异常信息。 - 日志保存到本地 `logs` 目录。 - 日志文件按日期或启动时间区分。 ## 7. 非功能需求 ### 7.1 平台与运行环境 - 第一阶段支持 Windows 桌面系统。 - 目标系统为 Windows 10 及以上，优先适配 Windows 10 / Windows 11。 - 开发语言为 Python。 - 指定 Python 版本为 Python 3.7。 - 软件应可在没有 Python 环境的电脑上运行。 ### 7.2 性能 - 单张预览操作应保持流畅。 - 批量合成时界面不应无响应。 - 大图处理应避免不必要的重复加载和重复缩放。 ### 7.3 稳定性 - 图片加载失败、路径不存在、输出目录无权限等情况应给出明确提示。 - 批量任务中单张失败时继续处理剩余图片。 - 程序异常时应写入日志。 ### 7.4 可维护性 - 图片处理逻辑应与界面逻辑分离。 - 模板、配置、日志应使用清晰的本地文件结构。 - 核心合成逻辑应可以被单独测试。 ## 8. 推荐技术方案 - 开发语言：Python 3.7。 - GUI：PySide6。 - 预览交互：QGraphicsView / QGraphicsScene。 - 图片合成：Pillow。 - 配置存储：JSON。 - 打包：PyInstaller，优先使用 onedir 模式。 说明：技术方案用于指导第一版实现。若后续出现明确约束，可以调整。 ## 9. 数据与文件结构 建议本地目录结构： ```text CMBot/ CMBot.exe config/ app_config.json templates.json logs/ output/ <时间戳>/ # 每次导出运行一个时间戳文件夹（如 20260617_143022） <印花文件名>/ # 其内按印花分组，子文件夹以印花文件名命名 <衣服文件名>_<印花文件名>.png # 文件名 = 衣服名_印花名，如 1_TY030.png ... resources/ ``` 模板配置建议： ```json { "templates": [ { "name": "左胸小号模板", "type": "builtin", "x_ratio": 0.35, "y_ratio": 0.28, "width_ratio": 0.12, "height_ratio": 0.12, "rotation": 0 } ] } ``` 应用配置建议（`app_config.json`，记录用户偏好，缺失或损坏时使用安全默认值）： ```json { "output_format": "PNG", "output_quality": 95, "output_dir": "", "last_garment_dir": "", "last_print_dir": "", "last_template": "正方形模板", "last_batch_mode": "full_combo", "update_source": "" } ``` 说明： - `last_garment_dir` / `last_print_dir`：上次打开的衣服 / 印花文件夹路径，用于让文件夹对话框定位到上次位置。 - `last_template`：上次选中的模板名称，用于启动恢复。 - `last_batch_mode`：上次选择的批量模式（取 `BatchMode` 枚举值，如 `full_combo` / `many_garments` / `many_prints` / `one_to_one`）。 - `update_source`：局域网更新源目录（含 `manifest.json`）。为空时不做更新检查。详见 `docs/10-lan-update.md`。 - 偏好的读取、分发与「改一次存一次」由主窗口集中处理，UI 控件不直接读写配置文件。 ## 10. 验收标准 - 可以加载衣服图片文件夹和印花图片文件夹。 - 可以在列表中选择参与合成的图片。 - 可以在预览区显示衣服底图和印花图。 - 可以拖动印花并同步坐标。 - 可以缩放印花并同步尺寸。 - 可以旋转印花并同步角度。 - 可以选择内置模板并应用到预览。 - 可以保存和复用自定义模板。 - 程序重启后自动恢复上一次选择的模板和批量模式。 - 可以分别把印花的位置、尺寸、旋转独立重置为当前选中模板的值。 - 可以导出当前单张合成图。 - 可以按多衣服 × 单印花模式批量导出。 - 可以按单衣服 × 多印花模式批量导出。 - 可以按一一匹配模式批量导出。 - 可以按全组合模式批量导出。 - 可以筛选出衣服颜色和印花颜色过于接近、合成后效果不明显的组合。 - 批量导出时显示进度，失败项写入日志。 - 打包后的程序可在无 Python 环境的 Windows 电脑上运行。 ## 11. 暂不做 - 不做云端账号和在线素材库。 - 不做复杂权限和审批流。 - 不做完整图片编辑器能力。 - 不做 AI 自动生成印花图。 - 不做第一阶段自动抠图和自动识别衣服区域。 - 不做移动端应用。