PandaNest SDK · 开发者指南

面向 CAD / ERP / MES / 自动化脚本 开发者。 本文只描述稳定的对外接口(命令行参数、输入输出格式、退出码)。 内部实现细节(内核版本、内部接口约定、二进制格式)随版本变化,不在本文范围。


1. PandaNest 是什么

PandaNest 是一个二维排料(套料)SDK:把一个零件清单排进标准板材,尽量少用板、尽量省料, 并输出机床能直接用的结果。

输入:零件 DXF(多段线轮廓 + 内孔)+ 板材尺寸 + 工艺参数
输出:每块板放哪些件、每件的坐标/角度/镜像、用了多长、利用率、共边线、分层 DXF、HTML 报告

典型用法

运行形态:一个命令行程序 PandaNestfab.exe,不弹窗、不装服务、不写注册表。 进程退出时结果已经落盘,调用方只需读文件。


2. 快速开始

2.1 目录要求

你的目录\
  PandaNestfab.exe        主程序
  PandaCanvas.dll         画布引擎(GUI 模式用,CLI 模式用不到)
  pcore.dll               排料内核
  kcore.dll               授权组件
  libwinpthread-1.dll     运行库
  dxf_skel_AC1021.dxf     DXF 导出模板

依赖:.NET Framework 4.8(Windows 10/11 自带,无需安装)。 把整个目录拷走就能用,不需要管理员权限。

2.2 最短调用

PandaNestfab.exe --cli --dxf parts.dxf --secs 20

控制台会打印说明头 + 每出一版结果一行,最后给最优结果:

t=  1.42  sheets=5  groups=5  parts=400  len=12,284  utilSheet=79.31  utilNest=81.63
t=  7.03  sheets=5  groups=5  parts=400  len=12,200  utilSheet=79.31  utilNest=81.68
# 共 7 版;最优 长度 12,200  板材 5 张  排样 5  利用率 79.31%(排样 81.68%)

字段含义:

字段 含义
sheets 用了几张板
groups 排样数(几个不同的排版,用于评估换模次数)
parts 已排零件数
len 总用长(mm)
utilSheet 板材利用率(零件面积 / 所有板面积)
utilNest 排样利用率(零件面积 / 实际占用面积)

2.3 带导出的一行调用

PandaNestfab.exe --cli --dxf parts.dxf --qty 20 --secs 20 --cc 1 ^
  --quiet --out r.txt --csv r.csv --export r.dxf --report reports

一次产出:文本摘要、CSV 明细、分层 DXF、HTML 报告。


3. 核心优势

维度 说明
小 外壳 167 KB(exe 157 KB + 画布 DLL 10 KB),无安装包、无 COM 注册,拷两个文件即可
快 400 件首个方案约 1.4 秒;4000 件 / 49 张板约 10 秒;CLI 无界面开销,纯计算
全 共边 + 割缝补偿、多头(2~8)、剪切(冲剪一体 L 型直角剪)、重复偏好、排样方向、分层 DXF、CSV、HTML 报告
稳 每次调用独立进程,连续调用不会因为内核内部状态而失败(详见 §8)
纯文件接口 不依赖 COM/管道/共享内存:--out 文本、--csv、--export、--report
可嵌入 进程不弹窗,CreateNoWindow = true 即可;参数全部是命令行开关,便于封装成面板

4. 命令行参数

所有参数形式:--名字 值,顺序随意;不认识的值会被忽略(建议显式传值)。

4.1 输入与规模

参数 默认 说明
--dxf <路径> 自动找 零件图 DXF(闭合多段线 = 零件轮廓,内部闭合线 = 内孔)
--qty <n> 20 每种零件数量
--sheet <宽x高> 2500x1250 板材尺寸(mm)
--sheets <n> 60 可用板材张数上限
--edge <mm> 5 四边留边
--gap <mm> 5 零件间距
--rot <free\|90\|0> free 旋转授权:任意角 / 只允许 90° / 不允许旋转
--tilt <度> 0 允许倾斜(0 = 只用直角排)
--threads <n> 12 计算线程数
--secs <秒> 20 计算时长上限,到时取当前最优

4.2 排样策略

参数 默认 说明
--mult <0~4> 不设置 重复偏好:0 = 每张板都单独优化(最省料);数值越大越倾向「同一排版复制多张板」(省换模);≥5 无效
--dir <-1~3> 不设置 排样起点方向(四个角),-1 = 由内核决定

4.3 共边(相邻零件共用一条切割线)

参数 默认 说明
--cc 0\|1 0 共边总开关
--ccgap <mm> 0.1 割缝补偿:0 = 不产生共边线;0.02~4 = 零件按该值分离但仍共边;≥零件间距通常无解
--ccmin <mm> 0 最短共边长度(太短的边不共)
--ccmax <mm> 1000 最长共边长度
--ccdiff 0\|1 1 是否允许不同零件之间共边
--ccsafety <n> 3 安全挡位(数值越大越保守)
--ccholes 0\|1 1 内孔轮廓也参与共边
--ccblock <mm> 500 共边分块尺寸(大板分块计算)

