# 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);
    }
}
```