极限切割 SDK 技术手册

《极限切割》的第一个版本是我在在外地做项目的时候，利用晚上休息时间在小旅馆写的，然后作为免费软件在网上发布。后来在热心客户们的建议和指导下，于2004年完成了《极限切割》的第一个商品化版本并实现销售。经过几年的技术积累，2008年完成最终版本的架构设计、底层数据结构设计和一个高性能算法设计，尽管期间面向的市场领域不断拓展，这套体系一直保持至今未发生任何改变，足以见证系统架构体系设计的通用性和前瞻性。当然，在这个过程中一直得到广大热心客户们提供的各种有建设性的建议和意见，《极限切割》所支持的功能也不断拓展，历经十几年风风雨雨，一直保持健壮的生命力。

　　
　　近年来越来越多的第三方开发团队使用《极限切割》SDK开发应用项目，并向我们咨询一些技术问题。这里我们做一个系统介绍，以帮助大家顺利使用这套SDK。

《极限切割》的开放式系统架构

《极限切割》软件系统采用开放式系统架构，通过主程序 xcut.exe 把一系列功能组件集成在一起，通过主程序菜单、工具条等统一调用。功能组件全部都是独立的 *.exe 程序，完全按照《极限切割》系统的相关规定设计，可以按照统一的标准与主程序 xcut.exe 集成。换句话讲，《极限切割》系统自身就是用 SDK 组合起来的，可作为使用 SDK 的过程中的一个非常好的参考范例。
　　
　　为什么功能组件没有选择DLL、OCX等方式，而是选用了 *.exe 的形式？原因是，这种形式的功能组件和xcut.exe运行在不同的进程中，功能组件的运行错误不会扩散至xcut.exe，不会导致《极限切割》主系统崩溃。
　　

如果第三方开发者了解《极限切割》主系统与功能组件之间的调用方式和数据交换方式，那么原则上可以在自己的系统中使用《极限切割》的功能组件。同样，第三方开发者也可以采用《极限切割》的功能组件设计标准，为《极限切割》系统设计新的功能组件。
　　
　　我们进入《极限切割》安装文件夹，一般默认位置在 “C:\Program Files (x86)\Queek\极限切割10.0”，可以看到 xcut.exe 和 xcut.ini 这两个文件。 运行 xcut.exe 后，能看到《极限切割》主窗口，如上图的样子。主窗口所展现的菜单和工具条以及图标等，全部通过 xcut.ini 配置。下面我们列举 xcut.ini 的开头若干行内容，看看庐山真面目。您可以尝试修改相关内容，并重启《极限切割》，看看主窗口会不会和您预期的一样发生变化。曾经见过有人把这个界面修改的我自己都不认识了。

[Root]
SoftwareName=极限切割10
Company=济南黑格软件有限公司
MainMenuName=主菜单
MenuItemCount=6
MenuFullSize=1
SeparatorHeight = 68
Logo=Logo.exe
OpenFileFilters=极限切割任务文件(*.xcut)|*.xcut|极限切割2006任务文件(*.xct)|*.xct|极限切割2005及更早版本任务文件(*.cut)|*.cut|所有文件(*.*)|*.*
SaveFileFilters=极限切割文档(*.xcut)|*.xcut|Access文档(*.mdb)|*.mdb|极限切割2006文档(*.xct)|*.xct|极限切割2005及更早版本文档(*.cut)|*.cut|所有文件(*.*)|*.*
OEM=0
Debug=0

ToolBarCount=1

[Menu(0)]
Name=文件(&F)
SubCount=9

[Menu(0,0)]
Action=

[Menu(0,1)]
Action=

[Menu(0,2)]
Action=

[Menu(0,3)]
Action=

[Menu(0,4)]
Action=QUEEKPROJECTSUMMARY.EXE
Name=汇总
Hint=显示开料任务汇总
Image=Summary.png
DisabledImage=Summary_.png
SaveTmpFile=1
LoadTmpFile=0

从上述配置文件可以看出，《极限切割》的软件名称（SoftwareName=极限切割10）、经销商名称（Company=济南黑格软件有限公司）等等，都是可以随意修改的。这可以给代理商带来很多方便。

主程序xcut.exe如何调用功能组件？

拿排料计算组件为例，该组件在 xcut.ini 中是这样定义的：