共边结果会写进 --export 的 COMMON_CUT 图层,--csv 里也有每件的共边标记。

4.4 剪切(数控冲床 / 冲剪一体机)

参数 默认 说明
--shear 0\|1 不设置 剪切模式:排布必须能被 L 型直角剪整条切开、零件之间不能互扣
--sheargap <mm> 0 剪刀与料的间隙

开剪切后板材数量通常会增加(排布自由度下降),这是工艺换材料的正常代价。 共边与剪切目前不能同时开。

4.5 多头 / 多炬(一台机床多个切割头)

参数 默认 说明
--mtorch <n> 不设置 头数(2/3/4/6/8),≥2 生效

多头是「同一张板由多个头分左右区域同时切」,每个头有独立的切割顺序; 件数会按头分配,--csv 里带「头号」列。

4.6 输出

参数 默认 说明
--out <文件> cli_result.txt 文本摘要(UTF-8)
--csv <文件> 无 排样明细 CSV(UTF-8 带 BOM,Excel 直接打开)
--export <文件> 无 分层 DXF:SHEET / CUTLINE / PART / COMMON_CUT
--report <目录> 无 排样订单报告(HTML,含每件尺寸/数量/占比 + 缩略图)
--report2 <文件> 无 排样结果报告(HTML,含利用率/张数 + 每件坐标/角度/包围盒)
--stream <文件> 无 每出一版解追加一行(供外部轮询进度)
--quiet 关 不打印任何内容,只写文件(推荐给程序调用)
--diag 关 打印诊断细节(贴合对数、坐标范围、角度分布),调试用
--help — 打印产品说明与全部参数

5. 输出文件格式

5.1 文本(--out)

# 零件 20 种 × 20 件 = 400 件
# 板材 2500x1250 × 60 张  边距 5 间距 5 旋转 free …
t=  1.42  sheets=5  groups=5  parts=400  len=12,284  utilSheet=79.31  utilNest=81.63
# 共 7 版;最优 长度 12,200  板材 5 张  排样 5  利用率 79.31%(排样 81.68%)
# 共边 251 条,总长 31,614 mm

以 # 开头是摘要行,以 t= 开头是每次迭代的记录。解析只需关注 # 共 … 和 # 共边 … 两行。

5.2 CSV(--csv)

列(表头固定,UTF-8 带 BOM,Excel 直接打开):

排样组,张数,零件名,X(mm),Y(mm),角度,镜像
1,1,P01,305.00,5.00,90.00,
列 含义
排样组 第几个排样(同一排版复制多张板时,这里相同、张数 > 1)
张数 这个排样要复制几张板
零件名 零件标识(与 DXF 里的图层/块名对应)
X / Y 零件定位点(mm,Y 向上)
角度 旋转角度(度)
镜像 是否镜像(空 = 否)

5.3 DXF(--export)

图层 内容
SHEET 板材外框
CUTLINE 用长裁切线(每张板一条)
PART / HOLE 零件轮廓 / 内孔
STATS 统计文字(板号/利用率/用长)
COMMON_CUT 共边线段(每条一段线)

坐标系与零件原 DXF 一致(mm,Y 向上),可直接叠加到原图上比对。

5.4 HTML 报告

两份都是单文件 HTML,内联 SVG,不需要联网即可查看。


6. 集成示例

6.1 C#(AutoCAD .NET / BricsCAD / ZWCAD)

using System.Diagnostics;
using System.Text;

public static class PandaNestCaller
{
    const string Exe = @"C:\PandaNest\PandaNestfab.exe";

    public static string Nest(string partDxf, string outDir)
    {
        string txt = System.IO.Path.Combine(outDir, "nest.txt");
        string csv = System.IO.Path.Combine(outDir, "nest.csv");
        string dxf = System.IO.Path.Combine(outDir, "nest.dxf");

        var psi = new ProcessStartInfo(Exe)
        {
            Arguments = $"--cli --dxf \"{partDxf}\" --qty 20 --sheet 2500x1250 --secs 20 " +
                        $"--cc 1 --quiet --out \"{txt}\" --csv \"{csv}\" --export \"{dxf}\"",
            UseShellExecute = false,
            CreateNoWindow  = true
        };

        using (var p = Process.Start(psi))
        {
            if (!p.WaitForExit(180000))
            {
                p.Kill();
                throw new TimeoutException("PandaNest 计算超时");
            }
            if (p.ExitCode != 0)
                throw new Exception($"PandaNest 失败,退出码 {p.ExitCode}");
        }

        foreach (var line in System.IO.File.ReadAllLines(txt, Encoding.UTF8))
            if (line.StartsWith("# 共"))
                return line;

        return null;
    }
}

6.2 Python

import subprocess, csv, pathlib

EXE = r"C:\PandaNest\PandaNestfab.exe"

