sadi-sdk-ts API 文档

版本：1.1.92
基于 WebGL2 的 BIM 三维渲染 SDK

目录

1. 安装
2. 快速开始
3. Scene
4. SceneContext
5. Element
6. Instance
7. Geometry
8. Material
9. Color
10. Label
11. Token
12. CameraInfo
13. SelectResult
14. Plane
15. Group
16. Storey
17. Light
18. Type
19. SceneTree / CategoryNode / TypeNode
20. RotateCamera
21. Wander
22. WanderSettings
23. Manager 类
    • SelectionManager
    • VisibleManager
    • ColorManager
    • BloomManager
    • ViewManager
    • AnimationManager
    • GroupManager
    • SelectableManager
    • MarqueeManager
    • SceneManager
    • ColorMediumManager
    • VisibleRecordManager
24. 过滤器
    • SceneContextFilter
    • CategoryFilter
    • TypeFilter
    • VisibleFilter
    • StoreyFilter
    • BloomFilter
    • LockedFilter
    • BoxInsideFilter
    • BoxIntersectsFilter
    • OrFilter
    • AndFilter
    • MaterialFilter
25. GeometryEngine
26. 方案记录
    • ColorRecord
    • ColorRecordItem
    • ExtraColorItem
    • VisibilityRecord
    • RecordMedium
    • ElementUniqueId
    • CameraRecord
27. 接口
    • IAxisControl
    • ISketchControl
    • IWireControl
    • IExtrusionWire / SpaceWire / WallWire
    • PipeWire
    • IWaterFlowControl
    • WaterFlowSegment
    • ICuboidEditer
28. 工具
    • Box
    • SceneUtils
29. 枚举
    • Category
    • SelectMode
    • SectionMode
    • VisibilityType
    • ModelType
    • WaterFlowType
    • SelectAction
    • LoadState
30. 事件

安装

npm i sadi-sdk-ts

依赖：gl-matrix

快速开始

import { Scene, Token, LoadState } from "sadi-sdk-ts";

const div = document.getElementById("app") as HTMLDivElement;
const scene = new Scene(div);

const token: Token = { type: "bearer", value: "your-token" };

scene.load_url(
  "https://your-server.com/model.sadi",
  token,
  (scene, progress) => {
    if (progress === "end") {
      const sc = scene.scene_context;
      // 开始交互...
    }
  },
);

Scene

场景入口类。

构造函数

| 方法 | 入参 | 返回 | 说明 | | ---------------------------------- | ---------------- | ------- | ----------------------------- | | constructor(div: HTMLDivElement) | div — 容器 DOM | Scene | 创建场景，内部自动创建 canvas |

属性

| 属性 | 类型 | 说明 | | ----------------- | --------------------- | --------------------- | | efficiency_mode | boolean | 急速模式，默认 true | | scene_context | SceneContext | 场景上下文（只读） | | fps_changed | (f: number) => void | fps 变化回调（set） | | after_draw | () => void | 绘制结束回调 | | on_crash | () => void | GPU 崩溃回调 |

方法

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | -------------------------------- | ------------------------ | | update_size() | — | void | 手动更新 canvas 尺寸 | | enable_measure(flag: boolean) | flag — 激活/关闭 | void | 测量工具 | | enable_navigation_cube(flag: boolean) | flag — 激活/关闭 | void | 导航立方体 | | set_navigation_cube(size: number, action?) | size — 大小；action — 位置计算函数 (c: HTMLCanvasElement, size: number) => {x, y} | void | 设置导航立方体大小和位置 | | enable_section(flag: boolean) | flag — 激活/关闭 | void | 剖切框/面 | | reset_section() | — | void | 重置剖切框 | | enable_skybox(flag: boolean) | flag — 激活/关闭 | void | 天空盒（beta） | | enable_snappoint(flag: boolean) | flag — 激活/关闭 | void | 对象捕捉 | | set_label(labels: Label[]) | labels — 标签数组 | void | 设置场景标签 | | update_label(label: Label) | label — 标签（按 id 匹配） | void | 更新单个标签 | | set_cad(data: {cad: HTMLImageElement, points: Float32Array} \| null) | data — CAD 数据或 null | void | 设置 CAD 底图 | | enable_sketch_plane(flag: boolean) | flag — 激活/关闭 | ISketchControl \| undefined | 草图绘制 | | enable_wire(flag: boolean, ext: IWire) | flag — 激活/关闭；ext — 线框数据 | IWireControl \| undefined | 显示线框 | | enable_wall_editer(flag: boolean) | flag — 激活/关闭 | ICuboidEditer \| undefined | 绘制长方体 | | enable_axis(flag?: boolean) | flag — 激活/关闭，默认 true | IAxisControl \| undefined | 坐标轴控件 | | enable_waterflow(flag?: boolean) | flag — 激活/关闭，默认 true | IWaterFlowControl \| undefined | 水流效果 | | select_render(name: RenderName) | name — 渲染器名称 | void | 切换渲染器（deprecated） | | screenshot(callback: (img: ImageData) => void) | callback — 截图回调 | void | 截图 | | dispose() | — | void | 释放所有资源 | | load_url(url: string, token: Token, action: (scene: Scene, progress: LoadState) => void) | url — 模型地址；token — 认证；action — 进度回调 | void | 加载模型 | | load_cache(buffer: ArrayBuffer, action: (scene: Scene, progress: LoadState) => void) | buffer — 缓存数据；action — 进度回调 | void | 加载缓存 |

SceneContext

场景上下文，包含所有构件数据和管理器。

属性

