旋转成型与路径扫掠的公开 API 草案

[vilicvane]

背景

主分支已有 extrude(face, distance)、loft(sections, {spine?})、布尔、圆角、倒角和抽壳；本 issue 开发分支补充通用旋转成型与单截面沿路径扫掠。底层 Replicad 提供相应 PipeShell 能力；Code3D 的 coil 也使用扫掠内核。

补充一个重要场景：规则螺旋弹簧可以由截面绕直线旋转多圈、同时沿轴进给生成。这是螺旋运动，也可视为一种有规则路径的扫掠。普通无进给的 revolve 不能用超过一圈的角度生成弹簧。

公开 API 草案

import type {EdgeModel, FaceModel, LineAnchor, SolidModel} from '@code3d/core';

export type RevolveConfig = Readonly<{
  angle: number;     // 总旋转角度，单位为度
  advance?: number;  // 沿有向轴的总进给量；默认 0
}>;

/** 纯旋转或螺旋旋转。 */
export function revolve(profile: FaceModel, axis: LineAnchor, config: RevolveConfig): SolidModel;

/** 将平面截面沿连续开放曲线扫掠。 */
export function sweep(profile: FaceModel, spine: EdgeModel): SolidModel;

核心参数成组时使用 XxxConfig（这里是 RevolveConfig）；未来非核心调节参数再集中到独立的 options，不把核心参数命名成 options。第一版同时提供 profile.revolve(axis, config)、profile.sweep(spine)；函数与对应方法调用得到相同模型语义。

import {bezier, circle, line, rectangle, revolve, sweep} from '@code3d/core';

// 截面在 XY 平面、远离 Y 轴；纯旋转得到内半径 6、外半径 10 的环。
const section = rectangle(4, 12).rotate(90, 0, 0).originOffset(-8, 0, 0);
const axis = line([0, -20, 0], [0, 20, 0]);
export const ring = revolve(section, axis, {angle: 360});

// 同一轴上旋转 5 圈、总进给 25，形成简单弹簧形体。
const wireSection = circle(1).rotate(90, 0, 0).originOffset(-8, 0, 0);
export const spring = revolve(wireSection, axis, {angle: 5 * 360, advance: 25});

// 弯曲路径仍由通用扫掠表示。
const path = bezier([[0, 0, 0], [0, 8, 0], [5, 16, 0], [5, 24, 0]]);
export const bentRod = sweep(circle(2), path);

需要确定的语义

• 坐标和摆放：结果继承 profile 的完整局部参考架，不按输出包围盒重新居中。轴或路径保留其所属模型/引用身份；在共同组合关系闭包中求得相对于截面的位姿，然后构造结果。单独检查与组合检查沿用现有值和实例规则。
• 角度和进给：正角遵守有向轴右手规则，负角反向；advance 的正负独立表示沿有向轴的总位移。在角度 θ 处，轴向位移为 advance × θ / angle。纯旋转超过一圈会重走已有形体，应诊断；带非零进给时可以超过一圈。angle 和 advance 均须为有限数值，角度非零。
• 螺旋进给与路径扫掠：两者的中心路径可以相同，截面沿程姿态未必相同；需用弹簧实例验证端面和线材截面。规则螺旋体可由短参数表达，任意弯曲路径仍使用 sweep。
• 输入有效性：旋转轴必须是直线、方向非零；截面穿轴或生成退化实体时诊断。螺旋的相邻圈干涉仍需单独验证。扫掠路径采用连续开放 EdgeModel，起始切线非零；截面原点必须位于路径起点、截面法向与起始切线同向，不暗中移动作者截面。直线、弯曲 Bézier 和单孔截面已验证；闭合或退化路径被拒绝，多孔截面明确诊断。原生有效性检查拒绝无效实体，但并不保证识别全部几何自交。
• 拓扑和观察：结果是普通 SolidModel，可继续进行布尔、fillet、chamfer、shell、导出和拓扑选择。输入截面边、轴/路径与新生成表面的来源按现有操作规则记录；分裂、合并不猜测旧 ID。光标进入调用或参数时能分别观察截面、轴/路径与结果，预览使用同一已求解位姿。
• 缓存和生命周期：按几何、相对位姿及参数构造缓存身份；释放临时原生句柄。错误与取消不损坏输入模型值。