def nest(part_dxf, out_dir, qty=20, secs=20, common_cut=True):
    out_dir = pathlib.Path(out_dir); out_dir.mkdir(parents=True, exist_ok=True)
    txt, csvf, dxf = out_dir/"r.txt", out_dir/"r.csv", out_dir/"r.dxf"

    args = [EXE, "--cli", "--dxf", part_dxf, "--qty", str(qty), "--secs", str(secs),
            "--quiet", "--out", str(txt), "--csv", str(csvf), "--export", str(dxf)]
    if common_cut:
        args += ["--cc", "1", "--ccgap", "0.1"]

    proc = subprocess.run(args, capture_output=True, timeout=300)
    if proc.returncode != 0:
        raise RuntimeError(proc.returncode)

    summary = next((l.strip() for l in txt.read_text(encoding="utf-8").splitlines()
                    if l.startswith("# 共")), "")
    rows = list(csv.DictReader(csvf.open(encoding="utf-8-sig")))
    return summary, rows, dxf

if __name__ == "__main__":
    summary, rows, dxf = nest(r"C:\temp\parts.dxf", r"C:\temp\nest")
    print(summary, len(rows), dxf)

6.3 批处理(多订单)

for %%f in (orders\*.dxf) do (
  PandaNestfab.exe --cli --dxf "%%f" --secs 15 --quiet ^
    --out "out\%%~nf.txt" --csv "out\%%~nf.csv" --export "out\%%~nf.dxf"
)

7. 退出码

码 含义 建议处理
0 正常(至少输出一版结果) 读文件
2 参数/运行异常(文本里有 ERROR …) 记日志、提示用户
3 找不到零件 DXF 检查 --dxf 路径
4 内核加载失败(缺文件/改名等) 检查目录完整性
6 未授权:计算结果可预览,但输出文件被忽略 提示用户授权,或改用 --report 预览

8. 并发与稳定性

每次调用请用独立进程(本文所有示例都是这样)。

原因:排料内核有个内部模块在一个进程里只能初始化一次,第二次调用会被内核判为非法状态 (返回失败码)。用独立进程调用完全绕开这个问题——这也是我们推荐的调用方式:

✔ 一个订单一个进程(进程本身很轻,启动 < 0.5s)
✔ 并发跑多个订单 = 启动多个进程(互不影响)
✘ 不要在一个进程里反复调用 DLL 接口(SDK 的 DLL 接口尚未对外开放)

线程数 --threads 是单个进程内部的并行度;一台 8 核机器建议 --threads 12, 同时跑 2~3 个进程即可吃满 CPU。


9. 授权说明

没授权也能用:可以调用、会正常计算、控制台能看到每版结果和最优结果(预览模式), 但不输出任何文件(--csv / --export / --report / --report2 会被忽略, 并打印一行说明)。这样开发者可以先把集成跑通,再谈授权。

状态 计算 预览(控制台/文本) 输出文件 CLI 退出码
已授权 ✅ ✅ ✅ 0
未授权 ✅ ✅ ❌(参数被忽略) 6(请求了输出时)

两种授权:开发机授权(DEV)= 开发者自己的 1 台开发机,用于集成/调试/打包; 客户机授权(RT)= 最终客户每台机器一份,随产品交付。两种都解锁全部输出功能。

拿到授权

# 1) 客户机器上取机器码
PandaNestfab.exe --cli --machine
→ 35CF6764

# 装好授权后可以看详情
PandaNestfab.exe --cli --license
→ 授权状态 / 类型 / 持有者 / 到期 / 机器码

# 2) 把机器码发给我们,换回 panda.lic

# 3) 把 panda.lic 放到 PandaNestfab.exe 同目录,重启即生效

授权文件绑定机器、可设到期日;GUI 未授权时「导出 DXF / 导出 CSV / 引擎报告」 会置灰,标题栏显示「未授权 · 仅预览」。

商业合作方式(分成、结算、支持范围)见同目录 《授权与合作政策》。

10. 性能参考(实测)

场景 结果 用时
20 种 × 20 件 = 400 件,2500×1250,间距 5 5 张板,利用率 81.7% 首个方案 1.4s / 稳定 7s
同上去共边 5 张板 + 251 条共边线 8s
4000 件(20 种 × 200) 49 张板 / 23 个排样 10~20s
双头(2 头)400 件 6 张板,按头分 208 / 192 件 8s

时长由 --secs 控制;给得越长结果通常越好,但边际收益递减。


11. 常见问题

Q:调用时会不会弹窗? 不会。主程序是 Windows GUI 子系统程序,命令行模式下不创建任何窗口;CreateNoWindow = true 即可。

Q:中文乱码? - --out / --csv 文件固定 UTF-8(CSV 带 BOM,Excel 直接打开)。 - 重定向 stdout 时也是 UTF-8;直接把输出接到控制台查看时用系统默认编码(不乱码)。

Q:能同时开共边和剪切吗? 目前不能(内核限制,两个都开通常无解)。按机床选一个。

Q:结果里为什么只有部分零件? 说明订单太大、板材张数不够。加大 --sheets,或减少 --qty。 若 parts 小于总数,即板材不够。

Q:能不能不写文件、只要返回值? 用 --quiet --out 写到临时文件后读取即可;未来版本会提供 --json 单行输出。