设置和保存的程序

设置是制造环境

制造设置定义了零件相对于库存、夹具和工具的放置方式。 cam.ManufacturingSetup 记录标识符、修订版本、刚性工作框架、世界坐标库存和夹具包络以及工具组件。本机内核接受 CAD 快照和资源，并生成有序的操作结果和一个发布的程序。

保存的应用程序使用 CamProgramDocument，便携式文档还存储在 Toolpath.data。该合同保留 NC 及其程序表示以及重新打开工作空间所需的设置、库存和图纸快照。可选操作保留单独的操作标识；可选的内核数据保留本机源证据。

便携式文件合同

文档将其自身标识为 format: "cadcamfun-cam" 和 version: 1。必填字段有 gcode, program, 发电机 settings, printer 额外的， stock，以及一个自由形式的 drawing 快照。可选字段有 operations, kernelArtifact， 和 kernelRequest.

每个存储操作都有一个唯一的 id, name, gcode， 和 program，带有可选工具、设置和源元素标识符。保留其 NC 和身份可以使操作往返独立于其显示标签。

操作顺序及组成

combineCamOperations 保留操作秩序。它使用操作标识符命名工具路径标识符，在提供时使用显式操作工具，并在存在多个操作时为显示名称添加前缀。组合程序采用来自第一次操作的单位和工件偏移。

对于单个操作，组合NC就是原文。对于多个操作，助手将其现有 NC 部分与操作注释连接起来。该帮助程序不会将所有部分重新发布到单个控制器程序中。本机内核是生成有序操作并发出一个集成程序的途径。

编写预生成部分的调用者必须确保兼容的单位、零点偏移、刀具编号、标题和程序结尾。成功的文档组合证明了其存储部分的顺序和一致性；它不添加机器清除证据。

生成并保存

1. 捕获绘图元素和待加工的毛坯。选择材料、机器、工具、工件偏置和质量控制。
2. 称呼 POST /api/toolpaths/manufacture 和 schemaVersion: 1、工作身份、名称和捕获的元素。按加工顺序明确提供操作或允许内核对其进行计划。
3. 检查返回的结果、问题、个人索赔和 release。工件可以是预览的或被阻止的；收到结果并不意味着输出已验证。
4. 建立一个 CamProgramDocument 其 G 代码、程序、工件和捕获的请求描述相同的结果。通过刀具路径创建或更新端点将其与该 G 代码一起保存。

制造端点评估提供的快照，而无需编写绘图或创建刀具路径。发电机 /generate 是一个单独的设置驱动路径，还可以为便携式文档提供 NC。

持久性验证

sidecar 通过格式识别可移植文档，并在保存之前解码完整模式。文档的 G 代码必须与刀具路径行的 G 代码匹配。操作标识符必须是唯一的，并且它们的有序组合必须重现保存的文本。 sidecar 重新解析操作 NC 以重建程序移动，而不是信任客户端提供的移动数据。

对于具有捕获请求的新本机工件，sidecar 会重新运行该请求并比较生成的工件、程序和原始 NC。失败或阻塞的结果、更改的工件以及不匹配的文本将被拒绝。没有捕获请求的新提供的工件将被删除，除非它是已保留在行上的未更改的工件。

当提供的源元素和库存与关联的存储工程图匹配时，该服务将计算工程图修订摘要。客户无法提供值得信赖的 sourceRevision 或任意验证声明。保存的修订由服务派生或仅为同一现有工件保留。

编辑 NC 并保留证据

更新可以取代 NC，同时发送未更改的先前便携式文档。该服务识别该情况，根据新文本重建已解析的程序，并删除不再匹配的操作和本机源证据。不一致的新文档会被拒绝，而不是默默地合并不相关的程序。

普通自由形式刀具路径数据仍然受支持。对 NC 的更改会删除不再匹配的陈旧本机工件元数据。客户提供 verification 和 response 字段不会成为可信的本地证据。