| 属性 | 类型 | 说明 | | -------------------- | -------------------------- | ------------------------------------------------- | | scene | Scene | 所属场景（只读） | | storeys | Storey[] | 所有楼层（只读） | | elements | Element[] | 所有构件（只读） | | spaces | Element[] | 所有空间（只读） | | instances | Instance[] | 所有几何实例（只读） | | geometries | Geometry[] | 所有几何体（只读） | | materials | Material[] | 所有材质（只读） | | types | Type[] | 所有类型（只读） | | wander | Wander | 漫游对象（只读） | | light | Light | 太阳光（只读） | | ao_radius | number | AO 半径，默认 20 | | ao_factor | number | AO 强度，默认 2.0 | | shadow | boolean | 是否显示阴影，默认 false | | shadow_factor | number | 阴影强度，默认 1.2 | | bias | number | 阴影误差，默认 50 | | ambient | Color | 环境光颜色 | | exposure | number | 曝光度，默认 1.0 | | highlight_color | Color | 高亮颜色 | | background | Color | 背景颜色 | | background_image | HTMLImageElement \| null | 背景图片（set） | | box | Float32Array | 场景范围框 [minX, minY, minZ, maxX, maxY, maxZ] | | section_box | Float32Array \| null | 剖切框 | | section_plane | Plane | 剖切平面 | | section_mode | SectionMode | 剖切模式 | | select_mode | SelectMode | 选择模式 | | select_action | SelectAction | 选择效果，默认 Highlight | | can_rotate | boolean | 允许旋转 | | can_scale | boolean | 允许缩放 | | can_move | boolean | 允许移动 | | changed | boolean | 场景是否需要重绘 | | uniqueId | string | 文件名称 | | edge_color | Color | 边线颜色 | | edge_width | number | 边线宽度，默认 1 | | outline_color | Color | 轮廓线颜色 | | outline_width | number | 轮廓线宽度，默认 2 | | selection_manager | SelectionManager | 选择管理器（只读） | | visible_manager | VisibleManager | 可见性管理器（只读） | | color_manager | ColorManager | 颜色管理器（只读） | | bloom_manager | BloomManager | 泛光管理器（只读） | | group_manager | GroupManager | 打组管理器（只读） | | selectable_manager | SelectableManager | 可选管理器（只读） | | marquee_manager | MarqueeManager | 灯带管理器（只读） | | animation_manager | AnimationManager | 动画管理器（只读） | | view_manager | ViewManager | 视图管理器（只读） | | scene_manager | SceneManager | 场景管理器（只读） |

方法

| 方法 | 入参 | 返回 | 说明 | | -------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------- | ----------------- | | set_sketch_plane(origin: Float32Array, normal: Float32Array) | origin — 原点；normal — 法线 | void | 设置参考平面 | | add_event_listener<K extends keyof SceneEventMap>(type, listener, options?) | type — 事件类型；listener — 回调；options — 选项 | void | 添加事件监听 | | remove_event_listener<K extends keyof SceneEventMap>(type, listener, options?) | type — 事件类型；listener — 回调；options — 选项 | void | 移除事件监听 | | select(x: number, y: number, model: SelectMode) | x, y — 屏幕坐标；model — 选择模式 | SelectResult \| null | 屏幕坐标选择 | | get_screen_point(p: vec3) | p — 3D 坐标 | vec2 | 3D 坐标转屏幕坐标 | | create_element(id: number, geos: Geometry[], category: Category, color: Color) | id — ID；geos — 几何体；category — 类别；color — 颜色 | Element | 创建构件 | | save_extra_elements() | — | ArrayBuffer | 保存附加构件 | | load_extra_elements(buffer: ArrayBuffer) | buffer — 数据 | void | 加载附加构件 | | scale_element(element: Element, scale: [number, number, number]) | element — 构件；scale — 缩放比例 | void | 缩放构件 | | rotate_element(element: Element, axis: [number, number, number], rad: number) | element — 构件；axis — 旋转轴；rad — 弧度 | void | 旋转构件 | | move_element(element: Element, move: [number, number, number]) | element — 构件；move — 移动向量 | void | 移动构件 | | reset_element_pose(element: Element) | element — 构件 | void | 重置构件姿态 | | delete_element(element: Element) | element — 构件 | void | 删除构件 | | set_location(element: Element, loc: [number, number, number]) | element — 构件；loc — 位置 | void | 设置构件位置 |

Element

构件对象。

属性

| 属性 | 类型 | 说明 | | -------------- | ------------ | ----------------------- | | id | number | 数据库 ID（只读） | | name | string | 构件名称（只读） | | originId | number | 原始文件中的 ID（只读） | | index | number | 构件索引（只读） | | typeId | number | 类型 ID（只读） | | storey_index | number | 楼层索引（只读） | | category | Category | 构件类别（只读） | | visible | boolean | 是否可见（只读） | | locked | boolean | 是否锁定（只读） | | bloom | boolean | 是否泛光（只读） | | instances | Instance[] | 包含的实例（只读） | | model_type | ModelType | 模型类型（只读） | | location | vec3 | 位置（只读） |

方法

| 方法 | 入参 | 返回 | 说明 | | ----------- | ---- | -------------- | ---------- | | get_box() | — | Float32Array | 获取范围框 |

Instance

几何实例。

属性

| 属性 | 类型 | 说明 | | ------------- | -------------- | ------------------------- | | matrix | Float32Array | 变换矩阵（只读） | | color | Uint8Array | 颜色（只读，含 override） | | material_id | number | 材质 ID（只读） | | id | number | 数据库 ID（只读） |

Geometry

几何体数据。

属性

| 属性 | 类型 | 说明 | | ------------ | ---------------------- | -------- | | id | number | ID | | offset | number | 偏移 | | pointCount | number | 顶点数量 | | points | Float32Array | 顶点数据 | | edges | Float32Array \| null | 边线数据 | | faces | Face[] | 面数组 |

方法

| 方法 | 入参 | 返回 | 说明 | | -------------------------------- | ------------------ | ---------------- | -------------------- | | get_point(index: number) | index — 顶点索引 | Float32Array | 获取顶点坐标 | | get_face_center(index: number) | index — 面索引 | vec3 | 获取面中心 | | get_face_normal(index: number) | index — 面索引 | vec3 | 获取面法线 | | get_face_point_count() | — | number | 获取所有面的顶点总数 | | get_line() | — | GeometryLine[] | 获取边线 |