交付状态（已合并并推送）

工作分支 issue-201-revolve-root-0919 已实现上述 RevolveConfig 签名、函数与 FaceModel 方法、纯旋转及带进给的多圈旋转。正负角度、正负进给及反向轴已做几何回归；零体积结果报错。结果继承截面局部参考架，轴位姿从共同关系上下文转换。纯旋转沿内核历史转移拓扑来源；螺旋结果提供稳定可选的输出拓扑 ID，目前不推测其输入截面到端盖的拓扑对应。

App 工具参数可用 @code3d.param config.angle 等路径匹配对象字面量中的数值属性，追踪与编辑已有赋值，并在已有对象字面量中补入省略属性。line(...) 可直接作为轴；光标落在 config 属性键名或数值上时，Tab 均可进入对应参数。作者 TypeScript 签名仍要求 RevolveConfig；编辑中的调用暂缺第三个参数时，运行时按 360°、零进给预览，面板可写入 {angle: ...}，直接填写进给时会一并补入默认角度。可在 App 打开 packages/app/examples/operations/revolve.ts 验收五圈弹簧。含展开、动态键或同名简写的歧义属性不做直接源码写回。螺旋面目前要求单一外边界，不接受孔；尚未自动诊断相邻圈自交。revolve 已单独提交为 fbdbe85275c987ea28886be51de12cb0f8848100，并随本批在 0d311b286de3c0032a70fe5dbd308b4663df5ee9 本地合入 main，已于 2026-09-19 随 a4bb474 推送至远端 main。

sweep(profile, spine) 与 profile.sweep(spine) 已在同一分支完成第一版，沿用共同关系上下文与截面局部参考架。PipeShell 的单截面路径构造保留起始端盖的拓扑来源，缓存包括路径相对位姿和输入几何；临时原生句柄在成功或失败后释放。Core 测试覆盖直线、弯曲路径、单孔通管、关系摆放、旋转截面、拓扑及错误诊断；App 源码观察与示例也通过。验收入口：http://127.0.0.1:5183/#/file/examples/operations/sweep.ts。扫掠已提交为 880fef00a8c40c4e37dd613895901098e49af200，并随本批在 0d311b286de3c0032a70fe5dbd308b4663df5ee9 本地合入 main，已于 2026-09-19 随 a4bb474 推送至远端 main。

主区最终验证：Core 相关 14 项、App 定向 6 项与浏览器 config/Tab 1 项通过；Core/App 类型检查、packages/App/Web 构建、Web 120 页链接/锚点/资源检查、Prettier 与 diff check 通过。main 与开发 worktree 均 clean。远端 main 已包含本批提交；官网源码已更新，已随 alpha.12 部署至 https://www.code3d.org/ 。

剩余范围

1. 用规则弹簧进一步验证相邻圈干涉和复杂截面的可用边界。
2. 用真实弯管模型验证极端曲率、扫掠自交和路径尖点的诊断边界。
3. 根据真实用例决定闭合路径、多个孔及显式姿态模式；各项可拆独立 issue。

相关：#163 讨论按两点定义轴的关系变换 API，可复用其引用与坐标归属结论，但本 issue 不依赖新增轴构造器。现有公开参考：packages/core/docs/api.md、packages/core/docs/local-coordinates.md；内部约定：.agents/skills/code3d-coordinate-semantics/SKILL.md。

[vilicvane]

第一版已在独立工作区 issue-201-revolve-root-0919 完成，开发会话 w1:p1V。实现了 RevolveConfig、纯旋转与多圈轴向进给、对象字面量参数工具、源码观察和相应文档。Core 几何测试、公开类型测试、App 源码目标整组 124 项测试、源码观察测试、App 构建及官网链接检查通过。

当前改动尚未提交或集成，供验收。通用 sweep、螺旋孔截面与自动相邻圈干涉诊断仍在本 issue 的后续范围。