CAD几何图形

绘图实体

@cadcamfun/core 直接导出 CAD 功能或在 cad 命名空间。架构优先 2D 实体使用 _tag 鉴别器：直线、圆、圆弧、折线、矩形、椭圆、样条线、文本、尺寸、剖面线和块。每个实体都有稳定的标识符、层、可见性和锁定状态；选择属于编辑器状态。

实体几何使用毫米和弧度。弧角标准化为一整圈，相等的起始/结束角度代表一个完整的圆。局部实体变换应用缩放、旋转，然后平移； Affine2D 支持可以包括剪切的组合变换。场景元素和参数历史适配器有自己记录的角度字段，包括度值放置和特征控制。

entitySchemaOf(tag) 返回一种实体类型的模式。在调用几何函数之前解码导入的数据。边界、曲面细分、相交、偏移和捕捉是单独的操作；渲染镶嵌曲线不会替换其分析实体。

约束草图

草图模型包含命名点、点之间的线、具有圆心和半径的圆以及逆时针圆弧。共享点标识符表示共享端点。约束包括重合、水平和垂直对齐、距离、长度、平行线和垂直线、相等长度和半径、相切、对称性和几何入射。

数值求解器通过 Levenberg-Marquardt 迭代和中心差雅可比行列式最小化约束残差。它报告自由度、自由点、冗余方程和冲突约束。结果可能是完全约束、约束不足、过度约束、冲突或失败。欠约束的解决方案可以满足每个维度，同时仍然允许运动；呼叫者必须保留这种区别。

草图约束接收数字。参数历史在调用求解器之前解析参数表达式。草图角度约束为弧度；转换用户输入的尺寸时，使用该功能自己的输入约定。

参数历史记录

参数化零件存储其参数和有序特征历史记录。重建按顺序评估表达式和特征，以便特征可以参考之前创建的草图、平面、实体或工具。核心包括拉伸、旋转、放样和扫描、布尔值、孔、图案、面编辑、文本、螺纹、钣金特征和配合控制。精确表示的可用性取决于特定的特征序列。

rebuild 产生网格体和特征问题。 rebuildExact 通过边界表示内核重播历史并记录为什么物体缺乏精确的表示。保留历史记录作为可编辑来源；生成的主体是派生输出。失败或不受支持的功能必须通过其问题记录保持可见。

网格几何形状和放置

网格使用索引三角形几何体。 CAD 层提供原始构造、网格布尔值、扫描和放样助手、拓扑和法线实用程序以及几何清理。 CAM 模型适配器将支持的场景元素转换为网格，包括嵌套组件，因此分析和刀具路径生成可以使用相同的放置几何体。

元素位置、旋转、缩放和平移会影响生成的零件。精确的场景放置镜像围绕边界框中心的视口变换。非均匀缩放可以删除元素的精确模型路径；场景转换会报告原因，并可能在导出期间使用多面表示。

精确的边界表示

cad.brep 通过面、环、边使用、边和顶点拓扑公开解析和 NURBS 几何体。其模块涵盖基元、扫描、放样、布尔、面编辑、混合、缝纫、镶嵌、分类、验证、质量属性以及 STEP 读写。 history-brep.ts 和 scene-step.ts 将此内核连接到参数化部件并放置场景元素。

POST /api/cad/exact/analyze 返回每个零件的有效性问题、体积、面积、质心、边界、拓扑计数、表面计数、识别的孔和加工分类。它还返回跳过的元素以及原因和总计。棱柱形加工结果报告轮廓、孔、型腔和顶部/底部水平面；不受支持的部件是有原因的。

POST /api/cad/exact/assembly 报告干涉、预期重叠、接触和未确定的对、物料清单项目、接头和紧固件计划。未确定的几何形状是报告的结果，而不是间隙的证明。这些分析路线在不改变绘图的情况下计算结果。

进出口

该核心具有 DXF 和绘图导入助手、棱柱形 STEP 解释路径和精确的 STEP B-rep 阅读器。棱柱路径读取合适的板、支架和法兰的占地面积和挤压高度；它报告了棱镜无法描述的特征。当需要精确支持的 STEP 拓扑时，选择精确的读卡器，并从任一路径检查诊断。

