From 9e08f99429c5195174d60b06cf7e35d6ee6d8f96 Mon Sep 17 00:00:00 2001 From: wangdequan Date: Sun, 2 Aug 2026 07:00:43 -0400 Subject: [PATCH] P3-03: add OCCT primitives and placement --- config/runtime-baseline.json | 2 +- docs/web-cad-implementation-plan.zh-CN.md | 18 ++- src/facade/geometryRuntime.ts | 140 ++++++++++++++++++++-- src/facade/index.ts | 4 +- src/facade/mockFacade.ts | 2 +- src/facade/types.ts | 42 +++++++ tests/facade.test.ts | 6 +- 7 files changed, 195 insertions(+), 19 deletions(-) diff --git a/config/runtime-baseline.json b/config/runtime-baseline.json index 09ee935..7aa5479 100644 --- a/config/runtime-baseline.json +++ b/config/runtime-baseline.json @@ -2,7 +2,7 @@ "baselineId": "bitbybit-web-cad-runtime-0.1", "entrypoint": "BitBybitWebCadFacade", "frontendFramework": "React 18 + Vite 6 + TypeScript 5", - "geometry": { "provider": "@bitbybit-dev/occt-worker", "kernel": "OCCT WASM", "version": "1.1.1", "execution": "dedicated worker", "wasmSha256": "1b6a8fc7b83d222854f73b66af8d0e45ad4fdee025904b447e885d4e18ae8656", "status": "basic-runtime-integration" }, + "geometry": { "provider": "@bitbybit-dev/occt-worker", "kernel": "OCCT WASM", "version": "1.1.1", "execution": "dedicated worker", "wasmSha256": "1b6a8fc7b83d222854f73b66af8d0e45ad4fdee025904b447e885d4e18ae8656", "status": "primitive-and-placement-integration" }, "viewport": { "provider": "Three.js internal adapter", "package": "three", "version": "0.185.1", "baseline": "WebGL2", "status": "adapter-skeleton" }, "persistence": { "database": "@sqlite.org/sqlite-wasm 3.53.0-build1", "filesystem": "OPFS VFS with in-memory fallback", "writer": "single worker", "crossOriginIsolation": "required for OPFS worker", "status": "worker-skeleton" }, "targetBrowsers": "Capability matrix to be locked in P0-02", diff --git a/docs/web-cad-implementation-plan.zh-CN.md b/docs/web-cad-implementation-plan.zh-CN.md index 0a51849..885beba 100644 --- a/docs/web-cad-implementation-plan.zh-CN.md +++ b/docs/web-cad-implementation-plan.zh-CN.md @@ -1596,7 +1596,7 @@ P0 基线/治理 | P5-01 Three.js 视口适配器 | `IN PROGRESS` | `src/facade/threeViewport.ts` 使用 `three@0.185.1`，已挂载 WebGL2 场景和资源释放 | | P3-01 Bitbybit OCCT WASM 运行时 | `IN PROGRESS` | 精确锁定 `@bitbybit-dev/occt-worker@1.1.1`，专用 Worker 可加载 34,524,750 字节 OCCT WASM；尚未建立 FreeCAD/OCCT 自构建脚本，不能标记完成 | | P3-02 几何句柄与网格协议 | `IN PROGRESS` | Facade 已定义并实现受控 `ShapeHandle`、`MeshAsset`、`SubshapeRef` 类型；底层 OCCT hash 不出运行时，句柄篡改/释放后访问被拒绝；稳定子形状命名尚未实现 | -| P3-03 基本体和变换 | `IN PROGRESS` | 真实 OCCT Box 创建与三角化通过；Cylinder/Sphere/Cone、Placement、单位误差预算和黄金模型尚未实现 | +| P3-03 基本体和变换 | `IN PROGRESS` | 真实 OCCT Box/Cylinder/Sphere/Cone 和 FreeCAD 风格 Placement 已通过浏览器矩阵；0.05 mm 网格精度下曲面包围盒最大离散误差约 0.023 mm；自动化浏览器黄金测试尚未进入 CI | | P5-02 网格增量接入 | `IN PROGRESS` | Three Adapter 可用 `BufferGeometry` 接收 Facade `MeshAsset`，替换时释放旧 GPU geometry；对象缓存与文档增量同步尚未实现 | | P8-01 第一批自动化场景 | `IN PROGRESS` | `tests/facade.test.ts` 已覆盖初始化、schema、串行持久化队列、自动保存合并、资源引用、事件、任务生命周期、禁用命令、请求上下文、特征提交和历史；E2E/黄金几何待补齐 | @@ -1633,4 +1633,18 @@ P0 基线/治理 | Three 网格消费 | `PASS` | `MeshAsset` 转为 Three `BufferGeometry`，旧 geometry 在替换/销毁时释放；选择变化不再重建场景 | | 生产构建 | `PASS` | Vite 输出独立 `geometryWorker` 与 OCCT WASM；WASM 约 34.5 MB，gzip 约 8.6 MB | -限制和下一任务：P3-02 还需设计稳定 `SubshapeRef` 的持久命名算法；P3-03 继续加入 Cylinder、Sphere、Cone 和 Placement，并用黄金包围盒/体积核验；P5-02 需要按文档对象 ID 建立多对象网格缓存，而不是仅加载一个启动预览实体。 +限制和下一任务：P3-02 还需设计稳定 `SubshapeRef` 的持久命名算法；P3-03 需要把已通过的浏览器黄金包围盒矩阵纳入 CI，并补充体积核验；P5-02 需要按文档对象 ID 建立多对象网格缓存，而不是仅加载一个启动预览实体。 + +### 16.12 P3-03 基本体与 Placement 验证记录 + +所有输入先在 Facade 边界验证有限数、正尺寸、角度范围、非零方向向量和文档版本；错误输入不会触发 Worker 初始化。Placement 使用平移和轴角旋转，固定 `scaleFactor=1`，不把缩放混入 FreeCAD Placement 语义。变换产生新句柄，源形状保持不变。 + +| 算例 | 结果 | 包围盒/误差 | +|---|---|---| +| Cylinder `r=2,h=4,Y轴,中心原点` | 106 顶点、100 三角形 | X `[-1.9854,1.9854]`、Y `[-2,2]`、Z `[-2,2]`；最大离散误差约 0.0146 mm | +| Sphere `r=1.5,center=[1,2,3]` | 168 顶点、306 三角形 | Z `[1.5,4.5]`；X/Y 极值最大离散误差约 0.0228 mm | +| Cone `r1=2,r2=1,h=3,Y轴` | 138 顶点、160 三角形 | Y `[0,3]`、Z `[-2,2]`；X 极值误差约 0.0146 mm | +| Box Placement `translation=[5,-1,2]` | 24 顶点、12 三角形 | 变换后 X `[4,6]`、Y `[-3,1]`、Z `[0.5,3.5]`，与解析值一致 | +| 相同 Box 双句柄 | `PASS` | 释放第一个句柄后第二个仍可网格化；最终引用释放才删除 OCCT 缓存形状 | + +浏览器验证使用 `crossOriginIsolated=true` 的 Chrome、专用 OCCT Worker 和 `precision=0.05`。上述曲面误差均小于网格精度；这是三角网格显示误差，不代表 B-Rep 几何尺寸误差。 diff --git a/src/facade/geometryRuntime.ts b/src/facade/geometryRuntime.ts index bf32f73..271b123 100644 --- a/src/facade/geometryRuntime.ts +++ b/src/facade/geometryRuntime.ts @@ -1,10 +1,11 @@ import { BitByBitOCCT, OccStateEnum } from '@bitbybit-dev/occt-worker' import type { Inputs } from '@bitbybit-dev/occt' -import type { CreateBoxInput, GeometryCapabilities, MeshAsset, ShapeHandle } from './types' +import type { ApplyPlacementInput, CreateBoxInput, CreateConeInput, CreateCylinderInput, CreateSphereInput, GeometryCapabilities, MeshAsset, ShapeHandle } from './types' type KernelShapeReference = Inputs.OCCT.TopoDSShapePointer type KernelMesh = Inputs.OCCT.DecomposedMeshDto type ShapeEntry = { handle: ShapeHandle; reference: KernelShapeReference } +type KernelReferenceEntry = { count: number; reference: KernelShapeReference } const unavailableCapabilities = (): GeometryCapabilities => ({ provider: 'Bitbybit OCCT', @@ -19,13 +20,63 @@ const finitePositive = (value: number, name: string) => { if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a finite number greater than zero.`) } +const finiteNonNegative = (value: number, name: string) => { + if (!Number.isFinite(value) || value < 0) throw new RangeError(`${name} must be a finite non-negative number.`) +} + +const validateDocumentVersion = (value: number) => { + if (!Number.isSafeInteger(value) || value < 0) throw new RangeError('documentVersion must be a non-negative safe integer.') +} + +const validateVector = (value: [number, number, number], name: string, allowZero = true) => { + if (value.length !== 3 || value.some((coordinate) => !Number.isFinite(coordinate))) throw new RangeError(`${name} must contain three finite coordinates.`) + if (!allowZero && value.every((coordinate) => coordinate === 0)) throw new RangeError(`${name} must not be the zero vector.`) +} + +const validateAngle = (value: number, name: string, allowZero = false) => { + if (!Number.isFinite(value) || value > 360 || value < (allowZero ? 0 : Number.EPSILON)) throw new RangeError(`${name} must be between ${allowZero ? '0' : '0 (exclusive)'} and 360 degrees.`) +} + export const validateBoxInput = (input: CreateBoxInput) => { finitePositive(input.width, 'width') finitePositive(input.length, 'length') finitePositive(input.height, 'height') - if (!Number.isSafeInteger(input.documentVersion) || input.documentVersion < 0) throw new RangeError('documentVersion must be a non-negative safe integer.') + validateDocumentVersion(input.documentVersion) const center = input.center ?? [0, 0, 0] - if (center.length !== 3 || center.some((coordinate) => !Number.isFinite(coordinate))) throw new RangeError('center must contain three finite coordinates.') + validateVector(center, 'center') +} + +export const validateCylinderInput = (input: CreateCylinderInput) => { + finitePositive(input.radius, 'radius') + finitePositive(input.height, 'height') + validateVector(input.center ?? [0, 0, 0], 'center') + validateVector(input.direction ?? [0, 1, 0], 'direction', false) + validateAngle(input.angle ?? 360, 'angle') + validateDocumentVersion(input.documentVersion) +} + +export const validateSphereInput = (input: CreateSphereInput) => { + finitePositive(input.radius, 'radius') + validateVector(input.center ?? [0, 0, 0], 'center') + validateDocumentVersion(input.documentVersion) +} + +export const validateConeInput = (input: CreateConeInput) => { + finiteNonNegative(input.radius1, 'radius1') + finiteNonNegative(input.radius2, 'radius2') + if (input.radius1 === 0 && input.radius2 === 0) throw new RangeError('At least one cone radius must be greater than zero.') + finitePositive(input.height, 'height') + validateVector(input.center ?? [0, 0, 0], 'center') + validateVector(input.direction ?? [0, 1, 0], 'direction', false) + validateAngle(input.angle ?? 360, 'angle') + validateDocumentVersion(input.documentVersion) +} + +export const validatePlacementInput = (input: ApplyPlacementInput) => { + validateVector(input.placement.translation, 'translation') + validateVector(input.placement.rotationAxis, 'rotationAxis', false) + validateAngle(input.placement.rotationAngle, 'rotationAngle', true) + validateDocumentVersion(input.documentVersion) } export const assertShapeHandleIntegrity = (actual: ShapeHandle, expected: ShapeHandle) => { @@ -78,6 +129,7 @@ export class BitbybitGeometryRuntime { private cancelInitialization: (() => void) | null = null private sequence = 0 private readonly shapes = new Map() + private readonly kernelReferences = new Map() capabilities(): GeometryCapabilities { return { ...this.capabilitiesState } } @@ -113,6 +165,7 @@ export class BitbybitGeometryRuntime { subscription.unsubscribe() worker.terminate() this.shapes.clear() + this.kernelReferences.clear() this.worker = null this.client = null this.initialization = null @@ -141,20 +194,62 @@ export class BitbybitGeometryRuntime { center: input.center ?? [0, 0, 0], originOnCenter: input.originOnCenter ?? true, }) - const handle: ShapeHandle = { - id: `shape-${Date.now().toString(36)}-${(++this.sequence).toString(36)}`, - kernel: 'bitbybit-occt', - kind: 'solid', - documentVersion: input.documentVersion, - } - this.shapes.set(handle.id, { handle, reference: kernelShape }) - return handle + return this.registerShape(kernelShape, input.documentVersion) + } + + async createCylinder(input: CreateCylinderInput): Promise { + validateCylinderInput(input) + const client = await this.readyClient() + const kernelShape = await client.occt.shapes.solid.createCylinder({ + radius: input.radius, + height: input.height, + center: input.center ?? [0, 0, 0], + direction: input.direction ?? [0, 1, 0], + angle: input.angle ?? 360, + originOnCenter: input.originOnCenter ?? false, + }) + return this.registerShape(kernelShape, input.documentVersion) + } + + async createSphere(input: CreateSphereInput): Promise { + validateSphereInput(input) + const client = await this.readyClient() + const kernelShape = await client.occt.shapes.solid.createSphere({ radius: input.radius, center: input.center ?? [0, 0, 0] }) + return this.registerShape(kernelShape, input.documentVersion) + } + + async createCone(input: CreateConeInput): Promise { + validateConeInput(input) + const client = await this.readyClient() + const kernelShape = await client.occt.shapes.solid.createCone({ + radius1: input.radius1, + radius2: input.radius2, + height: input.height, + angle: input.angle ?? 360, + center: input.center ?? [0, 0, 0], + direction: input.direction ?? [0, 1, 0], + }) + return this.registerShape(kernelShape, input.documentVersion) + } + + async applyPlacement(input: ApplyPlacementInput): Promise { + validatePlacementInput(input) + const source = this.resolveShape(input.shape) + const client = await this.readyClient() + const kernelShape = await client.occt.transforms.transform({ + shape: source.reference, + translation: input.placement.translation, + rotationAxis: input.placement.rotationAxis, + rotationAngle: input.placement.rotationAngle, + scaleFactor: 1, + }) + return this.registerShape(kernelShape, input.documentVersion) } async mesh(shape: ShapeHandle, precision = 0.05): Promise { finitePositive(precision, 'precision') - const client = await this.readyClient() const entry = this.resolveShape(shape) + const client = await this.readyClient() const mesh = await client.occt.shapeToMesh({ shape: entry.reference, precision, adjustYtoZ: false }) return normalizeBitbybitMesh(entry.handle, mesh) } @@ -164,6 +259,12 @@ export class BitbybitGeometryRuntime { if (!entry) return this.assertHandle(shape, entry.handle) this.shapes.delete(shape.id) + const kernelReference = this.kernelReferences.get(entry.reference.hash) + if (kernelReference && kernelReference.count > 1) { + kernelReference.count -= 1 + return + } + this.kernelReferences.delete(entry.reference.hash) const client = this.client if (client && this.capabilitiesState.status === 'ready') await client.occt.deleteShape({ shape: entry.reference }) } @@ -171,6 +272,7 @@ export class BitbybitGeometryRuntime { dispose() { this.cancelInitialization?.() this.shapes.clear() + this.kernelReferences.clear() this.client?.occtWorkerManager.cleanPromisesMade() this.worker?.terminate() this.client = null @@ -186,6 +288,20 @@ export class BitbybitGeometryRuntime { return this.client } + private registerShape(reference: KernelShapeReference, documentVersion: number) { + const handle: ShapeHandle = { + id: `shape-${Date.now().toString(36)}-${(++this.sequence).toString(36)}`, + kernel: 'bitbybit-occt', + kind: 'solid', + documentVersion, + } + const kernelReference = this.kernelReferences.get(reference.hash) + if (kernelReference) kernelReference.count += 1 + else this.kernelReferences.set(reference.hash, { count: 1, reference }) + this.shapes.set(handle.id, { handle, reference }) + return handle + } + private resolveShape(shape: ShapeHandle) { if (shape.kernel !== 'bitbybit-occt') throw new Error(`Unsupported geometry kernel: ${shape.kernel}`) const entry = this.shapes.get(shape.id) diff --git a/src/facade/index.ts b/src/facade/index.ts index 258b51a..06ba6de 100644 --- a/src/facade/index.ts +++ b/src/facade/index.ts @@ -1,6 +1,6 @@ export { createMockFacade } from './mockFacade' export { createSqliteProjectPersistence, PersistenceWriteQueue, ProjectAutosaveScheduler, SqliteProjectPersistence } from './projectStore' export { ThreeViewportAdapter } from './threeViewport' -export { assertShapeHandleIntegrity, BitbybitGeometryRuntime, normalizeBitbybitMesh, validateBoxInput } from './geometryRuntime' +export { assertShapeHandleIntegrity, BitbybitGeometryRuntime, normalizeBitbybitMesh, validateBoxInput, validateConeInput, validateCylinderInput, validatePlacementInput, validateSphereInput } from './geometryRuntime' export { PROJECT_SCHEMA_MIGRATIONS, PROJECT_SCHEMA_SQL, PROJECT_SCHEMA_VERSION } from './projectSchema' -export type { BitBybitViewportAdapter, BitBybitWebCadFacade, CommandState, CreateBoxInput, DocumentSnapshot, FacadeEvent, FacadeState, GeometryCapabilities, MeshAsset, ModelTreeItem, PersistenceCapabilities, ProjectResource, ProjectSaveResult, ShapeHandle, SubshapeRef, TaskSnapshot } from './types' +export type { ApplyPlacementInput, BitBybitViewportAdapter, BitBybitWebCadFacade, CommandState, CreateBoxInput, CreateConeInput, CreateCylinderInput, CreateSphereInput, DocumentSnapshot, FacadeEvent, FacadeState, GeometryCapabilities, MeshAsset, ModelTreeItem, PersistenceCapabilities, Placement, ProjectResource, ProjectSaveResult, ShapeHandle, SubshapeRef, TaskSnapshot } from './types' diff --git a/src/facade/mockFacade.ts b/src/facade/mockFacade.ts index 57ca309..110d449 100644 --- a/src/facade/mockFacade.ts +++ b/src/facade/mockFacade.ts @@ -132,7 +132,7 @@ export function createMockFacade(): BitBybitWebCadFacade { selection: { getObjectId: () => state.selectedObjectId, select, clear: () => select('') }, task: { getActive: () => getState().task, begin: beginTask, update: (draft) => { if (state.task) state = { ...state, task: { ...state.task, draft: { ...state.task.draft, ...draft } } }; emitState() }, apply: applyTask, cancel: () => { if (state.task) state = { ...state, task: { ...state.task, status: 'cancelled' } }; emitState() } }, project: { capabilities: () => projectPersistence.capabilities(), save: (document = getState().document) => projectPersistence.save(document), load: (documentId) => projectPersistence.load(documentId), resource: projectPersistence.resource }, - geometry: { capabilities: () => geometryRuntime.capabilities(), initialize: () => geometryRuntime.initialize(), createBox: (input) => geometryRuntime.createBox(input), mesh: (shape, precision) => geometryRuntime.mesh(shape, precision), release: (shape) => geometryRuntime.release(shape), dispose: () => geometryRuntime.dispose() }, + geometry: { capabilities: () => geometryRuntime.capabilities(), initialize: () => geometryRuntime.initialize(), createBox: (input) => geometryRuntime.createBox(input), createCylinder: (input) => geometryRuntime.createCylinder(input), createSphere: (input) => geometryRuntime.createSphere(input), createCone: (input) => geometryRuntime.createCone(input), applyPlacement: (input) => geometryRuntime.applyPlacement(input), mesh: (shape, precision) => geometryRuntime.mesh(shape, precision), release: (shape) => geometryRuntime.release(shape), dispose: () => geometryRuntime.dispose() }, viewport: { createAdapter: () => new ThreeViewportAdapter() }, getState, subscribe: (listener) => { listeners.add(listener); return () => { listeners.delete(listener) } }, notify, } diff --git a/src/facade/types.ts b/src/facade/types.ts index 991a8cd..9239d9f 100644 --- a/src/facade/types.ts +++ b/src/facade/types.ts @@ -85,6 +85,44 @@ export type CreateBoxInput = { documentVersion: number } +export type CreateCylinderInput = { + radius: number + height: number + center?: [number, number, number] + direction?: [number, number, number] + angle?: number + originOnCenter?: boolean + documentVersion: number +} + +export type CreateSphereInput = { + radius: number + center?: [number, number, number] + documentVersion: number +} + +export type CreateConeInput = { + radius1: number + radius2: number + height: number + center?: [number, number, number] + direction?: [number, number, number] + angle?: number + documentVersion: number +} + +export type Placement = { + translation: [number, number, number] + rotationAxis: [number, number, number] + rotationAngle: number +} + +export type ApplyPlacementInput = { + shape: ShapeHandle + placement: Placement + documentVersion: number +} + export type CommandState = { id: string status: 'hidden' | 'disabled' | 'enabled' | 'active' @@ -204,6 +242,10 @@ export interface BitBybitWebCadFacade { capabilities(): GeometryCapabilities initialize(): Promise createBox(input: CreateBoxInput): Promise + createCylinder(input: CreateCylinderInput): Promise + createSphere(input: CreateSphereInput): Promise + createCone(input: CreateConeInput): Promise + applyPlacement(input: ApplyPlacementInput): Promise mesh(shape: ShapeHandle, precision?: number): Promise release(shape: ShapeHandle): Promise dispose(): void diff --git a/tests/facade.test.ts b/tests/facade.test.ts index 204e828..939336e 100644 --- a/tests/facade.test.ts +++ b/tests/facade.test.ts @@ -3,7 +3,7 @@ import assert from 'node:assert/strict' import { createMockFacade } from '../src/facade/mockFacade' import { PROJECT_SCHEMA_MIGRATIONS, PROJECT_SCHEMA_SQL, PROJECT_SCHEMA_VERSION } from '../src/facade/projectSchema' import { PersistenceWriteQueue, ProjectAutosaveScheduler } from '../src/facade/projectStore' -import { assertShapeHandleIntegrity, normalizeBitbybitMesh, validateBoxInput } from '../src/facade/geometryRuntime' +import { assertShapeHandleIntegrity, normalizeBitbybitMesh, validateBoxInput, validateConeInput, validateCylinderInput, validatePlacementInput, validateSphereInput } from '../src/facade/geometryRuntime' import type { ShapeHandle } from '../src/facade/types' test('facade exposes a stable initial document projection', () => { @@ -20,6 +20,10 @@ test('geometry boundary validates dimensions before invoking OCCT', () => { assert.throws(() => validateBoxInput({ width: 0, length: 2, height: 3, documentVersion: 1 }), /width/) assert.throws(() => validateBoxInput({ width: 1, length: 2, height: 3, center: [0, Number.NaN, 0], documentVersion: 1 }), /center/) assert.doesNotThrow(() => validateBoxInput({ width: 1, length: 2, height: 3, documentVersion: 0 })) + assert.throws(() => validateCylinderInput({ radius: 1, height: 2, direction: [0, 0, 0], documentVersion: 1 }), /direction/) + assert.throws(() => validateSphereInput({ radius: -1, documentVersion: 1 }), /radius/) + assert.throws(() => validateConeInput({ radius1: 0, radius2: 0, height: 2, documentVersion: 1 }), /radius/) + assert.throws(() => validatePlacementInput({ shape: { id: 'shape', kernel: 'bitbybit-occt', kind: 'solid', documentVersion: 1 }, placement: { translation: [0, 0, 0], rotationAxis: [0, 0, 0], rotationAngle: 0 }, documentVersion: 2 }), /rotationAxis/) }) test('geometry handles reject forged document ownership', () => {