验证实现是 apps/sidecar/src/services/cam-program.ts; runKernelRequest, prepareCamProgramData， 和 drawingRevision 共享生成和保存所使用的相同请求适配器和身份逻辑。

保存的程序可以包含从重复刀具路径生成的子程序。刀具路径可以共享子程序的规则在 凸轮页面.

刚性工作框架

A WorkFrame 有原点和 X/Y/Z 轴。 validateWorkFrame 需要有限坐标、单位轴、成对正交性和数值公差内的右手方向。 workToWorld 应用框架； worldToWork 项目回来。无效帧、无效点和数字溢出会产生范围错误。

validateSetup 还检查非空设置标识符、非负安全整数修订、正体积有限包络、唯一夹具/工具标识符以及正有限刀具和刀架尺寸。切割长度不得超过伸出量。验证返回特定于字段的问题，以便调用者可以识别需要更正的值。

分度工作台加工

cam/indexing.ts 求解索引方向 table-AC 和 table-BC 布局。它将选定的工作平面法线旋转到机器 +Z 上，遵守旋转限制，并且更喜欢较小的可到达倾斜。程序点穿过工作框架和工作台绕机器枢轴旋转。

该适配器对带有固定刀具轴的工作台分度进行建模。倾斜头、控制器倾斜平面循环和同步五轴运动是独立的功能。旋转位置为度数；框架轴仍然是单位向量。

共享设置类型

ManufacturingSetup, WorkFrame, ToolAssembly, validateSetup, validateWorkFrame, workToWorld， 和 worldToWork 是通过出口 cam。便携式操作和文档模式导出自 @cadcamfun/api，这使得它们可用于 sidecar 持久性和桌面恢复逻辑。

在桌面上重新打开

saved-program.ts 捕获当前设置、库存、图纸以及正在保存的精确 NC。仅当其 NC 和哈希与这些字节匹配时，它才会保留内核工件。恢复时，它检查存储的工件和版本，恢复兼容的操作结果，重置重播验证，加载编辑器，并从快照恢复生成器和库存控制。

当只有普通 G 代码可用时，桌面会对其进行解析并显示。成功打开文本不会重新创建丢失的生成请求或升级程序的证据级别。

将源和结果放在一起

更改几何形状、库存、刀具尺寸、工作框架、机器、材料或操作顺序后重新生成。保留源快照以实现可重复性，并将更改的 NC 文件视为需要自己分析的新输出。源版本检查和工件重放可防止将早期结果作为不同程序字节的证据。

评估捕获的设置

快照适配器是本机制造请求的公共边界。这个独立的示例捕获了聚合物毛坯和稍大的库存盒，然后返回工件的实际发布级别。它既不写入绘图也不写入刀具路径。

import { cam } from "@cadcamfun/core"

const prepared = cam.kernel.jobOfSnapshot({
  schemaVersion: 1, id: "blank-job", name: "Blank", material: "POM",
  elements: [{ id: "blank", type: "cube", x: 20, y: 20, z: 5,
    width: 40, height: 40, depth: 10 }],
  stock: { x: 20, y: 20, width: 44, height: 44, depth: 11 },
  resolution: 0.5
})
if (prepared.status === "failed") throw new Error(JSON.stringify(prepared.issues))
const result = cam.kernel.runJob(prepared.value)
if (result.status === "failed") throw new Error(JSON.stringify(result.issues))
console.log(result.value.release)
console.log(result.value.claims)
console.log(result.value.identity.nc)

立方体位置为其中心；它的底部是 Z0。快照库存 X/Y 为其中心，宽度/高度为全尺寸。适配器将毛坯底部放置在所选零件的最低 Z 轴处，然后添加声明的深度。内核工作原点默认为库存顶部的库存中心； stock-corner 选择其最小 X/Y 和顶部 Z。

