astral3d

name	astral3d
description	Astral3D 是开源的 3D 工业可视化与编辑框架，提供基于 Web 的轻量三维场景搭建、模型导入（glTF/OBJ/FBX/STEP）、设备孪生、动画与交互编辑能力，常用于工业 IoT、数字孪生、智慧园区、CAD/BIM 轻量化展示。
tags	["web","3d","visualization","threejs","digital-twin","gltf","step"]

项目地址： https://github.com/AstralEngine/astral3d（如仓库迁移请以 znlgis.github.io 链接为准）

演示： https://astral3d.com/

许可证： Apache-2.0 / MIT（视具体仓库）

概述

Astral3D 主要特性：

• 基于 Three.js / Babylon.js 的高层封装
• 场景编辑器：可视化拖拽、属性面板、节点树
• 资产管理：模型库、材质库、HDR 环境
• 动画与状态机：物体动画、相机路径、时间轴
• 交互：射线拾取、点击、悬浮、UI 弹窗
• 数据接入：MQTT、WebSocket 实时推送
• 导出：JSON 场景、glTF、嵌入 SDK

不同发行版（开源版 / 商业版 / 企业版）功能差异较大，本 SKILL 聚焦开源版与通用 SDK 用法。

---

安装

# Web SDK（npm）
npm install astral3d

# 编辑器（如有桌面版）：从官网下载

CDN：

<script src="https://cdn.jsdelivr.net/npm/astral3d/dist/astral3d.umd.js"></script>

---

入门：嵌入页面

<div id="scene" style="width:100%;height:100vh"></div>
<script type="module">
  import { Viewer } from 'astral3d';

  const viewer = new Viewer({
    container: document.getElementById('scene'),
    scene: '/scenes/factory.json',     // 由编辑器导出
    background: 'env/sky.hdr'
  });

  await viewer.load();

  // 监听点击事件
  viewer.on('pick', (obj) => console.log('clicked', obj.name));
</script>

---

场景模型

概念	说明
Scene	场景容器（场景树、灯光、相机）
Asset	资源（模型、纹理、HDR）
Entity	场景节点
Component	实体组件（Transform、Mesh、Light、Animator、Script）
Plugin	编辑器/运行时插件

---

加载模型

import { ModelLoader } from 'astral3d';

const car = await ModelLoader.load('/models/car.glb');
viewer.scene.add(car);

// 设置位置 / 旋转
car.position.set(10, 0, 0);
car.rotation.y = Math.PI / 4;

支持格式：glTF/GLB（首选）、OBJ、FBX、STL、IFC、STEP（通过 OCCT.js）。

---

场景编辑器

Astral3D 通常配套桌面/Web 编辑器：

1. 新建场景 → 选模板（空 / 工业园区 / 数据中心）
2. 拖入模型库资产
3. 编辑材质、灯光、HDR
4. 设置交互（点击事件、动画轨道）
5. 导出 .json 场景文件 → 由 Viewer 加载

---

数据驱动（IoT 实时）

import { MqttBridge } from 'astral3d';

const bridge = new MqttBridge('wss://broker:8083/mqtt');
bridge.subscribe('factory/device/+/temp', (topic, payload) => {
    const id = topic.split('/')[2];
    const dev = viewer.scene.findById(id);
    dev.userData.temp = +payload;
    dev.material.color.setHSL(0.6 - payload/100, 1, 0.5);
});

或 WebSocket：

const ws = new WebSocket('wss://server/iot');
ws.onmessage = ({ data }) => {
    const { id, status } = JSON.parse(data);
    viewer.scene.findById(id).visible = status === 'on';
};

---

交互与拾取

viewer.on('hover', (e) => {
    const obj = e.intersect?.object;
    if (obj) viewer.outline(obj);
});

viewer.on('pick', (e) => {
    const obj = e.intersect?.object;
    viewer.popup({
        target: obj,
        html: `<div class="card">${obj.name} 状态：${obj.userData.status}</div>`
    });
});