sceneToStep 将场景编写为 STEP AP214。精确支撑的实体保留精确的几何形状；仅网格实体可以作为多面实体发射。非实体元素会因原因而被跳过。这 faceted 选项控制后备。没有回应 step 不含可出口固体。

HTTP 精确路由接受 elements 或 drawingId;显式元素优先。快照数组允许 1–2、000 元素以及最多 200 个标识符的可选选择。通过存储的绘图，边车根据绘图访问规则读取场景。缺少源、空绘图、未知绘图或被拒绝的绘图会产生相应的请求或访问错误。

技术图纸

这 drawing 命名空间提供来自 3D 模型的投影、剖面、尺寸、图纸组合和 SVG 输出。这是与可编辑的 2D 实体绘图和加工程序分开的表示。模型更改后应重新生成投影和截面几何形状；工作表导出捕获用于构建它的模型状态。

在哪里扩展几何图形

开始于 packages/core/src/cad/index.ts 用于公共 CAD 曲面。实体运营就在旁边 entities.ts;约束求解是在 sketch.ts;网格历史记录位于 history.ts;确切的重播在 history-brep.ts;确切的拓扑和交换如下 brep/. packages/core/src/drawing/ 拥有图纸输出。同一文件夹中的支持模块包括 expr.ts （参数表达式如 width / 2 + 3，按依赖顺序解决，并将循环报告为错误）， tolerance.ts （曲线的弦矢段计数）， gear.ts （ISO 53 渐开线正齿轮轮廓）， thread.ts, sheet-metal.ts, fasteners.ts, recipes.ts （发出完整的、完全受限的特征历史的生成器）， dfm.ts （带有测量值和要求值的制造设计结果），以及 dxf.ts.

几何函数对值进行操作，无需打开应用程序存储。 Sidecar 服务处理访问和持久性，桌面适配器处理交互和渲染。在边界处保持明确的转换，以便显示网格、精确实体和保存的历史记录保留其独特的含义。

构建、验证和导出实体

这一完整的核心示例构建了一个 40 × 25 × 8 毫米的盒子，其一个角位于世界原点，检查其拓扑，对其进行测量，并导出 STEP 文本。它仅需要工作区核心包并且不执行任何应用程序写入。

import { cad } from "@cadcamfun/core"

const solid = cad.brep.makeBox(40, 25, 8)
const report = cad.brep.validateBrep(solid)
if (!report.valid) throw new Error(JSON.stringify(report.issues))

const mass = cad.brep.massProperties(solid)
console.log(mass.volume.toFixed(3)) // "8000.000" cubic millimetres
console.log(mass.centroid) // approximately { x: 20, y: 12.5, z: 4 }
const step = cad.brep.writeStepBreps([{ name: "Bracket blank", brep: solid }], {
  author: "Workshop",
  timestamp: "2026-01-01T00:00:00.000Z"
})
console.log(step.startsWith("ISO-10303-21;")) // true

明确的时间戳使得重复的交换输出可再现。如果没有它，STEP 写入将使用当前时间。 massProperties 还返回面积、每个面的面积以及单位密度下关于质心的惯性张量；体积为 mm3，面积为 mm2。计算物理质量时明确转换密度。

来源： packages/core/src/cad/brep/primitives.ts, mass.ts, validate.ts， 和 step.ts.

验证和转换选项

validateBrep 回报 valid, 问题记录, manifoldSolid，以及可选的属/卷。 manifoldSolid 表示每条边以相反含义使用两次的封闭壳。默认几何距离公差按模型尺寸的 10⁻⁵ 缩放，底面为 10⁻⁶ 毫米。调用者可以提供 tol，跳过体积/方向检查 skipVolume，或使用粗细分进行定向 coarseVolume.

精确分析 API machining 标志默认为 true。 STEP场景导出 faceted 回退默认为 true，并且装配紧固件规划的 washers 选项默认为 true。选择 ID 指的是场景元素，包括通过场景遍历解析的子组件。这些 HTTP 选项影响分析/导出，而不影响存储的绘图。