Material

材质。

属性

| 属性 | 类型 | 说明 | | ------------------ | ------------ | ------------------- | | id | number | 材质 ID | | offset | number | 偏移 | | color | Uint8Array | 颜色 [R, G, B, A] | | R | number | 红色通道 | | G | number | 绿色通道 | | B | number | 蓝色通道 | | A | number | Alpha 通道 | | Roughness | number | 粗糙度 | | Metallic | number | 金属度 | | Specular | number | 高光度 | | AmbientOcclusion | number | 环境光遮蔽 | | transparent | number | 透明度（即 A） |

Color

颜色类，支持多种构造方式。

构造函数

| 方法 | 入参 | 返回 | 说明 | | ----------------------------------------------------------------------------- | ----------------------------------------------- | ------- | ------------------------ | | constructor() | — | Color | 白色 [255,255,255,255] | | constructor(color: string) | color — 十六进制，如 #FF0000 或 #FF0000FF | Color | 从十六进制构造 | | constructor(color: [number,number,number] \| [number,number,number,number]) | color — RGB 或 RGBA 数组 | Color | 从数组构造 | | constructor(color: Uint8Array) | color — 3 或 4 长度 Uint8Array | Color | 从 Uint8Array 构造 |

属性

| 属性 | 类型 | 说明 | | ------ | ------------ | ------------------------ | | R | number | 红色 0-255 | | G | number | 绿色 0-255 | | B | number | 蓝色 0-255 | | A | number | Alpha 0-255 | | data | Uint8Array | 底层颜色数据 [R,G,B,A] |

Label

标签。

属性

| 属性 | 类型 | 说明 | | ----------------- | ---------------------------------------------- | ----------------------- | | id | string | 唯一标识 | | type | "string" \| "img" \| "div" | 标签类型 | | data | HTMLImageElement \| string \| HTMLDivElement | 标签内容 | | point | vec3 | 标签位置 | | shadow_color | string | 阴影颜色 | | font | string | 字体，如 "14px Arial" | | font_color | string | 字体颜色 | | font_back_color | string | 字体背景颜色 |

Token

模型加载认证 Token。

属性

| 属性 | 类型 | 说明 | | --------- | -------------------- | ---------------------------------------------------------------- | | type | TokenType | 认证类型："bearer" \| "sadicode" \| "custom" \| "directlyLoad" | | value | string | Token 值 | | headers | [string, string][] | 自定义 headers（type 为 custom 时使用） |

CameraInfo

摄像机信息。

属性

| 属性 | 类型 | 说明 | | --------------- | --------- | ------------------------------------------------------------- | | theta | number | 和 Z 轴夹角 | | phi | number | 和 X 轴夹角 | | factor | number | 缩放系数 | | orthographic | boolean | 是否正交。修改后需将 factor 设为 1.0，movement 设为 [0,0,0] | | movement | vec3 | 移动偏移 | | movement_step | number | 透视相机滚轮移动速度 | | fovy | number | 视角，单位为度 |

SelectResult

选择结果。

属性

| 属性 | 类型 | 说明 | | ---------------- | ---------------------- | ----------------- | | select_mode | SelectMode | 选择模式 | | element_index | number | 构件索引，默认 -1 | | element | Element \| null | 构件 | | instance_index | number | 实例索引，默认 -1 | | instance | Instance \| null | 实例 | | face_index | number | 面索引，默认 -1 | | face | InstanceFace \| null | 面 | | point | vec3 \| null | 点 |

方法

| 方法 | 入参 | 返回 | 说明 | | ------------- | ---- | --------------- | ------------------------------------ | | get_plane() | — | Plane \| null | 返回选中面的平面（仅 face 模式有效） |

Plane

平面。

构造函数

| 方法 | 入参 | 返回 | 说明 | | --------------------------------------------------------- | ---------------------------------------- | ------- | -------- | | constructor(origin: Float32Array, normal: Float32Array) | origin — 平面原点；normal — 平面法线 | Plane | 创建平面 |

属性

| 属性 | 类型 | 说明 | | -------- | -------------- | -------- | | origin | Float32Array | 平面原点 | | normal | Float32Array | 平面法线 |

方法

| 方法 | 入参 | 返回 | 说明 | | -------------------------- | ------------ | ------ | ---------------- | | project(p: Float32Array) | p — 点坐标 | vec3 | 点在平面上的投影 |

Group

打组信息。

属性

| 属性 | 类型 | 说明 | | --------- | ------------ | -------------------------------------- | | name | string | 组名称 | | indices | Int32Array | 构件索引数组，默认 new Int32Array(0) |

Storey

楼层。

构造函数

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------- | -------- | | constructor(id: number, index: number, name: string, elevation: number) | id — 楼层 ID；index — 楼层索引；name — 名称；elevation — 标高 | Storey | 创建楼层 |

属性

| 属性 | 类型 | 说明 | | ----------- | -------- | -------- | | id | number | 楼层 ID | | index | number | 楼层索引 | | name | string | 楼层名称 | | elevation | number | 楼层标高 |

Light

太阳光（平行光模拟）。

属性

| 属性 | 类型 | 说明 | | ------- | -------- | ------------------------------ | | theta | number | 入射角度和 Z 轴角度，默认 60 | | phi | number | 入射角度和 X 轴角度，默认 60 | | color | Color | 光照颜色，默认 [204,204,204] |

Type

构件类型。

构造函数

| 方法 | 入参 | 返回 | 说明 | | --------------------------------------- | --------------------------------- | ------ | -------- | | constructor(id: number, name: string) | id — 类型 ID；name — 类型名称 | Type | 创建类型 |

属性

| 属性 | 类型 | 说明 | | ------ | -------- | -------- | | id | number | 类型 ID | | name | string | 类型名称 |

SceneTree / CategoryNode / TypeNode

场景树结构。