...
[Menu(3,10)] //第3个主菜单的第10个子菜单项，注意编号从0开始
Name=计算  //菜单项名称是“计算”。这个可以查看一下极限切割的菜单即可找到这一项。
Action=XcutCalc.exe	//注释：功能组件名称是 XcutCalc.exe，这个是排料计算的组件。
SaveTmpFile=1 //xcut.exe在调用该组件之前需要把原材料、零件清单写入临时文件。
LoadTmpFile=1 //xcut.exe在调用该组件之后需要把计算结果读入内存，以便显示计算结果。
DirtyFile=1 //xcut.exe在调用该组件之后需要标记数据为“脏”的，以便关闭文件时提醒保存。
...

可以看出，在《极限切割》主程序 xcut.exe 调用 xcutcalc.exe　组件之前，首先把计算条件，包括原材料清单、零件清单、计算参数等等写入一个任务文件，比如任务文件的名称可能是 temp.mdb。然后执行一个命令行程序调用，调用格式大致如下，

xcutcalc.exe "c:\temp.mdb"

当然，中间文件　“c:\temp.mdb”　的位置可以根据应用要求放置在其他文件夹也行。
　　
　　xcutcalc.exe 完成计算后，把计算结果也保存在同一个任务文件内。在 xcutcalc.exe 结束后，xcut.exe 从任务文件读出计算结果，并在作业显示片板中展示计算结果。
　　
　　这里有两个问题要解决，第一个问题是，xcut.exe 如何通过命令行参数调用 xcutcalc.exe 的？答案是，调用 Windows API 函数 CreateProcess；第二个问题是， xcut.exe 如何等待 xcutcalc.exe计算结束？答案是调用 WindowsAPI 函数 WaitForSingleObject。我们用 Delphi 编写了一个函数 ShowModalProcess 可以实现这两个功能，代码如下，大家可以参考。

unit Process;

interface
uses Windows, Forms;

function ShowModalProcess(const CmdLine : string): DWORD;

implementation

function ShowModalProcess;
var
  SI : TStartupInfo;
  PI : TProcessInformation;
  R : LongBool;
begin
  FillChar(SI, Sizeof(SI), 0);
  SI.cb := sizeof(SI);
  SI.wShowWindow := SW_SHOW;
  R := CreateProcess(
    nil,
    PChar(CmdLine),
    nil,
    nil,
    False,
    0,
    nil,
    nil,
    SI,
    PI
  );
  if R then
  begin
    Result := WaitForSingleObject(PI.hProcess, INFINITE);
  end
  else
  begin
    Application.MessageBox('System Error !' , 'Warning');
    Result := WAIT_FAILED;
  end;
end;

end.

任务文件结构

《极限切割》主程序和功能组件之间通过任务文件交换数据，任务文件默认是 xcut 格式，本质上是 XML文件。另外一种格式是 mdb 格式，即 Access 数据库文件格式。两种文件结构逻辑上是等价的，建议大家采用 mdb 格式，借助 SQL 命令，可以很容易读写这个文件。下面我们介绍一下 mdb 文件格式。

mdb文件中的数据表

利用《极限切割》创建一份新文件，另存为 mdb 格式。用微软的 Access 打开这份文件，即可查看其中的内容。这里面和应用开发直接相关的表如下：

表名	用途
_Root_	任务信息，提供计算用的基本参数设置，对应极限切割的“任务信息”窗口。
Raws	原材料清单，提供原材料材质、规格、尺寸、数量等信息。
Parts	零件清单，提供零件材质、规格、尺寸、数量等信息。
Jobs	作业清单，排料结果中每一种排料图对应一个作业。
Cuts	作业清单中的零件，提供零件编号、位置等信息。
Spaces	作业清单中的余料，提供余料位置和尺寸信息。

数据表结构以及数据表结构的自行定制

任务文件数据表的结构定义和中文说明，保存在 _Tables_ 和 _Fields_ 两个数据表中，在 Access 系统中打开 _Tables_ 即可看到其内容。
　　
　　如果大家打算修改《极限切割》任务文件的结构，可以修改安装目录里面的 Default.mdb 文件里面的 _Tables_ 和 _Fields_ 两个数据表。这两个数据表定义了任务文件的数据结构。从这里可以看出，《极限切割》的底层数据结构是可以随意订制化的结构。底层采用这样一种动态的数据结构，使得《极限切割》十几年来一直能够追随应用需求的变化，而软件本身几乎不需要做任何修改。
　　
　　注意，修改 Default.mdb 时，请不要随意删减《极限切割》原有内容，因为可能这会影响系统的基本功能。