每个部分的场景导出返回 exact, faces, valid，以及可选注释。检查旁边的这些字段 skipped：可以导出有效的多面体，而不保留分析曲面。

来源： packages/core/src/cad/brep/validate.ts, scene-analysis.ts, scene-step.ts, assembly-analysis.ts， 和 packages/api/src/cad-exact.ts.

修复失败的重建或导出

原始维度必须是正的且有限的。直接几何函数可能会因无效尺寸而引发范围错误；传输层和服务层必须将这些故障转换为它们自己的类型化结果。重建问题与功能 ID 相关，因此可以从源头修复故障，而不是通过保留较早的网格来隐藏故障。

来源： packages/core/src/cad/sketch.test.ts, history.ts, scene-step.ts， 和 apps/sidecar/test/cad-exact.test.ts.

一步一步解决草图

草图是纯数据：一组 entities （点、线、圆、弧）和数组 constraints。直线、圆和圆弧通过标识符引用点，因此共享端点的两条直线共享相同的点 ID。解算器仅移动点坐标和圆半径；它从不添加或删除实体。

import { cad } from "@cadcamfun/core"

const sketch = {
  entities: [
    { id: "p1", kind: "point", x: 0, y: 0 },
    { id: "p2", kind: "point", x: 38, y: 1 },   // rough positions are fine:
    { id: "p3", kind: "point", x: 39, y: 26 },  // the solver moves them
    { id: "p4", kind: "point", x: 1, y: 24 },
    { id: "l1", kind: "line", p1: "p1", p2: "p2" },
    { id: "l2", kind: "line", p1: "p2", p2: "p3" },
    { id: "l3", kind: "line", p1: "p3", p2: "p4" },
    { id: "l4", kind: "line", p1: "p4", p2: "p1" },
  ],
  constraints: [
    { type: "fixed", point: "p1", x: 0, y: 0 },
    { type: "horizontal", line: "l1" },
    { type: "horizontal", line: "l3" },
    { type: "vertical", line: "l2" },
    { type: "vertical", line: "l4" },
    { id: "width", type: "length", line: "l1", value: 40 },
    { id: "depth", type: "length", line: "l2", value: 25 },
  ],
}

const result = cad.solveSketch(sketch)
result.status     // "fully-constrained"
result.dof        // 0
result.iterations // 3
result.residual   // < 1e-9
// points now at (0,0) (40,0) (40,25) (0,25)

运行相同的草图，无需 fixed 约束，结果变为 under-constrained 和 dof = 2 和 free = ["p1", "p2", "p3", "p4"]。矩形仍然具有正确的尺寸，但它可以在 X 和 Y 方向上滑动。添加第三个长度， { id: "w2", type: "length", line: "l3", value: 50 }，状态变为 conflicting. conflicts 然后列出不能同时满足的命名约束，最差的先列出（例如 w2 和 width）。列出您关心的约束条件 id;未命名的约束使用生成的标签进行报告，例如 vertical#4.

约束参考

每个约束都是一个带有 type 和一个可选的 id。长度以毫米为单位，角度以弧度为单位。在参数历史中，任何 value 也可以是参数表达式字符串。

弧线是逆时针从 start 至 end 关于 center。圆的半径是求解器变量，因此没有半径的圆 radius, diameter, equalRadius，或相切约束出现在 free.

构建参数化零件

A History 是一个参数表加上一个有序的特征列表。参数是其他参数的数字或表达式。它们按依赖顺序解析，循环是命名循环的错误。特征在任何尺寸字段中按名称引用参数。

import { cad } from "@cadcamfun/core"

const history = {
  parameters: { width: 40, depth: 25, thick: 8, hole: "width / 8" },
  features: [
    // the rectangle sketch from the previous section, with dimension
    // values replaced by parameter names: value: "width", value: "depth"
    { id: "s1", type: "sketch", plane: "XY", sketch: rectangleSketch },
    { id: "e1", type: "extrude", sketch: "s1", depth: "thick", operation: "new" },
    { id: "h1", type: "hole", plane: "XY", offset: "thick",
      at: [20, 12.5], diameter: "hole", depth: "thick" },
  ],
}