SceneTree

| 方法 | 入参 | 返回 | 说明 | | ------------------------------- | ----------------- | ---------------- | ---------------------- | | constructor(sc: SceneContext) | sc — 场景上下文 | SceneTree | 创建场景树 | | build() | — | CategoryNode[] | 构建并返回类别节点数组 |

CategoryNode

| 属性 | 类型 | 说明 | | ---------- | ------------ | -------------- | | name | string | 类别名称 | | category | Category | 类别枚举 | | types | TypeNode[] | 包含的类型节点 |

TypeNode

| 属性 | 类型 | 说明 | | --------- | ------------ | ------------------ | | name | string | 类型名称 | | type_id | number | 类型 ID | | indices | Int32Array | 该类型下的构件索引 |

RotateCamera

旋转相机。

构造函数

| 方法 | 入参 | 返回 | 说明 | | ------------------------------- | ----------------- | -------------- | ------------ | | constructor(sc: SceneContext) | sc — 场景上下文 | RotateCamera | 创建旋转相机 |

属性

| 属性 | 类型 | 说明 | | ---------- | -------------- | ---------------------------------------- | | location | Float32Array | 相机位置 | | fovy | number | 视野范围角度（弧度），需在 active 前设置 | | aspect | number | 宽高比（只读） |

方法

| 方法 | 入参 | 返回 | 说明 | | ---------------------------------------------------------------- | ---------------- | ---------------------------------------------- | ------------ | | active() | — | void | 激活旋转相机 | | deactive() | — | void | 关闭旋转相机 | | isActive() | — | boolean | 是否激活 | | set_euler(euler: { yaw: number, pitch: number, roll: number }) | euler — 欧拉角 | void | 设置欧拉角 | | get_euler() | — | { yaw: number, pitch: number, roll: number } | 获取欧拉角 |

Wander

漫游。

构造函数

| 方法 | 入参 | 返回 | 说明 | | ------------------------------- | ----------------- | -------- | ------------ | | constructor(sc: SceneContext) | sc — 场景上下文 | Wander | 创建漫游对象 |

属性

| 属性 | 类型 | 说明 | | ----------- | ---------------- | -------------------- | | storey | Storey | 当前漫游楼层（只读） | | isRunning | boolean | 漫游状态（只读） | | eye | vec3 | 眼睛位置（只读） | | height | number | 相机高度，默认 1500 | | moveStep | number | 漫游速度，默认 100 | | angleStep | number | 转向速度，默认 2 | | fps | number | 帧率，默认 40 | | settings | WanderSettings | 漫游设置 |

方法

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------------------------- | ------------------------------------------------------------- | ------ | -------- | | start(location: vec3, xangle: number, storey: Storey) | location — 起始位置；xangle — X 方向角度；storey — 楼层 | void | 开始漫游 | | stop() | — | void | 结束漫游 |

WanderSettings

漫游设置。

属性

| 属性 | 类型 | 说明 | | ------------------ | ---------- | ---------------------------- | | x | number | 小地图 X 位置，默认 50 | | y | number | 小地图 Y 位置，默认 50 | | scale | number | 缩放，默认 1/4 | | width | number | 宽度，默认 400 | | height | number | 高度，默认 300 | | fixed | boolean | 固定位置，默认 true | | show_map | boolean | 显示地图，默认 false | | edge_width | number | 边线宽度，默认 1 | | edge_color | number[] | 边线颜色，默认 [0,0,0,1] | | background_color | number[] | 背景颜色，默认 [0,0,0,0.5] | | fovy | number | 视野角度 |

Manager 类

SelectionManager

选择集管理。

| 属性 | 类型 | 说明 | | ------------- | -------------------------------- | -------------------------- | | highlighted | IterableIterator<SelectResult> | 当前高亮的选择结果（只读） |

| 方法 | 入参 | 返回 | 说明 | | -------------------------------------------------- | ---------------------- | ----------- | ------------------------------------ | | highlight(selection: SelectResult) | selection — 选择结果 | void | 高亮/取消高亮切换 | | highlight_without_check(selection: SelectResult) | selection — 选择结果 | void | 高亮（不检查，deprecated） | | highlight_elements(elements: Element[]) | elements — 构件数组 | void | 高亮构件 | | highlight_all() | — | void | 高亮所有构件 | | clear_highlighted() | — | void | 清空高亮 | | commit() | — | void | 提交修改（触发 select_changed 事件） | | get_highlighted_elements() | — | Element[] | 获取高亮构件 |

VisibleManager

可见性管理。所有修改需调用 commit() 生效。

| 方法 | 入参 | 返回 | 说明 | | ----------------------------------- | --------------------- | ------ | ------------------------ | | hide(elements: Element[]) | elements — 构件数组 | void | 隐藏构件（无法隐藏空间） | | show(elements: Element[]) | elements — 构件数组 | void | 显示构件（无法显示空间） | | hide_category(category: Category) | category — 类别 | void | 按类别隐藏 | | show_category(category: Category) | category — 类别 | void | 按类别显示 | | show_space(spaces: Element[]) | spaces — 空间数组 | void | 显示空间 | | hide_space(spaces: Element[]) | spaces — 空间数组 | void | 隐藏空间 | | commit() | — | void | 提交生效 |

ColorManager

颜色管理。所有修改需调用 commit() 生效。

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------------------------ | --------------------------------- | -------------------------------------------- | -------------- | | set_instance_color(instance: Instance, color: Color) | instance — 实例；color — 颜色 | void | 设置实例颜色 | | reset_instance_color(instance: Instance) | instance — 实例 | void | 重置实例颜色 | | set_element_color(element: Element, color: Color) | element — 构件；color — 颜色 | void | 设置构件颜色 | | reset_element_color(element: Element) | element — 构件 | void | 重置构件颜色 | | reset_color() | — | void | 重置所有颜色 | | commit() | — | void | 提交颜色修改 | | save_to_record(record: ColorRecord) | record — 颜色方案 | void | 保存颜色到方案 | | load(record: ColorRecord) | record — 颜色方案 | { has_color: boolean, has_bloom: boolean } | 加载颜色方案 |