数据表字段详解

---

数据表 _Root_ : 任务信息，提供计算用的基本参数设置，对应极限切割的“任务信息”窗口。

序号	字段	字段标题	数据类型	取值范围	说明
0	Raws	原材料清单	数据表
1	Parts	零件清单	数据表
2	Jobs	作业清单	数据表
3	Title	标题	字符串
4	CreatedDep	编制部门	字符串
5	CreatedBy	编制人	字符串
6	CreatedDate	编制日期	字符串
7	Customer	客户名称	字符串
8	Note	备注	字符串
9	ShipDate	交货日期	字符串
10	CutTextDefine	零件标签文字定义	字符串		不推荐使用
11	UseRatio	利用率	浮点数	$[0,1]$
12	CutWidth	刀口宽度	浮点数	$[0,\infty ]$
13	CutLength	刀口长度	浮点数	$[0,\infty ]$	-1 表示长度无限大
14	MinCutSize	最小切割尺寸	浮点数	$[0,\infty ]$
15	CutHead	刀具定位尺寸	浮点数		不推荐使用
16	CutTail	后清边尺寸	浮点数		不推荐使用
17	ModifyX0	左磨边尺寸	浮点数	$[-\infty ,\infty ]$
18	ModifyX1	右磨边尺寸	浮点数	$[-\infty ,\infty ]$
19	ModifyY0	下磨边尺寸	浮点数	$[-\infty ,\infty ]$
20	ModifyY1	上磨边尺寸	浮点数	$[-\infty ,\infty ]$
21	XtoleranceU	X尺寸正公差	浮点数	$[-\infty ,\infty ]$
22	XtoleranceL	X尺寸负公差	浮点数	$[-\infty ,\infty ]$
23	YtoleranceU	Y尺寸正公差	浮点数	$[-\infty ,\infty ]$
24	YtoleranceL	Y尺寸负公差	浮点数	$[-\infty ,\infty ]$
25	LengthUnit	长度单位	字符串		推荐“毫米”
26	AreaUnit	面积单位	字符串		推荐“平方米”
27	UnitRatio	单位换算	字符串
28	Decimal	小数位数	浮点数	0,1,2,3,4,5,6,7,8
29	MarginX0	左清边	浮点数	$[-\infty ,\infty ]$
30	MarginX1	右清边	浮点数	$[-\infty ,\infty ]$
31	MarginY0	上清边	浮点数	$[-\infty ,\infty ]$
32	MarginY1	下清边	浮点数	$[-\infty ,\infty ]$
33	EasyCut	切割模式	布尔	0,1
34	FirstCutDirection	首刀方向	浮点数	0=无限制,1=水平,2=竖直
35	MaxLayers	切割层数	浮点数	0,1,2,…
36	CutByRaw	按原材料顺序切割	布尔	0,1
37	MinSpaceSize	最小余料尺寸	浮点数	$[0,\infty ]$
38	VolumnUnit	体积单位	字符串
39	VolumnUnitRatio	体积单位换算	浮点数	$[0,\infty ]$
40	WeightUnit	重量单位	字符串
41	MinSpaceXSize1	最小余料尺寸	浮点数	$[0,\infty ]$
42	MinSpaceYSize1	最小余料尺寸	浮点数	$[0,\infty ]$
43	MinSpaceXSize2	最小余料尺寸	浮点数	$[0,\infty ]$
44	MinSpaceYSize2	最小余料尺寸	浮点数	$[0,\infty ]$

---

数据表 Raws : 原材料清单，提供原材料材质、规格、尺寸、数量等信息。

序号	字段	字段标题	数据类型	取值范围	说明
0	RawIndex	编号	整数	从 0 开始的整数编号
1	MaterType	材料类型	字符串	“线材”、“板材”、“坯材”
2	Material	材质	字符串
3	MaterCode	物料编码	字符串
4	MaterName	原材料名称	字符串
5	Xsize	X尺寸	浮点数	-1代表无穷大
6	Ysize	Y尺寸	浮点数	-1代表无穷大
7	Zsize	Z尺寸	浮点数	-1代表无穷大
8	Density	密度	浮点数
9	Weight	单件重量	浮点数
10	Price	数量单价	浮点数
11	AreaPrice	面积单价	浮点数
12	WeightPrice	重量单价	浮点数
13	Quantity	数量	浮点数	只能取整数值
14	Used	使用数量	浮点数	只能取整数值
15	Unused	未使用数量	浮点数	只能取整数值
16	MaxXSize	最大X尺寸	浮点数	-1代表无穷大
17	MaxYSize	最大Y尺寸	浮点数	-1代表无穷大
18	MinSpaceXSize1	余料最小X尺寸1	浮点数
19	MinSpaceYSize1	余料最小Y尺寸1	浮点数
20	MinSpaceXSize2	余料最小X尺寸2	浮点数
21	MinSpaceYSize2	余料最小Y尺寸2	浮点数
22	Note	备注	字符串
23	UseFirst	优先使用	布尔	0、1

