DP/Server/docs/API_PLT_Processing.md

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)。 如果上传此文件，接口将执行轮廓匹配算法。
size_labels	String	是	-	尺码列表 (JSON 字符串)。 例如: ["S", "M", "L", "XL"] 用于告诉算法文件里包含了哪些尺码。
dpi	Integer	否	150	输出图片分辨率。 建议与 PS 画布分辨率一致。
rotation	Integer	否	0	强制旋转角度 (仅针对 file)。 可选值: 0, 90, -90, 180。 接口会自动处理图片旋转和坐标变换。

2.2 响应结构 (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)

// 假设 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);
    }
}