feat: AI套图分层方案 + Gemini集成 - 4种图案类型处理 + 正片叠底 + 宽高比 + 模型选择

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-07 16:59:56 +08:00
parent 12395d8eca
commit dae906aba7
277 changed files with 15009 additions and 19922 deletions
--- a/Server/docs/API_PLT_Processing.md
+++ b/Server/docs/API_PLT_Processing.md
@@ -0,0 +1,136 @@
+# PLT 裁片处理接口文档 (PS 插件专用)
+
+本文档描述了用于处理 PLT 样板文件并生成 Photoshop 可用图像数据的后端接口。
+
+## 1. 接口概览
+
+该接口接收 PLT 格式的服装样板文件，在服务器端进行解析、几何计算和渲染，最终返回按尺码分组的 **透明背景 PNG 图片 (Base64)** 以及在画布上的 **精确坐标信息**。
+
+**新功能**: 支持同时上传两个文件（标准文件 + 旋转后文件），接口会自动进行轮廓匹配，计算出最佳的旋转角度和相似度。
+
+Photoshop 插件可以直接使用返回的 Base64 图片数据创建图层，并根据坐标信息自动进行排版。
+
+## 2. 接口定义
+
+- **URL**: `/api/v1/algorithm/process_plt`
+- **Method**: `POST`
+- **Content-Type**: `multipart/form-data`
+- **认证方式**: Bearer Token (需登录)
+
+### 2.1 请求参数 (Form Data)
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| `file` | File | **是** | - | **标准 PLT 文件** (.plt)。 |
+| `rotated_file` | File | **否** | - | **已旋转/待匹配的 PLT 文件** (.plt)。<br>如果上传此文件，接口将执行轮廓匹配算法。 |
+| `size_labels` | String | **是** | - | **尺码列表** (JSON 字符串)。<br>例如: `["S", "M", "L", "XL"]`<br>用于告诉算法文件里包含了哪些尺码。 |
+| `dpi` | Integer | 否 | `150` | **输出图片分辨率**。<br>建议与 PS 画布分辨率一致。 |
+| `rotation` | Integer | 否 | `0` | **强制旋转角度** (仅针对 `file`)。<br>可选值: `0`, `90`, `-90`, `180`。<br>接口会自动处理图片旋转和坐标变换。 |
+
+### 2.2 响应结构 (JSON)
+
+```json
+{
+  "success": true,
+  "total_groups": 5,
+  
+  // 裁片分组数据 (主要返回 file 的内容)
+  "groups": [
+    {
+      "group_id": 1,
+      "pieces": [
+        {
+          "size": "S",
+          "image_base64": "data:image/png;base64,iVBORw0KGgo...", 
+          "width_px": 800,
+          "height_px": 600,
+          "width_cm": 13.54,
+          "height_cm": 10.16,
+          "center_x_cm": 25.4,
+          "center_y_cm": 30.2,
+          "left_cm": 18.63,
+          "top_cm": 35.28
+        },
+        ...
+      ]
+    }
+  ],
+  
+  // 匹配分析结果 (仅当上传了 rotated_file 时存在)
+  "match_analysis": [
+    {
+      "size": "S",
+      "matches": [
+        {
+          "standard_id": 0,    // 标准文件中的裁片ID
+          "rotated_id": 3,     // 旋转文件中的裁片ID
+          "distance": 0.7032,  // Hausdorff 距离 (越小越相似)
+          "angle": 0.0         // 建议旋转角度
+        },
+        {
+          "standard_id": 5,
+          "rotated_id": 1,
+          "distance": 1.0371,
+          "angle": 180.0       // 建议旋转 180 度
+        }
+      ]
+    },
+    ...
+  ]
+}
+```
+
+### 2.3 关键字段说明
+
+*   **`image_base64`**: 
+    *   这是最核心的字段。
+    *   包含了裁片的 **PNG 图片数据**（带透明通道）。
+    *   格式为标准 Data URI: `data:image/png;base64,...`。
+    *   PS 插件可以直接读取此字符串并转换为图像对象。
+
+*   **`left_cm` / `top_cm`**:
+    *   **推荐使用**这两个字段进行定位。
+    *   表示裁片 **左上角** 在画布中的坐标（单位：厘米）。
+    *   坐标系原点通常取决于 PLT 文件的最小包围盒。
+    *   **注意**: PS 的 Y 轴向下，而 CAD 通常向上。接口返回的 `top_cm` 是基于数学坐标系的，在 PS 中使用时可能需要根据画布高度进行翻转 (`CanvasHeight - top_cm`)，或者直接使用（取决于具体需求）。
+
+*   **`match_analysis`**:
+    *   用于分析两个 PLT 文件之间的裁片对应关系。
+    *   可以用来判断某些裁片是否需要旋转 180 度才能匹配（例如倒顺毛面料）。
+
+## 3. Photoshop 插件调用示例 (JavaScript/ExtendScript)
+
+```javascript
+// 假设 response 是从接口获取的 JSON 对象
+var groups = response.groups;
+
+for (var i = 0; i < groups.length; i++) {
+    var group = groups[i];
+    var pieces = group.pieces;
+    
+    for (var j = 0; j < pieces.length; j++) {
+        var piece = pieces[j];
+        
+        // 1. 获取 Base64 图片数据 (去掉前缀)
+        var base64Data = piece.image_base64.split(",")[1];
+        
+        // 2. 保存为临时文件并打开 (伪代码)
+        var tempFile = saveBase64ToPng(base64Data);
+        var doc = app.open(tempFile);
+        
+        // 3. 复制到主文档
+        doc.activeLayer.copy();
+        app.activeDocument = mainDoc;
+        var newLayer = mainDoc.paste();
+        newLayer.name = piece.size + "-" + group.group_id;
+        
+        // 4. 定位 (将厘米转换为像素)
+        var dpi = 150; // 与请求参数一致
+        var x_px = piece.left_cm * dpi / 2.54;
+        var y_px = piece.top_cm * dpi / 2.54;
+        
+        // 移动图层
+        newLayer.translate(x_px, y_px);
+    }
+}
+```