BloomManager

泛光管理。所有修改需调用 commit() 生效。

| 属性 | 类型 | 说明 | | ------------- | ----------- | -------------------- | | blooms | Element[] | 泛光构件列表（只读） | | bloomRange | number | 泛光半径，默认 10 | | bloomFactor | number | 泛光强度，默认 1.0 |

| 方法 | 入参 | 返回 | 说明 | | -------------------------------- | --------------------- | ------ | ------------ | | set_bloom(elements: Element[]) | elements — 构件数组 | void | 设置泛光构件 | | clear() | — | void | 清空泛光 | | commit() | — | void | 提交修改 |

ViewManager

视图交互。

| 方法 | 入参 | 返回 | 说明 | | ----------------------------------------------- | --------------------------------------------------------------------------------------- | ------ | ---------------------- | | rotate(xdeg: number, zdeg: number) | xdeg — X 轴旋转角度（度）；zdeg — Z 轴旋转角度（度） | void | 旋转视图 | | zoom_view(theta: number, phi: number) | theta — theta 角度；phi — phi 角度 | void | 自适应视图 | | move(x: number, y: number) | x, y — 移动量 | void | 移动视图 | | set_move_3d(mv: vec3) | mv — 3D 移动向量 | void | 设置 3D 移动 | | scale(factor: number) | factor — 缩放系数 | void | 缩放 | | zoom_to(element: Element \| Element[]) | element — 单个或多个构件 | void | 缩放到构件 | | animation(rotate, move, scale, stepCount?) | rotate — 旋转目标；move — 移动目标；scale — 缩放目标；stepCount — 步数，默认 10 | void | 视图动画（deprecated） | | animation_by_time(rotate, move, scale, time?) | rotate — 旋转目标；move — 移动目标；scale — 缩放目标；time — 时间(ms) | void | 按时间动画 |

AnimationManager

动画管理。

| 属性 | 类型 | 说明 | | ---------------- | --------- | ---------------------- | | __hasAnimation | boolean | 是否有动画（内部属性） |

| 方法 | 入参 | 返回 | 说明 | | -------------------------------------------- | -------------------------------------- | ------ | -------- | | add_animation(elements: Element[], config) | elements — 构件；config — 动画配置 | void | 添加动画 | | clear_animation() | — | void | 清空动画 |

config 结构：

{
    name: string,                    // 动画名称
    rotationCenter: vec3,            // 旋转中心
    rotationAxis: vec3,              // 旋转轴
    initialAngle: number,            // 初始角度
    finalAngle: number,              // 结束角度
    initialMovement: vec3,           // 初始位置
    finalMovement: vec3,             // 结束位置
    time: number,                    // 时间(ms)
    callback: (obj: __Animation) => void  // 完成回调
}

GroupManager

打组管理。

| 方法 | 入参 | 返回 | 说明 | | -------------------------------------------------------------------- | --------------------------------------------------- | ------------------- | ------------ | | get_elements(group: Group) | group — 组 | Element[] \| null | 获取组内构件 | | add_elements(group: Group, elements: Element[]) | group — 组；elements — 构件 | boolean | 添加构件到组 | | set_elements(group: Group, elements: Element[]) | group — 组；elements — 构件 | boolean | 设置组的构件 | | export(group: Group, mediums: RecordMedium[]) | group — 组；mediums — 中间数据 | ArrayBuffer | 导出组 | | import(group: Group, mediums: RecordMedium[], buffer: ArrayBuffer) | group — 组；mediums — 中间数据；buffer — 数据 | void | 导入组 |

SelectableManager

可选管理。所有修改需调用 commit() 生效。

| 方法 | 入参 | 返回 | 说明 | | ----------------------------- | --------------------- | ------ | ------------ | | lock(elements: Element[]) | elements — 构件数组 | void | 锁定构件 | | unlock(elements: Element[]) | elements — 构件数组 | void | 解锁构件 | | unlock_all() | — | void | 解锁所有构件 | | commit() | — | void | 提交修改 |

MarqueeManager

灯带管理。

| 属性 | 类型 | 说明 | | ------------ | --------- | ------------------ | | hasMarquee | boolean | 是否有灯带（只读） |

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------ | -------- | | add_marquee(start: vec3, end: vec3, normal: vec3, width: number, color: vec3) | start — 起点；end — 终点；normal — 法线；width — 宽度；color — 颜色 | void | 添加灯带 | | commit() | — | void | 提交修改 | | clear_marquee() | — | void | 清空灯带 |

SceneManager

场景管理（模板和放置构件）。

| 属性 | 类型 | 说明 | | ----------- | ----------- | ------------------ | | templates | Element[] | 模板列表（只读） | | elements | Element[] | 放置的构件（只读） |

| 方法 | 入参 | 返回 | 说明 | | --------------------------------------------------------------- | ------------------------------------------------ | ------------- | ---------------------------- | | add_template(buffer: ArrayBuffer) | buffer — 模板数据 | void | 添加模板 | | add_element(template: Element, id: number, loc: vec3 \| mat4) | template — 模板；id — ID；loc — 位置或矩阵 | void | 放置构件 | | prompt_template(template: Element, id: number) | template — 模板；id — ID | void | 预览模板 | | commit() | — | void | 提交（add_element 后需调用） | | save() | — | ArrayBuffer | 保存放置构件 |

ColorMediumManager

颜色方案传递。

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------------------------ | ----------------------------------------- | -------------------- | -------------------- | | constructor(sc: SceneContext) | sc — 场景上下文 | ColorMediumManager | 创建管理器 | | export(mediums: RecordMedium[], record: ColorRecord) | mediums — 中间数据；record — 颜色方案 | ArrayBuffer | 导出颜色方案传递文件 | | import(mediums: RecordMedium[], buffer: ArrayBuffer) | mediums — 中间数据；buffer — 数据 | ColorRecord | 导入颜色方案 |

