@nebula-spatial/viewer 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.4.2
+
+### Fixed
+
+- 修复 `assets.openUsdBaseUrl` 指向跨域 runtime 时，OpenUSD pthread Worker 因入口同源限制抛出 `SecurityError` 的问题；通过 Blob 模块入口导入远端 runtime，保留同源与 Node 加载行为，并补充回归测试及 CORS、CSP 部署说明。
+
+## 0.4.1
+
+### Added
+
+- 内置普通模型预览新增 FBX 格式，支持按 `.fbx` 扩展名自动识别，并复用模型舞台、相机适配、up-axis 切换和资源释放契约；FBX 优先按文件 `GlobalSettings` 的正向 Y/Z up-axis 声明转换到 Viewer 的 Z-up 世界，无法判断时回退 Y-up，并可由显式 `upAxis` 覆盖；FBXLoader 生成的传统 Lambert/Phong 材质会转换为可由 Viewer 环境光照明的 PBR 材质。
+
 ## 0.4.0
 
 0.4.0 将 Viewer 从以 CAD 为主的 facade 扩展为统一资产预览器，并把 3D 模型与仿真资产接入同一个 Three.js 场景、相机、渲染器和帧循环。CAD 专属状态仍保留在 `viewer.cad`，但资产生命周期、内置 UI、加载状态和扩展机制已统一。

package/README.md

@@ -1,7 +1,7 @@
 # @nebula-spatial/viewer
 
 浏览器侧只读 Three.js 统一资产 Viewer Facade。负责场景运行时、相机、输入、拾取、渲染循环和
-资源释放；`openAsset()` 统一加载 CAD、GLB/glTF、URDF、MJCF 与 USD，`viewer.cad` 保留与
+资源释放；`openAsset()` 统一加载 CAD、GLB/glTF、FBX、URDF、MJCF 与 USD，`viewer.cad` 保留与
 `@nebula-spatial/cad-loader` 集成的兼容能力。
 
 Viewer 不解析 DXF/DWG，也不提供编辑命令、历史记录或业务状态管理。
@@ -211,6 +211,8 @@ Three.js Camera。应用成功后会同步发布 `camera-change` 和 `viewport-c
 
 ```ts
 const preview = viewer.openAsset('/models/robot.glb', { format: 'auto' });
+// .fbx 扩展名同样可自动识别：
+const fbxPreview = viewer.openAsset('/models/chair.fbx');
 const stop = preview.subscribe((snapshot) => updateLoadingUi(snapshot));
 await preview.ready;
 await preview.close();
@@ -221,7 +223,7 @@ stop();
 旧句柄的 `close()` 只等待自己的资源清理，不会关闭后来打开的资产。`closeAsset()` 关闭调用瞬间
 的活动资产。普通模型以 borrowed 方式挂入唯一 scene runtime，GPU 资源只由模型 session 释放。
 
-GLB/glTF 文件没有权威的 up 轴声明（规范 Y-up，CAD 导出常为 Z-up）。预览世界固定 Z-up；
+GLB/glTF 与 FBX 模型的 authored up 轴在 Viewer 中统一由 `upAxis` 声明。预览世界固定 Z-up；FBX 会先读取 `GlobalSettings` 中正向的 Y/Z `UpAxis` 与 `UpAxisSign` 声明，声明缺失、损坏或当前不支持时才回退到 Y-up。显式传入的 `upAxis` 始终优先；GLB/glTF 为兼容 CAD-kernel 导出继续默认使用 Z-up；
 对轴向错误的模型传 `upAxis: 'y'` 打开（仅旋转资产根节点，不移动相机与世界），或运行期用
 `preview.setUpAxis('y' | 'z')` / `preview.getUpAxis()` 切换（切换后自动重铺地面并重新适配
 相机，不平移贴地）。能力标志为 `capabilities.canReorientUpAxis`。仿真资产的格式自带 up 轴，
@@ -286,21 +288,22 @@ const preview = viewer.openAsset('https://cdn.example.com/robot/scene.xml', {
     },
   },
 });
-await preview.ready;
-```
-
-对于私有 OSS/S3/CDN，常见的预签名 URL 只授权一个具体 Object Key。`root.usd` 的签名通常不能
-复用于 `asset.usdc`、`physics/physics.usda`、纹理等兄弟资源，也不能把入口 URL 的 query
-原样拼接到其他路径。`resourceResolver.resolve(path)` 必须为每个 `path` 返回独立有效的签名 URL
-或已经取得的 `Blob`；入口 URL 自身也必须仍在有效期内。USD loader 会先提取分层 USD 的外部
-引用，再通过该 resolver 递归取得 layer、mesh、material 和 texture 资源；任一依赖返回 401/403
-都会作为鉴权加载失败报告，不会进入视觉降级流程。
-
-`{ kind: 'files', files, entry }` 只表示浏览器已经持有的本地 `File | Blob` 文件包，不能把远端
+await preview.ready;
+```
+
+对于私有 OSS/S3/CDN，常见的预签名 URL 只授权一个具体 Object Key。`root.usd` 的签名通常不能
+复用于 `asset.usdc`、`physics/physics.usda`、纹理等兄弟资源，也不能把入口 URL 的 query
+原样拼接到其他路径。`resourceResolver.resolve(path)` 必须为每个 `path` 返回独立有效的签名 URL
+或已经取得的 `Blob`；入口 URL 自身也必须仍在有效期内。USD loader 会先提取分层 USD 的外部
+引用，再通过该 resolver 递归取得 layer、mesh、material 和 texture 资源；任一依赖返回 401/403
+都会作为鉴权加载失败报告，不会进入视觉降级流程。
+
+`{ kind: 'files', files, entry }` 只表示浏览器已经持有的本地 `File | Blob` 文件包，不能把远端
 URL 字符串放进 `files[].file`。业务层负责入口选择、必要的格式判断、鉴权和依赖映射；不能只依赖