---

数据表 Parts : 零件清单，提供零件材质、规格、尺寸、数量等信息。

序号	字段	字段标题	数据类型	取值范围	说明
0	PartIndex	编号	整数	从 0 开始的整数编号
1	Task	合同号	字符串
2	Work	工单号	字符串
3	MaterType	材料类型	字符串	“线材”、“板材”、“坯材”
4	Barcod	条形码	字符串	与标签打印程序配合使用
5	DMCode	二维码	字符串	与标签打印程序配合使用
6	Material	材质	字符串
7	MaterCode	物料编码	字符串
8	MaterName	名称	字符串
9	Xsize	X尺寸	浮点数	-1代表无穷大
10	Ysize	Y尺寸	浮点数	-1代表无穷大
11	Zsize	Z尺寸	浮点数	-1代表无穷大
12	ModifyX0	左磨边	浮点数	数字2147483647表示NULL
13	ModifyX1	右磨边	浮点数	数字2147483647表示NULL
14	ModifyY0	下磨边	浮点数	数字2147483647表示NULL
15	ModifyY1	上磨边	浮点数	数字2147483647表示NULL
16	XtoleranceU	X正公差	浮点数	数字2147483647表示NULL
17	XtoleranceL	X负公差	浮点数	数字2147483647表示NULL
18	YtoleranceU	Y正公差	浮点数	数字2147483647表示NULL
19	YtoleranceL	Y负公差	浮点数	数字2147483647表示NULL
20	Rotate	允许旋转	布尔	0=排料时不允许旋转，1=允许旋转
21	NotRotate	纹理	布尔	此项目废弃，禁止使用
22	Texture	纹理号	浮点数	取整数值，相同纹理号的零件排料时保持相同的方向
23	FilledPart	填充件	布尔	0，1	用于填充余料位置
24	Price	数量单价	浮点数
25	AreaPrice	面积单价	浮点数
26	WeightPrice	重量单价	浮点数
27	Quantity	数量	浮点数
28	Finished	完成数量	浮点数	系统自动产生，不允许修改
29	Unfinished	剩余数量	浮点数	系统自动产生，不允许修改
30	Note	备注	字符串
31	TopLine	上封边	浮点数	数字2147483647表示NULL
32	BottomLine	下封边	浮点数	数字2147483647表示NULL
33	LeftLine	左封边	浮点数	数字2147483647表示NULL
34	RightLine	右封边	浮点数	数字2147483647表示NULL
35	Shape	形状数据	字符串	格式参见《Q代码技术手册》
36	ShapeCode	形状	字符串	异形模版名称
37	ShapeParams	形状参数	字符串	异形模版参数
38	_A	参数A	字符串	具体参见《Q代码技术手册》
39	_B	参数B	字符串	具体参见《Q代码技术手册》
40	_C	参数C	字符串	具体参见《Q代码技术手册》
41	_D	参数D	字符串	具体参见《Q代码技术手册》
42	_E	参数E	字符串	具体参见《Q代码技术手册》

关于 xcutcalc.exe 的使用说明

xcutcalc.exe 是排料计算模块，正常调用的话会显示一个操作窗口。如果在调用的时候不想弹出这个窗口，可以修改 xcutcalc.ini 文件，把项 RunSilent 设置成 1 即可。参见下面的例子：
　　
例子 文件 xcutcalc.ini 内容：

[Speed]
Speed1=5
Speed2=10
Speed3=120
Speed4=300
Speed5=600
DefaultSpeedIndex=2

[MainForm]
caption=多材质开料优化计算
SpeedSelector=1
SpeedConfig=1

RunSilent=1

---

服务信息

我们为《极限切割》这套软件建立了一个专门的网站，网址是 http://www.queek.com，欢迎大家登陆了解该产品最新信息。