VisibleRecordManager

可见性方案。

| 方法 | 入参 | 返回 | 说明 | | ----------------------------------------------------------- | ------------------------------------------- | ---------------------- | ------------------ | | constructor(sc: SceneContext) | sc — 场景上下文 | VisibleRecordManager | 创建管理器 | | save_to_record(record: VisibilityRecord) | record — 可见性方案 | void | 保存当前可见性状态 | | export(record: VisibilityRecord, mediums: RecordMedium[]) | record — 可见性方案；mediums — 中间数据 | ArrayBuffer | 导出可见性方案 | | import(mediums: RecordMedium[], buffer: ArrayBuffer) | mediums — 中间数据；buffer — 数据 | VisibilityRecord | 导入可见性方案 |

过滤器

SceneContextFilter

过滤上下文收集器。

| 构造函数 | 入参 | 返回 | 说明 | | ------------------------------- | ----------------- | -------------------- | ---------- | | constructor(sc: SceneContext) | sc — 场景上下文 | SceneContextFilter | 创建过滤器 |

| 属性 | 类型 | 说明 | | ----------- | ------------ | -------------------- | | elements | Element[] | 过滤后的构件（只读） | | instances | Instance[] | 过滤后的实例（只读） |

| 方法 | 入参 | 返回 | 说明 | | ----------------------------- | ----------------- | -------------------- | -------- | | where_pass(filter: IFilter) | filter — 过滤器 | SceneContextFilter | 链式过滤 |

CategoryFilter

| 构造函数 | 入参 | 返回 | 说明 | | ---------------------------------------------------- | -------------------------------------------------- | ---------------- | -------- | | constructor(category: Category, include?: boolean) | category — 类别；include — 是否包含，默认 true | CategoryFilter | 类别过滤 |

TypeFilter

| 构造函数 | 入参 | 返回 | 说明 | | ------------------------------------------------ | --------------------------------------------------- | ------------ | -------- | | constructor(typeId: number, include?: boolean) | typeId — 类型 ID；include — 是否包含，默认 true | TypeFilter | 类型过滤 |

VisibleFilter

| 构造函数 | 入参 | 返回 | 说明 | | ------------------------------- | -------------------- | --------------- | ---------- | | constructor(include: boolean) | include — 是否可见 | VisibleFilter | 可见性过滤 |

StoreyFilter

| 构造函数 | 入参 | 返回 | 说明 | | ----------------------------------------------------- | --------------------------------------------------------- | -------------- | -------- | | constructor(storeyIndex: number, include?: boolean) | storeyIndex — 楼层索引；include — 是否包含，默认 true | StoreyFilter | 楼层过滤 |

BloomFilter

| 构造函数 | 入参 | 返回 | 说明 | | ------------------------------- | -------------------- | ------------- | -------- | | constructor(include: boolean) | include — 是否泛光 | BloomFilter | 泛光过滤 |

LockedFilter

| 构造函数 | 入参 | 返回 | 说明 | | ------------------------------- | -------------------- | -------------- | -------- | | constructor(include: boolean) | include — 是否锁定 | LockedFilter | 锁定过滤 |

BoxInsideFilter

| 构造函数 | 入参 | 返回 | 说明 | | --------------------------------------------------- | ----------------------------------------------- | ----------------- | ------------ | | constructor(box: Float32Array, include?: boolean) | box — 范围框；include — 是否包含，默认 true | BoxInsideFilter | Box 包含过滤 |

BoxIntersectsFilter

| 构造函数 | 入参 | 返回 | 说明 | | --------------------------------------------------- | ----------------------------------------------- | --------------------- | ------------ | | constructor(box: Float32Array, include?: boolean) | box — 范围框；include — 是否包含，默认 true | BoxIntersectsFilter | Box 相交过滤 |

OrFilter

| 构造函数 | 入参 | 返回 | 说明 | | ---------------------------------------------------- | ------------------------------------------------------- | ---------- | ------ | | constructor(filters: IFilter[], include?: boolean) | filters — 过滤器数组；include — 是否包含，默认 true | OrFilter | 或过滤 |

AndFilter

| 构造函数 | 入参 | 返回 | 说明 | | ---------------------------------------------------- | ------------------------------------------------------- | ----------- | ------ | | constructor(filters: IFilter[], include?: boolean) | filters — 过滤器数组；include — 是否包含，默认 true | AndFilter | 与过滤 |

MaterialFilter

| 构造函数 | 入参 | 返回 | 说明 | | ---------------------------------- | ----------------------- | ---------------- | ------------------------- | | constructor(material_id: number) | material_id — 材质 ID | MaterialFilter | 材质过滤（instance 级别） |

GeometryEngine

几何引擎（基于 WASM）。

| 方法 | 入参 | 返回 | 说明 | | ---------------------------------------------------------- | -------------------------------------------------------- | ------------------ | ------------------------ | | constructor() | — | GeometryEngine | 创建引擎 | | init() | — | Promise<void> | 初始化引擎（必须先调用） | | make_points_prism(points: Float32Array, v: Float32Array) | points — 闭合轮廓；v — 拉伸方向和距离 [vx, vy, vz] | Geometry \| null | 创建拉伸体 | | make_pipe(points: Float32Array, radius: number) | points — 中心线；radius — 半径 | Geometry \| null | 创建管道 |

方案记录

ColorRecord

颜色方案。