-Viewer 自动识别所有资产形态，也不能把本地样本验证等同于任意远端资产都兼容。普通 glTF 的
-外部资源仍由 `GLTFLoader` 按 URL 请求，不应假设所有格式的子资源都经过 `resourceResolver`；
-私有 glTF 资产优先采用同源/签名目录，或交付为 GLB。
+Viewer 自动识别所有资产形态，也不能把本地样本验证等同于任意远端资产都兼容。普通 glTF 与 FBX 的
+外部资源仍由对应 Three.js loader 按 URL 请求，不应假设这些格式的子资源都经过 `resourceResolver`；
+私有 glTF/FBX 资产优先采用同源或可独立鉴权的资源目录。单个本地 FBX 文件适合使用内嵌纹理；
+若纹理是外置文件，应使用可保持相对目录结构的远端 URL。
 
 OpenUSD 使用 pthread WASM，部署必须在安全上下文中提供以下响应头：
 
@@ -312,7 +315,10 @@ Cross-Origin-Embedder-Policy: require-corp
 `@mujoco/mujoco` 和 `@openusd-wasm/three-loader` 保持动态加载。Vite 浏览器构建需要将 MuJoCo
 包中的 Node-only 裸模块 `module` 精确 alias 到一个导出 `createRequire()` 的浏览器拒绝模块；
 仓库的 `vite.config.ts` 和独立消费者验证脚本包含该配置。可通过 `assets.mujocoBaseUrl` 与
-`assets.openUsdBaseUrl` 指向自行托管的 runtime 文件目录。
+`assets.openUsdBaseUrl` 指向自行托管的 runtime 文件目录。
+跨域 OpenUSD runtime 使用 Blob 模块 Worker 入口导入原始 runtime；CDN 仍需允许 CORS，
+若部署配置了 CSP，还需允许 `worker-src blob:` 及对应 CDN 的脚本加载。该入口不替代上述跨源隔离响应头。
+
 
 ## CAD 快速开始
 

package/dist/assets/types.d.ts

@@ -2,7 +2,7 @@ import type { Object3D, WebGLRenderer, Scene, Camera, Box3, ColorRepresentation
 import type { CadLoadSource, CadOpenOptions } from '../cad/types';
 import type { ViewerViewMode } from '../types';
 export type AssetPreviewKind = 'cad' | 'model' | 'simulation';
-export type BuiltinAssetFormat = 'cad' | 'glb' | 'gltf' | 'urdf' | 'mjcf' | 'usd' | 'usda' | 'usdc' | 'usdz';
+export type BuiltinAssetFormat = 'cad' | 'glb' | 'gltf' | 'fbx' | 'urdf' | 'mjcf' | 'usd' | 'usda' | 'usdc' | 'usdz';
 export type AssetFormat = BuiltinAssetFormat | (string & {});
 export interface AssetFileEntry {
     readonly path: string;
@@ -37,10 +37,11 @@ export interface OpenAssetOptions {
     readonly mujocoBaseUrl?: string;
     readonly openUsdBaseUrl?: string;
     /**
-     * Which authored axis is "up" for a plain model asset. glTF's normative
-     * coordinate system is Y-up, but CAD-kernel exporters emit Z-up files with no
-     * in-file declaration, so this cannot be inferred reliably. Defaults to 'z',
-     * matching the preview world; 'y' rotates the model root into world +Z.
+     * Which authored axis is "up" for a plain model asset. FBX first uses a
+     * supported positive Y/Z declaration from GlobalSettings, then falls back to
+     * 'y' when it is missing or cannot be read. GLB/glTF retain the existing 'z'
+     * default for CAD-kernel compatibility. An explicit value always wins. 'y'
+     * rotates the model root into world +Z.
      * Ignored by simulation assets, whose formats declare their own up axis.
      */
     readonly upAxis?: AssetUpAxis;

package/dist/{index-Lsk3kHNe.js → index-C9CW-EyW.js}

@@ -5758,7 +5758,7 @@ const ss = {
       kind: "asset-loader",
       id: "nebula.model-loader",
       assetKind: "model",
-      formats: ["glb", "gltf"],
+      formats: ["glb", "gltf", "fbx"],
       presentation: {
         preferredViewMode: "3d",
         interactionMode: "object",
@@ -5769,7 +5769,7 @@ const ss = {
         clearColor: B.dark
       },
       async createSession(e, t) {
-        const { createModelSession: i } = await import("./session-CGaj14lM.js");
+        const { createModelSession: i } = await import("./session-B2SfkK9o.js");
         return i(e, t);
       }
     });
@@ -5853,7 +5853,7 @@ const cs = {
         clearColor: B.dark
       },
       async createSession(e, t) {
-        const { createSimulationSession: i } = await import("./session-B_UiRctl.js").then((r) => r.s);
+        const { createSimulationSession: i } = await import("./session-B-qVl3Yy.js").then((r) => r.s);
         return i(e, t);
       }
     });

package/dist/index.js

@@ -1,4 +1,4 @@
-import { c as o } from "./index-Lsk3kHNe.js";
+import { c as o } from "./index-C9CW-EyW.js";
 import { configureCadTextBuilder as t } from "@nebula-spatial/cad-loader";
 export {
   t as configureViewerText,