const mesh = cad.rebuild(history)
mesh.parameters // { width: 40, depth: 25, thick: 8, hole: 5 }
mesh.bodies     // one mesh body, id "e1"
mesh.issues     // []

const exact = cad.rebuildExact(history, mesh)
exact.bodies[0].brep        // present: the history has an exact representation
exact.warnings              // []
cad.brep.massProperties(exact.bodies[0].brep).volume // 7842.92… mm³
cad.brep.validateBrep(exact.bodies[0].brep).valid    // true

基准平面是右旋的： XY 有 u = X，v = Y，正常 +Z； YZ 有 u = Y，v = Z，法线 +X； ZX 有 u = Z，v = X，正常 +Y。草图、孔或文本也可以放置在较早版本的 ID 上 plane 功能，具有 offset 沿着正常。

精确的基元和放置

B-rep 内核直接构建解析实体。每个构造函数都有一个可选的位置 Frame;如果没有，实体将放置在世界框架中。

维度必须是正数且有限；否则构造函数会抛出范围错误。跑步 validateBrep 在信任体积或导出结果之前，对您从布尔值、扫描或导入构建的任何内容进行分析。直接来自构造函数的原语在构造时是有效的。

可靠重建的建模实践

• 在添加尺寸之前固定一个点并约束方向。约束不足的草图可以满足每个尺寸，并且在下一次重建时仍然会移动。
• 为每个面向用户的维度提供一个 id 因此，冲突报告会命名一个人认可的事物。
• 首选参数和表达式 ("width / 2 + 3", "max(a, b) * 2") 重复的文字；一次编辑即可驱动整个部分。
• 仅当较早的功能存在于列表中后，才通过 ID 引用它们。对历史记录重新排序可能会将有效的参考变成问题。
• 使用 targets 当一个零件有多个实体时，使用布尔值。默认情况下，该操作适用于迄今为止构建的每个实体。
• 查看 issues 每次之后 rebuild 和每个身体 brep 之后存在 rebuildExact 在依赖精确质量属性或 STEP 导出之前。
• 在草图中保留毫米和弧度单位。度值字段按原样记录（旋转角度、锥度、埋头孔角度）。

设计食谱

import { cad } from "@cadcamfun/core"

const recipe = cad.buildRecipe("mounting_plate", { width: 100, depth: 60, thickness: 10, fastener: "M8" })
recipe.summary  // "100 x 60 x 10 mm plate with four holes for M8 screws (Ø9 mm, medium fit)"
recipe.derived  // { holeDiameter: 9, edgeDistance: 18, holeSpacingX: 64, holeSpacingY: 24 }
recipe.rules    // ["hole diameter from ISO 273",
                //  "centre to edge >= 1.5 x hole diameter",
                //  "centre to centre >= 2.5 x hole diameter"]

recipe.history.parameters  // { width: 100, depth: 60, thick: 10, hole: 9, inset: 18 }
// features: sketch "outline", extrude "plate", holes hole_sw, hole_se, hole_ne, hole_nw
//           placed at ["inset","inset"], ["width - inset","inset"], …

const mesh = cad.rebuild(recipe.history)          // issues: []
const exact = cad.rebuildExact(recipe.history, mesh)
cad.brep.massProperties(exact.bodies[0].brep).volume  // 57455.31 mm³ = 60000 − 4·π·4.5²·10

历史记录很普通：您可以在编辑器中打开它，更改参数并重建。该配方只选择了合理的数字。

渐开线齿轮

const spec = { moduleValue: 2, teeth: 18 }          // pressureAngle defaults to 20°
cad.gearDimensions(spec)
// { pitchRadius: 18, baseRadius: 16.914, tipRadius: 20, rootRadius: 15.5 }

const outline = cad.gearOutline(spec, 6)   // 324 points, 6 per flank
cad.gearOutline({ moduleValue: 2, teeth: 5 })
// throws: 'A gear needs a module > 0 and at least 6 whole teeth'

紧固件和配合数据

价值观来自于 cad.metricThread(size), clearanceHole(size, fit) 和 tapDrill(size);仅通过两个助手查询 M6 行。相关规则，以及 M6 螺钉及其 Ø6.6 间隙孔的实际结果：