| 属性 | 类型 | 说明 | | ------------------ | ------------------- | ---------------------- | | version | number | 版本（只读，当前为 5） | | sadiId | string | sadi 文件 ID | | name | string | 方案名称 | | items | ColorRecordItem[] | 主模型颜色项 | | extra_items | ExtraColorItem[] | 附加构件颜色项 | | light_color | Color | 光颜色 | | light_phi | number | 光方向和 X 轴角度 | | light_theta | number | 光方向和 Y 轴角度 | | shadow | boolean | 阴影设置 | | shadow_factor | number | 阴影系数 | | bias | number | 阴影补偿距离 | | ambient | Color | 环境光颜色 | | background_color | Color | 背景颜色 | | ao | number | 环境光遮蔽半径 | | ao_factor | number | 环境光遮蔽系数 | | edge_width | number | 边线宽度 | | edge_color | Color | 边线颜色 | | outline_width | number | 轮廓线宽度 | | outline_color | Color | 轮廓线颜色 | | bloom_range | number | 泛光半径 | | bloom_factor | number | 泛光强度 | | bloom_exposure | number | 泛光曝光 | | blooms | Int32Array | 主模型泛光构件索引 | | extra_blooms | Int32Array | 附加构件泛光 ID |

ColorRecordItem

颜色记录项。

| 属性 | 类型 | 说明 | | ------------- | ------------ | ---------------- | | instance_id | number | 实例 ID（索引） | | color | Uint8Array | 颜色 [R,G,B,A] | | r | number | 红色 0-255 | | g | number | 绿色 0-255 | | b | number | 蓝色 0-255 | | a | number | Alpha 0-255 |

ExtraColorItem

附加构件颜色项。

| 属性 | 类型 | 说明 | | ---------- | ------------ | -------- | | element | number | 构件 ID | | instance | number | 实例索引 | | color | Uint8Array | 颜色 |

VisibilityRecord

可见性方案。

| 属性 | 类型 | 说明 | | ----------------- | ---------------- | ---------------- | | name | string | 方案名称 | | main_indices | Int32Array | 主模型索引 | | extra_indices | Int32Array | 附加构件索引 | | section_mode | SectionMode | 剖切模式 | | section_box | Float32Array | 剖切框数据 | | main_frozen | Int32Array | 主模型锁定索引 | | extra_frozen | Int32Array | 附加构件锁定索引 | | visibility_type | VisibilityType | 可见类型 |

RecordMedium

方案传递中间数据。

| 属性 | 类型 | 说明 | | ----------- | -------- | ------- | | elementId | number | 构件 ID | | uniqueId | string | 唯一 ID | | index | number | 索引 |

ElementUniqueId

方案传递使用。

| 属性 | 类型 | 说明 | | ----------- | -------- | ------- | | index | number | 索引 | | unique_id | string | 唯一 ID |

CameraRecord

相机记录。

| 构造函数 | 入参 | 返回 | 说明 | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------- | ------------ | | constructor(name: string, theta: number, phi: number, movement: vec3, factor: number, orthographic: boolean) | name — 名称；theta — theta；phi — phi；movement — 移动；factor — 缩放；orthographic — 是否正交 | CameraRecord | 创建相机记录 |

| 属性 | 类型 | 说明 | | --------------------- | ------------ | ---------------- | | camera_theta | number | theta（只读） | | camera_phi | number | phi（只读） | | camera_movement | vec3 | 移动（只读） | | camera_factor | number | 缩放（只读） | | camera_orthographic | boolean | 是否正交（只读） | | name | string | 名称（只读） | | nameLength | number | 名称长度（只读） | | nameData | Uint8Array | 名称数据（只读） |

| 方法 | 入参 | 返回 | 说明 | | ----------------- | ---- | -------- | ------------ | | getByteLength() | — | number | 获取字节长度 |

接口

IAxisControl

坐标轴控件接口（enable_axis 返回）。

| 方法 | 入参 | 返回 | 说明 | | -------------------------------------------- | --------------- | ------ | ------------ | | set_element(e: Element) | e — 构件 | void | 设置操作构件 | | set_callback(action: (e: Element) => void) | action — 回调 | void | 操作回调 | | lock_ratio() | — | void | 锁定缩放比例 | | unlock_ratio() | — | void | 解锁缩放比例 | | close() | — | void | 关闭控件 |

ISketchControl

草图控制器接口（enable_sketch_plane 返回）。

| 属性 | 类型 | 说明 | | -------- | --------- | ------------------ | | closed | boolean | 是否闭合（只读） | | points | vec3[] | 绘制线的点（只读） |

| 方法 | 入参 | 返回 | 说明 | | --------------------------------------- | --------------- | ------ | ------------ | | complete() | — | void | 结束草图绘制 | | set_pick_callback(action: () => void) | action — 回调 | void | 设置拾取回调 |

IWireControl

线框预览控制器接口（enable_wire 返回）。

| 方法 | 入参 | 返回 | 说明 | | ------------ | ---- | ------ | -------- | | complete() | — | void | 退出编辑 |

IExtrusionWire / SpaceWire / WallWire

拉伸轮廓接口。

| 属性 | 类型 | 说明 | | --------------- | -------------- | --------------------------------- | | points | Float32Array | 线框点（只读） | | ext_profile | Float32Array | GeometryEngine 需要的轮廓（只读） | | valid | boolean | 是否有效（只读） | | point_changed | () => void | 点变化回调 |

SpaceWire 构造函数： | 构造函数 | 入参 | 返回 | 说明 | |------|------|------|------| | constructor(profile: vec3[], dir: vec3, dis: number) | profile — 轮廓点；dir — 拉伸方向；dis — 拉伸距离 | SpaceWire | 创建空间轮廓 |

| 属性 | 类型 | 说明 | | ----------- | -------- | ---------------- | | profile | vec3[] | 轮廓点（只读） | | direction | vec3 | 拉伸方向（只读） | | distance | number | 拉伸距离（只读） |

| 方法 | 入参 | 返回 | 说明 | | --------------------------- | ------------ | ------ | ------------ | | set_distance(dis: number) | dis — 距离 | void | 设置拉伸距离 |

PipeWire

管道线框。

| 构造函数 | 入参 | 返回 | 说明 | | ----------------------------------------------------------- | ------------------------------------------------------------------ | ---------- | ------------ | | constructor(spine: vec3[], radius: number, normal?: vec3) | spine — 中心线；radius — 半径；normal — 法线，默认 [0,0,1] | PipeWire | 创建管道线框 |

