--- url: /index.md --- # ### :zap: 快速开始 :::code-tabs @tab bash ```bash git clone https://github.com/mlt131220/Astral3D.git cd Astral3D pnpm install pnpm run sdk:build pnpm run editor:dev ``` ::: --- --- url: /ai/index.md --- # AI小星 `AI小星` 是 Astral3D 编辑器内置的 AI 助手入口，负责把自然语言指令转换为编辑器操作、查询结果和多轮工具调用。 本分组文档只讲两件事： 1. **怎么使用 AI小星** 2. **怎么给 AI小星新增、删除和调试可调用能力** ## 文档目录 * [使用方法](./使用方法.md) * [AI能力接入与删除指南](./AI能力接入与删除指南.md) ## 适用对象 这组文档适合两类人： 1. **使用者** 想知道如何打开 AI小星、如何提问、如何查看回复和处理工具执行确认 2. **开发者** 想知道如何把 SDK 方法或 editor 本地工具接入给 AI小星使用 ## 建议阅读顺序 如果你第一次接触这套能力，建议按下面顺序阅读： 1. 先看 [使用方法](./使用方法.md) 2. 再看 [AI能力接入与删除指南](./AI能力接入与删除指南.md) --- --- url: /ai/usage/index.md --- # AI小星使用方法 本文面向使用者，说明如何在编辑器中打开 `AI小星`、如何向它提问、如何理解它的回复，以及在遇到工具确认、多轮执行或异常时该怎么处理。 ## 一、AI小星是什么 `AI小星` 是编辑器内的自然语言助手。\ 它不是一个单纯的聊天框，而是一条完整链路： 1. 读取当前场景上下文 2. 把用户问题发送给后端大模型 3. 在需要时触发工具调用 4. 执行编辑器操作或查询 5. 把工具结果回传给模型继续回答 因此，`AI小星` 可以做的事情不仅是解释说明，还包括： * 创建对象 * 查找和选中对象 * 修改变换、材质、相机、灯光 * 统计场景信息 * 采样性能指标 * 生成或挂接脚本 ## 二、如何打开 AI小星 在编辑器页面中，找到右侧或对应入口中的 `AI小星` 面板并打开。 打开后，前端会自动完成当前 AI artifact 版本的注册；如果后端还没有这一版，会自动先发布再注册。 > 截图位：AI小星入口待补充 ## 三、如何发送指令 在输入框中直接输入自然语言即可。 推荐写法： ### 1. 直接说目标 例如： * 添加一个红色的盒子 * 选中名为 Ground 的对象 * 把当前选中对象右移 2 米 * 统计一下当前场景的对象数量 ### 2. 尽量写清对象和动作 比起只写： ```txt 改一下 ``` 更推荐写： ```txt 选中名为 Ground 的对象，并把它改成深灰色材质 ``` ### 3. 复杂任务拆步骤表达更稳定 例如： ```txt 先添加一个盒子，再在它上方 10 米放一个点光源 ``` ## 四、AI 回复时会发生什么 ### 1. 普通文字回复 如果问题只需要解释、说明或总结，AI 会直接返回文本。 ### 2. 工具调用 如果问题需要真正操作编辑器，AI 可能会： 1. 先回复一句计划说明 2. 调用一个或多个工具 3. 再基于工具结果继续回复 ## 五、常见可用能力 当前常见能力包括但不限于： * 创建基础几何体 * 选中对象 * 聚焦对象 * 修改位置、旋转、缩放 * 修改材质 * 调整相机 * 添加灯光 * 列出场景对象 * 搜索场景对象 * 查看对象详情 * 查看当前选择 * 统计场景信息 * 测量性能 ## 六、工具确认是什么意思 某些工具具备副作用或风险，系统可能要求确认后再执行。 这时你会看到： * 待确认状态 * 确认执行 * 取消执行 一般规则是： * 查询类、只读类工具通常自动执行 * 改场景、写脚本、资产写入类能力可能要求确认 ## 七、如何重试 如果一次执行失败，通常可以直接在面板中使用“重试”。 重试时系统会根据上一次请求类型自动判断： 1. 如果上次是普通用户消息，就重新发起聊天请求 2. 如果上次已经进入 `tool_result continuation`，就继续按上一轮 tool result 重试 这意味着你不一定需要手动重新输入整段指令。 ## 八、如何清空会话 如果你发现当前上下文已经被多轮对话污染，或者 AI 总是沿用上一轮目标，可以直接清空当前会话再重新提问。 清空会话会重置： * 当前消息列表 * 当前 pending tool call * 当前会话 id * 上一次请求记录 但不会影响你的真实场景内容。 ## 九、提问技巧 ### 1. 对象最好带名称 比起： ```txt 改这个盒子 ``` 更推荐： ```txt 把名为 Box_01 的对象改成蓝色 ``` ### 2. 明确单位和目标位置 例如： * 上移 2 米 * 放到原点 * 旋转 90 度 ### 3. 查询类指令先于修改类指令更稳 当你不确定对象名时，先问： ```txt 列出当前场景中的对象 ``` 再继续： ```txt 选中其中名为 Ground 的对象 ``` ### 4. 大任务分两轮成功率更高 例如先问： ```txt 列出当前场景中的对象 ``` 再问： ```txt 把其中名为 Ground 的对象改成绿色 ``` ## 十、常见问题 ### 1. 为什么 AI 说“无法找到对象” 常见原因： * 场景里确实没有这个对象 * 对象名不准确 * 你说的是业务叫法，不是场景真实名称 推荐先让 AI 列出对象，确认名称后再继续操作。 ### 2. 为什么 AI 说“未注册工具” 这通常不是“前端有没有这个函数”这么简单，而是以下某一层出了问题： * 工具没有进入 callable manifest * 当前 artifact 版本未刷新 * 后端这一轮没有把该工具下发给模型 * 前端执行器没有注册 这类问题更适合开发者参考 [AI能力接入与删除指南](./AI能力接入与删除指南.md) 排查。 ### 3. 为什么 AI 的回复看起来像分几段完成 因为它可能经历了： 1. 先解释准备做什么 2. 触发工具调用 3. 再根据工具结果继续说明 这是正常的多轮 continuation，不是异常。 ## 十一、建议的使用顺序 如果你是第一次使用 `AI小星`，推荐顺序是： 1. 先用查询类能力熟悉场景信息 2. 再用简单单步修改指令 3. 最后再尝试多步骤组合任务 推荐从这些提示词开始： ```txt 列出当前场景中的对象 ``` ```txt 添加一个红色的盒子 ``` ```txt 选中名为 Ground 的对象 ``` ```txt 统计一下当前场景的对象和资源数量 ``` ## 十二、如果你是开发者 如果你的目标不是使用 `AI小星`，而是给它新增或删除能力，请直接阅读： * [AI能力接入与删除指南](./AI能力接入与删除指南.md) 这篇文档会讲清楚： * SDK 方法如何暴露给 AI * editor 本地工具如何暴露给 AI * 从哪里删除 AI 能力 * 从哪一层排查“代码有了但 AI 不能用” --- --- url: /astral/nf8y5syx/index.md --- # 寻求合作，共创价值 > 您好！我们是 ==Astral 3D== 开源项目的核心开发团队。\ > \==Astral 3D Editor== 是一个功能强大的、完全开源的 Web3D 编辑器，致力于为开发者和设计师提供高效、便捷的 3D 场景创作工具。\ > 我们拥有深厚的 `WebGL、WebGPU、Three.js、Babylon.js、Vue/React` 等全栈开发经验，除了维护核心的开源项目外，我们也承接相关的商业项目，旨在将专业的技术实力转化为您的商业价值。 ## 我们的合作模式 我们专注于提供高质量的 ==Web 前后端== 技术开发服务，主要合作模式包括： * **Web3D 项目外包:** * **产品3D展示:** 将您的产品以交互式3D模型的形式呈现在网页上。 * **数据可视化:** 构建复杂的 3D 数据可视化大屏，让数据生动直观。 * **虚拟展厅/数字孪生:** 为您的业务打造沉浸式的在线虚拟空间。 * **3D场景与游戏开发:** 基于 Web 技术开发轻量级的 3D 互动场景或小游戏。 * **Web 开发外包:** * **复杂前端页面开发:** 擅长使用 `Vue/React` 等现代框架构建高性能、高交互性的 Web 应用。 * **全栈项目开发:** 提供从前端到后端的整套解决方案。 * **定制化开发与技术咨询:** * 基于我们的开源编辑器进行二次开发，为您量身定制专属功能。 * 提供 `Web3D` 相关的技术咨询、方案设计和性能优化服务。 * **更多的合作可能性？** * 专业团队，为您提供所需。 ## 为什么选择我们？ * **核心团队，技术保障:** 您将直接与开源项目的核心开发者沟通，我们对 ==Web3D 技术/ Web前后端== 有深入的理解和丰富的实战经验。 * **开源基础，降本增效:** 基于我们成熟的开源编辑器/其他产品，可以为您快速搭建项目原型，显著缩短开发周期，降低开发成本。 * **代码质量，值得信赖:** 开源意味着我们的代码经过了社区的广泛检验，我们始终坚持高标准的编码规范和交付质量。 * **专注高效，沟通直接:** 我们是纯粹的技术团队，沟通直接高效，致力于用最合适的技术方案解决您的实际问题。 ## 联系方式 如果您有项目需求或合作意向，欢迎添加我的微信进行深入沟通。请在好友申请中备注“**商务合作**”或“**您的公司/项目名**”，以便我能快速通过并了解您的需求。 | 商务微信 | |:--------------------------------------------------------------:| | ![WeChat](/images/wechat-qrcode.jpg){width="300" height="300"} | 微信号：**mahaibing130802** 我们期待通过精湛的技术，助力您的业务在==数字化浪潮==中脱颖而出。 --- --- url: /guide/0q1bxrub/index.md --- # 日志 ::: demo-wrapper img no-padding ## 简要说明 日志面板用于查看编辑器运行过程中的日志信息，便于排查问题。 ## 功能说明 * **清空日志**：一键清除当前日志列表 * **右键菜单**：支持复制与删除单条日志 * **日志级别**：trace / debug / info / warn / error --- --- url: /guide/18al65zg/index.md --- # 广告牌 ::: demo-wrapper img no-padding ## 简要说明 广告牌用于在场景中展示图片或文字信息。选中广告牌对象后可进行配置。 ## 图片模块 * **启用**：显示/隐藏图片 * **置顶**：是否始终在上层渲染 * **宽度/高度**：图片尺寸 * **旋转**：旋转角度 * **间距**：图文间距 * **位置**：图片相对文字的位置（左/右/上/下/中） ## 文本模块 * **启用**：显示/隐藏文字 * **内容**：文本内容 * **字号/颜色/字重/倾斜**：基础字体样式 * **行间距/内边距**：排版控制 * **对齐**：水平与垂直对齐 * **描边**：描边宽度与颜色 * **填充**：背景填充与颜色 --- --- url: /guide/1h8cz3hk/index.md --- # 高斯泼溅 ::: demo-wrapper img no-padding ## 简要说明 3D 高斯泼溅（3D Gaussian Splatting，简称 3DGS）是一种基于点云的新型三维重建渲染技术，能以极高的视觉质量呈现真实场景的照片级效果。 Astral3D 编辑器内置了对 3DGS 的完整支持，包括加载、预览、编辑、打包与还原。 ## 支持格式 | 格式 | 扩展名 | 说明 | | ------ | --------- | ---------------------------------------------- | | PLY | `.ply` | 通用点云格式（含压缩） | | SPZ | `.spz` | 高压缩比格式，推荐用于生产环境 | | SPLAT | `.splat` | 常见的 3DGS 导出格式 | | KSPLAT | `.ksplat` | 带关键帧的泼溅格式 | | SOG | `.sog` | Scene of Gaussians 格式 | | RAD | `.rad` | 分页流式加载格式，适合超大模型（千万级泼溅点） | ## 添加高斯泼溅到场景 ### 方式一：内置资源库 1. 打开 **资源中心** 面板 2. 切换到 **高斯泼溅** 分类 3. **双击** 资源卡片即可添加到场景，或 **拖拽** 到视口中指定位置 ### 方式二：资产中心 在首页的 **资产中心** 上传高斯泼溅文件后，可在编辑器的 **公共资源** 面板中找到并添加到场景。 ## 右侧边栏配置 选中场景中的高斯泼溅对象后，右侧边栏会显示专用的配置面板： ### 来源地址 * 显示当前模型的资源 URL * 可修改 URL 并点击 **重载** 按钮切换到新的泼溅模型 * 重载会保留对象原有的名称和空间变换（位置/旋转/缩放） ### LoD 设置 * **LoD 状态**：显示当前模型是否启用了 LoD（Level of Detail）渐进式细节 * **细节级别**：滑块控制 LoD 缩放因子（`0.1` ~ `4.0`），值越大渲染的泼溅点越多、画面越精细，性能消耗也越高 * 若模型未启用 LoD（如非 LoD 格式的文件），面板会显示"LoD 未启用"提示 > **提示**：`.rad` 格式的模型使用分页流式加载，会自动开启 LoD，适合加载超大规模场景（如城市级别的数千万泼溅点）。 ## 视口信息 当场景中存在高斯泼溅对象时，视口左下角的统计信息栏会额外显示 **高斯泼溅点数**（Splats），方便实时监控场景复杂度。 ## 注意事项 * 当前 **Web GIS** 场景暂不支持高斯泼溅（与大气/体积云的深度判断存在兼容性问题） * 高斯泼溅的 GPU 资源在对象从场景中移除时会自动释放，无需手动清理 * 超大模型建议使用 `.rad` 格式以获得最佳的加载性能和内存占用 --- --- url: /guide/2xlh6nrf/index.md --- # 对象 ::: demo-wrapper img no-padding ## 简要说明 对象面板用于查看与编辑当前选中模型的属性，不同对象类型会显示不同字段（如相机、灯光、网格等）。 ## 基础信息 * **类型**：对象类型（只读） * **UUID**：可重新生成 * **名称**：可直接编辑 ## 变换 * **位置/旋转/缩放**：旋转单位为角度 * 带有关键帧图标的字段支持动画关键帧 ## 相机/灯光参数 仅在对象具备对应属性时显示。 * **相机**：`fov / near / far` 或 `left / right / top / bottom` * **灯光**：`intensity / color / groundColor / distance / angle / penumbra / decay` * **阴影**：`castShadow / receiveShadow / bias / normalBias / radius / intensity` ## 渲染与显示 * **visible**：显示/隐藏对象 * **frustumCulled**：视锥裁剪 * **renderOrder**：渲染顺序 ## UserData 以 JSON 形式编辑用户数据，点击输入框打开编辑器。 --- --- url: /guide/4tirtbsc/index.md --- # 资源中心 ::: demo-wrapper img no-padding ::: ## 上传资源 ::: demo-wrapper img no-padding ::: * **类型**：可上传资源类型默认为：==模型、材质、纹理、广告牌、HDR、3D Tiles==; * **分类**：从树节点中选择资源所属的详细类别; * **标签**：为资源添加特定的标签，比如 ==“有动画、有骨骼”== 之类的，便于在资源列表顶部勾选标签快速搜索； * **缩略图**：可以从本地选择，或者在选择资源文件后，点击 ==通过预览截图== 生成。 ::: tabs @tab 通过预览截图 > 假设在`模型`类型下我先选择了一个飞机模型，然后点击按钮`通过预览截图` ::: * **文件**：不同类型的资源具有不同的文件格式支持。 ::: tabs @tab 模型 * \[x] glb * \[x] gltf * \[x] fbx * \[x] obj @tab 材质 * \[x] zip > 默认解析为==PBR材质==。\ > 上传的ZIP包内文件应依照特定规则（以下两种之一）： > > * 一. zip包中包含一个`material.json`的文件，其中指明各类贴图使用的纹理文件及材质属性，示例如下： > > ```json:no-line-numbers title="material.json" > { > textures: { > baseColor: xxx.[png/jpg/webp/tga/hdr/exr], > normal: xxx.[png/jpg/webp/tga/hdr/exr], > bump: xxx.[png/jpg/webp/tga/hdr/exr], > displacement: xxx.[png/jpg/webp/tga/hdr/exr], > roughness: xxx.[png/jpg/webp/tga/hdr/exr], > metalness: xxx.[png/jpg/webp/tga/hdr/exr], > ao: xxx.[png/jpg/webp/tga/hdr/exr], > emissive: xxx.[png/jpg/webp/tga/hdr/exr], > alpha: xxx.[png/jpg/webp/tga/hdr/exr], > env: xxx.[png/jpg/webp/tga/hdr/exr], > light: xxx.[png/jpg/webp/tga/hdr/exr], > }, > properties: { > metalness: 1, > roughness: 0.5, > ... > } > } > ``` > > * 二. zip包中不包含`material.json`文件，此时包中的各纹理文件应语义化命名，如下(文件名均为按照关键字模糊匹配)： > > ::: file-tree > > * \*.zip > * %baseColor%.\[png/jpg/webp/tga/hdr/exr] // 基础颜色贴图(高光反射/光泽度工作流:diffuse, 金属/粗糙度工作流:baseColor) > * %normal%.\[png/jpg/webp/tga/hdr/exr] // 法线贴图 > * %bump%.\[png/jpg/webp/tga/hdr/exr] // 凹凸贴图,如果定义了法线贴图，则将忽略该贴图 > * %displacement%.\[png/jpg/webp/tga/hdr/exr] // 置换贴图(位移贴图) > * %roughness%.\[png/jpg/webp/tga/hdr/exr] // 粗糙度贴图(使用该纹理的绿色通道) > * %metalness%.\[png/jpg/webp/tga/hdr/exr] // 金属度贴图(使用该纹理的蓝色通道) > * %ao%.\[png/jpg/webp/tga/hdr/exr] // 环境遮挡贴图(该纹理的红色通道) > * %emissive%.\[png/jpg/webp/tga/hdr/exr] // 自发光贴图(放射贴图) > * %alpha%.\[png/jpg/webp/tga/hdr/exr] // 透明贴图(一张灰度纹理，用于控制整个表面的不透明度：黑色：完全透明；白色：完全不透明) > * %env%.\[png/jpg/webp/tga/hdr/exr] // 环境贴图(一般不会设置，因为会使用scene.environment) > * %light%.\[png/jpg/webp/tga/hdr/exr] // 光照贴图(需要第二组UV) > ::: @tab 纹理 * \[x] png * \[x] jpg/jpeg * \[x] webp @tab 广告牌 * \[x] png * \[x] jpg/jpeg * \[x] webp * \[x] svg @tab HDR * \[x] hdr * \[x] exr @tab 3D Tiles * \[x] zip > 上传的zip文件根节点目录下需包含`tileset.json` ::: * **名称**：默认会在上传资源文件后自动获取文件名填充； * **大小**：会在上传资源文件后自动计算，无需填写。 ## 预览资源 ::: demo-wrapper img no-padding ::: ## 编辑资源 ::: demo-wrapper img no-padding ::: --- --- url: /guide/5s7acuj0/index.md --- # 动画编辑器 ::: demo-wrapper img no-padding ## 简要说明 动画编辑器位于扩展栏下拉菜单中，需选中模型后可编辑动画轨道与关键帧。 ## 动画列表 * 下拉选择当前动画 * **新增动画**：输入名称创建空动画 * **锁定/解锁**：锁定父模型，便于复杂层级编辑 ## 时间轴与轨道 * 左侧为轨道树，右侧为时间轴 * 支持添加/删除关键帧 * 右键时间轴可删除选中的关键帧 ## 播放控制 * **跳转到首帧/末帧** * **播放 / 暂停 / 继续 / 停止** * 显示当前时间与总时长 > 未选中对象时显示空状态提示。 --- --- url: /guide/6xkx4dnv/index.md --- # 介绍 > `Astral 3D Engine` 是一个基于 `ThreeJS` 的三维快速开发引擎。 > `Astral 3D Editor` 是一个以 `Astral 3D` 作为底层的三维可视化编辑器。 > 从诞生之初，其定位便是快捷、轻量、可扩展的3D低代码创作工具，意在解决Web3D产品开发难，迭代速度慢，并且视觉效果不达标的行业痛点，推动Web3D的发展。 ## 重点功能 * \[x] 场景数据无损压缩; * \[x] 网络分包渐进存取； * \[x] 支持30+模型格式； * \[x] `BIM`模型在线轻量化; * \[x] `CAD`图纸解析预览； * \[x] 碰撞检测； * \[x] 粒子系统； * \[x] 插件系统； * \[x] 脚本系统； * \[x] 动画编辑器； * \[x] Billboard、HtmlPanel(在线解析html、Vue/React/...打包工程)、UIPanel、热力图、动态路径； * \[x] 资源中心； * \[x] 3DTiles支持； * \[x] 数据组件 (API接口、前端SQL、静态JSON)； * \[x] WebGIS场景 * \[x] [低代码数据大屏](https://bi.astraltwin.cn) * \[ ] WebGPU 支持 (:tada:开发阶段) ## WebGIS 快速开始 ### 编辑器 1. 在项目创建时选择 **WebGIS** 类型 2. 进入场景后在右侧 **GIS地图源** 面板配置地图源 3. 使用 **GIS位置** 面板快速定位视角 ### SDK ```ts import { ViewerGIS } from "@astral3d/engine"; const viewer = new ViewerGIS({ container: document.getElementById("app")!, gis: { initialPosition: { longitude: 104.0668, latitude: 30.5728, altitude: 50000 }, mapSources: [{ id: "osm", name: "OSM", enabled: true, category: "2dtiles", preset: "osm" }], }, }); ``` ## 需要掌握的技能 本项目二开及与服务器交互需要一定前端基础知识，建议在开发前先学习一下以下内容，会对项目理解非常有帮助: * [Vue3](https://vuejs.org/) * [ThreeJS](https://threejs.org/) * [Naive UI](https://www.naiveui.com/zh-CN/os-theme) * [TypeScript](https://www.typescriptlang.org/) * [Vite](https://vitejs.dev/) * [UnoCSS](https://uno.antfu.me/) --- --- url: /guide/7eo51kfy/index.md --- # 2D图纸 ::: demo-wrapper img no-padding ::: ## 简要说明 \==拖入(双击)== 添加至场景中的图纸会自动占据中心视口一半的位置，其与3D视图中间的 ==垂直分割线== 可以左右拖动以改变占据视口的大小。 图纸可以与3D视图联动，提供更直观的设计体验。 这一功能不仅提升了图纸的可视化效果，还为设计和协作提供了极大的便利。 **主要亮点：** * 使用OffscreenCanvas技术在Worker线程中对图纸内容进行渲染，不会阻塞主线程3D场景的渲染。 * 图纸与3D视图联动，操作简单高效。 * 灵活调整视口分割线，优化工作空间。 ## 功能说明 * **图纸加载**：支持将图纸拖入或双击添加至场景。 * **视口分割**：通过拖动分割线调整2D图纸与3D视图的占比。 * **图纸复位**：将图纸的显示区域恢复为初始状态。 * **图层显隐**：查看图纸的图层列表，并显示/隐藏任意图层。 * **新增标记**：在3D视图中选中模型后，便可以在图纸中新增对应的标记框。 * **删除标记**：删除当前选中的标记。 ### 图纸加载 * **功能描述**：将图纸拖入或双击添加至场景后，图纸会自动占据中心视口的一半位置。 * **操作方式**： * 在左侧CAD图纸列表中双击目标图纸，快速加载到场景中。 ### 视口分割 * **功能描述**：调整2D图纸与3D视图的占比，优化工作空间。 * **操作方式**： * 拖动2D图纸与3D视图中间的垂直分割线，调整两者的占比。 ### 图纸复位 * **功能描述**：将图纸的显示区域恢复为初始状态。 * **操作方式**： * 点击图纸菜单栏中的复位按钮（第一个）。 ### 图层显隐 ::: demo-wrapper img no-padding ::: * **功能描述**：查看图纸的图层列表，并显示/隐藏任意图层。 * **操作方式**： * 点击图纸菜单栏中的图层按钮（第二个）。 * 弹出的图层列表中，点击任一个图层前面的小眼睛图标即可隐藏对应图层，反正显示对应图层。 * 图层列表顶部的==全部图层==节点可以同时显示/隐藏所有图层。 ### 新增标记 * **功能描述**：在图纸中新增3D场景中所选中模型的对应的标记框。 * **操作方式**： * 在右侧3D场景中选中需要标注的模型。 * 点击图纸菜单栏中的新增标记按钮（第三个）。 * 在图纸需要标记的位置按住鼠标左键拖动，即可绘制出长方形标记框。 * 只会只要在图纸中点击该标记，右侧3D场景便会自动聚焦并选中相应模型。 ### 删除标记 * **功能描述**：删除当前选中的标记。 * **操作方式**： * 在图纸上选中需要删除的标记。 * 点击图纸菜单栏中的删除按钮（第四个）。 * 标记及其与模型的关联关系将被移除。 --- --- url: /guide/ae7ufigr/index.md --- # 历史记录 ::: demo-wrapper img no-padding ## 简要说明 历史记录用于查看与回溯编辑操作，支持撤销/重做与持久化。 ## 功能说明 * **列表**：上半部分为已执行操作（Undo），下半部分为可重做操作（Redo） * **点击跳转**：可快速回到指定状态 * **持久化**：勾选后在会话间保存历史记录（可能影响性能） * **清空**：清空所有历史记录 --- --- url: /guide/chhmeza7/index.md --- # 界面 ::: demo-wrapper img no-padding ## 简要说明 预览页用于展示场景的最终效果，默认关闭编辑能力，仅保留交互操作与功能菜单。 ## 布局结构 * **视口区**：展示 3D 场景 * **图纸区**：若项目包含图纸，可与视口并排显示 * **场景树**：左上角按钮打开/关闭 * **操作栏**：底部悬浮菜单 ## 操作栏功能 * **主视角**：恢复初始视角 * **自动旋转** * **剖切**：开启/关闭剖切盒 * **测量**：距离/角度/面积，右键结束测量 * **爆炸**：对选中模型进行爆炸展开 * **漫游**：进入第一人称/第三人称漫游 * **小地图** * **设置** * **全屏/退出全屏** --- --- url: /guide/component/h4v1bkyh/index.md --- # 脚本 > 主要面相于开发人员，主要功能有： > > 1. 编写脚本逻辑，并将其挂载于实体模型上； > 2. 脚本组件使用`JavaScript`编程语言； > 3. 脚本组件由事件驱动，在对应生命周期内执行； > 4. 脚本组件可以访问实体模型的属性和方法； > 5. 运行时执行脚本逻辑，并获取脚本执行结果； ### 内置变量 在脚本中已经内置了以下变量： | 变量 | 描述 | 类型 | |----------|------------|--------------------------------------------------------------| | this | 当前实体模型的引用 | `THREE.Object3D` | | THREE | THREE对象 | `THREE` | | helper | 辅助类函数集合 | [Helper](#helper) | | renderer | 当前渲染器的引用 | `THREE.WebGLRenderer` | | scene | 当前场景的引用 | `THREE.Scene` | | camera | 当前场景相机的引用 | `THREE.PerspectiveCamera` | | controls | 当前场景控制器的引用 | [CameraControls](https://github.com/yomotsu/camera-controls) | | timer | 场景运行时间跟踪 | `three/addons/misc/Timer.js` | ### 内置方法 在脚本中已经内置了以下方法： | 方法 | 描述 | 传入参数 | |--------|-----------|-------------------| | render | 驱动场景渲染一帧。 | `{delta?:number}` | ### 内置生命周期 支持以下几个基本生命周期： | 生命周期 | 描述 | 参数 | |-----------------|-------------------------------|----------------------------------------------------------------| | loaded | 场景加载完成时执行，仅执行一次 | - | | beforeAnimation | 场景当前动画帧循环开始之前触发，每一帧执行一次 | `{"delta":number}` | | afterAnimation | 场景当前动画帧循环完成之后立即触发，每一帧执行一次 | `{"delta":number,"toBeRender":(_needRender: boolean) => void}` | | beforeRender | 场景当前动画帧循环完成之后渲染之前触发，每一次渲染执行一次 | `{"delta":number}` | | afterRender | 场景当前帧渲染完成之后触发，每一次渲染执行一次 | `{"delta":number}` | | beforeDestroy | 场景销毁前调用，仅执行一次 | - | | afterDestroy | 场景销毁后调用，仅执行一次 | - | > Tips: > > > `toBeRender`:由于本系统默认为事件驱动渲染，而非持续渲染，故提供此方法以便在脚本中实现自定义的逻辑。推荐用法： > > > > ```javascript > > afterAnimation(delta,toBeRender){ > > // 传入true则下一帧一定渲染 > > toBeRender(true); > > } > > ``` ### 内置事件 支持以下几个基本事件： | 事件 | 描述 | 参数 | |------------------------------------------------|------------|--------------------------------| | onPick | 模型单击事件 | `intersect:THREE.Intersection` | | onDoubleClick | 模型双击事件 | `intersect:THREE.Intersection` | | bindDataChange | 数据绑定变更事件 | `data:any, config?:any, index?:number` | | onKeydown | 键盘按下事件(全局) | `event:KeyboardEvent` | | onKeyup | 键盘抬起事件(全局) | `event:KeyboardEvent` | | onPointerDown | 指针按下事件(全局) | `event:PointerEvent` | | onPointerUp | 指针抬起事件(全局) | `event:PointerEvent` | | onPointerMove | 指针移动事件(全局) | `event:PointerEvent` | | onTouchStart | 触屏按下事件(全局) | `event:TouchEvent` | | onTouchEnd | 触屏释放事件(全局) | `event:TouchEvent` | > `bindDataChange` 仅在当前模型数据组件获取到新数据时触发，参数依次为 `data / config / index`。 *** ### 辅助类(Helper) | 成员 | 描述 | 类型 | |-----------|----------------------|--------------------------------| | scene | 当前场景的引用，内置变量scene的引用 | `THREE.Scene` | | Animation | 未实例化的动画类 | [Animation](#helper-animation) | | 方法 | 描述 | 参数 | 返回值 | |--------------|------------------------|------------------------------------------------------------------|------------------| | objectByUuid | 通过uuid获取场景中的Object3D对象 | `uuid:string` | `THREE.Object3D` | | moveObject | 移动3D对象到指定位置 | `object: Object3D``parent: Object3D``before: Object3D` | - | | removeObject | 从场景中移除3D对象 | `object: THREE.Object3D` | - | ### 动画类(Animation) #### 基础用法 ```javascript const animation = new helper.Animation(this); ``` #### API ```typescript new helper.Animation(object:THREE.Object3D) ``` | 成员 | 描述 | 类型 | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------| | object | 构造函数形参值，动画绑定的对象。 如果实例化时传入参数this(如上)，则指向内置变量this | `THREE.Object3D` | | actions | 动画动作集合 | `THREE.AnimationAction[]` | | actionsMap | 动画动作映射表，key为动作名称，value为THREE.AnimationAction对象 | `Map` | | lastPlayAction | 正在播放的动作名称 | `THREE.AnimationAction \| undefined` | | repetitions | 动画重复次数 | `number` | | ActionLoop (static) | 动画循环模式枚举： LoopOnce - 只执行一次 LoopRepeat - 重复次数为repetitions的值, 且每次循环结束时候将回到起始动作开始下一次循环。 LoopPingPong - 重复次数为repetitions的值, 且像乒乓球一样在起始点与结束点之间来回循环。 | `Enum` | | 方法 | 描述 | 参数 | 返回值 | |-----------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------| | getAction | 获取指定名称的动画动作,用于用户直接调用[THREE.AnimationAction的方法](https://threejs.org/docs/index.html#api/zh/animation/AnimationAction) | `name:string` | `THREE.AnimationAction \| undefined` | | play | 播放指定名称的动画动作,支持链式调用 | `name:string` `loop:AnimationActionLoopStyles = helper.Animation.ActionLoop.LoopRepeat` `timeScale:number = 1` | `this(helper.Animation)` | | pause | 暂停动画,支持链式调用 | `name:string \| undefined` | `this(helper.Animation)` | | stop | 停止动画,支持链式调用 | `name:string \| undefined` | `this(helper.Animation)` | ### 基础用法 完整结构： ```javascript /** * 场景加载完成时执行，仅执行一次 */ function loaded() { console.group('loaded'); console.log(this); console.log(renderer); console.log(scene); console.log(camera); console.log(controls); console.log(timer); console.groupEnd() } /** * 场景当前动画帧循环开始之前触发，每一帧执行一次 * @param {number} delta */ function beforeAnimation(delta) {} /** * 场景当前动画帧循环完成之后立即触发，每一帧执行一次 * @param {number} delta * @param {(_needRender: boolean) => void} toBeRender 设置下一帧是否将渲染 */ function afterAnimation(delta,toBeRender) {} /** * 场景当前动画帧循环完成之后渲染之前触发，每一次渲染执行一次 * @param {number} delta */ function beforeRender(delta) {} /** * 场景当前帧渲染完成之后触发，每一次渲染执行一次 * @param {number} delta */ function afterRender(delta) {} /** * 场景销毁前调用，仅执行一次 */ function beforeDestroy() {} /** * 场景销毁后调用，仅执行一次 */ function afterDestroy() {} /** * 模型单击事件 * @param {THREE.Intersection} intersect */ function onPick(intersect) {} /** * 模型双击事件 * @param {THREE.Intersection} intersect */ function onDoubleClick(intersect) {} /** * 数据绑定变更事件（仅当前模型） * @param {any} data * @param {any} config * @param {number} index */ function bindDataChange(data, config, index) {} /** * 键盘按下事件(全局) * @param {KeyboardEvent} event */ function onKeyDown(event) {} /** * 键盘抬起事件(全局) * @param {KeyboardEvent} event */ function onKeyUp(event) {} /** * 指针按下事件(全局) * @param {PointerEvent} event */ function onPointerDown(event) {} /** * 指针抬起事件(全局) * @param {PointerEvent} event */ function onPointerUp(event) {} /** * 指针移动事件(全局) * @param {PointerEvent} event */ function onPointerMove(event) {} /** * 触屏按下事件(全局) * @param {TouchEvent} event */ function onTouchStart(event) {} /** * 触屏释放事件(全局) * @param {TouchEvent} event */ function onTouchEnd(event) {} ``` *** ### 示例代码 #### 1. 动态天空盒/模型动画/键盘事件 ::: tabs#animate @tab Scene#scene ```javascript function afterAnimation(delta,toBeRender){ toBeRender(true) } const DEG2RAD = Math.PI / 180; function beforeRender(delta) { const t = delta * DEG2RAD; scene.backgroundRotation.y = t; } ``` @tab:active Wolf#wolf ```javascript const anime = new helper.Animation(this); function loaded() { anime.play("01_Run_Armature_0"); } function onKeyDown(event) { // 按下1则执行 "01_Run_Armature_0" 动画,按下2则执行 "02_walk_Armature_0" 动画，按下3则执行 ""05_site_Armature_0"" 动画, switch (event.key) { case "1": anime.stop(); anime.play("02_walk_Armature_0"); break; case "2": anime.stop(); anime.play("05_site_Armature_0"); break; case "3": anime.stop(); anime.play("01_Run_Armature_0"); break; } } function beforeDestroy() { anime.stop(); } ``` ::: --- --- url: /guide/component/h4v1bmhb/index.md --- # 脚本(开源版本) > 主要面相于开发人员，主要功能有： > > 1. 编写脚本逻辑，并将其挂载于实体模型上； > 2. 脚本组件使用`JavaScript`编程语言； > 3. 脚本组件由事件驱动，在对应生命周期内执行； > 4. 脚本组件可以访问实体模型的属性和方法； > 5. 运行时执行脚本逻辑，并获取脚本执行结果； ### 内置变量 在脚本中已经内置了以下变量： | 变量 | 描述 | 类型 | |----------|------------|--------------------------| | this | 当前实体模型的引用 | `THREE.Object3D` | | THREE | THREE对象 | `THREE` | | helper | 辅助类函数集合 | [Helper](#helper) | | renderer | 当前渲染器的引用 | `THREE.WebGLRenderer` | | scene | 当前场景的引用 | `THREE.Scene` | | camera | 当前场景相机的引用 | `THREE.PerspectiveCamera` | | controls | 当前场景控制器的引用 | `THREE.OrbitControls` | | clock | 场景运行时间跟踪 | `THREE.Clock` | ### 内置生命周期 支持以下几个基本生命周期： | 生命周期 | 描述 | 参数 | |---------------|-----------------------------|------------------------------------| | init | 场景启动后（加载完成时）执行，仅执行一次 | - | | start | 开始运行，在第一次`update`之前调用，仅执行一次 | - | | stop | 停止运行时（场景销毁前）调用，仅执行一次 | - | | beforeUpdate | 场景每帧更新前运行 | - | | update | 场景每帧更新时运行 | `{"time":number, "delta": number}` | | afterUpdate | 场景每帧更新后运行 | - | | beforeDestroy | 场景销毁前调用，仅执行一次 | - | | destroy | 场景销毁时调用，仅执行一次 | - | ### 内置事件 支持以下几个基本事件： | 事件 | 描述 | 参数 | |---------------|--------|-----------------------------------------------------------------------------------| | onKeydown | 键盘按下事件 | `event:KeyboardEvent` | | onKeyup | 键盘抬起事件 | `event:KeyboardEvent` | | onPointerdown | 指针按下事件 | `event:MouseEvent` | | onPointerup | 指针抬起事件 | `event:MouseEvent` | | onPointermove | 指针移动事件 | `event:MouseEvent` | | onPick | 鼠标点击事件 | `{intersects: THREE.Intersection[], pickPosition: THREE.Vector2}` | | bindDataChange | 数据绑定变更事件 | `data:any, config?:any, index?:number` | > `bindDataChange` 在当前模型数据组件获取到新数据时触发。 *** ### 辅助类(Helper) | 成员 | 描述 | 类型 | |-----------|----------------------|--------------------------------| | scene | 当前场景的引用，内置变量scene的引用 | `THREE.Scene` | | Animation | 未实例化的动画类 | [Animation](#helper-animation) | | 方法 | 描述 | 参数 | 返回值 | |--------------|------------------------|------------------------------------------------------------------|------------------| | objectByUuid | 通过uuid获取场景中的Object3D对象 | `uuid:string` | `THREE.Object3D` | | moveObject | 移动3D对象到指定位置 | `object: Object3D``parent: Object3D``before: Object3D` | - | | removeObject | 从场景中移除3D对象 | `object: THREE.Object3D` | - | ### 动画类(Animation) #### 基础用法 ```javascript const animation = new helper.Animation(this); ``` #### API ```javascript new helper.Animation(object:THREE.Object3D) ``` | 成员 | 描述 | 类型 | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------| | object | 构造函数形参值，动画绑定的对象。 如果实例化时传入参数this(如上)，则指向内置变量this | `THREE.Object3D` | | actions | 动画动作集合 | `THREE.AnimationAction[]` | | actionsMap | 动画动作映射表，key为动作名称，value为THREE.AnimationAction对象 | `Map` | | lastPlayedAction | 正在播放的动作名称 | `THREE.AnimationAction \| undefined` | | repetitions | 动画重复次数 | `number` | | ActionLoop (static) | 动画循环模式枚举： LoopOnce - 只执行一次 LoopRepeat - 重复次数为repetitions的值, 且每次循环结束时候将回到起始动作开始下一次循环。 LoopPingPong - 重复次数为repetitions的值, 且像乒乓球一样在起始点与结束点之间来回循环。 | `Enum` | | 方法 | 描述 | 参数 | 返回值 | |-----------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------| | getAction | 获取指定名称的动画动作,用于用户直接调用[THREE.AnimationAction的方法](https://threejs.org/docs/index.html#api/zh/animation/AnimationAction) | `name:string` | `THREE.AnimationAction \| undefined` | | play | 播放指定名称的动画动作,支持链式调用 | `name:string` `loop:AnimationActionLoopStyles = helper.Animation.ActionLoop.LoopRepeat` `timeScale:number = 1` | `this(helper.Animation)` | | pause | 暂停动画,支持链式调用 | `name:string \| undefined` | `this(helper.Animation)` | | stop | 停止动画,支持链式调用 | `name:string \| undefined` | `this(helper.Animation)` | ### 基础用法 完整结构： ```javascript function init() { // 脚本初始化逻辑 console.group('init'); console.log(this); console.log(renderer); console.log(scene); console.log(camera); console.log(controls); console.groupEnd() } function start() { // 脚本开始运行逻辑 } function stop() { // 脚本停止运行逻辑 } function beforeUpdate() { // 每帧更新前运行逻辑 } function update({time, delta}) { // 每帧更新时运行逻辑 // 例如，每一帧更新物体旋转角度 this.rotationZ += 0.1; } function afterUpdate() { // 每帧更新后运行逻辑 } function beforeDestroy() { // 销毁前运行逻辑 } function destroy() { // 销毁时运行逻辑 } /* 事件直接触发对应函数即可 */ function onKeydown(event) { console.log('keydown', event); } function onKeyup(event) { console.log('keyup', event); } function onPointerdown(event) { console.log('pointerdown', event); } function onPointerup(event) { console.log('pointerup', event); } function onPointermove(event) { console.log('pointermove', event); } function onPick({intersects, pickPosition}) { console.log('onPick', intersects, pickPosition); } function bindDataChange(data, config, index) { console.log('bindDataChange', data, config, index); } ``` *** ### 示例代码 #### 1. 动态天空盒/模型动画/键盘事件 ::: tabs#animate @tab Scene#scene ```javascript const DEG2RAD = Math.PI / 180; function update({ time }) { const t = time * DEG2RAD; scene.backgroundRotation.y = t; } ``` @tab:active Wolf#wolf ```javascript const anime = new helper.Animation(this); function init() { anime.play("01_Run_Armature_0"); } function onKeydown(event) { // 按下1则执行 "01_Run_Armature_0" 动画,按下2则执行 "02_walk_Armature_0" 动画，按下3则执行 ""05_site_Armature_0"" 动画, switch (event.key) { case "1": anime.stop(); anime.play("02_walk_Armature_0"); break; case "2": anime.stop(); anime.play("05_site_Armature_0"); break; case "3": anime.stop(); anime.play("01_Run_Armature_0"); break; } } function beforeDestroy() { anime.stop(); } ``` ::: --- --- url: /guide/crvssx6j/index.md --- # 渲染器配置 ::: demo-wrapper img no-padding ## 简要说明 渲染器配置用于控制全局渲染参数，如抗锯齿、色调映射、阴影与 CSM。 ## WebGIS 提示 * WebGIS 场景强制使用后处理管线，抗锯齿与色调映射配置不生效 * 阴影与 CSM 在 WebGIS 中不启用，仅帧率限制有效 ## 基础设置 * **Antialias**：开关抗锯齿 * **Tone Mapping**：色调映射模式 * **Exposure**：色调映射曝光（非 No 模式可调） * **Frame Rate Limit**：帧率限制 ## 阴影（Shadows） * **启用**：全局阴影开关 * **类型**：Basic / PCF / PCF Soft / VSM ## 全局光影（CSM） * **启用** * **Fade**：级联边缘过渡 * **Shadow Far**：阴影最大距离 * **Frustum Split Mode**：practical / logarithmic / uniform * **Shadow Map Size** * **Light Intensity / Color / Direction** --- --- url: /guide/data-component/index.md --- # 数据组件 数据组件用于将数据集绑定到模型，并在运行时刷新数据、预览结果或驱动模型属性。仅在选中模型时显示配置内容。 ## 数据集选择 数据组件先选择数据集分组，再选择该分组下的数据集。 * **数据集分组**：默认选中第一个可用分组 * **数据集**：随分组实时变更；切换分组后，已选数据集会重置为空 * **切换数据集**：选择新数据集后会执行一次数据请求 这种方式可以避免所有数据集混在一个下拉框中，便于在数据集较多时快速定位。 ## 参数数据录入 当数据集包含占位参数时，右侧栏会显示参数表格。侧边栏表格只展示参数名和参数值，用于快速确认当前绑定参数。 点击参数表格区域后，会打开参数数据录入弹窗。弹窗内按参数来源展示，例如 `Params`、`Body`。Body 中的参数如果没有说明信息，说明列会为空。 ### 参数值控件 参数录入控件由数据中心配置的参数类型决定。 | 参数类型 | 录入控件 | | --- | --- | | `string` | 文本输入框 | | `number` | 数字输入框 | | `boolean` | 开关 | | `json` | 点击输入框后打开 JSON 编辑器 | 选择 `json` 类型时，会弹出 JSON 参数编辑器，用于录入对象、数组或其他合法 JSON 值。 ### 刷新时机 编辑参数时不会立即触发数据请求。只有点击参数数据录入弹窗的确认按钮并关闭弹窗后，才会使用最新参数触发数据结果刷新。 这样可以避免输入过程中频繁请求接口，尤其适合自动刷新或多个组件绑定同一数据集的场景。 ## 数据过滤器 用于在数据应用前进行二次处理。 * **启用过滤**：开关控制过滤器是否生效 * **过滤器函数**：仅可编辑函数体部分 ```javascript function filter(data) { // 示例：return data.filter(item => item.value > 100); } ``` > 关闭过滤器时，数据直接输出，不经过处理。 ## 自动刷新（轮询） 用于持续拉取数据并更新模型。 * **数据刷新**：勾选后启用轮询 * **间隔（秒）**：刷新间隔，建议 1~600 秒 多个数据组件如果绑定了相同数据集、相同参数和相同刷新间隔，运行时会复用同一次请求结果，避免重复请求。 ## 手动刷新 点击后立即执行一次数据请求与更新。手动刷新会使用当前已确认的参数值。 ## 应用于模型 勾选后会将数据自动应用到模型属性；未勾选时仅更新数据结果与数据缓存。 ## 过渡时间（transition） 用于控制数据应用到模型的过渡时间，单位为毫秒。 `0` 表示无过渡，属性立即生效。 ## 数据结果预览 以只读 JSON 形式展示当前数据结果，便于调试与确认效果。 如果接口、SQL 或参数配置错误，数据结果区域会显示错误信息。 ## 数据格式（AstralDataFormat） 数据组件支持以下标准结构。示例字段均为可选字段： > 数据集也可以返回非标准结构的数据，这类数据不会驱动模型，但会保留在数据结果中，供脚本使用，例如在 `bindDataChange` 中读取 `data`。 ```ts interface AstralDataFormat { position?: [number, number, number]; rotation?: [number, number, number]; // radians scale?: [number, number, number]; material?: { color?: string; // "#rrggbb" opacity?: number; transparent?: boolean; metalness?: number; roughness?: number; emissive?: string; emissiveIntensity?: number; }; visible?: boolean; animations?: Array<{ name: string; behavior: "play" | "pause" | "stop"; duration?: number; }>; } ``` --- --- url: /guide/dbd366ps/index.md --- # 项目 ::: demo-wrapper img no-padding ::: ## 新建项目 > 可以选择新建一个空项目或者依据内置模板创建。 ::: demo-wrapper img no-padding ::: --- --- url: /guide/dju4ekca/index.md --- # 资源中心 ::: demo-wrapper img no-padding ::: ## 简要说明 在扩展栏左上角下拉菜单中可将扩展面板切换到资源中心模块。 资源共分为==模型、材质、粒子、广告牌、Html面板、灯光、相机==。 编辑器已内置大多通用资源，也可在扩展栏右上角切换资源来源：==内置资源/公共资源==。 **主要亮点：** * **资源分类清晰**：支持多种资源类型，方便用户快速查找和使用。 * **资源来源灵活**：可切换内置资源和公共资源，满足不同场景需求。 * **高效管理**：支持资源的快速预览、搜索和分类管理。 * **扩展性强**：用户可自定义资源并上传到公共资源库。 ## 功能说明 * **资源搜索**：按名称模糊搜索已选择分类下的资源。 * **模型**：内置多种类型的模型，用户可快速预览模型并拖拽到场景中使用。 * **材质**：提供丰富的材质库，用户可实时预览材质效果并应用至模型。 * **粒子**：内置多种粒子效果模板，支持参数调整和自定义粒子效果创建。 * **广告牌**：支持图片和文字广告牌的快速创建，适用于场景标注和装饰。 * **Html面板**：允许嵌入自定义HTML内容，支持动态交互和样式调整。 * **灯光**：提供多种灯光类型（如点光源、聚光灯等），支持实时调整光照参数。 * **相机**：内置透视相机与正交相机，满足不同场景需求。 ### 资源搜索 搜索框位于扩展栏顶部中间。 输入搜索内容，将根据当前所选取资源类型进行模糊查询。 ### 模型 如本页首图，内置了多种类型的模型，用户可通过==拖拽/双击==方式将模型添加到场景中。 * \==拖拽==：模型将放置在鼠标放开的屏幕位置 * \==双击==：模型将放置在场景中心 ### 材质 内置了多类型的PBR材质、Shader材质，用户可通过==拖拽/双击==方式将材质应用到模型上; 成功应用的材质可在 右侧边栏-[材质](/guide/l1df4723/) 进行参数配置及修改。 * \==右键==：预览材质 * \==拖拽==：材质将应用至鼠标放开位置选取到的模型上 * \==双击==：材质将应用至所选取的模型上 **注意**：材质只能应用至Mesh节点，不能应用于Group、广告牌、粒子、Html面板等节点。即材质只能应用于本身就包含材质属性的模型节点。 ### 粒子 内置火焰、烟雾、萤火虫等常见粒子效果模板，用户可通过==拖拽/双击==方式将粒子添加到场景中; 成功添加的粒子可在 右侧边栏-[粒子](/guide/siz46vj0/) 调整粒子发射器参数及粒子行为。 * \==拖拽==：粒子将放置在鼠标放开的屏幕位置 * \==双击==：粒子将放置在场景中心 ### 广告牌 内置图标、文本广告牌，用户可通过==拖拽/双击==方式将广告牌添加到场景中; 成功添加的广告牌可在 右侧边栏-[广告牌](/guide/18al65zg/) 进行参数配置及修改。 * \==拖拽==：广告牌将放置在鼠标放开的屏幕位置 * \==双击==：广告牌将放置在场景中心 ### Html面板 内置多个Html面板模板，用户可通过==拖拽/双击==方式将Html面板添加到场景中; 该功能允许用户在场景中嵌入HTML内容，如视频播放器、交互式表单、数据图表等，支持动态更新; 成功添加的Html面板可在 右侧边栏-[Html面板](/guide/kk5cv2ij/) 进行参数配置及内容修改。 * \==拖拽==：Html面板将放置在鼠标放开的屏幕位置 * \==双击==：Html面板将放置在场景中心 ### 灯光 内置==环境光、平行光、半球光、点光源、聚光灯==五种灯光类型，用户可通过==拖拽/双击==方式将灯光添加到场景中; 成功添加的灯光（选中后）可在 右侧边栏-[对象](/guide/2xlh6nrf/) 进行参数配置及修改。 * \==拖拽==：灯光将放置在鼠标放开的屏幕位置 * \==双击==：灯光将放置在场景中心 ### 相机 内置==透视相机、正交相机==，用户可通过==拖拽/双击==方式将相机添加到场景中; 相机添加后可在[3D视口](/guide/jkg3yahd/)左上角进行主相机切换； 成功添加的相机（选中后）可在 右侧边栏-[对象](/guide/2xlh6nrf/) 进行参数配置及修改。 * \==拖拽==：相机将放置在鼠标放开的屏幕位置 * \==双击==：相机将放置在场景中心 --- --- url: /guide/f7smai4w/index.md --- # 顶栏 ::: demo-wrapper img no-padding ![顶栏](/images/manual/editor/header.png) ::: ::: tip 说明 `顶栏`部分为左中右布局，左侧为`基础操作区`，中间仅展示`场景名称`，右侧为`多功能区域` ::: ## 基础操作区 > 图标/按钮 从左到右依次是 ==Logo、撤回、重做、删除、清空、拷贝、全屏、导出、导入== ::: tabs @tab Logo 方寸藏寰宇，虚实映乾坤 @tab 撤回 撤销上一步操作。 @tab 重做 恢复被撤销的操作。 @tab 删除 删除当前选中的对象。 @tab 清空 清空场景中的所有内容并重置所有模块。 @tab 拷贝 复制当前选中的对象。 @tab 全屏 切换编辑器的全屏模式，全屏后会变为退出全屏图标，点击可退出全屏。 @tab 导出 导出功能分为三类: * 导出选中的物体; * 导出整个场景; * 导出场景离线包; 前两者所支持的导出格式一致，分别是`JSON、GLB、GLTF、OBJ、PLY、PLY(二进制)、STL、STL(二进制)、USDZ` @tab 导入 从文件系统导入模型/场景文件，允许多选，支持在此处导入的文件格式如下： * \[x] astral * \[x] glb * \[x] gltf * \[x] fbx * \[x] json (Three JSON / Astral3D JSON) * \[x] zip [+zip] * \[x] obj * \[x] mtl * \[x] ifc * \[x] 3dm * \[x] 3ds * \[x] 3mf * \[x] amf * \[x] dae * \[x] drc * \[x] kmz * \[x] ldr * \[x] mpd * \[x] md2 * \[x] pcd * \[x] ply * \[x] stl * \[x] svg * \[x] usdz * \[x] vox * \[x] vtk * \[x] vtp * \[x] vtu * \[x] wrl * \[x] xyz * \[x] js * \[x] brep * \[x] step/step * \[x] iges/igs [+zip]: 导入zip包时，系统会自动解析处理，分为下面几种情况： * 同时包含`model.obj`和`materials.mtl`，会按照`.obj`解析 * 遍历解析zip包中的`fbx`、`glb`、`gltf` ::: ## 多功能区域 > 图标/按钮 从左到右依次是 ==保存、预览、国际化、主题、主色调、设置== ::: tabs @tab 保存 打包当前场景，并保存至服务器。 @tab 预览 打开新的[预览页](/guide/chhmeza7/)窗口进行场景预览。 @tab 国际化 切换编辑器的语言，默认支持语言如下： * \[x] 简体中文 * \[x] English @tab 主题 切换编辑器的主题风格。 切换顺序为`深色`-->`跟随系统`-->`浅色`-->`深色` 系统默认为`深色`风格 @tab 主色调 调整编辑器的主色,系统会自动生成相应的浅色、深色色阶，用于鼠标经过以及选中等效果。 @tab 设置 打开编辑器的设置面板。 ::: --- --- url: /guide/fn9xwbkf/index.md --- # 天气 ::: demo-wrapper img no-padding ## 简要说明 天气面板用于配置场景的雾、雨、雪效果。 ## 雾（Fog） * **类型**：Linear / Exponential * **颜色**：雾颜色 * **近/远**：线性雾的距离范围 * **密度**：指数雾密度 ## 雨（Rain） * **速度**：雨滴下落速度 * **颜色**：雨滴颜色 * **尺寸**：雨滴大小 * **倾斜角**：雨滴方向角度 * **透明度**：雨滴透明度 ## 雪（Snow） * **速度**：雪花下落速度 * **密度**：雪花数量密度 * **尺寸**：雪花大小 * **透明度**：雪花透明度 ## WebGIS 提示 * WebGIS 天气效果会随高度自动淡出，可通过 `maxAltitude` 控制上限 * 雾支持 `atmospheric` 类型，用于与大气散射效果协同显示 --- --- url: /guide/g3kxptm0/index.md --- # 动画 ::: demo-wrapper img no-padding ## 简要说明 动画面板用于控制当前选中模型的动画播放状态。仅当对象包含动画时显示。 ## 动画列表 * 展示所有动画剪辑名称 * 支持 **播放 / 暂停 / 继续 / 停止** * 若动画正在动画编辑器中编辑，控制会同步到编辑器 ## 播放速率 * **Time Scale**：调整动画播放速度（支持负值反向播放） --- --- url: /guide/gis-map-sources/index.md --- # GIS地图源 ::: demo-wrapper img no-padding ## 简要说明 GIS 地图源面板用于管理 WebGIS 场景的地图数据，可同时叠加多个 3D Tiles 与 2D Tiles 数据源。 ## 关键操作 * **新增/编辑/删除**：支持配置多个地图源 * **启用/禁用**：切换地图源显示状态 * **至少保留一个**：系统要求至少保留一个地图源 ## 地图源类型 ### 3D Tiles * **Google**：需要 `googleApiKey` * **Cesium Ion**：需要 `ionToken` 与 `ionAssetId` * **自定义**：填写 `tiles3dUrl` ### 2D Tiles * **预设**：天地图/高德/OSM * **自定义**：`tileUrl` 支持 `{x}/{y}/{z}` 占位符 * **天地图**：需要 `tiandituKey` ## 使用建议 * 2D Tiles 适合作为底图，3D Tiles 用于城市/建筑细节 * 调整启用状态时会自动刷新地图源渲染器 --- --- url: /guide/gis-position/index.md --- # GIS位置 ::: demo-wrapper img no-padding ## 简要说明 GIS 位置面板用于查看与控制相机的地理坐标，支持输入经纬度与高度进行飞行定位，并提供常用视角预设。 ## 当前位置 * **坐标**：经度、纬度（度） * **高度**：相对地表高度（米） ## 飞行定位 输入目标经纬度与高度后，点击“飞行”执行平滑过渡。 ## 视角预设 * **全球**：高空俯视 * **区域**：中等高度观察 * **街景**：低空近景 * **俯视**：正下视角 * **倾斜**：斜向观察 ## 提示 * 高度单位为米，建议从高空逐步进入近景 * 飞行过程中可点击“停止”中断 --- --- url: /guide/gis-post-processing/index.md --- # GIS后期处理 ::: demo-wrapper img no-padding ## 简要说明 WebGIS 场景使用专用后处理管线（EffectGIS），用于大气散射、体积云、太阳光晕与常规后处理效果。该管线在 WebGIS 中始终启用。 ## 核心模块 ### 体积云（VolumetricClouds） * **覆盖率**：云量密度 * **层级配置**：高度、厚度、密度、阴影 * **质量与性能**：分辨率比例、时间超采样、光束开关 ### 大气（Atmosphere） * **天空渲染**：开关天空背景 * **太阳/天光**：开启或关闭光照贡献 * **时间模式**：实时或固定时间 ### 轮廓（Outline） 用于选中高亮；WebGIS 中强制 `xRay` 以保证遮挡下可见。 ### 抗锯齿与色调映射 使用 SMAA 与 ToneMapping 控制整体画面风格与锐利度。 ## 通用后处理 支持 Bloom、亮度对比度、色差、色深、色相饱和、移轴、扫描线、故障、冲击波、暗角等效果。 ## 注意事项 * WebGIS 使用后处理管线渲染，渲染器里的抗锯齿与色调映射配置不生效 * 体积云与大气效果对性能影响较大，建议按设备能力调整质量参数 --- --- url: /guide/heatmap/index.md --- # 热力图 ::: demo-wrapper img no-padding ## 简要说明 热力图是从资源中心拖入场景的可视化对象，用于展示二维热度分布或高程起伏。\ 支持 **平面热力图** 与 **高程热力图** 两种模式。 ## 基础参数 * **类型**：平面 / 高程\ 平面模式仅显示颜色贴图；高程模式会根据热度生成高度起伏。 * **宽度 / 高度**：热力图平面尺寸（场景单位） ## 高程模式 仅在 **高程热力图** 下显示： * **高度缩放**：放大热度到高度的比例 * **分段数**：控制网格细分度\ 分段越高，地形越平滑，但开销更大 ## 热力图纹理 控制热力贴图的表现效果： * **半径**：每个点的影响半径（像素） * **模糊**：点扩散模糊程度（0~1） * **透明度范围**：最暗与最亮区域的透明度 * **渐变色**：定义颜色梯度\ 每个梯度点为 `0~1` 区间的比例，支持新增/删除与颜色调整 ## 数据设置 热力图数据由 **最大值 / 最小值 / 点列表** 组成： * **最大值 / 最小值**：用于归一化数值区间 * **点列表**：二维点数据（可在弹窗中编辑 JSON） ### 点数据格式 ```json [ { "x": -2, "y": 1.2, "value": 50 }, { "x": 3, "y": -1, "value": 80, "radius": 1.5 } ] ``` 字段说明： * **x / y**：热力图局部坐标\ 热力图以中心为原点，推荐范围约为 `[-width/2, width/2]` 与 `[-height/2, height/2]` * **value**：热度值 * **radius**：可选，单点半径（覆盖默认半径） > 点击点列表预览区域可打开 JSON 编辑器，保存时会进行格式与字段校验。 ## 使用建议 * 先确定 **尺寸** 与 **模式**，再调渐变与点数据 * 高程模式建议提高分段数以获得更平滑的起伏 * 点数量过多时注意性能开销 --- --- url: /guide/jkg3yahd/index.md --- # 3D场景 ::: demo-wrapper img no-padding ::: ## 简要说明 编辑器的核心视口，展示用户所编辑的场景内容。 **主要亮点：** * 提供六视角切换/主相机切换功能，方便用户观察3D场景。 * 自适应视口。 * 支持多种渲染模式，满足不同场景需求。 * 提供丰富的变换控制工具，便于编辑和调整模型。 ## 功能说明 * **主相机切换**：支持在默认的透视相机和其他添加进场景的相机之间切换，满足不同场景的观察需求。 * **六视图**：快速切换到==前、后、左、右、上、下==六个标准视角，便于精确调整模型。 * **渲染模式**：提供==真实、原色、法线、线框==四种渲染模式，适应不同的设计需求。 * **变换控制**：支持平移、旋转、缩放三种变换操作，用户可以通过鼠标或快捷键快速调整模型。 * **坐标参考**：可以切换==世界坐标、本地坐标==，以查看不同坐标系下的轴情况，帮助用户明确模型的方向和位置。 * **场景统计信息**：实时显示场景中的模型数量、顶点数、三角面数、帧时等信息，便于性能优化。 * **视角辅助**：提供视角导航工具，帮助用户快速调整观察方向。 * **操作快捷键**：内置聚焦、删除等快捷键操作，便于快速设计。 ### 主相机切换/六视图 ::: demo-wrapper img no-padding ::: ### 渲染模式 提供以下渲染模式： * **真实模式**：显示模型的材质效果，并进行实时采样，以产生类似光线追踪的效果。 * **原色模式**：显示模型的材质效果，便于检查纹理和光影。 * **法线模式**： * **线框模式**：仅显示模型的边框线条，便于查看内部结构。 ### 变换控制 ### 坐标参考 变换控制右边的按钮，点击后会在==世界坐标/本地坐标==之间切换。 用于表明场景中显示的坐标轴（X、Y、Z）所使用的参考坐标系。 比如：A模型在世界坐标下Y轴向上，但是本地坐标下却是Z轴向上。确定轴向可以辅助用户快速定位一些矩阵变换错误的原因。 ### 场景统计信息 在界面左下角显示场景的实时统计信息，包括： * 模型数量 * 顶点数 * 三角面数 * 帧时（帧率 = 1000/帧时） ### 视角辅助 在界面右下角提供了视角辅助器，方便用户快速切换视角，共支持22个视角。 其颜色会跟随编辑器主题变换（深色/浅色）。 ### 操作快捷键 支持以下快捷键操作： * **W**：切换到平移模式。 * **E**：切换到旋转模式。 * **R**：切换到缩放模式。 * **F**：聚焦选中模型。 * **Del**：删除选中模型。 * **Ctrl + Z**：撤销上一步操作。 * **Ctrl + Shift +Z**：重做被撤销的操作。 如果在设置中修改了对应快捷键，则请使用对应快捷键操作。 --- --- url: /guide/kk5cv2ij/index.md --- # Html面板 ::: demo-wrapper img no-padding ## 简要说明 Html 面板用于在场景中嵌入 HTML 内容，可作为面板或精灵类型显示。 ## 类型 * **CSS3DObject（panel）** * **CSS3DSprite（sprite）** 切换类型会重新构建对象并保留内容。 ## 内容上传 支持上传： * **.html** * **.zip**（包含多文件） 上传后会覆盖原有内容。 ## 代码管理 * 文件列表展示已解析的代码文件 * 点击 **编辑** 打开内置代码编辑器（支持部分文件类型） * 修改后会实时更新面板内容 --- --- url: /guide/l1df4723/index.md --- # 材质 ::: demo-wrapper img no-padding ## 简要说明 材质面板用于编辑选中对象的材质属性。只有对象具备材质时才会显示（如 Mesh / Line / Points / Sprite）。 ## 场景材质列表 顶部会展示当前场景中已有的材质列表，用于快速复用与切换材质。 ## 材质槽与类型 * **材质槽**：对象存在多材质时可切换当前 slot（对应模型子面/子网格） * **类型**：支持多种材质类型，切换类型会创建新材质并替换当前材质 **常见类型** * **Mesh**：`MeshStandardMaterial / MeshPhysicalMaterial / MeshPhongMaterial / MeshLambertMaterial / MeshBasicMaterial` * **Line**：`LineBasicMaterial / LineDashedMaterial` * **Points**：`PointsMaterial` * **Sprite**：`SpriteMaterial` * **Shader**：`ShaderMaterial / RawShaderMaterial` ## 基础信息 * **UUID**：可重新生成 * **名称**：可编辑 ## Shader/Program 仅当材质支持自定义着色器时可用： * **Program Info**：查看材质编译信息 * **Vertex Shader / Fragment Shader**：打开编辑器修改着色器代码 ## 属性详解 以下为当前面板能编辑的属性说明（实际显示取决于材质类型）。 ### 颜色与光照 * **color**：基础颜色（不含光照）；无贴图时直接作为漫反射颜色。 * **specular**：高光颜色（主要用于 Phong 材质）。 * **shininess**：高光强度/范围（Phong 材质，值越大高光越集中）。 * **emissive**：自发光颜色，不受场景光照影响。 * **reflectivity**：环境反射强度（仅部分材质生效）。 ### PBR/物理材质 * **roughness**：粗糙度，0 为镜面、1 为完全粗糙。 * **metalness**：金属度，0 为非金属、1 为金属。 * **clearcoat**：清漆层强度（物理材质）。 * **clearcoatRoughness**：清漆层粗糙度。 * **iridescence**：彩虹色强度（薄膜干涉效果）。 * **iridescenceIOR**：彩虹色折射率。 * **iridescenceThicknessRange**：薄膜厚度范围（nm）。 * **sheen**：丝绸/织物高光强度。 * **sheenRoughness**：丝绸高光粗糙度。 * **sheenColor**：丝绸高光颜色。 * **transmission**：透光强度（玻璃质感）。 * **attenuationDistance**：透光衰减距离（场景单位）。 * **attenuationColor**：透光衰减颜色。 * **thickness**：材质厚度（用于透光/次表面效果）。 ### 透明与深度 * **opacity**：不透明度（0~1）。 * **transparent**：开启透明混合；当 `opacity < 1` 时通常需要开启。 * **alphaTest**：透明裁剪阈值（小于该值的像素被丢弃）。 * **depthTest**：是否参与深度测试。 * **depthWrite**：是否写入深度缓冲。 ### 渲染与几何表现 * **side**：渲染面（Front / Back / Double）。 * **wireframe**：线框显示。 * **flatShading**：平面着色，显示更硬朗的面感。 * **blending**：混合模式（Normal / Additive / Multiply / Subtractive / Custom）。 * **vertexColors**：使用几何体的顶点颜色（需 `geometry.attributes.color`）。 * **depthPacking**：深度打包方式（用于 MeshDepthMaterial）。 ### 点/线/精灵 * **size**：点大小（Points）。 * **sizeAttenuation**：点大小随距离衰减（Points）。 ### 贴图（Map） 贴图通常依赖几何体 UV；`lightMap / aoMap` 需要第二套 UV（uv2）。 * **map**：基础颜色贴图（Albedo）。 * **specularMap**：高光强度贴图。 * **emissiveMap**：自发光贴图。 * **matcap**：MatCap 贴图（材质捕获，快速表现材质光照）。 * **alphaMap**：透明贴图（灰度）。 * **bumpMap**：凹凸贴图（高度图，若有 normalMap 通常忽略）。 * **normalMap**：法线贴图（增强表面细节）。 * **clearcoatNormalMap**：清漆层法线贴图。 * **displacementMap**：置换贴图（真实位移，需足够细分）。 * **roughnessMap**：粗糙度贴图。 * **metalnessMap**：金属度贴图。 * **iridescenceMap**：彩虹色强度贴图。 * **sheenColorMap**：丝绸高光颜色贴图。 * **sheenRoughnessMap**：丝绸高光粗糙度贴图。 * **iridescenceThicknessMap**：彩虹色厚度贴图。 * **envMap**：环境贴图（反射/折射）。 * **lightMap**：烘焙光照贴图（需 uv2）。 * **aoMap**：环境遮蔽贴图（需 uv2）。 * **gradientMap**：渐变贴图（Toon 材质）。 * **transmissionMap**：透光贴图。 * **thicknessMap**：厚度贴图（影响透光与次表面）。 > 部分字段仅在对应材质类型下可见，未显示代表该材质不支持该属性。 ## UserData 支持以 JSON 形式编辑材质 `userData`，点击输入框打开编辑器。 ## 使用建议 * 切换材质类型会创建新材质，建议先保存或记录原材质参数 * 贴图与环境反射效果受场景环境贴图影响，可在“场景配置”中调整 --- --- url: /guide/l8hd921o/index.md --- # 后期处理 ::: demo-wrapper img no-padding ## 简要说明 后期处理用于全局视觉增强。总开关关闭时，所有子效果不可用。 ## 色调映射（ToneMapping） * **模式**：LINEAR / REINHARD / ACES 等 * **曝光**：整体亮度 * **混合模式** ## 抗锯齿（SMAA） * **质量预设**：LOW / MEDIUM / HIGH / ULTRA ## 轮廓（Outline） * **边缘强度** / **脉冲速度** / **模糊强度** * **可见边缘颜色** / **隐藏边缘颜色** / **X-Ray** ## 辉光（UnrealBloom） * **强度** / **亮度阈值** / **平滑度** / **半径** ## 景深（Bokeh） * **焦距** / **范围** / **强度** / **分辨率比例** ## 像素化（Pixelate） * **像素大小** ## 移轴（TiltShift） * **偏移** / **旋转** / **焦点区域** / **羽化** ## 扫描线（Scanline） * **密度** / **滚动速度** / **混合模式** ## 亮度对比（BrightnessContrast） * **亮度** / **对比度** ## 色差（ChromaticAberration） * **偏移** / **径向调制** ## 色深（ColorDepth） * **位深**（1-32） ## 故障（Glitch） * **强度** / **持续时间** / **延迟** / **模式** / **出现概率** ## 色相饱和（HueSaturation） * **色相** / **饱和度** ## 镜头畸变（LensDistortion） * **畸变** / **主点** / **焦距** / **倾斜** ## 冲击波（ShockWave） * **振幅** / **波大小** / **速度** / **最大半径** * 支持点击触发 ## 暗角（Vignette） * **偏移** / **暗度** --- --- url: /guide/n6o11owv/index.md --- > 本文档适用于部署 Astral3D 编辑器到服务器上。 > 以[Java版本](https://github.com/yx8663/astral-service)后端为例，其他语言版本后端部署方式请参考官方文档。 ## 本地打包 ### 前端打包 ```bash # 确认 Node.js 版本（≥ 23.11.x） node -v # 拉取代码 git clone https://github.com/mlt131220/Astral3D.git # 进入项目 cd Astral3D # 安装依赖 pnpm install # 打包 Astral 3D Engine SDK pnpm run sdk:build # 打包Astral 3D Editor pnpm run editor:build ``` ### 后端打包 ```bash # 确认java环境 java -version # 确认maven环境 mvn -v # 拉取代码 git clone https://github.com/yx8663/astral-service # 安装依赖 mvn clean install # 修改数据库等配置（修改 astral-web/src/main/resources/application-dev.yml，详见 https://github.com/yx8663/astral-service/blob/develop/README.md#%E9%85%8D%E7%BD%AE） vim astral-web/src/main/resources/application-dev.yml # 编译打包（通过maven打包即可跨平台） # 生产环境推荐用clean package跳过测试 mvn clean package -DskipTests # jar包： astral-web/target/astral-web.jar ls -l astral-web/target/*.jar ``` ## 服务器部署(Windows) ### 基础环境 * [Nginx](https://nginx.org/en/download.html)/[caddy](https://caddyserver.com/) * [MySQL](https://www.mysql.com/cn/downloads/) 或者直接使用集成环境，如[PHPStudy](https://old.xp.cn/download.html)。 ### 前端部署 将Astral 3D Editor打包后的文件放到方便读取的目录下，如 `C:\www\Astral3dEditor`; ### 后端部署 1. 将后端部署所需文件/文件夹放到方便读取的目录下，如 `C:\www\Astral3DEditorBack`,所需文件/文件夹如下： * `static` 文件夹； * `astral-web/target/astral-web.jar`； * `astral-web/src/main/resources/application.yml` * `astral-web/src/main/resources/application-dev.yml` 2. 此时`C:\www\Astral3DEditorBack`内容如下： ```shell - static/ - application.yml - application-dev.yml - astral-web.jar ``` 3. 打开 MySQL 数据库，创建配置在 `application-dev.yml` 的数据库，并导入 `static/sql/astral_3d.sql` 文件； 4. 启动 MySQL 服务，并确保 MySQL 服务正常运行； 5. 在 `C:\www\Astral3DEditorBack` 下运行命令 `java -jar astral-web.jar` 启动后端服务，默认监听 `8080` 端口； ### Nginx 配置 1. 打开 Nginx 配置文件，假设nginx安装目录为`C:\nginx`,则配置文件路径为`C:\nginx\conf\nginx.conf`; 2. 在 `http` 块中添加以下配置： ``` http { # ... 忽略原有其他配置不变更 # 开启gzip gzip on; # 导入所有的server配置 include vhosts/*.conf; } ``` 3. 在 `C:\nginx\conf` 目录下创建 `vhosts` 目录(与上方http中增加的配置路径同名，并非一定要为`vhost`,可以自定义); 4. 在 `C:\nginx\conf\vhosts` 目录下创建 `astral3d.conf` 文件，内容如下： ``` server { # 监听端口,即前端部署的端口，一般设置为80 listen 80; # 域名/ip/localhost server_name 127.0.0.1; # 访问 server_name:listen 后，请求就会被转发到这个location块中 location / { # 前端部署的目录，即前端打包后的文件所在目录 root "C:\www\Astral3dEditor"; # 文件url重写规则，将请求转发到index.html（单页面应用） try_files $uri $uri/ index.html; # 项目入口文件 index index.html; # 协商缓存配置，30天 add_header Cache-Control "public, max-age=2592000"; expires 30d; etag on; } # 后端api接口代理，接口请求匹配 /api 的会走此处转发，下面都同理 location /api { # 后端接口访问地址，上面部署在了本机的8080端口 proxy_pass http://127.0.0.1:8080/api; } # 前端websocket代理 location /socket { proxy_pass http://127.0.0.1:8080/api/sys/ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_connect_timeout 10s; proxy_read_timeout 300s; proxy_send_timeout 300s; } location /file/static { log_not_found off; # 关闭日志 access_log off; # 强缓存设置，缓存时间设置为0.5年 add_header Cache-Control "public, max-age=15768000"; proxy_pass http://localhost:8080/api/common/static; } } ``` ### 启动服务 ```bash nginx -s start # 重启 nginx（如果修改了配置文件） nginx -s reload ``` 此时访问 `http://127.0.0.1` 即可访问到 Astral 3D Editor。 ## 服务器部署(Linux) ### 基础环境 * [Nginx](https://nginx.org/en/download.html)/[caddy](https://caddyserver.com/) * [MySQL](https://www.mysql.com/cn/downloads/) * JDK 1.8 以 Ubuntu/Debian 为例，可以通过以下命令安装基础环境： ```bash # 更新软件源 sudo apt update # 安装 Nginx、MySQL 与 JDK 1.8 sudo apt install -y nginx mysql-server openjdk-8-jdk # 确认 Nginx 环境 nginx -v # 确认 MySQL 环境 mysql --version # 确认 Java 环境 java -version ``` ### 前端部署 将 Astral 3D Editor 打包后的 `packages/editor/dist` 目录上传到服务器，例如部署到 `/www/astral3d/editor`： ```bash # 创建前端部署目录 sudo mkdir -p /www/astral3d/editor # 将 dist 目录内的所有文件同步到前端部署目录 sudo rsync -av --delete packages/editor/dist/ /www/astral3d/editor/ ``` ### 后端部署 1. 将后端部署所需文件/文件夹放到 `/www/astral3d/service` 目录，所需文件/文件夹如下： * `static` 文件夹； * `astral-web/target/astral-web.jar`； * `astral-web/src/main/resources/application.yml` * `astral-web/src/main/resources/application-dev.yml` 2. 此时 `/www/astral3d/service` 内容如下： ```shell - static/ - application.yml - application-dev.yml - astral-web.jar ``` 3. 打开 MySQL 数据库，创建配置在 `application-dev.yml` 的数据库，并导入 `static/sql/astral_3d.sql` 文件： ```bash # 登录 MySQL sudo mysql -u root -p # 创建数据库，数据库名需要与 application-dev.yml 中的配置保持一致 CREATE DATABASE astral_3d DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; # 退出 MySQL exit # 导入初始化 SQL sudo mysql -u root -p astral_3d < /www/astral3d/service/static/sql/astral_3d.sql ``` 4. 手动启动后端服务，确认服务可以正常运行： ```bash # 进入后端部署目录 cd /www/astral3d/service # 启动后端服务，默认监听 8080 端口 java -jar astral-web.jar ``` ### 后端服务托管 生产环境建议使用 systemd 托管后端进程，避免 SSH 断开后服务退出： ```bash # 创建低权限运行用户 sudo useradd --system --no-create-home --shell /usr/sbin/nologin astral3d # 授权后端部署目录 sudo chown -R astral3d:astral3d /www/astral3d/service # 创建 systemd 服务文件 sudo vim /etc/systemd/system/astral3d.service ``` `astral3d.service` 内容如下： ```ini [Unit] Description=Astral3D Java Service After=network.target mysql.service [Service] Type=simple User=astral3d WorkingDirectory=/www/astral3d/service ExecStart=/usr/bin/java -jar /www/astral3d/service/astral-web.jar Restart=on-failure RestartSec=5 SuccessExitStatus=143 [Install] WantedBy=multi-user.target ``` 启用并启动后端服务： ```bash # 重新加载 systemd 配置 sudo systemctl daemon-reload # 设置开机自启并立即启动 sudo systemctl enable --now astral3d # 查看服务状态 sudo systemctl status astral3d ``` ### Nginx 配置 1. 打开 Nginx 主配置文件，确认 `http` 块内已包含站点配置目录： ```bash sudo vim /etc/nginx/nginx.conf ``` ```nginx http { # ... 忽略原有其他配置不变更 # 开启 gzip gzip on; # 导入所有站点配置 include /etc/nginx/conf.d/*.conf; } ``` 2. 创建 Astral3D 站点配置： ```bash sudo vim /etc/nginx/conf.d/astral3d.conf ``` ```nginx server { # 监听端口，即前端部署的端口，一般设置为 80 listen 80; # 域名/ip/localhost server_name 127.0.0.1; # 前端部署的目录，即前端打包后的文件所在目录 root /www/astral3d/editor; # 项目入口文件 index index.html; # 访问 server_name:listen 后，请求就会被转发到这个 location 块中 location / { # 文件 url 重写规则，将请求转发到 index.html（单页面应用） try_files $uri $uri/ /index.html; # 协商缓存配置，30 天 add_header Cache-Control "public, max-age=2592000"; expires 30d; etag on; } # 后端 api 接口代理，接口请求匹配 /api 的会走此处转发 location /api { # 后端接口访问地址，上面部署在了本机的 8080 端口 proxy_pass http://127.0.0.1:8080/api; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 前端 websocket 代理 location /socket { proxy_pass http://127.0.0.1:8080/api/sys/ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_connect_timeout 10s; proxy_read_timeout 300s; proxy_send_timeout 300s; } location /file/static { log_not_found off; # 关闭日志 access_log off; # 强缓存设置，缓存时间设置为 0.5 年 add_header Cache-Control "public, max-age=15768000"; proxy_pass http://127.0.0.1:8080/api/common/static; } } ``` ### 启动服务 ```bash # 检查 Nginx 配置是否正确 sudo nginx -t # 设置 Nginx 开机自启并立即启动 sudo systemctl enable --now nginx # 修改配置文件后重载 Nginx sudo systemctl reload nginx # 如服务器启用了防火墙，需要放行 80 端口 sudo ufw allow 80/tcp ``` 此时访问 `http://服务器IP` 或配置的域名即可访问到 Astral 3D Editor。 ## Docker 部署 ## 注意事项 1. 后端打包前请确认`Astral3DEditorGoBack/conf/app.conf`文件中的`runmode = prod`; 2. 后端部署时，请确保 MySQL 数据库配置正确，并导入 `Astral3DEditorGoBack/static/sql/astral-3d-editor.sql` 文件； 3. 前端部署时，请确保 Nginx 配置正确，并将前端部署到服务器上； 4. 后端部署时，请确保后端程序启动成功，并监听 `Astral3DEditorGoBack/conf/app.conf`中配置的端口`httpport `，默认为 `8080` ； 5. 前端部署时，请确保前端程序启动成功，并监听 Nginx 配置中配置的端口,比如上面示例的 `80` 端口； 6. 部署完成后，请确保 Nginx 与 MySQL 服务正常运行； 7. 部署完成后，请确保前端程序与后端程序正常运行； --- --- url: /guide/nct00cif/index.md --- # 几何 ::: demo-wrapper img no-padding ## 简要说明 几何面板用于查看与调整选中对象的几何体信息。若对象不包含几何体则不会显示。 ## 基础信息 * **类型**：几何体类型（如 BoxGeometry、BufferGeometry 等） * **UUID**：可重新生成 * **名称**：可编辑 ## 几何工具 * **计算顶点法线**：重新计算法线 * **几何居中**：将几何体中心移动到原点 * **法线辅助**：几何体含有 `normal` 属性时可显示/隐藏法线 ## 参数面板 系统会根据几何体类型展示对应参数（如 Box/Circle/Sphere 等），用于直接调整尺寸或分段数。 ## BufferGeometry 信息 当几何体为 `BufferGeometry` 时，会显示： * **Index** 与 **Attributes** 列表（含 `itemSize` 与数量） * **Morph Attributes** 与 `morphTargetsRelative` 状态（若存在） ## Bounds 展示几何体包围盒尺寸（x/y/z）。 --- --- url: /guide/p8awar6v/index.md --- # 安装/使用 \[+node-versions]: **>= 23.0.0：** `23.0.0` 及以上的版本 \[+pnpm-versions]: **>= 10.0.0：** `10.0.0` 及以上的版本 \[+corepack]: 从 **v16.13** 开始，`Node.js` 附带 `Corepack` 用于管理包管理器 ## 依赖环境 * [Node.js](https://nodejs.org/) : **>= 23.0.0** \[+node-versions] * [pnpm](https://pnpm.io/zh/) : **>= 10.0.0** \[+pnpm-versions] :::: details 怎么安装依赖环境？ ::: steps 1. **请前往 [Node.js 官网](https://nodejs.org/zh-cn) 下载最新稳定版本** 请根据指引完成安装，一般而言，在安装过程中，您只需要保持其默认设置，直接选择下一步即可。 2. **安装 PNPM** 在您安装完成 node.js 后，请打开 终端，执行如下命令：\[+corepack] ```sh corepack enable pnpm # [optional] # 这会添加一个 packageManager 字段到你本地的 package.json， # 指示 Corepack 始终在该项目上使用特定的版本。 # 如果你想要可复现性，这可能很有用，因为所有使用 Corepack 的开发人员都将使用与你相同的版本 corepack use pnpm@latest-10 ``` 3. **完成** ::: :::: ## 安装 :::: steps * ### Git拉取项目 ```sh git clone https://github.com/mlt131220/Astral3D.git ``` * ### 进入目录 ```sh cd Astral3D ``` * ### 安装相关依赖 ::: code-tabs @tab pnpm ```sh pnpm install ``` ::: * ### 构建SDK ::: code-tabs @tab pnpm ```sh pnpm run sdk:build ``` ::: * ### 运行编辑器 ::: code-tabs @tab pnpm ```sh pnpm run editor:dev ``` ::: * ### 完成 :::: --- --- url: /guide/path/index.md --- # 路径 ::: demo-wrapper img no-padding ## 简要说明 路径对象用于展示轨迹、管线或流动效果。\ 支持 **带状路径（Ribbon）** 与 **管状路径（Tube）** 两种模式。 ## 基础参数 * **类型**：Ribbon / Tube * **圆角半径**：转角平滑程度 * **圆角分段**：转角细分数量，数值越大越平滑 * **闭合**：是否闭合成环 ## Ribbon 参数 仅在 Ribbon 模式下显示： * **宽度**：带状宽度 * **进度**：显示路径的比例（0~1） * **箭头**：是否显示方向箭头 * **侧向**：路径在中心线的偏移方向（左/右/两侧） ## Tube 参数 仅在 Tube 模式下显示： * **半径**：管道半径 * **径向分段**：管道圆周细分度 * **进度**：显示路径的比例（0~1） * **起始角**：管道起始角度（弧度） ## Flow 参数 用于贴图流动效果（需材质贴图支持）： * **启用流动** * **速度**：可为负值，控制流动方向 * **方向**：二维方向向量（x, y） > Flow 通过材质贴图偏移实现流动；若无贴图，视觉上不会有变化。 ## 说明与建议 * 路径的点数据来自资源中心或脚本配置，当前面板不直接编辑点列表 * 当修改进度或流动参数时可快速预览路径动效 --- --- url: /guide/plugin-pro/builtin/jj87cfk0/index.md --- # glTF 处理器 > 此插件提供了在 Web 端处理 glTF 文件的能力，主要能力如下： > > * 优化 glTF 文件： > * a. 压缩模型数据(包括贴图材质与几何数据)，减少文件大小; > * b. 网格顶点优化，减少顶点数量，提升渲染性能; > * c. 实例化网格，减少渲染 DrawCall，提升渲染性能; > * d. 压缩裁剪纹理贴图，减少内存占用，提升渲染性能; ## 面板 ![glTF处理器](/images/plugin/glTFHandler/plane.jpg) ## 使用方法 #### 1. 点击面板顶部上传区域，选择 glTF 文件（相关文件不会上传至服务器，仅用于本地处理）； #### 2. 修改配置选项或直接使用默认配置； #### 3. 点击“优化”按钮，开始处理 glTF 文件，优化日志会实时显示在面板顶部（原上传文件区域）； ## 配置说明 | 配置项 | 描述 | 值 | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | 压缩方式 | 网格浮点压缩方法Draco 压缩 geometry;Meshopt & Quantization 压缩 geometry 和 animation; | `Draco`|`Meshopt`|`Quantization`|`None` | | Meshopt 压缩级别 | 压缩方式选择`Meshopt`时需要选择压缩级别 | `low`|`medium`|`high` | | 实例化网格 | 使用 GPU 实例化技术共享网格引用，即生成`THREE.InstancedMesh`对象，减少 DrawCall | `true`|`false` | | 实例化网格界限 | 实例化网格所需的实例数,实例数低于该值的网格将不会实例化 | `min:2,max:Infinity` | | 展平场景树 | 将场景内子模型对象全部展平到场景根节点。开启合并网格时此项无法关闭 | `true`|`false` | | 合并网格 | 合并网格以减少渲染调用，合并后的网格无法单独选中。前置条件：开启展平场景树 | `true`|`false` | | 合并纹理 | 创建调色板纹理并合并材质 | `true`|`false` | | 合并纹理界限 | 合并纹理所需的纹理数,纹理数低于该值将不会合并 | `min:2,max:Infinity` | | 修剪 | 从文件中删除未被场景引用的属性 | `true`|`false` | | 修剪顶点 | 是否修剪未使用的顶点属性 | `true`|`false` | | 修剪子节点 | 是否修剪空的叶子节点 | `true`|`false` | | 修剪纹理 | 是否修剪实体(单色)纹理，将其转换为材质元素 | `true`|`false` | | 合并同位顶点 | 合并按位相同的顶点。合并和索引后，顶点之间的数据共享效率更高。文件大小可以减小，GPU 可以更高效地使用顶点缓存。开启简化网格时此项无法关闭 | `true`|`false` | | 简化网格 | 基于`meshoptimizer`的简化算法，生成具有较少三角形和顶点的网格。简化是有损的，但该算法旨在针对给定的参数尽可能地保持视觉质量。前置条件：开启合并同位顶点 | `true`|`false` | | 简化误差界限 | 简化网格误差容忍度，以网格尺寸的百分比表示 | `min:0.01,max:100` | | 简化锁定边界 | 是否锁定网格的拓扑边界，拓扑结构（尤其是分割顶点）会限制简化器 | `true`|`false` | | 简化比率 | 要保留的顶点的比率（0-1） | `min:0,max:1` | | 纹理压缩 | `AVIF`和`WebP`优化传输大小;`Auto`按原始格式进行压缩; | `WebP`|`AVIF`|`Auto`|`None` | | 纹理最大尺寸 | 超过该尺寸的纹理将被压缩,值一般为 2 的 N 次方 | `min:2,max:Infinity` | ## 结果 ![glTF优化结果](/images/plugin/glTFHandler/result.jpg) ![glTF优化文件对比](/images/plugin/glTFHandler/compare.jpg) ![glTF优化文件对比](/images/plugin/glTFHandler/compare2.jpg) --- --- url: /guide/plugin/31eucyqc/index.md --- # 入门 > Astral 3D 内置了插件系统，为其提供了巨大的灵活性和可扩展性。 ## 使用方法 1. 打开插件中心： ![插件中心入口](/images/plugin/entrance.jpg) 2. 单击需要使用的插件运行（以glTF处理器为例）： ![插件中心](/images/plugin/plane.jpg) ![glTF处理器](/images/plugin/glTFHandler/plane.jpg) ## 内置插件 Astral 3D Editor 内置了以下插件： * glTF处理器：在Web端处理glTF文件的能力。用于对 glTF 格式的模型文件进行压缩、优化等操作； --- --- url: /guide/plugin/322ucyqc/index.md --- # 入门 > Astral 3D 内置了插件系统，为其提供了巨大的灵活性和可扩展性。 ## 使用方法 1. 打开插件中心： ![插件中心入口](/images/pluginPro/entrance.jpg) 2. 在插件中心快速检索，安装需要使用的插件（以glTF处理器为例）： ![插件中心](/images/pluginPro/panel.jpg) 3. 安装后会弹出插件权限请求，调整进行安装： ![插件权限请求](/images/pluginPro/permission.jpg) ![安装完成](/images/pluginPro/install.jpg) 4. 单击运行已安装的插件： ![glTF处理器](/images/plugin/glTFHandler/plane.jpg) ## 内置插件 Astral 3D Editor 内置了以下插件： * glTF处理器：在Web端处理glTF文件的能力。用于对 glTF 格式的模型文件进行压缩、优化等操作； --- --- url: /guide/plugin/7ro8hsc0/index.md --- # 插件开发 > 开发插件时，插件入口类需要实现以下接口，并以esm方式导出，Astral3D Engine会加载默认导出模块。 ## 插件入口类接口 ```typescript export interface Plugin { // 插件名称，插件的唯一标识 name: string; // 插件版本号 version:number; // 插件图标 icon:string; // 插件安装函数，在插件安装时调用 install(config?: any): void; // 插件卸载函数，在插件卸载时调用 uninstall(): void; // 从插件盒子面板点击插件时的运行方法 run(): void; } ``` ## 示例插件 ```typescript // 暂未发布到npm，请自行将代码拷贝到项目中 // import { Plugin } from 'msy3d'; class ExamplePlugin implements Plugin { name = 'example-plugin'; version = 1.0; icon = 'https://example.com/icon.png'; install(config?: any): void { console.log('ExamplePlugin installed'); } uninstall(): void { console.log('ExamplePlugin uninstalled'); } run(): void { console.log('ExamplePlugin run'); } } export default ExamplePlugin; ``` --- --- url: /guide/plugin/builtin/jo87cfk0/index.md --- # glTF 处理器 > 此插件提供了在 Web 端处理 glTF 文件的能力，主要能力如下： > > * 优化 glTF 文件： > * a. 压缩模型数据(包括贴图材质与几何数据)，减少文件大小; > * b. 网格顶点优化，减少顶点数量，提升渲染性能; > * c. 实例化网格，减少渲染 DrawCall，提升渲染性能; > * d. 压缩裁剪纹理贴图，减少内存占用，提升渲染性能; ## 面板 ![glTF处理器](/images/plugin/glTFHandler/plane.jpg) ## 使用方法 #### 1. 点击面板顶部上传区域，选择 glTF 文件（相关文件不会上传至服务器，仅用于本地处理）； #### 2. 修改配置选项或直接使用默认配置； #### 3. 点击“优化”按钮，开始处理 glTF 文件，优化日志会实时显示在面板顶部（原上传文件区域）； ## 配置说明 | 配置项 | 描述 | 值 | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | 压缩方式 | 网格浮点压缩方法Draco 压缩 geometry;Meshopt & Quantization 压缩 geometry 和 animation; | `Draco`|`Meshopt`|`Quantization`|`None` | | Meshopt 压缩级别 | 压缩方式选择`Meshopt`时需要选择压缩级别 | `low`|`medium`|`high` | | 实例化网格 | 使用 GPU 实例化技术共享网格引用，即生成`THREE.InstancedMesh`对象，减少 DrawCall | `true`|`false` | | 实例化网格界限 | 实例化网格所需的实例数,实例数低于该值的网格将不会实例化 | `min:2,max:Infinity` | | 展平场景树 | 将场景内子模型对象全部展平到场景根节点。开启合并网格时此项无法关闭 | `true`|`false` | | 合并网格 | 合并网格以减少渲染调用，合并后的网格无法单独选中。前置条件：开启展平场景树 | `true`|`false` | | 合并纹理 | 创建调色板纹理并合并材质 | `true`|`false` | | 合并纹理界限 | 合并纹理所需的纹理数,纹理数低于该值将不会合并 | `min:2,max:Infinity` | | 修剪 | 从文件中删除未被场景引用的属性 | `true`|`false` | | 修剪顶点 | 是否修剪未使用的顶点属性 | `true`|`false` | | 修剪子节点 | 是否修剪空的叶子节点 | `true`|`false` | | 修剪纹理 | 是否修剪实体(单色)纹理，将其转换为材质元素 | `true`|`false` | | 合并同位顶点 | 合并按位相同的顶点。合并和索引后，顶点之间的数据共享效率更高。文件大小可以减小，GPU 可以更高效地使用顶点缓存。开启简化网格时此项无法关闭 | `true`|`false` | | 简化网格 | 基于`meshoptimizer`的简化算法，生成具有较少三角形和顶点的网格。简化是有损的，但该算法旨在针对给定的参数尽可能地保持视觉质量。前置条件：开启合并同位顶点 | `true`|`false` | | 简化误差界限 | 简化网格误差容忍度，以网格尺寸的百分比表示 | `min:0.01,max:100` | | 简化锁定边界 | 是否锁定网格的拓扑边界，拓扑结构（尤其是分割顶点）会限制简化器 | `true`|`false` | | 简化比率 | 要保留的顶点的比率（0-1） | `min:0,max:1` | | 纹理压缩 | `AVIF`和`WebP`优化传输大小;`Auto`按原始格式进行压缩; | `WebP`|`AVIF`|`Auto`|`None` | | 纹理最大尺寸 | 超过该尺寸的纹理将被压缩,值一般为 2 的 N 次方 | `min:2,max:Infinity` | ## 结果 ![glTF优化结果](/images/plugin/glTFHandler/result.jpg) ![glTF优化文件对比](/images/plugin/glTFHandler/compare.jpg) ![glTF优化文件对比](/images/plugin/glTFHandler/compare2.jpg) --- --- url: /guide/pnmbue0k/index.md --- # 场景配置 ::: demo-wrapper img no-padding ## 简要说明 场景配置用于设置项目与场景的基础信息与环境参数。 ## 工程信息 * **场景名称/分类/描述** * **版本号** * **项目类型**（Web3D / WebGIS） * **封面图**：支持一键截图生成 ## 场景配置 * **背景类型**：None / Color / Texture / Equirectangular * **背景参数**（Equirectangular）：模糊度、强度、旋转 * **环境贴图**：None / Equirectangular / ModelViewer * **网格**：显示/隐藏 * **辅助**：显示/隐藏（坐标轴、辅助线等） ## WebGIS 提示 * WebGIS 项目的地图源与初始视角在 **GIS地图源** 与 **GIS位置** 面板中配置 --- --- url: /guide/rf1xgf4z/index.md --- # BIM轻量化 ## 简要说明 通过编辑器的BIM轻量化功能，您可以将复杂的BIM工程文件（如`.rvt`）转换为轻量化的`.glTF`文件。\ 转换过程中保留了BIM构件的属性信息，同时对模型进行了压缩优化，方便在Web端进行高效解析与展示。 **主要亮点：** * 支持BIM文件的轻量化转换，优化模型大小。 * 保留构件属性，便于后续操作与分析。 * 界面设计与[CAD解析预览](/guide/u1631nwk/)类似，操作直观易用。 ## 功能说明 * **模型列表**：展示用户上传转换的所有BIM模型。 * **上传模型**：点击顶部==历史记录==右侧的==上传按钮==，会打开模型上传界面。 * **历史记录**：点击顶部==历史记录==按钮，会弹出历史上传记录列表。 ### 模型列表 * **功能描述**：展示用户上传并转换成功的所有BIM模型。 * **操作方式**：\ 如本页面首图，列表以网格形式展示；\ 从列表中直接==拖动==相应模型到中间的三维视口 或 ==双击==该模型，都可加载并渲染对应模型。 ### 上传模型 * **支持格式**：`.rvt、.rfa` * **转换方式**： * 文件会在上传后通过WebSocket发起轻量化转换请求。 * 转换结果通过WebSocket消息返回，并加载渲染展示。 * **转换配置**： * 极致轻量化：模型会在转换过程中执行==网格优化、材质贴图压缩并转换格式为WebP、网格实例化、网格合并==等模型优化操作，以确保输出的BIM轻量化模型是最小体积及最小渲染损耗的glTF模型。过程中可能执行的具体优化项可参考[glTF处理器](/guide/plugin/builtin/jo87cfk0/)章节； * 导出属性：生成的glTF模型中是否包含构件属性； * 转换视图：一个BIM文件中可能会包含多个3D视图，如果用户有确切的转换视图目标，可选择`按名称`并输入视图名称以转换；否则将自动以`默认3D视图`为目标转换； -视觉样式：此设置影响最终输出的模型材质。`着色`模式基本不包含任何材质贴图，以纯色材质方式输出；`真实`模式会包含用户建模时的材质贴图，输出材质更真实； * 坐标参考：一般情况下，一个BIM工程模型会由多工程师完成，便会存在多个单体BIM文件。此设置会决定最终输出模型与笛卡尔坐标系原点的相对位置信息。关于==原点、项目基点、测量点==的详细说明，可以参考这篇文章：[详解Revit坐标系](https://zhuanlan.zhihu.com/p/220113797) ### 历史记录 ::: demo-wrapper img no-padding ::: * **功能描述**：展示用户之前上传的所有BIM模型记录，方便快速查找和重新加载。 * **操作方式**：点击顶部==历史记录==按钮，弹出历史上传记录列表。 --- --- url: /guide/rzqb0h0l/index.md --- # 场景树 ## 简要说明 场景树是 Astral3D 编辑器中用于管理场景中所有对象的工具。它以树状结构展示场景中的层级关系，便于用户快速定位和操作对象。 ## 功能说明 * **节点搜索**：顶部搜索栏用于快速查找节点，模糊查询到的节点父级会自动展开，并在改节点下添加下划线。 * **层级管理**：通过拖拽操作，可以调整对象的父子关系。 * **对象选择**：点击场景树中的对象名称，可以在场景中选中对应的对象（不会自动聚焦）。 * **阵列对象**：右键菜单最上方提供`阵列`二级菜单，可快速创建`网格阵列`、`圆周阵列`、`随机阵列`。 * **聚焦对象**：右键菜单中提供聚焦选项，用以在视口中定位模型（更推荐使用快捷键，默认是`F`）。 * **删除对象**：右键菜单中提供删除选项，方便移除不需要的对象（更推荐使用快捷键，默认是`Del`）。 * **拷贝对象**：右键菜单中提供拷贝选项，方便快速复制对象（同[顶栏](/guide/f7smai4w/)基础操作区中的拷贝）。 ## 阵列菜单 * `阵列`菜单位于场景树右键菜单最上方。 * `默认相机`与`默认场景`节点不支持阵列。 * 阵列结果会生成新的阵列根节点，并插入到源对象同级、源对象之后。 * 阵列根节点命名规则为：`原名称_网格阵列`、`原名称_圆周阵列`、`原名称_随机阵列`。 ## 阵列类型 ### 网格阵列 * 适合按规则行列复制模型。 * 可配置：`行数`、`列数`、`行间隔`、`列间隔`、`起始位置`、`复制模式`。 ### 圆周阵列 * 适合沿圆周分布模型。 * 可配置：`数量`、`半径`、`起始角度`、`结束角度`、`旋转轴`、`旋转方式`、`中心位置`、`复制模式`。 ### 随机阵列 * 适合在指定空间范围内随机散布模型。 * 可配置：`数量`、`范围尺寸`、`中心位置`、`复制模式`。 ## 复制模式 * `无关联复制`：逐个复制对象，保留原有对象结构。 * `实例化网格复制`：将可实例化的普通 `Mesh` 转为 `InstancedMesh`，适合大量重复对象。 * `合并网格复制`：将阵列结果按普通 `Mesh` 合并输出，适合减少节点数量。 ## 使用说明 1. 在场景树中右键目标模型节点。 2. 选择`阵列`，再选择`网格阵列`、`圆周阵列`或`随机阵列`。 3. 在弹窗中填写配置项并确认。 4. 编辑器会生成新的阵列根节点，可继续进行选择、移动、删除、撤销和重做。 ## 注意事项 * `实例化网格复制`和`合并网格复制`仅支持由普通 `Mesh` 组成的模型对象。 * 遇到 `SkinnedMesh`、`InstancedMesh`、`BatchedMesh`、MorphTarget、线段、点、精灵、相机、灯光等对象时，会直接提示不支持。 * 对于多层级、多 `Mesh`、多材质模型，`实例化网格复制`与`合并网格复制`允许输出为一个阵列根节点下的多个结果子节点。 --- --- url: /guide/sekzh2c0/index.md --- # 设置中心 ::: demo-wrapper img no-padding ## 简要说明 设置中心用于管理编辑器与预览相关的通用配置。 ## 系统设置 当前暂无可用的系统设置项。 ## 预览设置 用于配置预览页中的漫游角色： * 提供多种角色模型选择 * 漫游开启时切换角色会自动刷新 ## 快捷键 用于设置常用操作的快捷键（单键绑定）： * **移动 / 旋转 / 缩放** * **撤销 / 重做**（`Ctrl/Meta + 键`，重做为 `Ctrl/Meta + Shift + 键`） * **聚焦**（选中对象聚焦到视图中心） --- --- url: /guide/siz46vj0/index.md --- # 粒子 ::: demo-wrapper img no-padding ## 简要说明 粒子面板用于配置粒子发射器与粒子行为，仅在选中粒子对象时显示。 ## 面板结构 粒子设置分为三大部分： * **Attributes**：发射器基础属性 * **Initializers**：粒子初始状态 * **Behaviours**：粒子生命周期行为 ## Attributes（发射器属性） 用于控制发射节奏与基础衰减： * **Total Emit Times**：总发射次数 * **Life**：发射器寿命 * **Damping**：阻尼（影响速度衰减） * **Rate（Num / Time）**：每次发射数量与发射间隔（范围设置） ## Initializers（初始化器） 用于定义粒子生成时的初始状态： **基础属性** * **Mass**：质量（关闭后，碰撞的 `useMass` 会自动关闭） * **Life**：粒子生命周期 * **Radius**：粒子尺寸范围 **位置与旋转** * **Position Zone**：初始生成区域\ 支持 `Point / Line / Box / Sphere` * **Rotation**：初始旋转与是否继承发射器旋转 **速度** * **Radial Velocity**：径向速度 * **Polar Velocity**：极坐标速度（角度以度为单位） * **Vector Velocity**：向量速度 ## Behaviours（行为） 用于控制粒子在生命周期内的变化与运动： **外观变化** * **Color / Alpha / Scale**：支持时间段与缓动 **动力学** * **Force**：持续外力 * **Rotate**：旋转行为 * **Random Drift**：随机漂移 * **Spring / Attraction**：弹簧与吸引 **交互** * **Collision**：碰撞行为（可选是否使用质量） ## 使用建议 * 先从 **Attributes** 设置发射节奏，再配置 **Initializers** 与 **Behaviours** * 参数修改为即时生效，建议逐步调节确认效果 * 粒子数量过大会影响性能，优先调整发射频率与生命周期 --- --- url: /guide/swepocsg/index.md --- # 界面 ::: demo-wrapper img no-padding ::: ::: tip 说明 整个编辑界面分为 `顶栏`,`左侧边栏`,`场景视口`,`扩展栏`,`右侧边栏` 五个区域 ::: ## 顶栏 用于基础操作与全局设置，包括保存、预览、主题与语言切换等。\ 详细说明见：[顶栏](/guide/f7smai4w/) ::: demo-wrapper img no-padding ## 左侧边栏 用于管理场景结构与辅助功能入口： * **场景树**：管理对象层级与选中状态 * **CAD 解析预览**、**BIM 轻量化**：专业模型辅助工具 ::: demo-wrapper img no-padding ## 场景视口 编辑器核心区域，包含 3D 视图与 2D 图纸视图。\ 常见操作如选择对象、视角漫游、拖拽资源等均在此完成。 ::: demo-wrapper img no-padding ## 扩展栏 可切换 **资源中心 / 动画编辑器 / 日志** 等功能面板。 ::: demo-wrapper img no-padding ## 右侧边栏 根据当前选中对象动态显示配置面板： * **场景配置 / 渲染器配置 / 后期处理 / 天气** * **对象 / 几何 / 材质 / 动画 / 脚本 / 数据组件** * **热力图 / 路径 / UI面板**（从资源中心拖入后可见） ::: demo-wrapper img no-padding ## 交互要点 * 选中对象后，右侧边栏会切换到对象相关面板 * 拖拽资源到视口可快速添加对象 * 常用快捷键可在“设置中心”中查看与配置 --- --- url: /guide/ta6draim/index.md --- # 场景图纸 ::: demo-wrapper img no-padding ## 简要说明 场景图纸用于上传并展示项目的 2D 图纸，便于对照建模或定位。 ## 上传 * 支持 **图片 / PDF** * 通过拖拽或点击上传 ## 删除 * 移除图纸会清空当前显示 ## 预览 上传后会在视口中与 3D 场景并排显示，方便对照编辑。 --- --- url: /guide/u1631nwk/index.md --- # CAD解析预览 ## 简要说明 通过编辑器的CAD解析预览功能，您可以轻松上传并查看多种格式的CAD图纸。 无论是`.dwg`还是`.dxf`，都能快速解析并在三维视口中直观展示。 这一功能不仅提升了图纸管理的效率，还为三维设计和协作提供了极大的便利。 **主要亮点：** * 支持多种图纸格式，满足不同需求。 * 即时解析与预览，操作简单高效。 * 历史记录功能，方便快速查找和重新加载。 让您的设计流程更加流畅，体验前所未有的便捷与高效！ ## 功能说明 * **图纸列表**：展示用户上传并解析成功的所有图纸。 * **上传图纸**：点击顶部==历史记录==右侧的==上传按钮==，会打开图纸上传界面。 * **历史记录**：点击顶部==历史记录==按钮，会弹出历史上传记录列表。 ### 图纸列表 * **功能描述**：展示用户上传并解析成功的所有图纸。 * **操作方式**：\ 如本页面首图，列表以网格形式展示；\ 从列表中直接==拖动==相应图纸到中间的三维视口 或 ==双击==该图纸，都可加载并渲染对应图纸。 ### 上传图纸 ::: demo-wrapper img no-padding ::: * **支持格式**：`.dwg、.dxf、.png、.jpg(jpeg)` * **解析方式**： * `.dwg`格式图纸由于无法在前端直接解析，会在上传后通过WebSocket发起图纸解析请求。 * 解析结果通过WebSocket消息返回，并加载渲染展示。 * 如果`.dwg`图纸中包含缩略图，会自动解析为封面图，在`图纸列表`中展示。 ### 历史记录 ::: demo-wrapper img no-padding ::: * **功能描述**：展示用户之前上传的所有图纸记录，方便快速查找和重新加载。 * **操作方式**：点击顶部==历史记录==按钮，弹出历史上传记录列表。 --- --- url: /guide/ui-panel/index.md --- # UI面板 ::: demo-wrapper img no-padding ## 简要说明 UI面板用于在 3D 场景中构建可布局的界面元素（Block / Text）。\ 选中 UI 面板节点后，右侧边栏显示对应的配置项。 ## 节点结构 常见节点类型： * **UIPanel**：根节点 * **UIPanelBlock**：容器节点 * **UIPanelText**：文本节点 * **Inline / InlineBlock**：内联节点（表现与 Text 类似） 当选中 **UIPanel / UIPanelBlock** 时，可新增子节点： * **Add Block** * **Add Text** ## Block 配置 用于布局容器与背景样式： **尺寸与间距** * **Width / Height**：尺寸 * **Padding / Margin**：内外边距 * **Offset**：Z 轴偏移，用于避免层叠闪烁 **背景与边框** * **Background Color / Opacity** * **Background Image**：支持 URL 与本地图片（<=3MB） * **Background Size**：Cover / Contain / Stretch * **Border Radius / Width / Color** * **Overflow Hidden**：隐藏溢出内容 **布局** * **Flex Direction** * **Justify Content** * **Align Items** **交互状态** * **Hover / Active**：启用后可配置状态样式\ Block 状态支持修改 **背景色 / 透明度** ## Text 配置 用于文字内容与排版： **文本与尺寸** * **Text**：文字内容 * **Width / Height**：可切换 `auto` 自动尺寸 **字体样式** * **Font Size / Color / Opacity** * **Font Supersampling**：字体抗锯齿 * **Letter Spacing / Line Height** **排版与布局** * **Padding / Margin / Offset** * **Text Align** * **White Space**：normal / pre-line / pre-wrap / pre / nowrap * **Break On**：断行分隔符定义 **交互状态** * **Hover / Active**：Text 状态支持修改 **文字颜色** ## 使用建议 * 先确定容器尺寸与布局，再调整字体与背景 * 文字节点建议使用 `auto` 尺寸配合内边距控制布局 * 状态样式仅定义外观，交互触发逻辑由运行时控制 --- --- url: /guide/v0m2jmb5/index.md --- # 数据中心 数据中心用于管理数据源、数据集分组与数据集，是编辑器数据组件的数据入口。数据集创建后，可在编辑器右侧栏绑定到模型，并通过手动刷新或自动刷新获取结果。 ## 数据源管理 用于配置数据库等连接信息，支持新增、编辑、删除与测试连接。 **字段说明** * **名称**：数据源名称，必填 * **类型**：`MySQL / SQLServer / PostgreSQL / Oracle / 达梦` * **连接串**：如 `jdbc:postgresql://127.0.0.1:5432/db`，必填 * **用户名/密码**：可选 **常见操作** * **测试连接**：使用当前表单配置进行连通性测试 * **删除**：逻辑删除，删除后从列表移除 ## 数据集分组 用于组织数据集的树状分类。 * **父组**：根节点为 `Root`，其 `id = 0` * **新增子分组**：默认以当前选中节点作为父组 * **删除**：如后端提示仍包含子节点或数据集，将提示无法删除 ## 数据集 用于定义数据获取方式与返回结构，支持 `API / SQL / JSON` 三种类型。 ### 通用字段 * **名称**：必填 * **分组**：选择数据集分组，必填 * **类型**：`API | SQL | JSON` ### API 数据集 API 数据集用于配置接口请求。前端只保存请求信息，实际请求由后端执行。 **基础字段** * **Method**：请求方法，如 `GET / POST / PUT / DELETE` * **API interface**：接口地址 * 绝对地址：如 `https://example.com/api/list`，按外部接口请求 * 相对地址：如 `/test/data-component/position` 或 `test/data-component/position`，表示当前后端服务内部接口 > 相对地址不要填写前端页面的域名或端口。后端会在服务内部调用对应接口，避免部署在非默认端口时误请求到 `80/443` 端口。 **请求配置** 请求配置分为 `Params / Body / Headers / Cookies`。 * **Params**：Query 参数，最终拼接到请求地址上 * **Headers**：请求头参数，不允许覆盖 `Host / Content-Length / Transfer-Encoding / Connection` * **Cookies**：Cookie 参数，执行时会合并为 `Cookie` 请求头 * **Body**：请求体，支持 `none / JSON / Text / XML / form-data / x-www-form-urlencoded` **参数值模式** 参数值支持固定值和占位参数两种模式。 * **固定值**：按当前输入内容作为请求值 * **占位参数**：只输入变量名，界面会自动补全为 `${变量名}` 示例： | 录入方式 | 保存含义 | | --- | --- | | 固定值 `100` | 请求值固定为 `100` | | 占位参数 `value` | 执行时从变量 `value` 读取，等价于 `${value}` | 占位参数变量名会进行前端即时校验。变量名必须以字母或下划线开头，可包含字母、数字、下划线、点和中划线。 **参数类型** 参数可声明为 `string / number / boolean / json`。类型用于运行时变量值转换，也用于编辑器数据组件侧边栏选择合适的参数录入控件。 ### API Body 配置 不同 Body 类型的录入方式如下： | Body 类型 | 录入方式 | 说明 | | --- | --- | --- | | `none` | 不录入 | 不发送请求体 | | `JSON` | JSON 编辑器 | 支持格式化录入和 JSON 结构内的占位参数 | | `Text` | 文本输入 | 支持占位参数 | | `XML` | XML 文本输入 | 支持占位参数 | | `form-data` | 参数表格 | 适合普通表单字段 | | `x-www-form-urlencoded` | 参数表格 | 适合表单编码字段 | 选择 `JSON` 时，应在 JSON 编辑器中录入合法 JSON。JSON 字符串节点中可以使用完整占位参数，例如： ```json { "name": "${name}", "count": "${count}", "enabled": "${enabled}", "extra": "${extra}" } ``` JSON 编辑器失焦后会解析其中的占位参数，并在下方生成变量表。可在变量表中设置变量类型与说明，确保编辑器侧边栏录入参数时能使用数字输入框、开关或 JSON 编辑器，而不是全部按字符串处理。 ### SQL 数据集 SQL 数据集用于执行数据源查询。 **字段说明** * **DataSource**：选择数据源 * **SQL**：查询语句，推荐仅使用 `SELECT / WITH` 开头 SQL 支持占位参数，写法与 API 一致： ```sql select * from device where name = ${name} and status = ${status} ``` SQL 占位参数会进行前端即时校验。执行时，编辑器数据组件侧边栏会展示对应参数，并在用户确认后传入后端执行。 ### JSON 数据集 JSON 数据集用于保存静态 JSON 内容。 * **JSON**：合法 JSON 字符串内容 * 适合调试、固定配置、静态点位或无需动态请求的数据 ### 执行与预览 数据集可在创建后进行执行或预览，返回结果将用于数据组件或调试展示。带占位参数的数据集需要在编辑器数据组件侧边栏录入参数值后再执行。 --- --- url: /guide/webgis-viewport/index.md --- # WebGIS场景 ::: demo-wrapper img no-padding ## 简要说明 WebGIS 场景视口用于地球尺度的三维浏览，支持 3D Tiles 与 2D Tiles 地图源叠加，并使用 WebGIS 专用后处理管线渲染大气与体积云。 ## 主要能力 * **地球尺度坐标**：默认使用 ECEF 坐标体系 * **地图源叠加**：支持多地图源同时显示（3D/2D） * **地球浏览控制**：基于 GlobeControls 的地球控制器 * **GIS 后处理**：大气、体积云、太阳光晕与通用后处理 ## 交互要点 * **缩放/旋转/平移**：围绕地表与地图源进行浏览 * **视角预设**：通过 “GIS 位置” 面板快速切换全球/区域/街景视角 * **对象拾取**：优先拾取场景对象，其次是地表位置 ## 注意事项 * 地球尺度场景坐标较大，精度敏感的模型需关注可见性与缩放 * WebGIS 场景强制使用后处理管线，渲染器的抗锯齿与色调映射配置无效 --- --- url: /guide/zdiy72f2/index.md --- # 项目结构(更新中) 本指南将向您说明 `Astral 3D` 项目的文件结构。 `Astral 3D`代码是以`Monorepo`的方式管理的，它的文件结构是这样的： ::: file-tree * .git/ * .idea/ * common # 通用代码包 * build/ # vite构建相关 * packages # 主项目包 * docs/ # Astral 3D 文档 * **editor/** # Astral 3D 编辑器 * **sdk/** # Astral 3D 引擎 * .gitignore * .npmrc * CONTRIBUTING.md * LEGAL.md * LICENSE * package.json * pnpm-lock.yaml * pnpm-workspace.yaml * README.en.md * README.md ::: --- --- url: /notes/authorization/index.md --- # 授权 ## 软件著作权 ## 说明 本页用于展示 Astral3D 的授权与著作权信息。如需商务授权或技术合作，请通过项目官方渠道联系。 --- --- url: /pricing/asdwfada/index.md --- # Astral 3D && Astral 3D Editor 商业授权协议 **版本：V1.0 | 生效日期：**\[2025/03/18] ## 一、产品简介 * `Astral 3D` 是一款面向企业级用户的专业Web3D引擎； * `Astral 3D Editor` 是一款面向企业级用户的基于`Astral 3D`的Web3D编辑平台； * 支持标准软件私有化部署和项目级定制服务； * 适用于智慧园区、智慧建筑、智慧工厂、智慧场站等行业的数字孪生可视化需求； * 可轻量化解析处理CAD(.dwg、.dxf)图纸及BIM(.rvt)模型,实现从数据到可视化的无缝衔接； * 支持`glTF、FBX、OBJ、IFC、STEP/STP、PLY、VTK、3DTiles(.b3dm、.i3dm...)`等30+主流三维数据格式，用户可快速导入并搭建逼真的三维场景。 ## 二、授权版本说明 ### 1. 开源社区版 * **授权范围**：\ ❌ 禁止未授权进行商业用途\ ❌ 禁止转售或分许可核心代码 * **核心权益**：\ ✅ **基础功能使用权**：完整使用开源版本功能模块\ ✅ **社区更新支持**：获取公开版本的功能迭代（GitHub同步） * **限制说明**：\ ❌ 不包含私有云部署\ ❌ 不包含专属功能定制 ❌ 技术支持服务（需单独购买） ### 2. 标准企业版（项目授权） * **授权范围**：针对特定项目的授权使用，无源码，禁止分许可或转售。 * **核心权益**：\ ✅ **全量功能使用权**：完整使用商用版本功能模块。\ ✅ **私有云部署**：提供本地化服务器部署支持。\ ✅ **功能更新服务**：一年内免费获取系统功能迭代版本。 * **不包含内容**：\ ❌ 专属功能定制\ ❌ BIM轻量化支持（需单独购买）\ ❌ 技术支持服务（需单独购买） ### 3. 高级定制版（项目授权） * **授权范围**：针对特定项目的授权使用，无源码，禁止分许可或转售。 * **核心权益**：\ ✅ **全量功能使用权**：完整使用商用版本功能模块。\ ✅ **私有云部署**：提供本地化服务器部署支持。\ ✅ **功能更新服务**：两年内免费获取系统功能迭代版本。\ ✅ **专属功能定制**：根据项目需求进行定制化开发，如界面定制、功能定制、系统集成等（需签署附加需求文档）。 * **不包含内容**：\ ❌ BIM轻量化支持（需单独购买）\ ❌ 技术支持服务（需单独购买） ### 4. 标准企业版源码孵化 * **授权范围**：用户可基于源码进行商业产品孵化，禁止分许可或转售。 * **核心权益**：\ ✅ 全量源码：完整获取商用版本全量源码 * **不包含内容**：\ ❌ BIM轻量化支持（需单独购买）\ ❌ 技术支持服务（需单独购买） ## 三、报价详情 |版本|开源社区版|标准企业版|高级定制版|标准企业版源码孵化| | ------| -------------| -------------| -------------| --------------------| |**基础授权费用**|¥10000|¥50,000|面议|¥110,000| |**技术支持年费**|¥12,000/年|¥12,000/年|¥12,000/年|¥12,000起/年| |**付款方式**|全款预付|全款预付|全款预付|全款预付| **说明**： 1. 技术支持需单独签约，按自然年计费，到期后未续费则服务终止。 2. 企业版源码买断不包含`BIM轻量化支持(仅支持Windows服务器)`,该功能需单独购买 ## 四、技术支持服务内容（不包含开源社区版） * **响应时效**：5×24小时服务，紧急问题2小时内响应（公休日不做技术支持）。 * **服务范围**：\ ✅ 系统部署与故障排查\ ✅ 版本升级与数据迁移\ ✅ 基础功能使用指导\ ❌ 定制功能二次开发（需另签开发合同） ## 五、服务承诺 1. **源码交付**：在合同签订后 `[7]` 个工作日内提供完整源码包。 2. **更新策略**：功能更新以季度为周期推送，重大漏洞72小时内修复。 3. **数据安全**：部署完成后彻底清除测试数据，不保留客户服务器访问权限。 ## 六、购买流程 1. **需求确认**：签署《需求确认书》并支付预付款。 2. **部署与培训**：完成系统部署并提供2天线上培训。 3. **尾款支付**：验收通过后 `[7]` 个工作日内付清余款。 ## 附录 ### 1. 术语解释 * **开源商用授权**：基于协议（Apache 2.0）及附加条款，禁止未授权进行商业用途，`[杭州星孪数字科技]`保留追诉权力。 * **BIM轻量化**：将大型BIM模型压缩至Web端可流畅加载的格式。 * **私有云部署**：将系统部署至客户自有服务器或指定云环境。 ### 2. 联系方式 * **商务咨询**：`[ErSan]` | 微信：`[mahaibing130802]` | 邮箱：`[mlt131220@163.com]` *** **注**： * 本协议最终解释权归 `[杭州星孪数字科技]` 所有，具体条款以正式合同为准。 --- --- url: /pricing/lluiy8xf/index.md --- # 附：保密协议(示例) **协议编号**：`[编号]` | **生效日期**：`[日期]` *** ## 协议双方 **披露方**（甲方）：\ `[公司全称]`\ 地址：`[详细地址]`\ 联系人：`[姓名]`，职务：`[职位]` **接收方**（乙方）：\ `[公司全称]`\ 地址：`[详细地址]`\ 联系人：`[姓名]`，职务：`[职位]` ## 一、定义 1. **保密信息**：指本协议生效期间，一方（披露方）以书面、口头、电子或其他形式向另一方（接收方）披露的、标注或可合理识别为机密的信息，包括但不限于：\ ✅ 技术资料（如源代码、算法、设计文档）\ ✅ 商业数据（客户名单、报价策略、未公开财务信息）\ ✅ 产品规划（研发路线图、未发布功能说明）\ ✅ 其他双方书面确认的保密内容（详见附录）。 2. **除外信息**：以下信息不视为保密信息： * 已公开或非因接收方过错而成为公知的信息； * 接收方在披露前已合法持有并能提供书面证明的信息； * 独立开发或从第三方合法获得的信息。 ## 二、保密义务 1. **接收方责任**： * 仅将保密信息用于 `[合作目的，如“评估Astral Web3D Editor技术集成可行性”]`； * 采取不低于自身商业秘密的保护措施（如加密存储、访问权限控制）； * 仅向必须知悉的雇员/关联方披露，并确保其遵守本协议。 2. **披露方责任**： * 对提供的保密信息的准确性不承担责任； * 有权要求返还或销毁保密信息（书面通知后10个工作日内）。 ## 三、保密期限 自本协议生效之日起 `[5]` 年，不因协议终止而失效。 ## 四、违约责任 1. 若接收方违反保密义务，披露方有权： * 要求立即停止侵权行为； * 索赔直接经济损失及合理维权费用（律师费、调查费等）； * 向监管机构举报或提起诉讼。 2. 违约金：最低不低于人民币 `[XX]` 万元或实际损失的 `[X]` 倍（以较高者为准）。 ## 五、其他条款 1. **知识产权**：保密信息的所有权及知识产权始终归披露方所有。 2. **法律适用**：本协议受 `[中国]` 法律管辖，争议提交 `[XX]` 仲裁委员会仲裁。 3. **协议修改**：需双方书面同意并签字盖章生效。 ## 签署页 **甲方（披露方）**：\ 公司名称（盖章）：\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\ 授权代表签字：\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\ 日期：\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ **乙方（接收方）**：\ 公司名称（盖章）：\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\ 授权代表签字：\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\ 日期：\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ *** ### 附录：保密信息清单（示例） 1. Astral 3D Editor 私有化部署技术文档（版本号：`[ ]`） 2. BIM轻量化模块核心算法说明（文件编号：`[ ]`） 3. `[其他可列明具体文件]` *** **注意事项**： 1. 本协议需双方加盖公章或合同专用章后生效； 2. 建议由法务团队审核后使用； 3. 涉密电子文件建议通过安全渠道传输（如加密邮件/企业网盘）。 --- --- url: /pricing/n9hbihaaaf/index.md --- # 功能列表 > 开源代码已包含绝大部分基础功能，商用版本会持续性进行功能迭代及技术支持 --- --- url: /pricing/zmm6gsu1/index.md --- # Astral3D Editor 技术需求表 ## 一、企业基本信息 | 字段 | 内容 |\ |----------------------|--------------------------|\ | 公司名称 | `[填写全称]` |\ | 联系人 | `[姓名/职位]` |\ | 联系电话 | `[手机/固话]` |\ | 所属行业 | `[如建筑/制造/教育等]` |\ | 预计用户规模 | `[如50人/200+人等]` | ## 二、项目背景与目标 1. **核心需求场景**（可多选）：\ ✅ 建筑可视化 ✅ 工业设计 ✅ 教育培训 ✅ 游戏开发 ✅ 其他：`______` 2. **需解决的关键问题**： * `[例：大型BIM模型加载卡顿/多团队协作效率低等]` 3. **期望交付周期**： * 需求确认后 `[ ]` 个月内完成部署 ## 三、功能需求清单 ### 1. 基础功能模块 | 功能模块 | 优先级（高/中/低） | 是否需定制开发 | 补充说明 |\ |----------------|---------------------|----------------|-------------------------|\ | 3D模型导入导出 | `[ ]` | `[ ]` | 支持格式：`[如stp/dgn]` |\ | 实时协作编辑 | `[ ]` | `[ ]` | 最大并发用户数：`[ ]` |\ | 渲染效果调整 | `[ ]` | `[ ]` | `[如材质/PBR/光照需求]` | ### 2. BIM轻量化支持（仅高级版） * **输入格式**：`[如Revit/IFC]` * **输出要求**：\ ✅ Web端加载（如glTF） ✅ 移动端适配 ✅ 模型分层压缩率 ≥ `[ ]%` ### 3. 定制功能需求 | 功能描述 | 开发优先级 | 验收标准（可量化指标） |\ |--------------------------|------------|-------------------------------|\ | `[例：AI自动生成构件]` | `[ ]` | 识别准确率 ≥95%，响应时间 <3s |\ | `[填写其他需求]` | `[ ]` | `[如支持100万+面片实时渲染]` | ## 四、技术要求 1. **性能指标**： * 单模型最大支持面片数：`[ ]` 万 * 多人协作延迟要求：`[ ]` ms以内 2. **兼容性要求**：\ ✅ Windows ✅ macOS ✅ 主流浏览器（Chrome/Safari） 3. **安全合规**：\ ✅ 等保二级 ✅ GDPR ✅ 数据加密传输 ## 五、部署环境 | 项目 | 内容 |\ |--------------------|----------------------------------------------------------------------|\ | 服务器类型 | `[如本地物理机/阿里云/华为云]` |\ | 操作系统 | `[如CentOS 7.6/Windows Server 2019]` |\ | 数据库 | `[如MySQL 8.0/MongoDB 5.0]` |\ | 网络带宽 | 内网：`[ ]` Gbps，外网访问：`[ ]` Mbps | ## 六、验收标准 1. **功能测试**： * 通过测试用例 `[ ]` 条，关键功能达标率100% 2. **性能测试**： * 渲染帧率 >= `[ ]` FPS（提供目标场景/模型） 3. **安全测试**： * 渗透测试报告无高危漏洞 ## 七、其他需求 * **培训要求**：\ ✅ 现场培训（`[ ]` 天） ✅ 提供操作视频 * **文档交付**：\ ✅ 系统管理员手册 ✅ API接口文档 ## 提交说明 1. 请将本表格发送至 `[mlt131220@163.com]` ，标题格式：`[公司名称]-技术需求表` 2. 我司将在 `3` 个工作日内提供评估报告与方案书 3. 技术咨询：`[微信: mahaibing130802]` **注**：标 `✅` 项可勾选，`[ ]` 为必填项，`[例：...]` 为填写提示，请替换为实际内容。 --- --- url: /promotion/index.md --- # 推广中心 :::important 作者的话 `Astral 3D` 是一款基于 `Three.js` 的完全开源且免费的三维引擎。 如果使用起来觉得还不错，欢迎通过 [Star](https://github.com/mlt131220/Astral3D) 支持。 它源于个人的兴趣与曾经的工作需求，我将会长期维护它。 如果它对你产生了帮助，那我也深感荣幸。 如果你想，可以捐助我。 一切都是自由的，愿大家，平安喜乐。 \==岁岁平，岁岁安，岁岁平安。== ::: | 支付宝 | 微信 | |:-------------------------------------------------------:|:----------------------------------------------------------:| | ![Alipay](/images/AliPay.png){width="300" height="300"} | ![WeChat](/images/WeChatPay.png){width="300" height="300"} | > 本页面为各种大网站的推广链接，在此处购买您将会受到一定的优惠，而我收到一部分提成 :fire: 4核8G 200兆服务器，仅需49元/月，[点击这里购买](https://www.rainyun.com/Astral3D_)\ :fire: 专属优惠码：Astral3D 2核2G 轻量应用服务器 ￥38.00/年\ 从此链接购买享 **==9折优惠==**！！ 云服务器、云数据库、COS、CDN、短信等云产品特惠热卖中 --- --- url: /questions/index.md --- # 常见问题 本文主要包含了Astral3D过程中可能会遇到的常见问题与解决方法。 如果您遇到任何问题，您可以先在以下内容中寻找是否有相关的问题和解决方法。 如果没有找到，您可以先通过 Github [Discussions](https://github.com/mlt131220/Astral3DEditor/discussions/new?category=q-a) 与我们讨论。 如果您确定某处确实存在问题，请在 Github [Open an issue](https://github.com/mlt131220/Astral3DEditor/issues/new), 在 Issue 中说明该问题的具体细节，我们会尽快解决。 ## XXXXXX？ XXXXXXXXXXXXXXXXXXX --- --- url: /questions/index.md --- # 常见问题 本文主要包含了Astral3D过程中可能会遇到的常见问题与解决方法。 如果您遇到任何问题，您可以先在以下内容中寻找是否有相关的问题和解决方法。 如果没有找到，您可以先通过 Github [Discussions](https://github.com/mlt131220/Astral3D/discussions/new?category=q-a) 与我们讨论。 如果您确定某处确实存在问题，请在 Github [Open an issue](https://github.com/mlt131220/Astral3D/issues/new), 在 Issue 中说明该问题的具体细节，我们会尽快解决。 ## XXXXXX？ XXXXXXXXXXXXXXXXXXX --- --- url: /sdk/index.md --- # Astral3D SDK `@astral3d/engine` 是 Astral3D 的核心引擎包，覆盖渲染、资源加载、对象管理、脚本事件、数据驱动等能力。SDK 文档已按功能拆分，便于快速检索。 ## 快速开始 ### 安装 ```bash pnpm add @astral3d/engine three ``` ### 最小示例 ```ts import { App, Viewer, Box } from "@astral3d/engine"; const viewer = new Viewer({ container: document.getElementById("app")!, edit: { enabled: true }, grid: { enabled: true }, request: { baseUrl: "/file/static/" }, }); App.addObject(Box()); ``` ## 文档目录 **核心类** * [App](./core/App.md) * [Viewer](./core/Viewer.md) * [ViewerWrapper](./core/ViewerWrapper.md) * [ViewerGIS](./core/ViewerGIS.md) * [Preview](./core/Preview.md) * [Loader](./core/Loader.md) * [Package](./core/Package.md) **模块** * [App 模块](./modules/AppModules.md) * [Viewer 模块](./modules/ViewerModules.md) * [ViewerGIS 模块](./modules/ViewerGISModules.md) **对象** * [基础对象](./objects/BasicObjects.md) * [扩展对象](./objects/ExtendedObjects.md) **工具** * [工具类](./tools/Tools.md) * [Roaming](./tools/Roaming.md) * [Measure](./tools/Measure.md) * [ClippedEdgesBox](./tools/ClippedEdgesBox.md) * [MiniMap](./tools/MiniMap.md) * [Export](./tools/Export.md) * [ModelExplode](./tools/ModelExplode.md) * [DataComponentManager](./tools/DataComponentManager.md) **数据绑定** * [DataBindingManager](./data-binding.md) **事件与信号** * [Viewer 事件](./events/ViewerEvents.md) * [Hooks 信号](./events/HooksSignals.md) **命令** * [Commands](./commands/Commands.md) * [对象类命令](./commands/ObjectCommands.md) * [几何类命令](./commands/GeometryCommands.md) * [材质类命令](./commands/MaterialCommands.md) * [场景类命令](./commands/SceneCommands.md) * [脚本类命令](./commands/ScriptCommands.md) **动画** * [Timeline / Animation](./animation/Timeline.md) **脚本** * [Script](./script/Script.md) **粒子** * [Particle / Particles](./particle/Particle.md) **Shader 材质** * [Shader Materials](./shader-materials.md) **常量** * [Constants](./constants/Constants.md) **工具函数** * [Utils](./utils/Utils.md) * [Common](./utils/Common.md) * [Scene](./utils/Scene.md) * [Handler](./utils/Handler.md) * [Request](./utils/Request.md) * [Signals](./utils/Signals.md) * [Log](./utils/Log.md) **DXF** * [DXF](./dxf/DXF.md) ## 使用建议 * SDK 中 `App` 为单例；`Viewer` 每个视口创建一个实例 * 编辑器场景推荐配合 `Hooks` 信号使用（如 `sceneGraphChanged`） * 复杂对象（Heatmap/Path/UIPanel）建议查看对应对象文档与 options 结构 * 类型定义集中在 `packages/sdk/types`，可用于类型提示与二次开发 --- --- url: /sdk/0kf3q4b8/index.md --- # App 模块 ## 概述 App 模块提供全局配置、项目配置、历史记录、资源管理、选择器、存储与 CSM 阴影等能力。 ## Config ### 构造函数 `new Config(storage: Storage)` * 入参：`storage` 本地存储实例 * 返回：`Config` 实例 ### 成员 * `config: IAppConfig.Config` 全局配置对象 ### 方法 * `setConfig(config: Record): void` 合并并持久化配置 * `syncStorage(): void` 与本地存储同步 * `getKey(key: string): any` 读取嵌套配置（`a.b.c`） * `setKey(key: string, value: unknown): void` 写入嵌套配置 * `getShortcutItem(key: string): string` 获取快捷键配置 * `setShortcutItem(key: string, value: any): Promise` 设置快捷键配置 * `clear(): void` 清空配置 ### IAppConfig.Config * `theme: 'os' | 'dark' | 'light'` * `mainColor: string` * `history: boolean` * `shortcuts: { translate; rotate; scale; undo; focus }` * `roamingCharacter: string` ## Project ### 构造函数 `new Project(app: App)` * 入参：`app` 全局 App 实例 * 返回：`Project` 实例 ### 成员 * `info: IAppProject.Info` 项目配置对象 ### 方法 * `getKey(key: string): any` 获取配置值（支持多层） * `setKey(key: string, value: unknown, executeAction = true): void` 设置配置并触发相关动作 * `setDrawingSrc(src: string): void` 设置图纸资源 * `setDrawingLayerVisible(layerName: string, visible: boolean): void` 设置图层显隐 * `setDrawingLayerAllVisible(visible: boolean): void` 批量设置图层显隐 * `resetDrawing(): void` 重置图纸配置 * `dispose(): void` 释放监听 ### IAppProject.Info 重点字段 * `renderer` 渲染器配置（fps/antialias/tonemapping/shadow） * `bvh` BVH 配置 * `csm` 级联阴影配置 * `effect` 后处理配置 * `weather` 天气配置 * `sceneInfo` 场景信息（id/name/type/version/zip 等） * `drawing` 图纸信息（imgSrc/layers/markList 等） ## History ### 构造函数 `new History()` ### 成员 * `undos: Command[]` 撤销栈 * `redos: Command[]` 重做栈 ### 方法 * `execute(cmd: Command, optionalName?: string): void` 执行命令并记录历史 * `undo(): Command | undefined` 撤销 * `redo(): Command | undefined` 重做 * `toJSON(): { undos: string[]; redos: string[] }` 序列化历史 * `fromJSON(json: any): void` 反序列化历史 * `clear(): void` 清空历史 * `goToState(id: number): void` 跳转历史状态 * `enableSerialization(id: number): void` 启用历史序列化 ## Resource ### 构造函数 `new Resource()` ### 方法 * `loadURLTexture(url: string | THREE.Texture, onload?, onerror?): THREE.Texture | void` 加载贴图 ## Selector ### 构造函数 `new Selector()` ### 方法 * `select(object: THREE.Object3D | null): void` 设置选中对象 * `deselect(): void` 取消选中 > Selector 内置 IFC 选中高亮与属性读取逻辑。 ## Storage ### 构造函数 `new Storage()` ### 方法 * `setModel/getModel/removeModel(key: string)` 模型存储 * `setOtherItem/getOtherItem/removeOtherItem(key: string)` 其他数据存储 * `setConfigItem/getConfigItem/removeConfigItem(key: string)` 配置存储 * `setPluginItem/getPluginItem/removePluginItem(key: string)` 插件存储 ## CSM ### 构造函数 `new CSM(options: IAppProject.CSM)` ### 成员 * `instance: CSM | null` three.js CSM 实例 * `enabled: boolean` 是否启用 ### 方法 * `reset(): void` 重置 CSM * `setupMaterial(material: THREE.Material): void` 注册材质 * `updateProperty(key: string, value: any): void` 更新属性并刷新 * `updateLightColor(color: string): void` * `updateLightIntensity(intensity: number): void` * `updateLightDirection(direction: 'x' | 'y' | 'z', value: number): void` * `updateFrustums(): void` * `update(): void` --- --- url: /sdk/0v3ah2k0/index.md --- # Common ## 常量 ### IS\_MAC * 类型：`boolean` * 说明：是否为 Mac 平台 ## 判断与对象 ### isNil `isNil(value): boolean` * 入参：`value` 任意值 * 出参：`boolean` * 说明：判断是否为 `null` 或 `undefined` ### isEmptyObject `isEmptyObject(obj): boolean` * 入参：`obj` 对象 * 出参：`boolean` * 说明：是否为空对象（无自有键值） ### deepAssign `deepAssign(target, source): void` * 入参： * `target` 目标对象 * `source` 源对象 * 出参：无 * 说明：深度合并对象（仅处理普通对象） ### deepEqual `deepEqual(a, b): boolean` * 入参：`a`/`b` 任意值 * 出参：`boolean` * 说明：深度比较 ### getNestedProperty `getNestedProperty(obj, path): any` * 入参： * `obj` 目标对象 * `path` 路径字符串（如 `a.b.c`） * 出参：`any` * 说明：按路径取值 ### escapeRegExp `escapeRegExp(str): string` * 入参：`str` 原始字符串 * 出参：转义后的字符串 * 说明：转义正则特殊字符 ## 性能 ### debounce `debounce(fn, wait): (...args) => void` * 入参： * `fn` 原函数 * `wait` 延迟时间（ms） * 出参：防抖后的函数 ### throttle `throttle(fn, wait): (...args) => void` * 入参： * `fn` 原函数 * `wait` 间隔时间（ms） * 出参：节流后的函数 ## 系统/单位 ### getOsTheme `getOsTheme(): "dark" | "light"` * 入参：无 * 出参：系统主题 ### remToPxNumber `remToPxNumber(rem: number): number` * 入参：`rem` 值 * 出参：像素值 ## 下载 ### downloadBlob `downloadBlob(blob, filename): void` * 入参： * `blob` 二进制数据 * `filename` 文件名 * 出参：无 ### saveArrayBuffer `saveArrayBuffer(buffer, filename): void` * 入参： * `buffer` 二进制数据 * `filename` 文件名 * 出参：无 ### saveString `saveString(text, filename): void` * 入参： * `text` 文本内容 * `filename` 文件名 * 出参：无 ## DOM ### createDivContainer `createDivContainer(): HTMLDivElement` * 入参：无 * 出参：`HTMLDivElement` * 说明：创建默认容器节点 --- --- url: /sdk/1p31iv1b/index.md --- # Viewer 模块 ## 概述 Viewer 模块封装了视口辅助、相机控制、后处理、天气、信号分发、粒子、拖拽、Tiles 管理、高斯泼溅管理等能力。 ## Helper ### 构造函数 `new Helper(viewer: Viewer, controls: CameraControls)` ### 成员 * `animating: boolean` 是否正在播放视角动画 ### 方法 * `init(): void` 初始化 Gizmo * `setConfig(): void` 应用主题与外观配置 * `update(): void` 更新 Gizmo 目标 * `render(): void` 渲染 Gizmo * `dispose(): void` 释放资源 ## CameraManage ### 构造函数 `new CameraManage(viewer: Viewer, controls: CameraControls)` ### 方法 * `setInteract(config: Partial): void` 更新相机控制参数 * `front()/rear()/left()/right()/top()/bottom(): Promise` 快速视角切换 ## CameraManageGIS ### 构造函数 `new CameraManageGIS(viewer: ViewerGIS)` ### 方法 * `getCurrentPosition(): GeoCoordinate` 获取当前相机地理坐标 * `getCurrentOrientation(): { heading; pitch }` 获取航向与俯仰角 * `setViewPosition(lon, lat, alt, heading?, pitch?): void` 设置视角 * `flyTo(options: FlyToOptions): Promise` 飞行到目标位置 * `flyToObject(object, options?): Promise` 聚焦到对象 * `focusEarth(): Promise` 全局视角 * `resetView(duration?): Promise` 重置到初始视角 ## Effect ### 构造函数 `new Effect(viewer: Viewer)` ### 成员 * `composer?: EffectComposer` 后处理合成器 * `outlinePass?: OutlinePass` 轮廓通道 * `enabled: boolean` 是否开启后处理（来自 Project 配置） * `needsContinuousRender: boolean` 是否需要持续渲染（含动画/时间驱动效果） ### 方法 * `createComposer(): void` 初始化后处理链 * `render(delta: number): void` 渲染后处理 * `clear(): void` 清空通道 * `dispose(): void` 释放资源 ### 支持的通道 `Outline / SMAA / UnrealBloom / Bokeh / Pixelate / TiltShift / Scanline / BrightnessContrast / ChromaticAberration / ColorDepth / Glitch / HueSaturation / LensDistortion / ShockWave / Vignette / ToneMapping` ## EffectGIS ### 构造函数 `new EffectGIS(viewer: ViewerGIS)` ### 说明 * WebGIS 强制使用后处理管线，没有 `enabled` 总开关 * Pass 顺序：RenderPass → NormalPass → 大气/体积云/Outline → LensFlare → 其他效果+ToneMapping → SMAA * Outline 在 WebGIS 中强制 `xRay=true`，边缘颜色统一 ### 关键成员 * `composer?: EffectComposer` 后处理合成器 * `outlinePass?: OutlineEffect` 选中高亮 ### 常用配置（App.project.effectGIS） * `SMAA / Antialiasing / ToneMapping` * `VolumetricClouds / Atmosphere` * `Outline / UnrealBloom / BrightnessContrast / ChromaticAberration / ColorDepth / HueSaturation / TiltShift / Scanline / Glitch / ShockWave / Vignette` ## Weather ### 构造函数 `new Weather(viewer: Viewer)` ### 方法 * `update(delta: number): boolean` 更新雨/雪/雾效果 * `dispose(): void` 释放资源 ## GISWeather ### 构造函数 `new GISWeather(viewer: ViewerGIS)` ### 说明 * WebGIS 天气支持基于高度的启用与淡出 * 配置复用 `App.project.weather`（fog/rain/snow） ## Signals ### 构造函数 `new Signals(viewer: Viewer)` ### 说明 * 监听并响应全局 `Hooks` 信号（如 `sceneGraphChanged`、`objectSelected`） * 内部会触发渲染更新、后处理刷新、相机更新等行为 ## ParticleSystem ### 构造函数 `new ParticleSystem(viewer: Viewer | Preview)` ### 成员 * `particlesGroup: THREE.Group` 粒子渲染组 * `needsUpdate: boolean` 是否需要更新 ### 方法 * `update(delta: number): void` 更新粒子系统 * `dispose(): void` 释放资源 ## Drag ### 构造函数 `new Drag(viewer: Viewer)` ### 成员 * `isDragging: boolean` 是否正在拖拽 ### 方法 * `setDragObjects(objects: THREE.Object3D[], type?: "eq" | "push" | "remove"): void` 设置拖拽物体 * `setMeasureInstance(measure: Measure): void` 关联测量模块 * `dispose(): void` 释放资源 ## AstralGlobalControls ### 说明 * 继承 GlobeControls，提供 CameraControls 兼容 API 子集 * 支持 `getTarget / getPosition / setTarget / setPosition / setLookAt` * 额外提供 pivot 锁定，便于围绕对象旋转 ## TilesManage ### 构造函数 `new TilesManage(viewer: Viewer | Preview | ViewerGIS)` ### 方法 * `addTiles(tiles: Tiles): Promise` 添加 3DTiles * `removeTiles(tiles: Tiles): void` 移除 3DTiles * `update(): boolean` 更新并返回是否需要渲染 * `resize(): void` 更新分辨率 * `getAllTileMesh(): THREE.Mesh[]` 获取当前 Tiles 所有 Mesh * `mergeMesh: Mesh | null` 获取合并后的静态 Mesh（用于 BVH/碰撞） * `dispose(): void` 释放资源 ## GaussianSplatManager ### 概述 3D 高斯泼溅管理器。负责内部渲染器生命周期管理、所有 `SplatMesh` 实例追踪与资源释放、LoD / Dyno 动态编辑参数调优，以及包围盒计算与缓存。 ### 构造函数 `new GaussianSplatManager(viewer: ViewerWrapper, options?: GaussianSplatOptions)` ### 成员 * `isInitialized: boolean` 内部渲染器是否已创建 * `splatCount: number` 当前管理的 SplatMesh 数量 ### 加载方法 * `loadFromUrl(url, filename?, options?): Promise` 从 URL 加载（支持 `.ply`/`.spz`/`.splat`/`.ksplat`/`.sog`/`.rad`） * `loadFromFile(file, filename, options?): Promise` 从 `File`/`Blob` 流式加载（适用于超大文件） * `loadFromBuffer(buffer, filename, options?): Promise` 从 `ArrayBuffer` 加载 * `reloadFromUrl(oldSplatMesh, newUrl, options?): Promise` 替换来源 URL 并重新加载（保留变换和名称） ### 管理方法 * `trackSplatMesh(splatMesh): void` 追踪实例并打上类型标识（`isSplat`/`type="GaussianSplat"`） * `removeSplatMesh(splatMesh): void` 移除并销毁指定 SplatMesh * `removeSplatMeshByUuid(uuid): void` 通过 uuid 移除 * `getAllSplatMeshes(): SplatMesh[]` 获取所有受管理的 SplatMesh * `getSplatMeshByUuid(uuid): SplatMesh | undefined` 通过 uuid 获取 * `rebuildRenderer(): void` 渲染引擎切换时重建内部渲染器 ### LoD 参数调优 * `setLodSplatScale(scale): void` 全局 LoD 泼溅数量缩放（`2.0` = 双倍细节） * `setBehindFoveate(foveate): void` 背后 foveation 缩放 * `setFoveation(fov0, fov, foveate): void` 固定 foveation 锥参数 * `setSplatMeshLodScale(splatMesh, scale): void` 单个 SplatMesh 的 LoD 缩放 ### Dyno 动态编辑 * `dynoPaint(splatMesh, indices, color, opacity?): void` 涂色（修改泼溅点颜色与不透明度） * `dynoRemove(splatMesh, indices): void` 删除泼溅点 * `dynoTransform(splatMesh, indices, matrix): void` 对泼溅点施加矩阵变换 ### 包围盒 * `static computeAndCacheBoundingBox(splatMesh): void` 计算并缓存本地空间包围盒 * `static getCachedBoundingBox(splatMesh): Box3 | null` 获取缓存的包围盒 * `static isSplatFormat(extension): boolean` 判断文件扩展名是否为 GS 格式 ### 帧更新 * `update(): boolean` 每帧调用，返回是否需要触发渲染（内含帧计数器收敛 + paged 持续渲染逻辑） ### 生命周期 * `dispose(): void` 销毁所有资源（SplatMesh、内部渲染器、signal 监听、定时器） ### LoadSplatOptions 结构 * `name?: string` 名称 * `lod?: boolean | number` 启用 LoD（默认 `true`） * `paged?: boolean` 分页流式加载（默认 `false`，`.rad` 建议 `true`） * `extSplats?: boolean` 扩展编码（默认 `false`） * `lodScale?: number` LoD 缩放因子（默认 `1.0`） * `onProgress?: (event) => void` 加载进度回调 * `onLoad?: (mesh) => void` 加载完成回调 * `addToScene?: boolean` 是否自动添加到场景（默认 `true`） --- --- url: /sdk/2i2zcpom/index.md --- # ClippedEdgesBox ## 概述 `ClippedEdgesBox` 提供模型局部剖切能力，基于裁剪平面与包围盒实现。 ## 构造函数 `new ClippedEdgesBox(viewer: Viewer)` * 入参：`viewer` 视口实例 * 出参：`ClippedEdgesBox` ## 成员 * `isOpen: boolean` 是否已开启剖切 * `sectionBox?: THREE.Box3` 当前剖切包围盒 * `lastSelected?: THREE.Object3D` 最近一次选中对象 ## 方法 * `open(): void` 开启剖切 * `close(): void` 关闭剖切并清理 * `reset(): void` 重置剖切状态 * `dispose(): void` 释放事件与资源 ## ClippedEdgesBoxGIS ### 概述 `ClippedEdgesBoxGIS` 是 WebGIS 场景专用的剖切盒，使用 ENU 局部坐标系替代固定的 X/Y/Z 轴，保证剖切盒与地表法向一致。 ### 构造函数 `new ClippedEdgesBoxGIS(viewer: ViewerGIS)` ### 说明 * 继承 `ClippedEdgesBox`，接口保持一致 * 根据目标对象中心建立 ENU 坐标系 * 剖切平面法向随地表法向动态调整 --- --- url: /sdk/2kb4bxlf/index.md --- # ModelExplode ## 概述 `ModelExplode` 用于计算并执行模型爆炸展开/还原。 ## 构造函数 `new ModelExplode()` * 入参：无 * 出参：`ModelExplode` ## 成员 * `meshExplodeData: Map>` 爆炸数据缓存 * `unrestoredModel: THREE.Object3D[]` 已爆炸未还原模型列表 ## 方法 * `computedExplodeData(model: THREE.Object3D): void` 计算爆炸数据 * `explodeModel(model: THREE.Object3D, scalar = 0.5): void` 执行爆炸 * `restore(): void` 还原模型 * `clear(): void` 清空缓存 --- --- url: /sdk/32a7smzm/index.md --- # DataBindingManager ## 概述 `DataBindingManager` 负责将数据写入模型绑定，并在需要时将数据驱动到模型属性上。数据绑定配置与数据存储在 `Object3D.dataComponent` 数组中。 ## 数据结构 ### DataComponentEntry ```ts interface DataComponentEntry { config?: DataComponentConfig; data?: unknown; } ``` ### DataComponentConfig ```ts interface DataComponentConfig { dataSetId?: unknown; filterEnabled?: boolean; filterBody?: string; autoRefreshEnabled?: boolean; autoRefreshInterval?: number; applyToModel?: boolean; transition?: number; // ms } ``` ### AstralDataFormat ```ts interface AstralDataFormat { position?: [number, number, number]; rotation?: [number, number, number]; scale?: [number, number, number]; material?: { color?: string; opacity?: number; transparent?: boolean; metalness?: number; roughness?: number; emissive?: string; emissiveIntensity?: number; }; visible?: boolean; animations?: Array<{ name: string; behavior: "play" | "pause" | "stop"; duration?: number; // 秒 }>; } ``` ## 方法 ### setConfig `DataBindingManager.setConfig(object, config, options?)` * 入参： * `object: THREE.Object3D` 目标对象 * `config: DataComponentConfig` 配置 * `options?: { index?: number }` 绑定索引（默认 0） * 返回：`DataComponentEntry` * 说明：写入 `object.dataComponent[index].config` ### setData `DataBindingManager.setData(object, data, options?)` * 入参： * `object: THREE.Object3D` * `data: unknown` 返回数据 * `options?: { index?: number; applyToModel?: boolean; transition?: number; onUpdate?: (object) => void }` * 返回：`{ changed: boolean; errors: string[] }` * 说明： * 总是写入 `object.dataComponent[index].data` * 若存在 Viewer，会触发 `bindDataChange` 事件 * 若 `applyToModel` 为真，则调用 `applyDataToObject` ### applyDataToObject `DataBindingManager.applyDataToObject(object, data, options?)` * 入参： * `object: THREE.Object3D` * `data: AstralDataFormat` * `options?: { transition?: number; onUpdate?: (object) => void }` * 返回：`{ changed: boolean; errors: string[] }` * 说明： * `transition` 单位 ms（为 0 时直接赋值） * `position/rotation/scale/material` 支持过渡 * `animations` 直接触发 `play/pause/stop`，不参与过渡 ## Viewer 事件 当 `setData` 且 `App.viewer` 存在时，会触发： ```ts viewer.addEventListener("bindDataChange", ({ object, data, config, index }) => { // 仅分发给对应模型 }); ``` ## 使用示例 ```ts import { DataBindingManager } from "@astral3d/engine"; const config = { dataSetId: 1, applyToModel: true, transition: 300 }; DataBindingManager.setConfig(mesh, config, { index: 0 }); DataBindingManager.setData(mesh, { position: [1, 2, 3], material: { color: "#ff00ff", opacity: 0.8 }, }); ``` --- --- url: /sdk/32v3r5vc/index.md --- # Viewer 事件 ## 概述 `Viewer` 继承自 `THREE.EventDispatcher`，使用 `addEventListener` 监听事件。 ```ts viewer.addEventListener("onPick", ({ object, intersect }) => { console.log(object.name); }); ``` ## 事件列表 * `loaded: {}` 场景加载完成 * `beforeAnimation: { delta: number }` 动画帧开始 * `afterAnimation: { delta: number; toBeRender: (_need: boolean) => void }` 动画帧结束 * `beforeRender: { delta: number }` 渲染前 * `afterRender: { delta: number }` 渲染后 * `beforeDestroy: {}` 销毁前 * `afterDestroy: {}` 销毁后 * `onPick: { intersect: THREE.Intersection; object: THREE.Object3D }` 单击拾取 * `onDoubleClick: { intersect: THREE.Intersection; object: THREE.Object3D }` 双击拾取 * `bindDataChange: { object: THREE.Object3D; data: unknown; config?: unknown; index?: number }` 数据绑定变更 * `onKeyDown: { event: KeyboardEvent }` * `onKeyUp: { event: KeyboardEvent }` * `onPointerDown: { event: PointerEvent }` * `onPointerUp: { event: PointerEvent }` * `onPointerMove: { event: PointerEvent }` * `onTouchStart: { event: TouchEvent }` * `onTouchEnd: { event: TouchEvent }` * `onSceneBackgroundChange: { backgroundType: "" | "Color" | "Texture" | "Equirectangular"; background: null | THREE.Color | THREE.Texture }` * `onSceneEnvironmentChange: { environmentType: "" | "Background" | "Equirectangular" | "ModelViewer"; environment: null | THREE.Texture }` ## 示例 ```ts viewer.addEventListener("bindDataChange", ({ object, data }) => { console.log("data change", object.uuid, data); }); ``` --- --- url: /sdk/46csf2od/index.md --- # 脚本类命令 ## 通用成员 * 继承 `Command` 的通用成员：`id/inMemory/updatable/type/name` * 命令内部会保存目标对象与必要的旧/新值用于撤销 ## AddScriptCommand ### 构造函数 `new AddScriptCommand(object: THREE.Object3D, script: ISceneScript)` * 入参： * `object` 目标对象 * `script` 脚本配置 * 出参：`AddScriptCommand` * 说明：向对象添加脚本 ## RemoveScriptCommand ### 构造函数 `new RemoveScriptCommand(object: THREE.Object3D, script: ISceneScript)` * 入参： * `object` 目标对象 * `script` 脚本配置 * 出参：`RemoveScriptCommand` * 说明：移除对象脚本 ## SetScriptValueCommand ### 构造函数 `new SetScriptValueCommand(object: THREE.Object3D, script: IScript.IStruct, attributeName: string, newValue: string)` * 入参： * `object` 目标对象 * `script` 脚本结构体 * `attributeName` 字段名 * `newValue` 新值 * 出参：`SetScriptValueCommand` * 说明：更新脚本字段 --- --- url: /sdk/4hbca399/index.md --- # Path 路径 ## 构造函数 `new Path(options?: Partial, material?: THREE.Material)` * 入参： * `options` 可选，路径配置 * `material` 可选，路径材质（不传则内部创建） * 出参：`Path` ## 成员 * `options: IPath.options` 当前配置 * `type: "Path"` 类型标识 * `isPath: true` 类型判断标记 ## 方法 * `updateOptions(options: Partial): void` 更新配置 * `setPoints(points: IPath.Point[]): void` 重设路径点 * `toJSON(meta?): any` 序列化 * `static fromJSON(json): Path` 反序列化 * `dispose(): void` 释放资源 ## 默认配置 * `getDefaultPathOptions(): IPath.options` ## options 结构（IPath.options） * `name: string` 名称 * `position: number[]` 本地坐标 * `mode: "path" | "tube"` 路径/管道 * `points: { x; y; z }[]` 路径点 * `closed: boolean` 是否闭合 * `cornerRadius: number` 转角半径 * `cornerSplit: number` 转角细分 * `up?: number[] | null` 上方向 * `path: { width; arrow; progress; side }` 路径模式参数 * `tube: { radius; radialSegments; progress; startRad }` 管道模式参数 * `flow: { enabled; speed; direction }` 流动贴图参数 * `material: { color; map; transparent; opacity; depthWrite; depthTest; side; repeat; offset; rotation }` 材质参数 --- --- url: /sdk/4k5lsm2a/index.md --- # ObjectArrayGenerator ## 概述 `ObjectArrayGenerator` 用于快速复制模型并按指定规则生成阵列结果，当前支持： * `网格阵列` * `圆周阵列` * `随机阵列` 阵列结果统一返回一个新的 `THREE.Group`，名称分别为： * `原名称_网格阵列` * `原名称_圆周阵列` * `原名称_随机阵列` ## 导出 ```ts import { ObjectArrayGenerator } from "@astral3d/engine"; ``` ## 复制模式 * `independent`：无关联复制，逐个深拷贝源对象。 * `instanced`：实例化网格复制，将普通 `Mesh` 转为 `InstancedMesh`。 * `merged`：合并网格复制，将阵列结果按普通 `Mesh` 合并输出。 ## createGridArray ```ts const group = ObjectArrayGenerator.createGridArray({ sourceObject, copyMode: "independent", rows: 3, columns: 4, rowSpacing: 2, columnSpacing: 3, startPosition: sourceObject, }); ``` ### 参数 * `sourceObject: THREE.Object3D` 源对象。 * `copyMode?: "independent" | "instanced" | "merged"` 复制模式。 * `rows: number` 行数。 * `columns: number` 列数。 * `rowSpacing: number` 行间隔。 * `columnSpacing: number` 列间隔。 * `startPosition?: THREE.Vector3 | THREE.Object3D | [number, number, number] | { x: number; y: number; z: number }` 起始位置。 ## createCircularArray ```ts const group = ObjectArrayGenerator.createCircularArray({ sourceObject, copyMode: "instanced", count: 8, radius: 12, startAngle: 0, endAngle: 360, axis: "y", rotationMode: "lookAtCenter", centerPosition: { x: 0, y: 0, z: 0 }, }); ``` ### 参数 * `sourceObject: THREE.Object3D` 源对象。 * `copyMode?: "independent" | "instanced" | "merged"` 复制模式。 * `count: number` 数量。 * `radius: number` 半径。 * `startAngle?: number` 起始角度，单位为度。 * `endAngle?: number` 结束角度，单位为度。 * `axis?: "x" | "y" | "z" | THREE.Vector3` 旋转轴。 * `rotationMode?: "none" | "lookAtCenter" | "tangent"` 旋转方式。 * `centerPosition?: THREE.Vector3 | THREE.Object3D | [number, number, number] | { x: number; y: number; z: number }` 中心位置。 ## createRandomArray ```ts const group = ObjectArrayGenerator.createRandomArray({ sourceObject, copyMode: "merged", count: 20, centerPosition: sourceObject, rangeSize: [20, 5, 20], }); ``` ### 参数 * `sourceObject: THREE.Object3D` 源对象。 * `copyMode?: "independent" | "instanced" | "merged"` 复制模式。 * `count: number` 数量。 * `centerPosition?: THREE.Vector3 | THREE.Object3D | [number, number, number] | { x: number; y: number; z: number }` 中心位置。 * `rangeSize: THREE.Vector3 | [number, number, number] | { x: number; y: number; z: number }` 范围尺寸。 ## 位置规则 * 传入 `THREE.Object3D` 时，若对象已在场景中，则使用对象当前位置。 * 传入的对象不在场景中且自身不是 `Scene` 时，会回退为 `Vector3(0, 0, 0)`。 * 传入 `THREE.Vector3`、数组或普通对象时，会转换为 `Vector3` 使用。 ## 返回结果 * 返回值类型为 `THREE.Group`。 * 返回结果会继承源对象的可见性、图层和部分 `userData`。 * 返回结果的 `userData.astralArray` 中会记录阵列类型、复制模式、数量和源对象 `uuid`。 ## 约束 * `instanced` 和 `merged` 仅支持由普通 `Mesh` 组成的模型对象。 * 不支持 `SkinnedMesh`、`InstancedMesh`、`BatchedMesh`、MorphTarget。 * 不支持 `Line`、`Points`、`Sprite`、`Camera`、`Light` 混入到阵列源对象中。 * 对于多层级、多 `Mesh`、多材质模型，允许输出为一个阵列根节点下的多个子结果节点。 ## 异常 `ObjectArrayGenerator` 在参数不合法或源对象不满足复制模式要求时会抛出 `ObjectArrayError`。 常见场景包括： * 行数、列数、数量不是有效数字。 * 数量小于 `1`。 * 旋转轴为空向量。 * 合并几何体时属性不兼容。 * 源对象包含不支持的对象类型。 --- --- url: /sdk/5113z5ht/index.md --- # MiniMap ## 概述 `MiniMap` 用于在视口中显示小地图视图，可跟随目标对象移动与朝向。 ## 构造函数 `new MiniMap(viewer: Viewer, options: IMiniMapOptions)` * 入参： * `viewer` 视口实例 * `options.mapSize` 小地图覆盖范围（世界单位） * `options.mapRenderSize` 渲染尺寸（像素） * `options.followTarget` 跟随对象 * `options.isShow` 初始是否显示 * 出参：`MiniMap` ## 成员 * `dom: HTMLDivElement` 容器节点 * `isShow: boolean` 是否显示 ## 方法 * `open(): void` 显示小地图 * `close(): void` 隐藏小地图 * `update(): void` 每帧更新 --- --- url: /sdk/5wvgufo7/index.md --- # Utils ## 概述 `Utils` 提供通用工具函数，包含对象/性能/DOM/场景/请求/日志等。 ## 目录 * [Common](./Common.md) * [Scene](./Scene.md) * [Handler](./Handler.md) * [Request](./Request.md) * [Signals](./Signals.md) * [Log](./Log.md) --- --- url: /sdk/6ssv17ho/index.md --- # 基础对象 ## 概述 基础对象是对 Three.js 常见几何体/光源/相机的快速创建封装。所有函数均无入参，返回一个已初始化的对象实例。 ## 使用方式 ```ts import { Box, Sphere, AmbientLight } from "@astral3d/engine"; const box = Box(); const light = AmbientLight(); ``` ## 几何/组 * `Group(): THREE.Group` 创建空组 * `Box(): THREE.Mesh` 立方体（1x1x1） * `Capsule(): THREE.Mesh` 胶囊 * `Circle(): THREE.Mesh` 圆形 * `Cylinder(): THREE.Mesh` 圆柱 * `Dodecahedron(): THREE.Mesh` 十二面体 * `Icosahedron(): THREE.Mesh` 二十面体 * `DoubleCone(): THREE.Mesh` 双锥 * `Octahedron(): THREE.Mesh` 八面体 * `Plane(): THREE.Mesh` 平面 * `Ring(): THREE.Mesh` 圆环 * `Sphere(): THREE.Mesh` 球体 * `Sprite(): THREE.Sprite` 精灵 * `Tetrahedron(): THREE.Mesh` 四面体 * `Torus(): THREE.Mesh` 圆环体 * `TorusKnot(): THREE.Mesh` 环面扭结 * `Tube(): THREE.Mesh` 管道 * `Teapot(): THREE.Mesh` 茶壶 > 默认材质：`MeshStandardMaterial`（Sprite 使用 `SpriteMaterial`）。 ## 光源 * `AmbientLight(): THREE.AmbientLight` * `DirectionalLight(): THREE.DirectionalLight` * `HemisphereLight(): THREE.HemisphereLight` * `PointLight(): THREE.PointLight` * `Spotlight(): THREE.SpotLight` ## 相机 * `OrthographicCamera(): THREE.OrthographicCamera` * `PerspectiveCamera(): THREE.PerspectiveCamera` --- --- url: /sdk/7t2afap1/index.md --- # Hooks 信号 ## 概述 SDK 使用 `signals` 实现全局事件总线。可通过 Hooks API 订阅/派发信号。 ## API * `useSignal()` 返回完整 Signal 操作集合 * `useAddSignal(name, listener, context?, priority?)` * `useAddOnceSignal(name, listener, context?, priority?)` * `useDispatchSignal(name, ...params)` * `useRemoveSignal(name, listener)` * `useSetSignalActive(name, active)` ## SignalsRegisterFn `SignalsRegisterFn(newSignals: string[])` 可在运行时注册新的信号。 ## 主要信号列表 ### App 相关 * `enterXR` * `offerXR` * `leaveXR` * `sceneCleared` * `transformModeChanged` * `snapChanged` * `spaceChanged` * `rendererCreated` * `rendererUpdated` * `rendererConfigUpdate` * `rendererDetectKTX2Support` * `sceneBackgroundChanged` * `sceneEnvironmentChanged` * `sceneFogSettingsChanged` * `sceneRainSettingsChanged` * `sceneSnowSettingsChanged` * `sceneGraphChanged` * `sceneRendered` * `sceneResize` * `cameraAdded` / `cameraRemoved` / `cameraChanged` / `cameraReset` * `geometryChanged` * `objectSelected` / `objectFocused` / `objectFocusByUuid` * `objectLocked` / `objectUnlocked` * `objectAdded` / `objectChanged` / `objectRemoved` * `materialAdded` / `materialChanged` / `materialRemoved` / `materialCurrentSlotChange` * `scriptAdded` / `scriptChanged` / `scriptRemoved` * `showGridChanged` * `historyChanged` * `viewportCameraChanged` * `viewportShadingChanged` * `intersectionsDetected` * `pathTracerUpdated` * `instantiateShaderMaterial` * `sceneLoadComplete` * `addLog` / `deleteLog` / `clearLogs` * `animationMixerUpdate` * `timelineTimeChanged` * `timelineRowChanged` ### Viewer 相关 * `viewerInitCompleted` * `pluginInstall` / `pluginUninstall` * `IFCPropertiesVisible` * `effectEnabledChange` * `effectPassConfigChange` * `effectGISPassConfigChange` * `particleBodyChanged` * `particleSystemAddEmitter` * `emitterAdd2ParticleSystem` ### 图纸相关 * `drawingMarkDone` * `cadViewerResize` ## 示例 ```ts import { useAddSignal, useDispatchSignal } from "@astral3d/engine"; useAddSignal("sceneGraphChanged", () => { console.log("scene updated"); }); useDispatchSignal("sceneGraphChanged"); ``` --- --- url: /sdk/7tcmi9bt/index.md --- # Export ## 概述 `Export` 用于导出当前选中对象或整个场景的常见格式文件。 ## 构造函数 `new Export()` * 入参：无 * 出参：`Export` ## 方法（对象） 以下方法默认导出 `App.selected`，若无选中对象则不执行。 * `exportObjectToJSON(): void` 导出 JSON * `exportObjectToGlb(): Promise` 导出 GLB * `exportObjectToGltf(): Promise` 导出 GLTF * `exportObjectToObj(): Promise` 导出 OBJ * `exportObjectToPly(): Promise` 导出 PLY * `exportObjectToPlyBinary(): Promise` 导出二进制 PLY * `exportObjectToStl(): Promise` 导出 STL * `exportObjectToStlBinary(): Promise` 导出二进制 STL * `exportObjectToUSDZ(): Promise` 导出 USDZ ## 方法（场景） 以下方法导出当前场景（剔除 `ignore` 对象）。 * `exportSceneToJSON(): void` 导出 JSON * `exportSceneToGlb(): Promise` 导出 GLB * `exportSceneToGltf(): Promise` 导出 GLTF * `exportSceneToObj(): Promise` 导出 OBJ * `exportSceneToPly(): Promise` 导出 PLY * `exportSceneToPlyBinary(): Promise` 导出二进制 PLY * `exportSceneToStl(): Promise` 导出 STL * `exportSceneToStlBinary(): Promise` 导出二进制 STL * `exportSceneToUSDZ(): Promise` 导出 USDZ --- --- url: /sdk/7txoheuk/index.md --- # Viewer ## 概述 `Viewer` 是视口渲染器，负责创建渲染器、相机控制、后处理、拾取、脚本事件分发等。一个页面可以创建多个 `Viewer` 实例。 > WebGIS 场景请使用 `ViewerGIS`，其使用地球尺度坐标与专用后处理管线。 ```ts import { Viewer } from "@astral3d/engine"; const viewer = new Viewer({ container: document.getElementById("app")!, edit: { enabled: true }, grid: { enabled: true }, request: { baseUrl: "/file/static/" }, }); ``` ## 构造函数 ### new Viewer(options: IViewerWrapperOptions) * 入参：`options` 视口配置 * 返回：`Viewer` 实例 ### IViewerWrapperOptions 关键字段 * `container?: HTMLElement` 挂载容器（不传则自动创建 div） * `hdr?: string` HDR 环境贴图 URL * `edit?: IViewerWrapperEdit` 编辑模式（gizmo/辅助线等） * `enableScript?: boolean` 是否启用脚本运行 * `request?: { baseUrl?: string }` 资源请求前缀 * `grid: IViewerWrapperGrid` 网格设置 * `control: IViewerWrapperControl` 相机控制参数 * `plugin?: { injectApi: Record }` 注入到插件的 API ## 成员 * `container: HTMLElement` 容器 * `options: IViewerWrapperOptions` 视口配置 * `renderer: THREE.WebGLRenderer` WebGL 渲染器 * `camera: THREE.PerspectiveCamera` 主相机（与 `App.camera` 同步） * `scene: THREE.Scene` 主场景（与 `App.scene` 同步） * `sceneHelpers: THREE.Scene` 辅助场景 * `grid?: THREE.Group` 网格对象 * `selectionBoxHelper: THREE.Box3Helper` 选中包围盒辅助 * `selectionBox: THREE.Box3` 选中包围盒（只读 getter） * `effect: Effect` 后处理管理器 * `pathtracer?: ViewerPathTracer` 光线追踪器（realistic 模式） * `raycaster: THREE.Raycaster` 拾取射线 * `modules: ViewerModules` 模块集合（Helper/Effect/Weather 等） * `css2DRenderer: CSS2DRenderer` 2D 标签渲染器 * `css3DRenderer: CSS3DRenderer` 3D DOM 渲染器 * `plugin: PluginManager` 插件系统 ## 访问器 * `get edit(): IViewerWrapperEdit` 获取编辑模式配置 * `set edit(config: IViewerWrapperEdit)` 设置编辑模式配置 * `get enableScript(): boolean` 是否启用脚本 * `set enableScript(enable: boolean)` 开/关脚本运行 ## 方法 ### 基础 * `createEngine(): THREE.WebGLRenderer` 创建默认渲染器 * `engineCreated(renderer: THREE.WebGLRenderer): void` 替换渲染器并重新绑定 * `initGrid(): void` 初始化/刷新网格 * `initModules(): ViewerModules` 初始化模块 * `loadEnv(setBg = true, onLoad?, onError?): void` 加载环境贴图并可选设为背景 ### 视口与交互 * `updateAspectRatio(): void` 更新所有相机宽高比 * `getIntersects(point: THREE.Vector2): THREE.Intersection[]` 计算拾取结果 * `render(delta?: number): void` 渲染一帧 * `animate(): void` 动画循环（内部调用） * `dispose(): void` 销毁并解绑事件 ### 事件触发辅助 * `onPointerDown(event: PointerEvent): void` * `onPointerUp(event: PointerEvent): void` * `onPointerMove(event: PointerEvent): void` * `onTouchStart(event: TouchEvent): void` * `onTouchEnd(event: TouchEvent): void` * `onDoubleClick(event: PointerEvent): void` ### 资源/功能封装 * `addParticle(emitter: Emitter, body: THREE.Sprite | THREE.Mesh, name?: string): void` 添加粒子 * `addTiles(tiles: Tiles, addMode?: "none" | "command" | "normal"): void` 添加 3DTiles * `removeTiles(tiles: Tiles): void` 移除 3DTiles * `getViewportImage(): Promise` 获取视口截图 ## 事件（ViewerEventMap） 可通过 `viewer.addEventListener` 监听。 * `loaded` 场景加载完成 * `beforeAnimation / afterAnimation` 动画循环前后 * `beforeRender / afterRender` 渲染前后 * `beforeDestroy / afterDestroy` 销毁前后 * `onPick / onDoubleClick` 拾取事件 * `bindDataChange` 数据绑定更新事件 * `onKeyDown / onKeyUp` 键盘事件 * `onPointerDown / onPointerUp / onPointerMove` 指针事件 * `onTouchStart / onTouchEnd` 触控事件 * `onSceneBackgroundChange / onSceneEnvironmentChange` 场景背景/环境变更 ## 示例 ```ts viewer.addEventListener("onPick", evt => { console.log(evt.object.name); }); viewer.addEventListener("bindDataChange", ({ object, data }) => { console.log(object.uuid, data); }); ``` --- --- url: /sdk/8hfk1lwp/index.md --- # Preview ## 概述 `Preview` 是资源预览器，用于在独立画布中预览模型、材质、纹理、看板、HDR、3DTiles 等资产。 ## 构造函数 ### new Preview(options: IPreviewSetting) * 入参：`options` 预览配置 * 返回：`Preview` 实例 ### IPreviewSetting 关键字段 * `container?: HTMLElement` 挂载容器 * `hdr?: string` HDR 环境贴图 * `request?: { baseUrl?: string }` 资源请求前缀 * `control: IViewerWrapperControl` 相机控制参数 ## 成员 * `container: HTMLElement` 容器 * `options: IPreviewSetting` 配置 * `renderer: THREE.WebGLRenderer` 渲染器 * `camera: THREE.PerspectiveCamera` 预览相机 * `scene: THREE.Scene` 预览场景 * `modules: PreviewerModules` 模块（controls/particleSystem/tilesManage） * `css3DRenderer: CSS3DRenderer` DOM 渲染器 ## 方法 * `loadEnv(options?): void` 加载 HDR 环境（可控制是否设置背景） * `load(fileOrUrl: string | File, type?: string): Promise` 预览指定资源 * `type` 支持：`Model | Material | Texture | Billboard | HDR | Tiles` * `clear(): void` 清空预览场景 * `render(): void` 渲染一帧 * `animate(): void` 动画循环（内部调用） * `dispose(): void` 销毁并解绑 * `addParticle(emitter, body, name?): ParticleEmitter` 添加粒子 * `addTiles(tiles: Tiles): Promise` 添加 3DTiles * `removeTiles(tiles: Tiles): void` 移除 3DTiles * `getViewportImage(): Promise` 获取截图 ## 事件 * `beforeRender` 渲染前 * `afterRender` 渲染后 ## 示例 ```ts import { Preview } from "@astral3d/engine"; const preview = new Preview({ container: document.getElementById("preview")!, control: { minAzimuthAngle: -Infinity, maxAzimuthAngle: Infinity, minDistance: 0.1, maxDistance: 500, maxPolarAngle: Math.PI, minPolarAngle: 0, maxZoom: 10, minZoom: 0.1, dollySpeed: 1, dollyToCursor: true, }, }); preview.load("/assets/model.glb", "Model"); ``` --- --- url: /sdk/8qn4x7zw/index.md --- # App ## 概述 `App` 是全局场景管理器（单例），负责场景/对象/材质/历史/资源等全局状态，并桥接信号系统。SDK 默认导出的是单例实例 `App`。 ```ts import App from "@astral3d/engine"; // 或 import { App } from "@astral3d/engine"; ``` ## 构造函数 ### new App() * 入参：无 * 返回：`App` 实例 * 说明：SDK 内部已创建单例 `App`，通常不需要手动 `new`。 ## 成员 * `scene: THREE.Scene` 默认场景 * `sceneHelpers: THREE.Scene` 辅助场景（辅助线/包围盒等） * `camera: THREE.PerspectiveCamera` 默认相机 * `viewportCamera: THREE.Camera` 当前视口相机 * `viewportShading: string` 当前视口渲染模式（如 `default`） * `geometries: Record` 场景几何缓存 * `materials: Record` 场景材质缓存 * `textures: Record` 场景贴图缓存 * `scripts: ISceneJson["scripts"]` 场景脚本集合 * `helpers: Record` 辅助对象集合（相机/灯光等） * `cameras: Record` 场景相机集合 * `selected: THREE.Object3D | null` 当前选中对象 * `locked: THREE.Object3D | null` 当前锁定对象 * `log: Logger` 日志对象 * `storage: Storage` 本地存储（IndexedDB） * `config: Config` 全局配置管理 * `project: Project` 项目配置管理 * `selector: Selector` 选中管理 * `history: History` 历史记录管理 * `resource: Resource` 资源加载封装 * `animationManager: AnimationManager` 动画管理 * `csm: CSM` 级联阴影管理 * `singleFrameTime: number` 渲染帧间隔（秒） * `viewer: Viewer | null` 当前绑定的 Viewer 实例 * `meshBVHService: MeshBVHService` BVH 服务 ## 方法 ### 渲染与配置 * `get FPS(): number` 获取渲染帧率上限 * `set FPS(fps: number)` 设置渲染帧率上限 * `setConfig(config: Record): void` 设置初始全局配置 ### 场景与对象 * `setScene(scene: THREE.Scene): THREE.Scene` 将传入场景复制到 `App.scene` * `addObject(object: THREE.Object3D, parent?: THREE.Object3D, index?: number): void` 添加对象到场景或指定父级 * `moveObject(object: THREE.Object3D, parent: THREE.Object3D, before: THREE.Object3D): void` 移动对象层级与顺序 * `nameObject(object: THREE.Object3D, name: string): void` 设置对象名称 * `removeObject(object: THREE.Object3D): void` 从场景移除对象 * `getObjectByUuid(uuid: string): THREE.Object3D | undefined` 按 UUID 查找对象 * `traverseMeshToArr(object: THREE.Object3D): THREE.Mesh[]` 获取对象树下所有 Mesh * `getSceneWithoutIgnore(): THREE.Scene` 复制场景且剔除 `ignore` 对象 ### 几何/材质/贴图 * `addGeometry(geometry: THREE.BufferGeometry): void` 注册几何 * `setGeometryName(geometry: THREE.BufferGeometry, name: string): void` 设置几何名称 * `addMaterial(material: THREE.Material | THREE.Material[]): void` 注册材质 * `removeMaterial(material: THREE.Material | THREE.Material[]): void` 移除材质引用 * `getMaterialByUuid(uuid: string): THREE.Material | undefined` 按 UUID 获取材质 * `setMaterialName(material: THREE.Material, name: string): void` 设置材质名称 * `addTexture(texture: THREE.Texture): void` 注册贴图 * `getObjectMaterial(object: THREE.Object3D, slot: number): THREE.Material` 获取对象材质或多材质 slot * `setObjectMaterial(object: THREE.Object3D, slot: number | undefined, newMaterial: THREE.Material): void` 设置对象材质 * `createPBRMaterial(textures?: Record, properties?: any): Promise` 创建 PBR 材质 ### 相机/视口 * `addCamera(camera: THREE.Camera): void` 注册相机 * `removeCamera(camera: THREE.Camera | THREE.Object3D): void` 移除相机 * `setViewportCamera(uuid: string): void` 切换视口相机 * `setViewportShading(value: string): void` 设置视口渲染模式 ### 选择/焦点/锁定 * `select(object: THREE.Object3D): void` 选中对象 * `selectById(id: number): void` 按 id 选中对象 * `selectByUuid(uuid: string): void` 按 uuid 选中对象 * `deselect(): void` 取消选中 * `lock(object?: THREE.Object3D | null): void` 锁定对象 * `unlock(): void` 解锁对象 * `focus(object: THREE.Object3D): void` 聚焦对象 * `focusById(id: number): void` 按 id 聚焦 * `focusByUuid(uuid: string): void` 按 uuid 聚焦 ### 脚本 * `addScript(object: THREE.Object3D, script: ISceneScript): void` 绑定脚本 * `removeScript(object: THREE.Object3D, script: ISceneScript): void` 移除脚本 ### 序列化 * `fromJSON(sceneJson: ISceneJson): Promise` 从 JSON 还原场景 * `toJSON(): ISceneJson` 导出场景 JSON ### 历史 * `execute(cmd: Command, optionalName?: string): void` 执行命令并记录历史 * `undo(): void` 撤销 * `redo(): void` 重做 ## 使用示例 ```ts import App from "@astral3d/engine"; import * as THREE from "three"; const box = new THREE.Mesh( new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: "#ffcc00" }) ); App.addObject(box); App.select(box); App.focus(box); ``` --- --- url: /sdk/aujyuftp/index.md --- # Handler ## zip `zip(data, needEncode = true): string` * 入参： * `data` 原始字符串 * `needEncode` 是否进行 base64 编码 * 出参：压缩后的字符串 ## unzip `unzip(b64Data, needDecode = true): string` * 入参： * `b64Data` 压缩字符串 * `needDecode` 是否进行 base64 解码 * 出参：解压后的字符串 --- --- url: /sdk/ax3pf1w8/index.md --- # 材质类命令 ## 通用成员 * 继承 `Command` 的通用成员：`id/inMemory/updatable/type/name` * 命令内部会保存目标对象与必要的旧/新值用于撤销 ## SetMaterialCommand ### 构造函数 `new SetMaterialCommand(object: THREE.Object3D, newMaterial: THREE.Material, materialSlot?: number)` * 入参： * `object` 目标对象 * `newMaterial` 新材质 * `materialSlot` 多材质槽位（可选） * 出参：`SetMaterialCommand` * 说明：替换材质 ## SetMaterialColorCommand ### 构造函数 `new SetMaterialColorCommand(object: THREE.Object3D, attributeName: string, newValue: any, materialSlot?: number)` * 入参： * `object` 目标对象 * `attributeName` 材质颜色字段（如 `color`） * `newValue` 新颜色值 * `materialSlot` 多材质槽位（可选） * 出参：`SetMaterialColorCommand` * 说明：更新材质颜色 ## SetMaterialMapCommand ### 构造函数 `new SetMaterialMapCommand(object: THREE.Object3D, mapName: string, newMap: THREE.Texture | null, materialSlot?: number)` * 入参： * `object` 目标对象 * `mapName` 贴图字段名（如 `map`/`normalMap`） * `newMap` 新贴图 * `materialSlot` 多材质槽位（可选） * 出参：`SetMaterialMapCommand` * 说明：更新材质贴图 ## SetMaterialRangeCommand ### 构造函数 `new SetMaterialRangeCommand(object: THREE.Object3D, attributeName: string, newMinValue: number, newMaxValue: number, materialSlot?: number)` * 入参： * `object` 目标对象 * `attributeName` 范围字段名 * `newMinValue` 新最小值 * `newMaxValue` 新最大值 * `materialSlot` 多材质槽位（可选） * 出参：`SetMaterialRangeCommand` * 说明：更新范围类属性 ## SetMaterialValueCommand ### 构造函数 `new SetMaterialValueCommand(object: THREE.Object3D, attributeName: string, newValue: any, materialSlot?: number)` * 入参： * `object` 目标对象 * `attributeName` 数值字段名 * `newValue` 新值 * `materialSlot` 多材质槽位（可选） * 出参：`SetMaterialValueCommand` * 说明：更新材质数值属性 ## SetMaterialVectorCommand ### 构造函数 `new SetMaterialVectorCommand(object: THREE.Object3D, attributeName: string, newValue: THREE.Vector2 | THREE.Vector3 | THREE.Vector4, materialSlot?: number)` * 入参： * `object` 目标对象 * `attributeName` 向量字段名 * `newValue` 新向量值 * `materialSlot` 多材质槽位（可选） * 出参：`SetMaterialVectorCommand` * 说明：更新材质向量属性 --- --- url: /sdk/d569pjdk/index.md --- # 对象类命令 ## 通用成员 * 继承 `Command` 的通用成员：`id/inMemory/updatable/type/name` * 命令内部会保存目标对象与必要的旧/新值用于撤销 ## AddObjectCommand ### 构造函数 `new AddObjectCommand(object: THREE.Object3D, parent?: THREE.Object3D | null, index?: number)` * 入参： * `object` 要添加的对象 * `parent` 父级对象，默认加入场景根 * `index` 插入位置（可选） * 出参：`AddObjectCommand` * 说明：将对象加入场景或指定父级 ## RemoveObjectCommand ### 构造函数 `new RemoveObjectCommand(object: THREE.Object3D)` * 入参：`object` 要移除的对象 * 出参：`RemoveObjectCommand` * 说明：从场景移除对象 ## MoveObjectCommand ### 构造函数 `new MoveObjectCommand(object: THREE.Object3D, newParent: THREE.Object3D, newBefore: THREE.Object3D)` * 入参： * `object` 目标对象 * `newParent` 新父级 * `newBefore` 新的顺序参考对象 * 出参：`MoveObjectCommand` * 说明：调整对象层级与顺序 ## SetPositionCommand ### 构造函数 `new SetPositionCommand(object: THREE.Object3D, newValue: THREE.Vector3, optionalOldValue?: THREE.Vector3)` * 入参： * `object` 目标对象 * `newValue` 新位置 * `optionalOldValue` 旧位置（可选） * 出参：`SetPositionCommand` * 说明：更新对象位置 ## SetRotationCommand ### 构造函数 `new SetRotationCommand(object: THREE.Object3D, newValue: THREE.Euler, optionalOldValue?: THREE.Euler)` * 入参： * `object` 目标对象 * `newValue` 新旋转（欧拉角） * `optionalOldValue` 旧旋转（可选） * 出参：`SetRotationCommand` * 说明：更新对象旋转 ## SetScaleCommand ### 构造函数 `new SetScaleCommand(object: THREE.Object3D, newValue: THREE.Vector3, optionalOldValue?: THREE.Vector3)` * 入参： * `object` 目标对象 * `newValue` 新缩放 * `optionalOldValue` 旧缩放（可选） * 出参：`SetScaleCommand` * 说明：更新对象缩放 ## SetUuidCommand ### 构造函数 `new SetUuidCommand(object: THREE.Object3D, newValue: string)` * 入参： * `object` 目标对象 * `newValue` 新 UUID * 出参：`SetUuidCommand` * 说明：重置对象 UUID ## SetValueCommand ### 构造函数 `new SetValueCommand(object: THREE.Object3D, attributeName: string, newValue: any)` * 入参： * `object` 目标对象 * `attributeName` 属性名 * `newValue` 新值 * 出参：`SetValueCommand` * 说明：更新对象任意字段 ## SetColorCommand ### 构造函数 `new SetColorCommand(object: THREE.Object3D, attributeName: string, newValue: any)` * 入参： * `object` 目标对象（需包含 `Color` 属性） * `attributeName` 颜色字段名 * `newValue` 颜色值（CSS 字符串/十六进制） * 出参：`SetColorCommand` * 说明：更新颜色类字段 --- --- url: /sdk/data-component-manager/index.md --- # DataComponentManager ## 概述 `DataComponentManager` 用于管理场景中 `Object3D.dataComponent` 的数据驱动刷新，负责数据集轮询/去重/任务调度，并调用 `DataBindingManager` 将数据应用到模型。 ## 初始化与依赖 * `ViewerWrapper` 会自动创建 `dataComponentManager` * 若在 `IViewerWrapperRequest` 中提供 `dataSetExecute`，会在构造时自动 `init` * 也可以在运行时通过 `setApi` 注入数据集请求函数 ## 关键方法 * `init(api?)` 初始化并注册信号监听 * `setApi(api)` 设置数据集请求接口 * `refreshObject(object, index = 0)` 手动刷新指定对象的 dataComponent * `dispose()` 释放资源与监听 ## 数据流 1. 读取 `Object3D.dataComponent[index].config` 2. 根据 `dataSetId` 请求数据集 3. 可选执行 `filterBody` 过滤逻辑 4. 调用 `DataBindingManager.setData`，触发 `bindDataChange` ## 示例 ```ts import { Viewer } from "@astral3d/engine"; const viewer = new Viewer({ container: document.getElementById("app")! }); viewer.dataComponentManager.setApi(async (dataSetId) => { return { data: await fetchData(dataSetId) }; }); // 手动刷新 viewer.dataComponentManager.refreshObject(mesh); ``` --- --- url: /sdk/de0bcc8l/index.md --- # Loader ## 概述 `Loader` 是资源加载器（单例），支持 glTF/FBX/OBJ/STL/IFC/STEP/PLY/PCD/GLB 等多种格式，同时封装贴图加载与场景 JSON 解析。 ```ts import Loader from "@astral3d/engine/lib/core/loader/Loader"; // 或 import { Loader } from "@astral3d/engine"; ``` ## 构造函数 ### new Loader() * 入参：无 * 返回：`Loader` 实例（SDK 默认导出单例） ## 主要成员 * `objectLoader: ObjectLoader` Three.js ObjectLoader（懒加载） * `dracoLoader: DRACOLoader` Draco 解码器（懒加载） * `ktx2Loader: EnhancedKTX2Loader` KTX2 解码器（懒加载） * `hdrLoader: HDRLoader` HDR 贴图加载 * `tgaLoader: TGALoader` TGA 贴图加载 * `exrLoader: EXRLoader` EXR 贴图加载 * `stepLoader: STEPLoader` STEP/IGES 解析 ## 方法 * `loadItemList(items: DataTransferItemList): Promise` 解析拖拽文件列表 * `loadFiles(files: File[], filesMap?: Record): Promise` 批量加载 * `loadFile(file: File, manager?: THREE.LoadingManager, addToScene = true): Promise` 加载单个文件 * `handleJSON(data: any, addToScene = true): Promise` 解析 JSON/Scene * `handleZIP(contents: ArrayBuffer, addToScene = true): Promise` 解析 zip 包 * `createGLTFLoader(manager?: THREE.LoadingManager): Promise` 创建 glTF Loader * `disposeGLTFLoaderEffects(loader: GLTFLoader): void` 清理 glTF Loader 资源 * `loadUrlTexture(extension: string, url: string, onload?, onerror?): THREE.Texture` 加载贴图（支持 hdr/tga/exr/常规） ## 支持的模型格式（loadFile） * `glb / gltf` * `fbx / obj / mtl` * `stl / ply / pcd / vtk / vtp / xyz` * `3dm / 3ds / 3mf / amf / dae / usdz / wrl / vox / md2` * `svg / drc` * `ifc / step / stp / iges / igs` * `json / js`（scene/object） * `zip`（内含 gltf/glb/fbx 等） ## 使用示例 ```ts import Loader from "@astral3d/engine"; const file = input.files?.[0]; if (file) { const object = await Loader.loadFile(file); console.log(object.name); } ``` --- --- url: /sdk/dg9ylawh/index.md --- # 扩展对象 ## 概述 扩展对象包含广告牌、热力图、路径、UI 面板、粒子发射器、3DTiles、高斯泼溅等高级组件，均继承自 Three.js 对象并支持序列化。 ## 对象列表 | 对象 | 类型标识 | 说明 | | ------------------------------------------------------------ | -------------------------- | ------------------------------- | | [Billboard 广告牌](/sdk/objects/billboard/) | `Billboard` | 场景中展示图片或文字信息 | | [HtmlPanel / HtmlSprite](/sdk/objects/html-panel/) | `HtmlPanel` / `HtmlSprite` | CSS3D 网页面板 | | [Heatmap 热力图](/sdk/objects/heatmap/) | `Heatmap` | 平面/高度模式热力图 | | [UIPanel 面板](/sdk/objects/ui-panel/) | `UIPanel` | 3D 空间 UI 面板（支持交互状态） | | [Path 路径](/sdk/objects/path/) | `Path` | 路径/管道（支持流动贴图） | | [ParticleEmitter 粒子发射器](/sdk/objects/particle-emitter/) | `Particle` | GPU 粒子发射器 | | [Tiles 3DTiles](/sdk/objects/tiles/) | `TilesGroup` | OGC 3D Tiles 模型 | | [GaussianSplat 高斯泼溅](/sdk/objects/gaussian-splat/) | `GaussianSplatGroup` | 3D 高斯泼溅（3DGS）模型 | --- --- url: /sdk/ds7pteqi/index.md --- # Script ## 概述 脚本模块为运行时脚本提供辅助 API。 ## Helper ### 构造函数 `new Helper(scene: THREE.Scene)` ### 方法 * `objectByUuid(uuid: string): THREE.Object3D | undefined` 按 uuid 获取对象 * `moveObject(object: THREE.Object3D, parent: THREE.Object3D, before: THREE.Object3D): void` 移动对象层级 * `removeObject(object: THREE.Object3D): void` 移除对象 ## Animation ### 构造函数 `new Animation(object: THREE.Object3D)` ### 成员 * `actions: THREE.AnimationAction[]` 动作集合 * `repetitions: number` 重复次数（默认 Infinity） ### 方法 * `getAction(name: string): THREE.AnimationAction | undefined` 获取动画 Action * `play(name: string, loop?, timeScale?): this` 播放 * `pause(name?: string): this` 暂停 * `stop(name?: string): this` 停止 ## Source `Source` 为脚本模板字符串，可用于初始化脚本内容。 ```ts import { Script } from "@astral3d/engine"; console.log(Script.Source); ``` --- --- url: /sdk/e5ti9k7d/index.md --- # ParticleEmitter 粒子发射器 ## 构造函数 `new ParticleEmitter(emitter: Particle.Emitter)` * 入参：`emitter` 发射器配置 * 出参：`ParticleEmitter` ## 成员 * `emitter: Particle.Emitter` 发射器实例 * `type: "Particle"` 类型标识 * `isEmitterProxy: true` 代理标记 ## 方法 * `getEmitterJSON(): IParticle.Config` 获取发射器配置 * `toJSON(meta?): any` 序列化 * `static fromJSON(json: IParticle.Object3DJSON): ParticleEmitter` 反序列化 * `dispose(): void` ## 默认配置 * `getDefaultParticleConfig(): IParticle.Config` --- --- url: /sdk/eaqrsj75/index.md --- # Commands ## 概述 `Command` 用于历史记录（Undo/Redo）。通过 `App.execute(new Command())` 执行并记录。 ```ts import { App, SetPositionCommand } from "@astral3d/engine"; App.execute(new SetPositionCommand(mesh, mesh.position.clone().set(1, 0, 0))); ``` ## 基类 Command ### 构造函数 `new Command()` * 入参：无 * 出参：`Command` ### 成员 * `id: number` 命令编号 * `inMemory: boolean` 是否驻留内存 * `updatable: boolean` 是否可合并更新 * `type: string` 命令类型 * `name: string` 命令名称 ### 方法 * `toJSON(): any` 序列化 * `fromJSON(json: any): void` 反序列化 ## 分类索引 * [对象类命令](./ObjectCommands.md) * [几何类命令](./GeometryCommands.md) * [材质类命令](./MaterialCommands.md) * [场景类命令](./SceneCommands.md) * [脚本类命令](./ScriptCommands.md) --- --- url: /sdk/gousyib8/index.md --- # Log ## ILog ```ts interface ILog { id: number; message: string; time: string; level: string; } ``` ## logger `logger` 为全局日志实例，提供日志写入与事件联动。 ### 成员 * `enabled: boolean` 是否启用日志 * `logs: ILog[]` 日志列表 ### 方法 * `trace(message: string): void` * `debug(message: string): void` * `info(message: string): void` * `warn(message: string): void` * `error(message: string): void` * `delLog(log: ILog): void` 删除日志 * `clearLogs(): void` 清空日志 * `dispose(): void` 移除监听 --- --- url: /sdk/guvrim38/index.md --- # Shader Materials ## 概述 SDK 内置一组 ShaderMaterial 封装，提供统一的初始化与更新接口。 ## 通用 API（所有 ShaderMaterial 类） * `static Name: string` 材质名称 * `static Material: ShaderMaterial` 共享材质实例（懒初始化） * `static PreviewMaterial: ShaderMaterial` 预览材质（独立实例） * `static InstanceShaderMaterial(): ShaderMaterial` 创建新实例 * `static Init(): ShaderMaterial` 初始化共享实例并派发 `instantiateShaderMaterial` * `static Update(): void` 更新共享实例（通常更新 `uTime`） * `static UpdatePreview(material: ShaderMaterial): void` 更新预览实例 ## 可用材质 * `CircleGridShaderMaterial` * `DynamicCheckerboardShaderMaterial` * `FlickerShaderMaterial` * `SlowSmokeShaderMaterial` * `SnowingShaderMaterial` * `StreamerWallShaderMaterial` ## 示例 ```ts import { CircleGridShaderMaterial } from "@astral3d/engine"; const mat = CircleGridShaderMaterial.Material; // 在渲染循环中 CircleGridShaderMaterial.Update(); ``` --- --- url: /sdk/hztp3ijj/index.md --- # Timeline / Animation ## 概述 时间轴用于动画轨道编辑。SDK 导出 `TimelineTrack` 类以及 `ITimelineKeyframe/Row/Model` 类型。 ## TimelineTrack ### 构造函数 `new TimelineTrack(container: HTMLDivElement, outlineContainer: HTMLDivElement, options: TimelineOptions)` ### 成员 * `timeline: Timeline` 时间轴实例 * `model: ITimelineModel` 时间轴数据模型 * `bindAction: THREE.AnimationAction | null` 当前绑定动画 ### 方法 * `setRows(rows: ITimelineRow[]): void` 设置轨道行 * `setRowIsVisible(keys: string[], visible: boolean): void` 设置行显隐 * `addKeyframe(attr: string): void` 添加关键帧 * `deleteRow(row: ITimelineRow): void` 删除轨道行 * `deleteSelectedKeyframes(): void` 删除选中关键帧 * `play(): void` 播放 * `pause(): void` 暂停/继续 * `stop(): void` 停止 * `setOptions(options: TimelineOptions): void` 更新配置 * `dispose(): void` 销毁 ### 事件 * `contextmenu` 右键 * `mousedown` 按下 ## 类型 ```ts export interface ITimelineKeyframe extends TimelineKeyframe { data: number[] | boolean[]; } export interface ITimelineRow extends TimelineRow { id: string; name: string; keyframes?: ITimelineKeyframe[]; track?: THREE.KeyframeTrack; } export interface ITimelineModel extends TimelineModel { rows: ITimelineRow[]; } ``` --- --- url: /sdk/ic9bvbw0/index.md --- # Roaming ## 概述 `Roaming` 提供第一人称/第三人称漫游能力，内部管理人物模型、移动与相机控制。 ## 构造函数 `new Roaming(viewer: Viewer)` * 入参： * `viewer` 视口实例 * 出参：`Roaming` ## 成员 * `group: THREE.Group` 漫游容器（加入场景） * `person?: THREE.Group` 人物模型 * `playerInitPos: THREE.Vector3` 人物初始位置 * `isRoaming: boolean` 是否正在漫游 ## 方法 * `startRoaming(): void` 进入漫游 * `exitRoaming(lastCameraPos?, lastCameraTarget?): void` 退出漫游并可还原相机 * `lastCameraPos?: THREE.Vector3` 退出后相机位置 * `lastCameraTarget?: THREE.Vector3` 退出后相机目标 * `resetPlayer(): void` 重置人物位置 * `reloadPerson(): Promise` 重新加载人物模型 * `render(delta: number): void` 每帧更新 * `dispose(): void` 释放事件与资源 ## 动画要求 人物模型需包含动画剪辑：`Enter / Idle / Walking / WalkingBackward / Jumping`。 ## RoamingGIS ## 概述 `RoamingGIS` 是 WebGIS 场景的漫游类，基于 ENU 局部坐标系适配地球尺度场景，并支持将 3D Tiles 地形纳入射线检测。 ## 构造函数 `new RoamingGIS(viewer: ViewerGIS)` ## 方法 * `startRoaming(): void` 进入漫游 * `exitRoaming(lastCameraPos?, lastCameraTarget?): void` 退出漫游并可还原相机 * `resetPlayer(): void` 重置人物位置 * `reloadPerson(): Promise` 重新加载人物模型 * `render(delta: number): void` 每帧更新 * `dispose(): void` 释放资源 ## RoamingStatus ### 构造函数 `new RoamingStatus(person: THREE.Group, clips: THREE.AnimationClip[])` * 入参： * `person` 人物模型 * `clips` 动画剪辑列表 * 出参：`RoamingStatus` ### 方法 * `init(): void` 初始化播放 * `setStatus(key: string, value: boolean): void` 更新键位状态 * `fadeIn(name: string): void` 进入动画 * `fadeOut(name: string): void` 退出动画 * `stopAllAction(): void` 停止全部动作 * `update(delta: number): void` 每帧更新 * `dispose(): void` 释放资源 --- --- url: /sdk/iop9pfaj/index.md --- # Tiles 3DTiles ## 构造函数 `new Tiles(options: ITiles.options)` * 入参：`options` 3DTiles 配置 * 出参：`Tiles` ## 成员 * `options: ITiles.options` 当前配置 * `renderer: TilesRenderer` 渲染器实例 * `type: "TilesGroup"` 类型标识 * `isTilesGroup: true` 类型判断标记 ## 方法 * `setCameraAndRenderer(camera, renderer): void` 绑定相机/渲染器 * `setDebug(debugOptions, needCreate = true): void` 调试模式 * `setErrorTarget(errorTarget: number): void` 设置目标误差（LOD 细节级别） * `setLRUCache(lruOptions): void` 设置 LRU 缓存 * `update(): void` 更新渲染 * `toJSON(meta?): any` / `static fromJSON(data, copyAttr?)` * `dispose(): void` ## 默认配置 * `getDefault3DTilesOptions(): ITiles.options` ## options 结构（ITiles.options） * `url: string` tileset 地址 * `name?: string` 组名称 * `reset2origin?: boolean` 是否重置到原点 * `debug?: { enabled; colorMode; displayBoxBounds; displaySphereBounds }` 调试显示 * `errorTarget?: number` 目标屏幕误差（像素） * `LRUCache?: { maxSize; minSize; maxBytesSize; minBytesSize }` 缓存限制 --- --- url: /sdk/irfiwp6t/index.md --- # 场景类命令 ## 通用成员 * 继承 `Command` 的通用成员：`id/inMemory/updatable/type/name` * 命令内部会保存目标对象与必要的旧/新值用于撤销 ## SetSceneCommand ### 构造函数 `new SetSceneCommand(scene: THREE.Scene)` * 入参：`scene` 新场景 * 出参：`SetSceneCommand` * 说明：替换当前场景 --- --- url: /sdk/k5ra8elw/index.md --- # Constants ## LAYERS * `DEFAULT: 0` * `EXPLODE: 10` * `SSR: 20` ## POSITION * `BOTTOM_LEFT` `BOTTOM` `BOTTOM_CENTER` `BOTTOM_RIGHT` * `TOP_LEFT` `TOP` `TOP_CENTER` `TOP_RIGHT` * `LEFT` `RIGHT` `CENTER` ## FPS\_OPTIONS * `NO_UPPER_LIMIT: 0` * `LOW: 24` * `MEDIUM: 30` * `HIGH: 60` * `ULTRA_HIGH: 120` ## ROAMING\_CHARACTERS * `JACKIE` * `WORK_MAN` * `X_BOT` * `Y_BOT` ## TILES\_DEBUG\_COLOR\_MODE * `None / Screen error / Geometric error / Distance / Depth / Relative depth / Is leaf / Random color / Random node color / Load order` ## TYPED\_ARRAYS * `Int8Array / Uint8Array / Uint8ClampedArray / Int16Array / Uint16Array / Int32Array / Uint32Array / Float32Array / Float64Array` ## BASE64\_TYPES * `data:image/png;base64` -> `png` * `data:image/jpeg;base64` -> `jpg` * `data:image/gif;base64` -> `gif` * `data:image/x-icon;base64` -> `ico` * `data:image/svg+xml;base64` -> `svg` * `data:image/webp;base64` -> `webp` * `data:audio/wav;base64` -> `wav` * `data:audio/mpeg;base64` -> `mp3` * `data:video/mp4;base64` -> `mp4` * `data:video/webm;base64` -> `webm` * `data:font/woff;base64` -> `woff` * `data:font/woff2;base64` -> `woff2` * `data:application/vnd.ms-fontobject;base64` -> `eot` * `data:application/x-font-ttf;base64` -> `ttf` * `data:application/octet-stream;base64` -> `ttf` * `data:application/font-woff;base64` -> `woff` * `data:application/font-woff2;base64` -> `woff2` ## TEXTURE\_MAPPING * `UVMapping` * `CubeReflectionMapping` * `CubeRefractionMapping` * `EquirectangularReflectionMapping` * `EquirectangularRefractionMapping` * `CubeUVReflectionMapping` ## TEXTURE\_WRAPPING * `RepeatWrapping` * `ClampToEdgeWrapping` * `MirroredRepeatWrapping` ## TEXTURE\_FILTER * `NearestFilter` * `NearestMipmapNearestFilter` * `NearestMipmapLinearFilter` * `LinearFilter` * `LinearMipmapNearestFilter` * `LinearMipmapLinearFilter` --- --- url: /sdk/kwcps0wu/index.md --- # Particle / Particles ## 概述 粒子系统基于 `three-nebula`，SDK 提供 `Particle` 命名空间（原始能力）与 `Particles` 预设工厂。 ## Particles（内置预设） ### 静态方法 * `Particles.smoke(initPosition?)` * `Particles.fire(initPosition?)` * `Particles.fireLine(initPosition?)` * `Particles.firefly(initPosition?)` * `Particles.fireworks(initPosition?)` 返回：`{ emitter: Particle.Emitter, body: THREE.Sprite }` ### 示例 ```ts import { Particles, Viewer } from "@astral3d/engine"; const { emitter, body } = Particles.smoke({ x: 0, y: 0, z: 0 }); viewer.addParticle(emitter, body, "Smoke"); ``` ## Particle 命名空间 `Particle` 对应 `three-nebula` 的导出，可用于自定义发射器、初始化器、行为等。 ```ts import { Particle } from "@astral3d/engine"; const emitter = new Particle.Emitter(); ``` ## IParticle.Config（结构概览） * `attr` 发射器基础属性（position/rotation/scale/totalEmitTimes/damping/life/numPan/timePan） * `init` 初始化器（mass/life/radius/rotation/position/velocity/body） * `behaviour` 行为（color/scale/alpha/force/rotate/randomDrift/spring/attraction/collision） > 详细字段可参考 `packages/sdk/types/objects/Particle.d.ts`。 --- --- url: /sdk/m40g6qsp/index.md --- # Heatmap 热力图 ## 构造函数 `new Heatmap(options?: Partial)` * 入参：`options` 可选，热力图配置（支持部分字段） * 出参：`Heatmap` ## 成员 * `options: IHeatmap.options` 当前配置 * `type: "Heatmap"` 类型标识 * `isHeatmap: true` 类型判断标记 ## 方法 * `setData(data: IHeatmap.Data): void` 设置数据 * `addData(points: IHeatmap.Point | IHeatmap.Point[]): void` 追加数据 * `clear(): this` 清空数据 * `setSize(size: IHeatmap.Size): void` 修改尺寸 * `setMode(mode: IHeatmap.Mode): this` 切换模式（平面/高度） * `updateHeatmapConfig(config: Partial): void` 更新热力图渲染配置 * `toJSON(meta?): any` 序列化 * `static fromJSON(json): Heatmap` 反序列化 * `dispose(): void` 释放资源 ## 默认配置 * `getDefaultHeatmapOptions(): IHeatmap.options` ## options 结构（IHeatmap.options） * `name: string` 名称 * `position: number[]` 本地坐标 * `mode: "flat" | "height"` 平面/高度模式 * `size: { width: number; height: number }` 实际尺寸 * `resolution: { width: number; height: number }` 贴图分辨率 * `material: { transparent; opacity; depthWrite; depthTest; side }` 材质参数 * `height: { scale; segments: { width; height } }` 高度模式参数 * `heatmap: { radius; blur; maxOpacity; minOpacity; gradient }` 热力图渲染参数 * `data: { max?; min?; points: { x; y; value; radius? }[] }` 数据点 --- --- url: /sdk/nec8glps/index.md --- # HtmlPanel / HtmlSprite ## HtmlPanelConverter * `HtmlPanelConverter.getInstance()` 获取单例 * `loadAsync({ url, isSprite, fileName? }): Promise` 加载 html/zip * `parseToCSS3D(options): HtmlPanel | HtmlSprite` 解析为 CSS3D 对象 ## HtmlPanel / HtmlSprite * 继承自 `CSS3DObject / CSS3DSprite` * `toJSON(meta?): any` * `static fromJSON(data): HtmlPanel | HtmlSprite` > 当加载 zip 时要求根目录存在 `index.html`。 --- --- url: /sdk/nfhd30he/index.md --- # Signals ## SignalsRegister * 类型：`Record` * 说明：全局信号注册表（内部维护） ## SignalsRegisterFn `SignalsRegisterFn(newSignals: string[]): void` * 入参：`newSignals` 新增信号名称列表 * 出参：无 * 说明：向全局信号表注册新信号 --- --- url: /sdk/objects/billboard/index.md --- # Billboard 广告牌 ## 构造函数 `new Billboard(options: IBillboard.options, material?: THREE.SpriteMaterial)` * 入参： * `options` 必填，广告牌配置 * `material` 可选，自定义 `SpriteMaterial`（会自动注入贴图） * 出参：`Billboard` ## 关键方法 * `toJSON(meta?): any` 序列化 * `static fromJSON(data): Billboard` 反序列化 ## 成员 * `options: IBillboard.options` 当前配置快照 * `type: "Billboard"` 类型标识 * `isBillboard: true` 类型判断标记 ## 事件 * `imgLoaded` 图片加载完成 * `redraw` 纹理重绘 ## options 结构（IBillboard.options） * `name: string` 名称 * `position: number[]` 本地坐标 `[x, y, z]` * `image` 图片配置 * `url?: string` 图片地址 * `visible: boolean` 是否显示 * `width: number` 宽度（像素） * `height: number` 高度（像素） * `rotate: number` 旋转角度（deg） * `margin: number` 与文本间距 * `position: string` 对齐位置（如 `center`） * `top: boolean` 是否置顶 * `text` 文本配置 * `value: string` 文本内容 * `visible: boolean` 是否显示 * `fontSize: number` 字号 * `fontColor: string` 颜色 * `fontFamily?: string` 字体 * `fontWeight: string | number` 粗细 * `fontStyle: string` 字体样式 * `lineGap: number` 行间距 * `padding: number` 内边距 * `align: string` 对齐方式（left/center/right） * `baseline: string` 基线 * `strokeWidth: number` 描边宽度 * `strokeColor: string` 描边颜色 * `fill: boolean` 是否填充 * `fillColor: string` 填充色 ## 默认配置 * `getDefaultBillboardOptions(): IBillboard.options` --- --- url: /sdk/oiqk4xeh/index.md --- *** lang: zh-CNtitle: UIPanel title: UIPanel 面板createTime: 2026/04/16 14:02:27 createTime: 2026/01/08 22:30:38permalink: /sdk/xooyc6l4/ permalink: /sdk/objects/ui-panel/--- *** # UIPanel 面板 ## 构造函数 `new UIPanel(options?: Partial, init?: { buildChildren?: boolean })` * 入参： * `options` 可选，UI 面板配置 * `init.buildChildren` 是否根据 `children` 构建子节点（默认 true） * 出参：`UIPanel` ## 成员 * `options: IUIPanel.options` 当前配置 * `type: "UIPanel"` 类型标识 * `isUIPanel: true` 类型判断标记 ## 方法 * `updateOptions(options: Partial): void` 更新配置 * `setProps(patch: Record): void` 更新 UI 属性 * `setStates(states?: UIPanelStateMap): void` 设置交互状态 * `applyState(state: string | null): void` 应用状态 * `hasInteractiveState(): boolean` 是否包含交互状态 * `getElementByNodeId(nodeId: string): UIPanelElement | null` 查找子节点 * `toJSON(meta?): any` 序列化 * `static fromJSON(json, init?): UIPanel` 反序列化 * `dispose(): void` 释放资源 ## 子元素类型 * `UIPanelBlock / UIPanelText / UIPanelInline / UIPanelInlineBlock` ## 默认配置 * `getDefaultUIPanelOptions(): IUIPanel.options` ## options 结构（IUIPanel.options） * `id: string` 根节点 ID * `type: "block" | "text" | "inline" | "inlineBlock"` 根节点类型 * `name: string` 名称 * `position: number[]` 本地坐标 * `rotation?: number[]` 欧拉角 * `scale?: number[]` 缩放 * `font?: { family?; texture?; weight?; style? }` 字体配置 * `props?: Record` UI 属性（如宽高、背景、布局） * `states?: Record>` 交互状态配置 * `children?: IUIPanel.Node[]` 子节点树 --- --- url: /sdk/ojfxxlbm/index.md --- # Request ## fetchController `fetchController(limit: number, timeout: number | boolean)` * 入参： * `limit` 并发上限 * `timeout` 超时时间（ms）或 `false` 不启用 * 出参：`(url: string, options?: any) => void` * 说明：返回一个带并发控制的 fetch 包装器 --- --- url: /sdk/pxznoixc/index.md --- # Scene ## 路径与坐标 ### getParentPath `getParentPath(parentObject, object, attr = "name", splitter = "/"): string` * 入参： * `parentObject` 父级对象 * `object` 目标对象 * `attr` 用于路径的字段名 * `splitter` 分隔符 * 出参：路径字符串 ### getMousePosition `getMousePosition(dom, x, y): number[]` * 入参： * `dom` DOM 元素 * `x` 鼠标 x * `y` 鼠标 y * 出参：归一化坐标 `[x, y]` ## 对象判断 ### getMeshByInstancedMesh `getMeshByInstancedMesh(instancedMesh): THREE.Mesh` * 入参：`instancedMesh` 实例化网格 * 出参：普通 `Mesh` ### isGroup `isGroup(object3D): boolean` * 入参：`object3D` * 出参：是否为 Group ### isParticleObject `isParticleObject(object): boolean` * 入参：`object` * 出参：是否为粒子对象 ### isBillboardObject `isBillboardObject(object): boolean` * 入参：`object` * 出参：是否为 Billboard ### isHtmlPanelObject `isHtmlPanelObject(object): boolean` * 入参：`object` * 出参：是否为 HtmlPanel/HtmlSprite ### is3DTilesObject `is3DTilesObject(object): boolean` * 入参：`object` * 出参：是否为 3DTiles ### isHeatmapObject `isHeatmapObject(object): boolean` * 入参：`object` * 出参：是否为 Heatmap ### isPathObject `isPathObject(object): boolean` * 入参：`object` * 出参：是否为 Path ## 动画相关 ### getAnimations `getAnimations(object = App.scene): THREE.AnimationClip[]` * 入参：`object` 根对象（默认场景） * 出参：动画剪辑数组 ### getAnimationClips `getAnimationClips(object = App.scene): THREE.AnimationClip[]` * 入参：`object` 根对象（默认场景） * 出参：动画剪辑数组 ## 遍历 ### safeTraverseByCondition `safeTraverseByCondition(obj, callback, condition?): void` * 入参： * `obj` 根对象 * `callback` 回调 * `condition` 条件（默认全部通过） * 出参：无 ## 材质 ### parseMaterialZip `parseMaterialZip(zipFile: File): Promise` * 入参：`zipFile` 材质包 zip * 出参：`Promise` ## 相机 ### focusObject `focusObject(object, controls, enableTransition = true): void` * 入参： * `object` 目标对象 * `controls` 相机控制器 * `enableTransition` 是否过渡 * 出参：无 ## UIPanel 辅助 ### UIPANEL\_TYPES * 类型：`Set` * 说明：UIPanel 相关类型集合 ### isUIPanelObject `isUIPanelObject(object): boolean` * 入参：`object` * 出参：是否为 UIPanel ### isUIPanelRelatedObject `isUIPanelRelatedObject(object): boolean` * 入参：`object` * 出参：是否为 UIPanel 相关对象 ### findUIPanelRoot `findUIPanelRoot(object): Object3D | null` * 入参：`object` * 出参：UIPanel 根节点 ### findUIPanelNodeId `findUIPanelNodeId(object): string | null` * 入参：`object` * 出参：节点 ID ## 性能监控 ### Stats #### 构造函数 `new Stats(viewer: Viewer)` * 入参：`viewer` 视口实例 * 出参：`Stats` #### 成员 * `domElement: HTMLElement` 面板节点 * `visible: boolean` 是否显示 #### 方法 * `showPanel(type: number | "fps" | "ms" | "mb"): void` 切换面板 * `showAllPanels(show: boolean): void` 显示/隐藏全部面板 * `dispose(): void` 释放事件与资源 --- --- url: /sdk/r63ka2lp/index.md --- # Measure ## 概述 `Measure` 提供距离、面积、角度测量能力，通过拾取点位生成标注与结果。 ## 构造函数 `new Measure(viewer: Viewer, mode?: MeasureMode)` * 入参： * `viewer` 视口实例 * `mode` 测量模式，默认 `MeasureMode.Distance` * 出参：`Measure` ## 成员 * `mode: MeasureMode` 当前测量模式 * `isCompleted: boolean` 当前测量是否完成 * `isClose: boolean` 测量是否已关闭 * `measureGroup: THREE.Group` 测量结果容器 ## 事件 * `complete: { object: THREE.Group }` 完成一次测量后触发 ## 方法 * `open(): void` 开始测量 * `redraw(point: THREE.Sprite): void` 进入重绘模式 * `redrawComplete(): void` 结束重绘 * `complete(): void` 完成并生成结果 * `clear(): void` 清空所有测量 * `dispose(): void` 释放事件与资源 ## MeasureMode * `Distance` 距离 * `Area` 面积 * `Angle` 角度 --- --- url: /sdk/rqm8z5zt/index.md --- # 几何类命令 ## 通用成员 * 继承 `Command` 的通用成员：`id/inMemory/updatable/type/name` * 命令内部会保存目标对象与必要的旧/新值用于撤销 ## SetGeometryCommand ### 构造函数 `new SetGeometryCommand(object: THREE.Mesh, newGeometry: THREE.BufferGeometry)` * 入参： * `object` 目标网格 * `newGeometry` 新几何体 * 出参：`SetGeometryCommand` * 说明：替换网格几何体 ## SetGeometryValueCommand ### 构造函数 `new SetGeometryValueCommand(object: THREE.Object3D, attributeName: string, newValue: any)` * 入参： * `object` 目标对象 * `attributeName` 几何字段名 * `newValue` 新值 * 出参：`SetGeometryValueCommand` * 说明：更新几何字段 --- --- url: /sdk/ulcg8teuq/index.md --- # Package ## 概述 `Package` 用于场景打包/解包。 ## 构造函数 ### new Package(viewer: Viewer) * 入参：`viewer` 当前 Viewer 实例 * 返回：`Package` 实例 ## 主要方法 ### `pack(config: IPackConfig): Promise` 打包场景并按配置上传分包。 **IPackConfig** * `name: string` 首包名称 * `layer?: number` 拆分深度（0 表示拆到最深层） * `zipUploadFun: (file: File) => Promise` 上传函数（实际输出为 `.astral`） * `rawUploadFun?: (raw: { name: string; files: Record }) => Promise` 原始包上传（不压缩，给离线单包优化用） * `imageProcessLimit?: number` 贴图处理并发（默认按硬件核数自动取值） * `onZipProgress?: (info: { name: string; progress: number }) => void` 单包压缩进度（0-100） * `onProgress?: (progress: number) => void` 打包进度回调 * `onComplete?: (info: { firstUploadResult: any; totalSize: number; totalZipNumber: number }) => void` 完成回调 ### `packOffline(config: IOfflinePackConfig): Promise` 导出离线包（单包或多包）。 **IOfflinePackConfig** * `name: string` 首包名称 * `layer?: number` 拆分深度（0 表示拆到最深层） * `mode?: "single" | "multiple"` 导出模式（单包/分包） * `bundleName?: string` 单包导出文件名（不含后缀） * `imageProcessLimit?: number` 贴图处理并发 * `onZipProgress?: (info: { name: string; progress: number }) => void` 单包压缩进度（0-100） * `onProgress?: (progress: number) => void` 进度回调 * `onComplete?: (result: OfflinePackResult) => void` 完成回调 **OfflinePackResult** * `mode: "single" | "multiple"` * `entry: string` 首包文件名（`.astral`） * `files: File[]` 导出的 `.astral` 文件列表 * `totalSize: number` 总大小 * `totalZipNumber: number` 包数量 ### `unpack(config: IUnpackConfig): Promise` 解包并加载场景。 **IUnpackConfig** * `url: string` 首包 URL * `onSceneLoad?: (sceneJson: ISceneJson, configJson: IAppProject.Config) => void` 场景 JSON 解析完成回调 * `onProgress?: (progress: number) => void` 解包进度 * `onComplete?: () => void` 完成回调 * `offlineFiles?: File[]` 离线分包文件列表（`.astral`） * `offlineBundle?: Blob | ArrayBuffer | Uint8Array` 离线单包（`.astral`） * `offlineEntry?: string` 离线首包文件名（可选） ### `clear(): void` 清理内部缓存（贴图/几何/材质/骨骼映射等）。 ### `dispose(): void` 释放引用并清理资源。 ## 使用示例 ```ts const packer = viewer.package; await packer.pack({ name: "scene", zipUploadFun: async file => { return uploadPack(file); }, onZipProgress: ({ name, progress }) => console.log(name, progress), onProgress: p => console.log(p), }); ``` --- --- url: /sdk/viewer-gis-modules/index.md --- # ViewerGIS 模块 ## 概述 `ViewerGISModules` 是 WebGIS 场景的模块集合，围绕地球尺度坐标与 GlobeControls 进行适配，包含 GIS 相机管理、3D Tiles 管理、拖拽与天气等能力。 ## 模块结构（ViewerGISModules） * `cameraManage: CameraManageGIS` GIS 相机管理器 * `registerSignal: Signals` 信号注册与事件联动 * `shaderMaterialManager: ShaderMaterialManager` ShaderMaterial 更新管理 * `particleSystem: ParticleSystem` 粒子系统 * `dragControl: Drag` 拖拽控制 * `tilesManage: TilesManage` 3D Tiles 管理（用户添加的 tiles） * `weather: Weather` 通用天气效果 * `controls: AstralGlobalControls` GlobeControls 适配控制器 * `transformControls?: TransformControls` 仅编辑模式可用 ## 说明 * `controls` 基于 `AstralGlobalControls`，提供 CameraControls 兼容 API 子集 * `tilesManage` 管理用户添加的 3D Tiles；地图源的 2D/3D Tiles 由 `ViewerGIS` 内部 `maps` 管理 * `transformControls` 只有在 `edit.enabled` 为 true 时创建 ## 关联模块 `EffectGIS` 属于后处理模块，不在 `ViewerGISModules` 内，但由 `ViewerGIS` 统一管理。 --- --- url: /sdk/viewer-gis/index.md --- # ViewerGIS ## 概述 `ViewerGIS` 是 WebGIS 场景查看器，基于 `@takram/three-geospatial` 与 `3d-tiles-renderer` 构建，适用于地球尺度的三维场景与瓦片渲染。核心特性： * 使用 ECEF 坐标系（地心地固坐标）组织场景 * 支持 3D Tiles 与 2D Tiles 地图源叠加 * 强制使用 WebGIS 专用后处理管线（EffectGIS） * 内置 GlobeControls 兼容的控制器与 GIS 相机管理 ## 构造函数 `new ViewerGIS(options: IViewerWrapperOptions)` * `options.gis`：WebGIS 配置（初始位置、地图源） * 其余配置与 `Viewer` 保持一致（`container/edit/request/plugin` 等） ### IViewerWrapperGIS * `initialPosition`：初始地理位置 * `longitude`：经度（度） * `latitude`：纬度（度） * `altitude`：高度（米） * `mapSources`：地图源数组（支持多源叠加） ### IMapSource（摘要） * `id/name/enabled/category` * `category: "3dtiles"`： * `tiles3dProvider: "google" | "cesium" | "custom"` * `googleApiKey` / `ionToken` / `ionAssetId` / `tiles3dUrl` * `category: "2dtiles"`： * `preset: "tianditu_vec" | "tianditu_img" | "amap_vec" | "amap_img" | "osm" | "custom"` * `tiandituKey` / `tileUrl` ## 关键成员 * `isGIS: true` * `earth: Mesh`：地球占位球体（BackSide + depthWrite，用于深度与拾取） * `effect: EffectGIS`：WebGIS 专用后处理模块 * `gisWeather: GISWeather`：基于高度的天气效果 * `includeGlobeTilesInRaycast: boolean`：拾取时是否包含地球瓦片 * `enableSkinnedMeshPrecisionFix: boolean`：是否启用 SkinnedMesh 精度修复 * `modules.cameraManage: CameraManageGIS`：GIS 相机管理 * `modules.controls: AstralGlobalControls`：GlobeControls 适配控制器 * `modules.tilesManage: TilesManage`：3D Tiles 管理器 ## 常用方法 * `addMapSource/removeMapSource/updateMapSources`：管理地图源 * `getEarthSurfacePosition(screenX, screenY)`：屏幕坐标对应地表位置 * `getCenterEarthSurfacePosition()`：屏幕中心地表位置 * `validatePositionAboveEarth(position)`：检查位置是否在地表之上 * `adjustPositionAboveEarth(position, offsetAltitude?)`：将位置调整到地表之上 * `getEarthSurfaceRotation(position)`：计算“贴地”旋转 * `registerSkinnedMesh(object)` / `unregisterSkinnedMesh(object)`：SkinnedMesh 精度修复注册 * `focusToObject(object, enableTransition?)`：聚焦指定对象 ## 示例 ```ts import { ViewerGIS } from "@astral3d/engine"; const viewer = new ViewerGIS({ container: document.getElementById("app")!, gis: { initialPosition: { longitude: 104.0668, latitude: 30.5728, altitude: 50000 }, mapSources: [ { id: "osm", name: "OpenStreetMap", enabled: true, category: "2dtiles", preset: "osm", }, ], }, }); ``` ## 注意事项 * WebGIS 强制使用后处理管线，`renderer` 的抗锯齿与色调映射配置不生效。 * ECEF 坐标尺度大，放置对象建议使用 `adjustPositionAboveEarth` + `getEarthSurfaceRotation`。 * 大坐标精度问题在 SkinnedMesh 上更明显，可使用内置精度修复策略。 --- --- url: /sdk/viewer-wrapper/index.md --- # ViewerWrapper ## 概述 `ViewerWrapper` 是 `Viewer` 与 `ViewerGIS` 的基类，负责渲染器/场景/事件/ResizeObserver 等通用初始化逻辑，并提供脚本系统与数据组件管理的基础能力。 > `ViewerWrapper` 为抽象类，请使用 `Viewer` 或 `ViewerGIS` 实例化。 ## 构造函数（抽象） `new ViewerWrapper(options: IViewerWrapperOptions)` ### IViewerWrapperOptions 关键字段 * `container?: HTMLElement` 挂载容器 * `hdr?: string` HDR 环境贴图 * `edit?: IViewerWrapperEdit` 编辑模式（gizmo/辅助线等） * `enableScript?: boolean` 是否启用脚本系统 * `request?: IViewerWrapperRequest` 请求配置 * `baseUrl?: string` 资源前缀 * `dataSetExecute?: (dataSetId) => Promise<{ data; error? }>` 数据集执行接口 * `grid: IViewerWrapperGrid` 网格配置（仅 Web3D） * `control: IViewerWrapperControl` 相机控制参数 * `gis?: IViewerWrapperGIS` WebGIS 配置（初始位置/地图源） * `plugin?: { injectApi: Record }` 注入插件的 API ## 成员 * `container: HTMLElement` 容器 * `options: IViewerWrapperOptions` 配置 * `renderer: THREE.WebGLRenderer` 渲染器 * `camera: THREE.PerspectiveCamera` 相机（与 `App.camera` 同步） * `scene: THREE.Scene` 主场景（与 `App.scene` 同步） * `sceneHelpers: THREE.Scene` 辅助场景 * `raycaster: THREE.Raycaster` 拾取射线 * `css2DRenderer: CSS2DRenderer` 2D 标签渲染器 * `css3DRenderer: CSS3DRenderer` 3D DOM 渲染器 * `timer: THREE.Timer` 动画计时器 * `sceneBox3: THREE.Box3` 场景包围盒 * `isGIS: boolean` 是否为 WebGIS 场景 * `dataComponentManager: DataComponentManager` 数据组件管理器 * `pluginCommands: PluginCommands` 插件命令集 * `package: Package` 场景打包/解包器 ## 通用方法 * `updateAspectRatio(): void` 更新相机宽高比 * `loadEnv(setBg = true, onLoad?, onError?): void` 加载 HDR 环境 * `getIntersects(point: THREE.Vector2): THREE.Intersection[]` 射线拾取 * `dispose(): void` 清理基础资源（建议子类重写） ## 事件 `ViewerWrapper` 继承 `THREE.EventDispatcher`，事件类型与 `Viewer` 一致，详见 `ViewerEvents` 文档。 --- --- url: /sdk/w92dis86/index.md --- # 工具类 ## 概述 工具类为场景提供漫游、测量、模型爆炸、剖切盒、导出、MiniMap、阵列生成等功能。 ## 目录 * [Roaming / RoamingGIS / RoamingStatus](./Roaming.md) * [ObjectArrayGenerator](./ObjectArrayGenerator.md) * [Measure](./Measure.md) * [ClippedEdgesBox / ClippedEdgesBoxGIS](./ClippedEdgesBox.md) * [MiniMap](./MiniMap.md) * [Export](./Export.md) * [ModelExplode](./ModelExplode.md) * [DataBindingManager](../data-binding.md) * [DataComponentManager](./DataComponentManager.md) --- --- url: /sdk/xtdfxloc/index.md --- # DXF ## 概述 DXF 模块提供图纸解析（DxfParser）与预览渲染（DxfViewer）。 ## DxfViewer ### 构造函数 `new DxfViewer(data: any, canvas: HTMLCanvasElement, width: number, height: number, onComplete?: () => void)` ### 方法 * `callMethod(methodName: string, data?: any): void` 调用内部绘制方法 * `dispose(): void` 释放资源 * `selectRect(uuid: string): void` 选中标注 * `deleteRect(): void` 删除选中标注 ### 属性 * `selectRectIndex: number` 当前选中标注索引 ## DxfParser ### 构造函数 `new DxfParser()` ### 方法 * `parse(source: string | Readable): IDxf | null` 解析 DXF 字符串/流 * `parseSync(source: string): IDxf | null` 同步解析 * `parseStream(stream: Readable): Promise` 解析流 * `registerEntityHandler(handler: new () => IGeometry): void` 注册实体解析器 ### 常用类型 * `IDxf` 解析结果 * `IEntity` 实体基类 * `ILineEntity / ICircleEntity / ITextEntity / ...` 具体实体类型 > DXF 类型导出详见 `packages/sdk/lib/dxf/parser`。 --- --- url: /sdk/ytbviat7/index.md --- # GaussianSplat 高斯泼溅 ## 构造函数 `new GaussianSplat(options: GaussianSplatOptions)` * 入参：`options` 必填，高斯泼溅配置 * 出参：`GaussianSplat` ## 成员 * `options: GaussianSplatOptions` 当前配置快照 * `type: "GaussianSplatGroup"` 类型标识 * `isGaussianSplatGroup: true` 类型判断标记 * `splatMesh: SplatMesh | null` 内部 SplatMesh 引用（只读，加载完成前为 `null`） * `initialized: boolean` SplatMesh 是否已加载完成（只读） * `ready: Promise` 初始化 Promise，加载完成后 resolve ## 方法 * `attachSplatMesh(splatMesh: SplatMesh): void` 挂载已创建的 SplatMesh（首次拖入场景时使用） * `toJSON(meta?): any` 序列化（输出 `type + options`，不序列化 SplatMesh 子级） * `static fromJSON(data, copyAttr?): GaussianSplat` 反序列化（自动异步重新加载 SplatMesh） * `clone(recursive?): GaussianSplat` 基于 options 重新构造 * `dispose(): void` 释放资源（解除 SplatMesh 引用，GPU/WASM 资源由 `GaussianSplatManager` 负责清理） ## 默认配置 * `getDefaultGaussianSplatOptions(): GaussianSplatOptions` ## options 结构（GaussianSplatOptions） * `url: string` 资源 URL（打包/还原的唯一凭据） * `name?: string` 显示名称（默认 `"GaussianSplat"`） * `lod?: boolean | number` 是否启用 LoD（默认 `true`） * `paged?: boolean` 是否启用分页流式加载（默认 `false`，`.rad` 格式建议 `true`） * `extSplats?: boolean` 是否使用扩展编码（默认 `false`） * `lodScale?: number` LoD 细节缩放因子（默认 `1.0`） ## 支持格式 `.ply`、`.spz`、`.splat`、`.ksplat`、`.sog`、`.rad` ## 生命周期 1. **首次加载**：`GaussianSplatManager.loadFromUrl` → `buildSplatMesh` → 创建 `GaussianSplat` 包装 2. **打包保存**：`Package.pack` 走 `child.toJSON()`（与 `Tiles` 一致） 3. **加载还原**：`ObjectLoader` → `GaussianSplat.fromJSON` → 异步加载 SplatMesh 4. **销毁**：`GaussianSplatManager.handleObjectRemoved` 释放 GPU/WASM 资源 ## SDK 代码示例 ```ts import { GaussianSplat, AddObjectCommand, App } from "@astral3d/engine"; // 创建高斯泼溅对象 const gs = new GaussianSplat({ url: "https://example.com/model.spz", name: "我的泼溅模型", lod: true, }); // 添加到场景 App.execute(new AddObjectCommand(gs)); // 等待加载完成 await gs.ready; console.log("泼溅点数:", gs.splatMesh?.numSplats); ``` --- --- url: /update/64cj5dsm/index.md --- # 8月 ::: tip 这个月的任务突然就很繁重 而且还要兼顾其他工作，真是一件很辛苦的事情。 ::: ## :tada: 5-6日 :tada: ::: tip 重点功能实现 ::: * 修改工程打包方式，默认使用分批切块打包，一个场景存储为数十乃至数千资源包（取决于打包递归深度，递归深度默认为3层。后期增加用户可配置项：可选择整体打包/分批切块打包，分批切块打包可自定义递归深度） * 相应的，修改场景包加载还原方式，现在支持分批切块加载，即渐进式加载； * 涉及的多部分代码重构（工程打包、场景加载、工程预览...） ## 7日 * 场景编辑器顶部布局修改，去除菜单项，增加标题，导入导出改为按钮追加在各功能操作图标后方； ## 8日 * 完成封面图相关工作； ## 21日 * 新增fly组件，控制相机飞行的补间动画； * 修复模型树展开的节点在在加载内容后会关闭的Bug; * 大大降低模型树组件更新频率； * 预览态新增模型树； * 预览态改用EffectComposer渲染，新增模型选中时的Outline效果； ## 22日 * 新增预览态底部操作栏； * 完成预览态底部操作栏-返回主视角功能； * 完成预览态底部操作栏-自动旋转功能； * 完成预览态底部操作栏-全屏/退出全屏功能； ## 23日 * 完成预览态底部操作栏-剖切功能； * 完成预览态底部操作栏-测量功能； * 完成预览态底部操作栏-小地图功能（不满意，半成品）； ## 26日 * 修复模型选中后右侧操作面板无法查看对应属性的BUG [Issues #12](https://github.com/mlt131220/ES-3DEditor/issues/12); * 贴图新增repeat相关设置，可设置贴图重复模式、UV方向重复次数； * 解决场景不存在脚本时点击模型报错的BUG; ## 28日 * 解决打包错误造成的无法删除场景的BUG； * 预览态增加漫游功能； ## 29日 * 完成预览态漫游功能； ## 30日 * 漫游新增动画状态机，新增奔跑动画； --- --- url: /update/6k8gige3/index.md --- # 11月 ## 6日 * 修复雪花id过长，前端精度丢失而无法删除的bug； ## 7日 * 修复Flyto(改用新控制器后产生的bug); * 新增后处理（描边通道、抗锯齿通道）; * 预览页新增图纸显示; ## 8日 * 为cad解析的图元新增name值; * cad图纸查看时新增鼠标经过的元素辉光效果; * 解决cad转换后前端状态未更新的bug; * 测试环境开放CAD文件上传转换; ## 12日 * 优化后处理部分代码结构； * 规范项目文件名； * 解决添加图纸后资源库内容拖拽到场景上不生效的bug; * 解决图纸加载后新的图纸拖入无效的bug; ## 14日 * 项目列表按更新时间排序； * 新增辉光、半色调、变焦后处理效果； ## 19日 * 分离项目配置： * 去除已弃用属性； * 分离出项目级配置； * ThreeJS升级至R170; --- --- url: /update/8znubzxf/index.md --- # 7月 ::: tip 又摆烂到月底 不能怪LOL，也不能怪剑网情缘3，要怪就怪我的狗友吧。 月底了，just do it！ ::: ## 14日 * 修复顶部第二次打开播放（预览）报错的Bug; ## 23日 * 主题化场景（现有方案废弃，功能优先级下移搁置）; ## 25日 * 优化项目结构； ## 27-29日 * 新增首页，场景创建逻辑重构； * 新增模板场景，可快速创建场景； * 新增 Msy3D SDK，后期逐步抽离封装此编辑器功能至该SDK; --- --- url: /update/98pjt8xt/index.md --- # 2月 ## 28日 * 获取模型/获取贴图/获取几何数据接口 查询条件由 uuid 修改为 sceneId + uuid; * 引入Cesium引擎，增加 新建Cesium融合场景功能，动态切换至Cesium场景; --- --- url: /update/dbofligs/index.md --- # 7月 ## 13日 * ThreeJS 版本由 r146 更新至 r154; * 解决 three/examples/jsm/exporters/ColladaExporter.js 在 threejs r153 版本被移除的问题； * 使用 web-ifc-three 解析IFC BIM模型； * 完善场景树拖拽功能（拖动到内部时只能是Group / Scene）； * 添加场景选中模型时场景树自动展开选中并滚动到对应位置的功能； ## :tada: 19日 :tada: ::: tip 重点功能实现 ::: * 添加BIM轻量化模块； * 添加 websocket 与后端进行长连接，后端使用聊天室模式，便于后期进行三维协作； * 已支持上传Rvt模型并发起BIM轻量化，通过websocket接收结果，结果会广播给所有在线用户； ## 28日 * ThreeJS 版本由 r154 更新至 r155; --- --- url: /update/doebw5ta/index.md --- # 4月 ## 03日 * 全局配置项与全局常量归档； ## 07日 * 使用`TypeScript`重写`Viewport`; ## 09日 * `ToolBar` 加入 `Shading` 渲染模式选择； * `ThreeJS` 版本升级至`r163`; * 色彩空间变更,全局替换(R152版本提出，R162版本废弃)： Texture：将 `.encoding` 替换为 `.colorSpace`; WebGLRenderTarget: 将 `.outputEnding` 替换为 `.outputColorSpace`; * `Scene Background` 为 `Equirectangular` 类型时，增加 `Intensity && Rotation`数值设置项； ## 12日 * `ktx2Loader.setTranscoderPath`对应所需文件存储至又拍云； * 修复 `ThreeJS` 升级 `r163` 后CAD文件加载报错的BUG(`r163`版本`OrbitControls`调用了新函数`getRootNode`,需要在使用`OffscreenCanvas`渲染CAD文件的虚拟dom元素代理上实现); ## 15日 * 重写场景运行预览相关内容； * 右侧边栏新增脚本组件； * 右侧边栏新增动画组件； ## 18日 * 去除AR支持，添加XR支持； * 解决导入glb模型报错 `Couldn't load texture blob:http://xxxx` 的问题（`GLTFLoader`参数`manager`需要为`THREE.LoadingManager || undefined`,不能为`null`）； ## 23日 * 修改脚本默认内容； * 脚本新增内置变量、事件、生命周期； ## 24日 * 脚本默认内容更新，新增变量，新增Helper类； * 新增 预览 功能； ## 28日 * 新增补间动画管理器； * 弃用viewHelper，使用viewCube代替(右下角XYZ轴指示器改用Cube)； ## 29日 * 更改Header功能布局; * History 移动至右侧功能区； * 替换Logo; ## 30日 * 增加全局主色调修改功能（提供颜色选择弹窗）； * 全部工程列表新增预览操作； * 新增设置弹窗； --- --- url: /update/efnqd97u/index.md --- # 9月 ## 12日 * 新增插件入口（灵感来自于[utools-新一代效率工具平台](https://u.tools/)）; ## 18日 * 修改项目架构，优化打包及配置; * 新增插件中心 Dialog; ## 19日-21日 * 新增内置插件glTF处理器，支持glTF/glb文件在线压缩优化，一键下载或直接导入场景（具体查看[glTF处理器插件](http://editor-doc.mhbdng.cn/guide/plugin/builtin/glTFHandler.html)）; * 插件中心支持插件搜索; * 无图标插件默认使用适配主题的Logo图标; * 首页项目列表排序优化; --- --- url: /update/elfg1zow/index.md --- # 10月 ## 10日 * glTF处理器优化; * README更新； ## 22日 * 新增Camera六视图； ## 24日 * 引入新的相机控制器：由OrbitControls改为[camera-controls](https://github.com/yomotsu/camera-controls) ## 26日 * 修复打开抗锯齿以后相机控制器失效的BUG； * 优化本地存储； --- --- url: /update/fi34hwb4/index.md --- # 3月 ## 1日 * 动画编辑器进度 40%； ## 3日 * 动画编辑器进度 60%； ## 4日 * 动画编辑器进度80%； * 新增模型锁定功能； ## 5日 * 动画编辑器进度90%； ## 6日 * 动画编辑器进度99%； ## 7日 * 完成动画编辑器； * 动画编辑器 树右键删除row(未完成)； ## 8日 * 面板初始化时判断模型是否选中； ## 11日 * 整合资源中心； ## 21日 * 修改脚本中关于动画的执行； ## 22日 * 使用Promise重写Editor.Loader； * 重构导出逻辑； * 扩展面板新增资源中心； ## 23日 * 调整CAD/BIM资产样式以改善布局和滚动行为； * 场景树新增右键菜单； ## 24日 * cad上传取消缩略图字段，上传后自动生成； * 优化cad解析逻辑； * 在生产环境中禁用开发工具； * 添加wasm加速计算； ## 25日 * 修复顶部缺失国际化、主题等控制组件的bug； * 移除演示环境相关配置，优化打包逻辑； * 添加构建渐进式Web应用支持，更新图标和robots.txt配置； * 重构配置管理，优化静态方法和存储逻辑； * 删除不再使用的service worker注册和逻辑； * 修复阴影偏差值的处理，优化输入组件的精度设置； * 添加阴影强度设置，更新阴影类型选项及相关翻译； ## 26日 * 新增CSM； * 默认开启除灯光外的接收与投射阴影； * 新增CSM配置及打包支持； * 解决背景/环境取消后拉取仍然出现的bug； ## 27日 * 新增扩展面板`材质`资源； ## 29日 * 修复测量距离label会消失一帧的bug; * 修复面积测量过程中不显示label的bug; * 修复wasm修改porcess引起的报错； * 全局禁用浏览器默认右键菜单； --- --- url: /update/khikfd9q/index.md --- # 2月 ## 9日 - 12日 * 优化Grid实现； * 修改模型上不包含动画时的提示语； * 修复libs/three-nebula中的依赖包不存在的问题; * 修复monaco-editor与gltf处理器全局define冲突的问题，同时monaco-editor加载地址由cdn改为本地; * 新增粒子系统基础类； * 粒子系统基础完善，增加Body初始化器配置； ## 13日 * 粒子系统：新增颜色、缩放、α-effect、力行为配置项； ## 14日 * 完善粒子系统及配置； * 自定义ObjectLoader，弃用THREE.ObjectLoader； ## 15日 * 粒子的保存与加载； * 内置烟雾粒子效果； * 粒子的选中处理； ## 16日 * 资源库新增粒子选项：内置火焰、火线、烟花、萤火虫粒子特效； * 修复粒子选中全都定位到最后添加的粒子效果上的问题； * 修复撤销粒子的添加操作后再重做无法显示粒子的bug； * 解决空对象无法聚焦的bug； * 修复项目加载后视角未复原的bug； * 预览态加载粒子效果； * 材质属性可输入精度控制； * 修复场景加载物体材质被改为雪堆积材质的bug； * 基础样式调整； ## 17日 * 修复昨天更新后快捷键失效的bug； * 插件目录优化； ## 21日 * 修复场景信息计数错误的问题； * 当开启OutlinePass后处理时，设置场景渲染模式无效原因记录； * 为场景树节点按类型替换图标； * 替换viewCube,改用three-viewport-gizmo； * 完善three-viewport-gizmo的使用； ## 22日 * controls改用camera-controls； * 览模式下不添加模型Helper； * 资源库材质名称改为动态材质； * 默认场景贴图改为1k贴图； * 修复截屏空白的错误； * 改进场景渲染条件逻辑； * 将全局Loading signal替换为Pinia store； * 将Splitpanes替换为Naive UI Split组件； * 修复当播放动画时render调用逻辑错误没有循环渲染的问题； ## 23日 * 整理Scene组件代码结构； * 添加底部扩展面板(ExtraPane)组件； ## 24日 * 修改脚本地址，修改README； * 添加log类； ## 25日 * 完善Log系统； * 添加场景分割线大小持久化存储 ## 26日 * 新增动画编辑器前端组件； * 修复首页预览图显示过高的bug； * 修复编辑器无法清空场景的bug; ## 28日 * 动画编辑器进度 10%； --- --- url: /update/moioo5zp/index.md --- # 3月 ## 07日 * 新建Cesium融合场景 灵活配置cesium token、底图及底图类型; ## 08日 * 采用两个Canvas画布的方案成功将Cesium场景与ThreeJS场景融合; * Three摄像机视锥体远端面默认值修改为100,000; * 融合场景下引入Three的TransformControls; ## 09日 * Cesium融合场景下,Three TransformControls 拖动时锁定cesium场景渲染; * Cesium融合场景下,解决Three Scene 与 Three SceneHelper场景中心点重叠时，TransformControls绑定物体后自身定位偏移的BUG; ## 10日 * 解决EsInputNumber数值组件不随Object3D属性改变的BUG; * 添加 - 环境光 功能默认环境光颜色改为 0xffffff; * 解决材质组件下颜色选择器触发修改颜色后值永远为0(黑色)的BUG (需要使用十六进制值Hex色值); * 解决材质组件下设置面报错 Uncaught (in promise) RangeError: Maximum call stack size exceeded 的BUG; * 解决 场景ID/场景标题/场景描述/场景版本 设置保存后回显不存在的BUG; * 解决 场景ID/场景标题/场景描述/场景版本 网络拉取场景后执行 editor.clear() 被清空的BUG; * 解决 文件-发布 功能生成的项目文件不可用的问题；添加该功能演示环境不可用的提示； ## 13日 * Cesium融合场景保存至服务器时添加Loading效果; * 删除示例菜单(网络->从服务器获取工程 功能与示例功能效用相似); * 帮助菜单下添加此项目文档链接; * 去除菜单选中效果; ## 20日 * 本地indexDB存储为支持大模型场景存储，拆分为basic、images、geometry、models多表； ## 22日 * 解决侧边场景面板下修改背景、环境、雾不生效的BUG; * 解决本地IndexDB存储无贴图场景失败的BUG; ## 29日 * 场景树拖放功能开发; * 解决sceneJson解析有报错时notice.destroy()不执行的BUG; --- --- url: /update/oeg8mvgy/index.md --- # 5月 ## 14日 * 演示站点禁止删除场景； * 更正文档地址； ## 20日 * 新增多个ShaderMaterial材质贴图选项； * 更新渲染机制以支持动态ShaderMaterial材质; * 更新预览态以支持动态ShaderMaterial材质; ## 30日 * 解决GridHelper穿模显示的Bug; --- --- url: /update/oju4gahd/index.md --- # 8月 ## 29日 * 整站改用 又拍云 USS存储; --- --- url: /update/plan/vjlhhipo/index.md --- # 计划 * \[x] 场景数据无损压缩; * \[x] 网络分包渐进存取； * \[x] 支持30+模型格式； * \[x] `BIM`模型在线轻量化; * \[x] `CAD`图纸解析预览； * \[x] 碰撞检测 * \[x] 粒子系统 * \[x] 插件系统 * \[x] 动画编辑器 * \[x] Billboard、HtmlPanel(在线解析html、Vue/React打包工程) * \[ ] 资源中心 * \[ ] 数据组件 (API接口、前端SQL、WebSocket、静态JSON) * \[ ] Cesium场景融合（GIS支持） * \[ ] WebGPU 支持 * \[ ] 低代码数据大屏(:tada:开发阶段) --- --- url: /update/ptv58fgr/index.md --- # 6月 ## 1日 * (商用版本)修复场景保存后重新加载后处理显示配置错误的bug； * (商用版本)新增 像素风、LUT颜色滤镜 后处理效果； * (商用版本)新增 运动残影 后处理效果； * (商用版本)优化SDK配置项自执行逻辑； ## 2日 * (商用版本)优化脚本热更新； --- --- url: /update/ptvud2e5/index.md --- # 5月 ## 1日 * (商用版本)核心代码移植/重构至SDK-7； ## 2日 * (商用版本)核心代码移植/重构至SDK-8； * (商用版本)核心代码移植/重构至SDK-9； ## 18日 * (商用版本)核心代码移植/重构至SDK-10； * (商用版本)核心代码移植/重构至SDK-11； ## 19日 * (商用版本)核心代码移植/重构至SDK-12； * (商用版本)核心代码移植/重构至SDK-13； * (商用版本)核心代码移植/重构至SDK-14； ## 20日 * (商用版本)核心代码移植/重构至SDK-15； * (商用版本)核心代码移植/重构至SDK-16； ## 21日 * (商用版本)核心代码移植/重构至SDK-17； ## 30日 * (商用版本)核心代码移植/重构至SDK-18； ## 31日 * (商用版本)核心代码移植/重构至SDK完毕； > **移植重构过程中产生如下功能变更：** > > 1. 脚本功能变化： > * 生命周期`init`更名为`loaded`; > * 新增`onPick`,`onDoubleClick`,`onTouchStart`,`onTouchEnd`事件; > * 新增编辑态支持脚本运行； > * 脚本支持热更新运行； > 2. 新增帧率上限控制能力（默认上限60FPS）； > 3. 由GoLang后端迁移至Java后端； > 4. 其他忘了。 --- --- url: /update/rw89vgwo/index.md --- # 12月 ## 21日 * 预览态：漫游锁定鼠标； * 修复使用示例场景创建项目时排序错误的问题； * 项目操作选项label中英文切换； * 新增项目说明及关键字(SEO); * 新增项目详情弹窗; ## 23日 * 解决操作栏点击穿透到场景的问题； * 编辑器新增天气模块，重构Fog至天气模块； ## 24日 * 修复漫游人物陷入地下的bug； --- --- url: /update/sfp23i9i/index.md --- # 5月 ## 07日 * 取消了 Scene.toJson() 再分割数据保存至数据库的方案。更改为场景数据整合压缩打包存储； ## 09日 * 新增图纸组件； * 新增主区域图纸分栏； ## 10日 * 新增图纸矩形标注器； （1）确定要关联的模型；（2）确定关联的图纸矩形区域； --- --- url: /update/t48csw55/index.md --- # 6月 ::: tip 本月摆烂 爽是真的爽 ::: ## 29日 * 开源版本停更； --- --- url: /update/wjdm5npt/index.md --- # 1月 ## 8日 * 天气系统增加雨天效果； * Object3D新增ignore属性及traverseByCondition方法； * 编辑器的grid从SceneHelper迁移至主Scene; ## 9日 * 增加雪天（还需配置打包及预览，仍需优化以支持纯色材质）； ## 10日 * 完善雪效果及打包加载预览雪效果； ## 12日 * 修复雪天漫游选择初始位置会被雪平面遮挡而选中雪平面的问题； ## 13日 * 域名相关修改指向astraljs.com； * upyun默认上传位置修改； * 首页轮播图和默认图修改； ## 23日 * 默认环境贴图从upyun移动至项目静态资源； * 打包时处理背景和环境贴图不存在的情况； ## 24日 - 26日 * 修改六视图实现方式； --- --- url: /update/xis3xfo2/index.md --- # 3月 ## 01日 * 新增内置模型几何配置：`Capsule、Circle、Cylinder、Dodecahedron、Extrude、Tube、Icosahedron、Lathe、Octahedron、Plane`; ## 04日 * 新增内置模型几何配置：`Ring、Shape、Sphere`; ## 11日 * 新增内置模型几何配置：`Teapot、Tetrahedron、Torus、TorusKnot`; ## 19日 * `UserData`(自定义数据)的录入改用 `monaco-editor`;![自定义数据](/images/2024/03/UserData.png) ## 20日 * 修改`WebSocket`连接信息; ## 21日 * 新增`Player`预览场景;![预览界面](/images/2024/03/PlayerPreview.png) ## 22日 * 去除自动保存，改用手动保存按钮; * 新增出码功能； * 清除历史遗留变量； * BIM上传轻量化新增多个可配置项（极致轻量化 | 导出属性 | 转换视图 | 视觉样式 | 提取坐标系）;![BIM转换配置](/images/2024/03/BIMConversionSetting.png) ## 25日 * 采用新布局，优化界面显示； ## 26日 * 增加 PDMS(.rvm) 模型支持； ## 27日 * 增加 CAD 文件上传解析预览；![CAD预览](/images/2024/03/cad.png) ## 28日 * 图纸新增工具栏； * 图纸工具栏-复位功能； * 图纸工具栏-改色功能； * 图纸工具栏-图层控制； * 图纸工具栏-新增标记功能； * 图纸工具栏-删除标记功能；![CAD工具栏](/images/2024/03/cad-toolbar.png) ## 31日 * 场景Toolbar改用新UI;![Toolbar](/images/2024/03/scene-toolbar.png) * 更新资源库图标; * 更改默认天空盒; * 更改资源Tabs默认选中BIM; --- --- url: /update/xnmgi5kk/index.md --- # 4月 ## 4日 * 去除无用Signal； * 修改资源中心材质默认平铺方式为简单重复； * 修改默认色调映射和CSM光强度； * 修改打包config生成； ## 6日 * 新增扩展面板`Billboard资源`(1)； * 修复材质相关配置项语法错误； ## 7日 * 新增扩展面板`Billboard资源`(2); ## 9日 * 重构目录结构； * 完善Billboard； ## 10日 * 新增扩展面板`HtmlPanel`资源; * 场景新增`HtmlPlane`支持; ## 11日 * 修复打包后预览白屏； ## 12日 * 修复`loader`用法； * 改变`monaco-editor`用法； ## 13日 * 新增`HtmlPanel`配置面板; * 完善`HtmlPanel` Zip解析; ## 14日 * 完善`HtmlPanel` Zip解析; ## 15日 * 解决`cad\bim`上传按钮点击无响应的bug; ## 16日 * 修复属性面板旋转属性数据精度问题； * 修改位置旋转缩放默认步进速度； * 修复全局光影造成的材质条纹； ## 24日 * 改用`monorepo(pnpm workspace)`方式管理此项目(商用版本); * (商用版本)核心代码移植/重构至SDK-1; * (商用版本)核心代码移植/重构至SDK-2; ## 26日 * (商用版本)核心代码移植/重构至SDK-3； ## 27日 * (商用版本)核心代码移植/重构至SDK-4； ## 28日 * (商用版本)核心代码移植/重构至SDK-5； ## 30日 * (商用版本)核心代码移植/重构至SDK-6； --- --- url: /update/ycbwubyy/index.md --- # 4月 ## 01日 * 修改网络存储，去除footer设置弹窗界面的服务器地址input框； ## 05日 * 添加默认环境贴图及背景贴图； ## 07日 * 修复hdr贴图由于 toJson() 时是转换为 Uint16Array 而无法保存至服务器的问题；修复相关边界情况； ## 08日 - 10日 * 后端接口程序使用go语言重写；