---

相机控制与漫游

viewer.camera.flyTo({
    position: [50, 30, 80],
    target:   [0, 0, 0],
    duration: 2000
});

viewer.camera.firstPerson(true);     // 第一人称漫游
viewer.camera.followPath('path1');   // 路径漫游

---

动画

const animator = viewer.scene.findById('door').getComponent('Animator');
animator.play('open');         // 编辑器内定义的动画片段

// 时间轴 API
viewer.timeline
   .add('door.position.x', { from: 0, to: 5, duration: 1000 })
   .add('door.rotation.y', { to: Math.PI/2, duration: 1500 })
   .play();

---

典型工作流

工作流一：IoT 数字孪生场景搭建

1. 使用 Astral3D 编辑器新建场景，拖入厂房模型（glTF），布置灯光与 HDR 背景
2. 为设备节点命名（如 sensor_A1），配置交互弹窗模板
3. 导出 factory.json 场景文件
4. 在前端页面实例化 Viewer，加载场景文件
5. 通过 MqttBridge 连接 MQTT Broker，订阅设备遥测主题
6. 在回调中根据设备 ID 更新对应节点的颜色/透明度/标签

工作流二：Web 端轻量化 CAD 预览

1. 从服务端获取 STEP/IFC 文件 URL
2. 使用 ModelLoader.load() 加载模型（底层调用 OCCT.js 解析）
3. 将模型加入场景，调整位置、缩放
4. 添加 OrbitControls 供用户旋转/缩放查看
5. 可选：添加剖面裁剪（clipping plane）查看内部结构

---

性能优化

1. glTF Draco 压缩 + KTX2 纹理 减小加载体积
2. 静态合批：场景导出时启用 mergeStatic
3. LOD：编辑器为模型生成 3 级 LOD
4. 物理光照贴图：烘焙到资产中
5. Frustum culling + occlusion culling 默认开启
6. Worker 解码：DRACO/KTX2/FBX 使用独立 Worker
7. PBR 关闭高反射时改 unlit 材质

---

常见问题

问题	解决
模型加载失败	检查 CORS；统一用 glTF 2.0
中文按钮乱码	字体子集中包含 CJK
实时推送延迟	MQTT QoS 0；服务器 → 浏览器 WebSocket 直连
移动端发热	关闭实时阴影、降低分辨率 viewer.setPixelRatio(1)
相机穿透	启用碰撞或限制 minDistance

---

AI 使用建议

• 推荐工作流模式：AI 助手应优先使用编辑器导出的 .json 场景文件作为基础，再通过 API 动态注入数据和交互——避免在代码中手动构造复杂场景树。
• 关键注意事项：① MQTT/WebSocket 连接需处理断线重连；② 模型路径需确保 CORS 配置正确；③ glTF Draco 压缩后的模型需要 DRACOLoader 支持；④ 移动端需主动降低 pixelRatio 与关闭阴影。
• 常用代码模式：场景加载 → 数据源接入 → viewer.scene.findById() 定位节点 → 更新节点属性（颜色/位置/可见性）。对于新模型，优先使用 ModelLoader.load() 而非底层 Three.js API。

---

相关技能

• chili3d — Web CAD 参数化建模与 OCCT.js 集成：../chili3d/SKILL.md
• lightcad — 轻量 Web 2D CAD 框架与 DXF 编辑：../lightcad/SKILL.md
• occt — 底层 OCCT 几何内核（STEP/IGES/BREP）：../occt/SKILL.md

---

参考资源

• 仓库：https://github.com/AstralEngine/astral3d
• 演示：https://astral3d.com/
• 中文教程（znlgis）：https://znlgis.github.io/cad/tutorial/astral3d/

如官方文档/仓库地址有调整，请以 znlgis.github.io 中的最新链接为准。