| 属性 | 类型 | 说明 | | --------------- | -------------- | ---------------- | | radius | number | 半径 | | spine | vec3[] | 中心线（只读） | | long_spine | vec3[] | 长中心线（只读） | | points | Float32Array | 线框点（只读） | | point_changed | () => void | 点变化回调 |

IWaterFlowControl

水流控制接口（enable_waterflow 返回）。

| 方法 | 入参 | 返回 | 说明 | | ---------------------------------------- | ------------------- | ------ | -------- | | set_flow(segments: WaterFlowSegment[]) | segments — 水流段 | void | 设置水流 | | pause() | — | void | 暂停 | | restart() | — | void | 重启 | | set_type(type: WaterFlowType) | type — 水流类型 | void | 设置类型 |

WaterFlowSegment

水流段。

| 构造函数 | 入参 | 返回 | 说明 | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------ | ---------- | | constructor(element: Element, speed: number, phase: number, color: Color) | element — 管道构件；speed — 速度(mm/s)；phase — 初始相位(mm)；color — 颜色 | WaterFlowSegment | 创建水流段 |

| 属性 | 类型 | 说明 | | ----------- | -------------- | ------------ | | color | Color | 颜色 | | start | Float32Array | 起点 | | end | Float32Array | 终点 | | element | Element | 管道构件 | | phase | number | 初始相位(mm) | | speed | number | 速度(mm/s) | | direction | Float32Array | 方向（只读） |

| 方法 | 入参 | 返回 | 说明 | | ----------- | ---- | ------ | -------- | | reverse() | — | void | 反转方向 |

ICuboidEditer

长方体编辑接口（enable_wall_editer 返回）。

| 属性 | 类型 | 说明 | | --------- | -------- | ---------------- | | profile | vec3[] | 地面轮廓（只读） | | width | number | 宽度 | | height | number | 高度 |

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------ | --------------------- | ------ | ------------ | | set_callback(callback: () => void) | callback — 完成回调 | void | 设置完成回调 |

工具

Box

范围框工具（namespace）。

| 方法 | 入参 | 返回 | 说明 | | ------------------------------------------------- | ------------------------ | -------------- | ----------------- | | Box.in_side(box: Float32Array, p: Float32Array) | box — 范围框；p — 点 | boolean | 点是否在框内 | | Box.get_points(box: Float32Array) | box — 范围框 | Float32Array | 获取框的 8 个顶点 | | Box.unin(boxes: Float32Array[]) | boxes — 框数组 | Float32Array | 多个框的并集 | | Box.get_center(box: Float32Array) | box — 范围框 | Float32Array | 获取中心点 | | Box.get_diagonal(box: Float32Array \| number[]) | box — 范围框 | number | 获取对角线长度 |

SceneUtils

场景工具（namespace）。

| 方法 | 入参 | 返回 | 说明 | | --------------------------------------------------- | ----------------- | ----------- | ------------------------------ | | SceneUtils.get_visible_elements(sc: SceneContext) | sc — 场景上下文 | Element[] | 获取当前可见元素（含剖切过滤） |

枚举

Category

enum Category {
  INVALID, // 未定义
  OST_Topography, // 地形
  OST_Rooms, // 房间
  OST_Walls_Architectural, // 建筑墙体
  OST_Windows, // 窗
  OST_Floors_Structural, // 结构楼板
  OST_CurtainWallPanels_Obsolete, // 幕墙嵌板
  OST_CurtainWallMullions_Obsolete, // 幕墙竖梃
  OST_Ceilings, // 天花板
  OST_Stairs, // 楼梯
  OST_Roofs, // 屋顶
  OST_StructuralColumns, // 结构柱
  OST_StructuralFraming, // 结构框架
  OST_StairsRailing, // 栏杆扶手
  OST_Doors, // 门
  OST_DuctCurves, // 风管
  OST_PipeCurves, // 管道
  OST_CableTray, // 电缆桥架
  OST_DuctFitting, // 风管管件
  OST_PipeFitting, // 管件
  OST_CableTrayFitting, // 电缆桥架配件
  OST_GenericModel, // 常规模型
  OST_Furniture, // 家具
  OST_PlumbingFixtures, // 卫浴装置
  OST_DuctTerminal, // 风道末端
  OST_LightingFixtures, // 照明设备
  OST_ElectricalEquipment, // 电气设备
  OST_Sprinklers, // 喷头
  OST_FireAlarmDevices, // 火警设备
  OST_PipeAccessory, // 管道附件
  OST_Conduit, // 线管
  OST_ConduitFitting, // 线管配件
  OST_SecurityDevices, // 安全设备
  OST_MechanicalEquipment, // 机械设备
  OST_Planting, // 植物
  OST_SpecialityEquipment, // 专用设备
  OST_Mass, // 体量
  OST_MassInteriorWall, // 体量内墙
  OST_MassZone, // 体量分区
  OST_MassExteriorWall, // 体量外墙
  OST_MassSkylights, // 体量天窗
  OST_MassRoof, // 体量屋顶
  OST_MassFloor, // 体量楼层
  OST_MassGlazing, // 体量玻璃
  OST_Parking, // 停车场
  OST_Site, // 场地
  OST_BuildingPad, // 建筑地坪
  OST_Ramps, // 坡道
  OST_CurtaSystem, // 幕墙系统
}

SelectMode

enum SelectMode {
  none = 0b0, // 不选择
  element = 0b1, // 选择构件
  instance = 0b11, // 选择几何体
  face = 0b111, // 选择面
  point = 0b1111, // 选择点
  snap = 0b11111, // 对象捕捉
}

SectionMode

enum SectionMode {
  none, // 无剖切
  box, // 正交剖切
  plane, // 面剖切
}

VisibilityType

enum VisibilityType {
  Show, // 显示
  Hide, // 隐藏
}