来源： packages/core/src/cam/kernel/snapshot.ts, execute.ts， 和 kernel.test.ts.

快照选项和边界

HTTP 本机请求需要 1–2、000 元素、1 版本、非空作业 ID/名称以及最多 80 个字符的材料名称。它最多接受 500 个显式操作，如果提供的话，还可以接受 1–200 个刀具。省略操作会调用规划器；显式的空操作列表并不是发明操作的请求。

finishAllowance 接受 0–5 毫米； scallop 为正且最多 1 mm； deburr 为正且最多 5 mm。本机默认值使用材料的精加工余量、0.01 毫米扇贝和 0.01 毫米路径公差。重播分辨率可以单独提供。选修的 subprograms: true 仅在所选方言支持的情况下请求翻译的重复发射。

快照机器字段命名已注册的预设。下层 ManufacturingJob 可以携带完整的机器记录，包括明确的行程和工作台几何形状；公共快照机器字符串本身不接受任意机器记录。

来源： packages/api/src/cam-kernel.ts, ai-cam.ts， 和 packages/core/src/cam/kernel/contracts.ts.

解决保存被拒绝的问题

当其源选择/库存与关联的存储的工程图不匹配时，可以保留有效的本机工件而无需源工程图修订。这种缺失并不意味着已保存的 NC 是根据当前图形重新生成的。报告新鲜度时，独立阅读图纸修订和源快照。

来源： apps/sidecar/src/services/cam-program.ts 和 apps/sidecar/test/cam-program.test.ts.

查看 3D 的本地工作

机器 vmc-standard （立式加工中心（BT40，12 000 rpm，11 kW），后置 fanuc）， 材料 pom-c (Acetal POM-C (Delrin)). Stock volume 21296 mm³, final 16000 mm³, equal to the part volume, so remaining volume is 0. Estimated cycle time 149 s. Release: verified-program。 NC 的长度为 3071 行。

工作框架数学，已完成

import { cam } from "@cadcamfun/core"

const frame = cam.frameFromNormal({ x: 40, y: 0, z: 10 }, { x: 1, y: 0, z: 1 })
// xAxis (0.707, 0, -0.707)  yAxis (0, 1, 0)  zAxis (0.707, 0, 0.707)
cam.validateWorkFrame(frame)                     // []

const world = cam.workToWorld(frame, { x: 10, y: 5, z: 0 })   // (47.071, 5, 2.929)
cam.worldToWork(frame, world)                    // (10, 5, 0)

cam.validateWorkFrame({ origin: { x: 0, y: 0, z: 0 },
  xAxis: { x: 1, y: 0, z: 0 }, yAxis: { x: 0, y: 0, z: 1 }, zAxis: { x: 0, y: 1, z: 0 } })
// [{ field: "frame", message: "Work frame axes must be orthonormal and right-handed" }]

常见面的旋转解决方案

底面需要 180° 倾斜，超出默认限制，因此列表为空， indexToolpath 抛出“机器的旋转轴无法在其限制内到达此工作平面”。相反，在第二次设置中加工底面。

const [angles] = cam.anglesFor({ x: 1, y: 0, z: 1 }, "table-BC")   // { b: -45, c: 0 }
cam.partToMachine({ x: 40, y: 0, z: 10 }, angles, "table-BC", { x: 0, y: 0, z: 0 })
// (21.213, 0, 35.355): the origin rotated -45° about Y around the pivot

设置验证消息

cam.validateSetup({
  id: "", revision: -1, frame,
  stock: { min: { x: 0, y: 0, z: 0 }, max: { x: 0, y: 10, z: 10 } },
  fixtures: [],
  tools: [{ toolId: "t", cuttingDiameter: 6, cuttingLength: 30, stickout: 20,
            holderDiameter: 32, holderLength: 40 }],
})

问题会被返回，而不是抛出，并且所有问题都会一次性报告，因此表单可以将每个坏字段一起标记。