面向 CAD / ERP / MES / 自动化脚本 开发者。 本文只描述稳定的对外接口(命令行参数、输入输出格式、退出码)。 内部实现细节(内核版本、内部接口约定、二进制格式)随版本变化,不在本文范围。
PandaNest 是一个二维排料(套料)SDK:把一个零件清单排进标准板材,尽量少用板、尽量省料, 并输出机床能直接用的结果。
输入:零件 DXF(多段线轮廓 + 内孔)+ 板材尺寸 + 工艺参数
输出:每块板放哪些件、每件的坐标/角度/镜像、用了多长、利用率、共边线、分层 DXF、HTML 报告
典型用法
运行形态:一个命令行程序 PandaNestfab.exe,不弹窗、不装服务、不写注册表。
进程退出时结果已经落盘,调用方只需读文件。
你的目录\
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 自带,无需安装)。 把整个目录拷走就能用,不需要管理员权限。
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 |
排样利用率(零件面积 / 实际占用面积) |
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 报告。
| 维度 | 说明 |
|---|---|
| 小 | 外壳 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 即可;参数全部是命令行开关,便于封装成面板 |
所有参数形式:--名字 值,顺序随意;不认识的值会被忽略(建议显式传值)。
| 参数 | 默认 | 说明 |
|---|---|---|
--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 | 计算时长上限,到时取当前最优 |
| 参数 | 默认 | 说明 |
|---|---|---|
--mult <0~4> |
不设置 | 重复偏好:0 = 每张板都单独优化(最省料);数值越大越倾向「同一排版复制多张板」(省换模);≥5 无效 |
--dir <-1~3> |
不设置 | 排样起点方向(四个角),-1 = 由内核决定 |
| 参数 | 默认 | 说明 |
|---|---|---|
--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里也有每件的共边标记。
| 参数 | 默认 | 说明 |
|---|---|---|
--shear 0\|1 |
不设置 | 剪切模式:排布必须能被 L 型直角剪整条切开、零件之间不能互扣 |
--sheargap <mm> |
0 | 剪刀与料的间隙 |
开剪切后板材数量通常会增加(排布自由度下降),这是工艺换材料的正常代价。 共边与剪切目前不能同时开。
| 参数 | 默认 | 说明 |
|---|---|---|
--mtorch <n> |
不设置 | 头数(2/3/4/6/8),≥2 生效 |
多头是「同一张板由多个头分左右区域同时切」,每个头有独立的切割顺序; 件数会按头分配,
--csv里带「头号」列。
| 参数 | 默认 | 说明 |
|---|---|---|
--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 |
— | 打印产品说明与全部参数 |
--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= 开头是每次迭代的记录。解析只需关注 # 共 … 和 # 共边 … 两行。
--csv)列(表头固定,UTF-8 带 BOM,Excel 直接打开):
排样组,张数,零件名,X(mm),Y(mm),角度,镜像
1,1,P01,305.00,5.00,90.00,
| 列 | 含义 |
|---|---|
| 排样组 | 第几个排样(同一排版复制多张板时,这里相同、张数 > 1) |
| 张数 | 这个排样要复制几张板 |
| 零件名 | 零件标识(与 DXF 里的图层/块名对应) |
| X / Y | 零件定位点(mm,Y 向上) |
| 角度 | 旋转角度(度) |
| 镜像 | 是否镜像(空 = 否) |
--export)| 图层 | 内容 |
|---|---|
SHEET |
板材外框 |
CUTLINE |
用长裁切线(每张板一条) |
PART / HOLE |
零件轮廓 / 内孔 |
STATS |
统计文字(板号/利用率/用长) |
COMMON_CUT |
共边线段(每条一段线) |
坐标系与零件原 DXF 一致(mm,Y 向上),可直接叠加到原图上比对。
--report:面向工艺/报价(每件尺寸、数量、面积占比)--report2:面向机床/后处理(利用率、张数,每件 orientation / position / box)两份都是单文件 HTML,内联 SVG,不需要联网即可查看。
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;
}
}
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)
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"
)
| 码 | 含义 | 建议处理 |
|---|---|---|
| 0 | 正常(至少输出一版结果) | 读文件 |
| 2 | 参数/运行异常(文本里有 ERROR …) |
记日志、提示用户 |
| 3 | 找不到零件 DXF | 检查 --dxf 路径 |
| 4 | 内核加载失败(缺文件/改名等) | 检查目录完整性 |
| 6 | 未授权:计算结果可预览,但输出文件被忽略 | 提示用户授权,或改用 --report 预览 |
每次调用请用独立进程(本文所有示例都是这样)。
原因:排料内核有个内部模块在一个进程里只能初始化一次,第二次调用会被内核判为非法状态 (返回失败码)。用独立进程调用完全绕开这个问题——这也是我们推荐的调用方式:
✔ 一个订单一个进程(进程本身很轻,启动 < 0.5s)
✔ 并发跑多个订单 = 启动多个进程(互不影响)
✘ 不要在一个进程里反复调用 DLL 接口(SDK 的 DLL 接口尚未对外开放)
线程数 --threads 是单个进程内部的并行度;一台 8 核机器建议 --threads 12,
同时跑 2~3 个进程即可吃满 CPU。
没授权也能用:可以调用、会正常计算、控制台能看到每版结果和最优结果(预览模式),
但不输出任何文件(--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 / 引擎报告」 会置灰,标题栏显示「未授权 · 仅预览」。
商业合作方式(分成、结算、支持范围)见同目录 《授权与合作政策》。
| 场景 | 结果 | 用时 |
|---|---|---|
| 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控制;给得越长结果通常越好,但边际收益递减。
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 单行输出。