@nebula-spatial/studio 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (262) hide show
  1. package/README.md +206 -3
  2. package/dist/ai/contract.d.ts +73 -0
  3. package/dist/ai/host.d.ts +28 -0
  4. package/dist/asset/dependency-scan.d.ts +78 -0
  5. package/dist/asset/intake.d.ts +84 -0
  6. package/dist/asset/layout-detect.d.ts +40 -0
  7. package/dist/asset/media-type.d.ts +10 -0
  8. package/dist/asset/model-inspection.d.ts +127 -0
  9. package/dist/asset/record.d.ts +35 -0
  10. package/dist/asset/remote-asset-resolver.d.ts +36 -0
  11. package/dist/asset/repairs.d.ts +53 -0
  12. package/dist/asset/resource-locator.d.ts +15 -0
  13. package/dist/asset/revision-diff.d.ts +33 -0
  14. package/dist/asset/source-contracts.d.ts +21 -0
  15. package/dist/asset/source-paths.d.ts +15 -0
  16. package/dist/asset/usd-inspection.d.ts +39 -0
  17. package/dist/asset/usd-source-metadata.d.ts +142 -0
  18. package/dist/asset/visual-intake.d.ts +27 -0
  19. package/dist/asset/visual-record.d.ts +22 -0
  20. package/dist/asset/web-intake.d.ts +46 -0
  21. package/dist/asset-source-BExlEcRt.js +444 -0
  22. package/dist/assets/openusd_three_loader-DLiqJWUM.js +13769 -0
  23. package/dist/assets/usd-export-worker-BRxTLqer.js +182 -0
  24. package/dist/assets/usd-worker-DekqMsQv.js +1392 -0
  25. package/dist/builders-BAXRR5o5.js +1854 -0
  26. package/dist/core/asset-task.d.ts +105 -0
  27. package/dist/core/context.d.ts +23 -0
  28. package/dist/core/host.d.ts +432 -0
  29. package/dist/core/persistence-controller.d.ts +58 -0
  30. package/dist/core/plugins.d.ts +139 -0
  31. package/dist/core/scene-tree.d.ts +62 -0
  32. package/dist/core/versions.d.ts +2 -0
  33. package/dist/core/when.d.ts +13 -0
  34. package/dist/core/write-policy.d.ts +29 -0
  35. package/dist/delivery/build-plan.d.ts +2 -0
  36. package/dist/delivery/contracts.d.ts +362 -0
  37. package/dist/delivery/digest.d.ts +3 -0
  38. package/dist/delivery/evidence.d.ts +10 -0
  39. package/dist/delivery/export-evidence.d.ts +3 -0
  40. package/dist/delivery/index.d.ts +9 -0
  41. package/dist/delivery/prim-name.d.ts +17 -0
  42. package/dist/delivery/profile.d.ts +4 -0
  43. package/dist/doc/builders.d.ts +99 -0
  44. package/dist/doc/command.d.ts +195 -0
  45. package/dist/doc/domain-extensions.d.ts +34 -0
  46. package/dist/doc/node-facts.d.ts +87 -0
  47. package/dist/doc/physics-facts.d.ts +74 -0
  48. package/dist/doc/placement-policy.d.ts +71 -0
  49. package/dist/doc/random-placement.d.ts +30 -0
  50. package/dist/doc/scene-graph.d.ts +80 -0
  51. package/dist/doc/scene-regions.d.ts +29 -0
  52. package/dist/doc/schema.d.ts +452 -0
  53. package/dist/doc/task.d.ts +71 -0
  54. package/dist/doc/validate.d.ts +68 -0
  55. package/dist/editor/asset-source.d.ts +15 -0
  56. package/dist/editor/editor.d.ts +246 -0
  57. package/dist/editor/index.d.ts +22 -0
  58. package/dist/editor/shortcuts.d.ts +2 -0
  59. package/dist/editor/types.d.ts +143 -0
  60. package/dist/editor/ui-plugins.d.ts +64 -0
  61. package/dist/editor.js +1755 -0
  62. package/dist/editorial-BkAFWfbg.js +83 -0
  63. package/dist/export-evidence-DMNRhgL9.js +2705 -0
  64. package/dist/generalization/domain.d.ts +10 -0
  65. package/dist/generalization/generalization.d.ts +371 -0
  66. package/dist/generalization/index.d.ts +11 -0
  67. package/dist/generalization.js +1659 -0
  68. package/dist/history/undo-stack.d.ts +74 -0
  69. package/dist/index.d.ts +91 -0
  70. package/dist/index.js +2840 -0
  71. package/dist/mjcf-visual-Bt4bUxd1.js +72 -0
  72. package/dist/mujoco-runtime-BYZnrvbR.js +467 -0
  73. package/dist/persist/content-addressed.d.ts +11 -0
  74. package/dist/persist/create-scene-package-from-host.d.ts +7 -0
  75. package/dist/persist/indexeddb-store.d.ts +69 -0
  76. package/dist/persist/scene-file.d.ts +52 -0
  77. package/dist/persist/scene-package.d.ts +8 -0
  78. package/dist/persist/snapshot.d.ts +5 -0
  79. package/dist/physics-facts-tfQYyNTD.js +337 -0
  80. package/dist/placement-policy-DY_FNRDu.js +405 -0
  81. package/dist/ports/asset-ingestor.d.ts +41 -0
  82. package/dist/ports/asset-source.d.ts +57 -0
  83. package/dist/ports/delivery.d.ts +13 -0
  84. package/dist/ports/persistence.d.ts +29 -0
  85. package/dist/project/asset-catalog.d.ts +21 -0
  86. package/dist/project/contracts.d.ts +272 -0
  87. package/dist/project/editorial.d.ts +16 -0
  88. package/dist/project/identity.d.ts +20 -0
  89. package/dist/project/index.d.ts +9 -0
  90. package/dist/project/scene-document.d.ts +5 -0
  91. package/dist/project/source-dependencies.d.ts +7 -0
  92. package/dist/remote-asset-resolver-Cb8cfNmw.js +136 -0
  93. package/dist/scene/index.d.ts +12 -0
  94. package/dist/scene-graph-DBLKAhxa.js +681 -0
  95. package/dist/scene-session-Cy6vDJ1l.js +21981 -0
  96. package/dist/scene.js +244 -0
  97. package/dist/session-BRBrCLdd.js +963 -0
  98. package/dist/session-DI5tPJxn.js +825 -0
  99. package/dist/session-q3uuG7OP.js +296 -0
  100. package/dist/studio/delivery-catalog.d.ts +28 -0
  101. package/dist/studio/in-memory-asset-source.d.ts +15 -0
  102. package/dist/studio/index.d.ts +31 -0
  103. package/dist/studio/indexeddb-asset-source.d.ts +32 -0
  104. package/dist/studio/indexeddb-persistence.d.ts +13 -0
  105. package/dist/studio/remote-asset-importer.d.ts +56 -0
  106. package/dist/studio/source-package.d.ts +9 -0
  107. package/dist/studio/usd-export-client.d.ts +13 -0
  108. package/dist/studio/usd-export-protocol.d.ts +98 -0
  109. package/dist/studio/usd-export-worker.d.ts +1 -0
  110. package/dist/studio/usd-zip-reader.d.ts +14 -0
  111. package/dist/studio/web-asset-ingestor.d.ts +10 -0
  112. package/dist/studio/web-host.d.ts +8 -0
  113. package/dist/studio.js +5545 -0
  114. package/dist/urdf-session-CQir2nb2.js +1230 -0
  115. package/dist/usd-session-DZJnEEOs.js +7385 -0
  116. package/dist/util/asset-facts.d.ts +3 -0
  117. package/dist/util/data.d.ts +17 -0
  118. package/dist/util/diagnostics.d.ts +38 -0
  119. package/dist/util/geometry.d.ts +11 -0
  120. package/dist/util/hash.d.ts +9 -0
  121. package/dist/util/ids.d.ts +20 -0
  122. package/dist/util/math.d.ts +47 -0
  123. package/dist/util/ply-metadata.d.ts +19 -0
  124. package/dist/util/studio-source.d.ts +23 -0
  125. package/dist/version.d.ts +5 -0
  126. package/dist/view/appearance.d.ts +13 -0
  127. package/dist/view/authoring-appearance.d.ts +25 -0
  128. package/dist/view/bounds-preview.d.ts +34 -0
  129. package/dist/view/bounds.d.ts +11 -0
  130. package/dist/view/camera-zoom.d.ts +3 -0
  131. package/dist/view/geometry-anchors.d.ts +20 -0
  132. package/dist/view/gizmo-appearance.d.ts +5 -0
  133. package/dist/view/gizmo.d.ts +81 -0
  134. package/dist/view/group-selection.d.ts +13 -0
  135. package/dist/view/node-features.d.ts +39 -0
  136. package/dist/view/picking.d.ts +49 -0
  137. package/dist/view/placement.d.ts +48 -0
  138. package/dist/view/region-editing.d.ts +25 -0
  139. package/dist/view/rotation-guide.d.ts +36 -0
  140. package/dist/view/runtime-capabilities.d.ts +22 -0
  141. package/dist/view/scene-session.d.ts +258 -0
  142. package/dist/view/screen-bounds.d.ts +17 -0
  143. package/dist/view/selection-transform.d.ts +20 -0
  144. package/dist/wasm-module-DZn2AM1W.js +13 -0
  145. package/dist/xacro-DLRXyk60.js +76 -0
  146. package/node_modules/@nebula-spatial/cad-loader/CHANGELOG.md +48 -0
  147. package/node_modules/@nebula-spatial/cad-loader/README.md +108 -0
  148. package/node_modules/@nebula-spatial/cad-loader/dist/core/cad-types.d.ts +26 -0
  149. package/node_modules/@nebula-spatial/cad-loader/dist/core/errors.d.ts +5 -0
  150. package/node_modules/@nebula-spatial/cad-loader/dist/core/index.d.ts +24 -0
  151. package/node_modules/@nebula-spatial/cad-loader/dist/core/index.js +2354 -0
  152. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/bin-group-reader.d.ts +9 -0
  153. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/bin-parser.d.ts +78 -0
  154. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/dxbs-sidecar.d.ts +24 -0
  155. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/geometry-segments.d.ts +20 -0
  156. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/text-roundtrip.d.ts +4 -0
  157. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/types.d.ts +81 -0
  158. package/node_modules/@nebula-spatial/cad-loader/dist/core/runtime-text-decoder.d.ts +8 -0
  159. package/node_modules/@nebula-spatial/cad-loader/dist/core/types.d.ts +153 -0
  160. package/node_modules/@nebula-spatial/cad-loader/dist/core/utils/insert-bbox.d.ts +10 -0
  161. package/node_modules/@nebula-spatial/cad-loader/dist/core/utils/viewport-rect.d.ts +21 -0
  162. package/node_modules/@nebula-spatial/cad-loader/dist/index.d.ts +36 -0
  163. package/node_modules/@nebula-spatial/cad-loader/dist/index.js +5829 -0
  164. package/node_modules/@nebula-spatial/cad-loader/dist/loader/geo-loader.d.ts +59 -0
  165. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/automatic-external-resources.d.ts +26 -0
  166. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/external-variant-sidecar-fetch.d.ts +13 -0
  167. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/flow-control.d.ts +29 -0
  168. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/frame-budget-scheduler.d.ts +21 -0
  169. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-compact-executor.d.ts +19 -0
  170. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-local-adapter.d.ts +2 -0
  171. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-pipeline.d.ts +92 -0
  172. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-worker-adapter.d.ts +13 -0
  173. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node-builder.d.ts +34 -0
  174. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node-load-sink.d.ts +28 -0
  175. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node.d.ts +304 -0
  176. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare-worker-types.d.ts +94 -0
  177. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare.d.ts +38 -0
  178. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare.worker.d.ts +1 -0
  179. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/insert-model-builder.d.ts +10 -0
  180. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/insert-runtime-geometry.d.ts +15 -0
  181. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/line-canonical.d.ts +37 -0
  182. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/line-quality.d.ts +9 -0
  183. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/prepare-credit-gate.d.ts +20 -0
  184. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/transport.d.ts +2 -0
  185. package/node_modules/@nebula-spatial/cad-loader/dist/render-resource/cad-render-node.d.ts +80 -0
  186. package/node_modules/@nebula-spatial/cad-loader/dist/render-resource/geo-node-cad-render-node.d.ts +12 -0
  187. package/node_modules/@nebula-spatial/cad-loader/dist/scene/geo-cad-line-geometry.d.ts +28 -0
  188. package/node_modules/@nebula-spatial/cad-loader/dist/scene/geo-cad-line-material.d.ts +18 -0
  189. package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/block-geometry-registry.d.ts +35 -0
  190. package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/insert-instance-table.d.ts +23 -0
  191. package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/viewport-instance-presenter.d.ts +66 -0
  192. package/node_modules/@nebula-spatial/cad-loader/dist/selection/cad-insert-selection.d.ts +35 -0
  193. package/node_modules/@nebula-spatial/cad-loader/dist/selection/cad-text-selection.d.ts +31 -0
  194. package/node_modules/@nebula-spatial/cad-loader/dist/session/annotation-idle-gate.d.ts +14 -0
  195. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-document-session.d.ts +187 -0
  196. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-font-runtime.d.ts +11 -0
  197. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-insert-id.d.ts +6 -0
  198. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-text-warmup.d.ts +38 -0
  199. package/node_modules/@nebula-spatial/cad-loader/dist/session/create-cad-document-session.d.ts +5 -0
  200. package/node_modules/@nebula-spatial/cad-loader/dist/session/load-session.d.ts +90 -0
  201. package/node_modules/@nebula-spatial/cad-loader/dist/session/viewport-coverage.d.ts +32 -0
  202. package/node_modules/@nebula-spatial/cad-loader/dist/shared/abort.d.ts +3 -0
  203. package/node_modules/@nebula-spatial/cad-loader/dist/shared/cad-display-color.d.ts +55 -0
  204. package/node_modules/@nebula-spatial/cad-loader/dist/shared/cad-load-source.d.ts +8 -0
  205. package/node_modules/@nebula-spatial/cad-loader/dist/shared/color-buffer.d.ts +6 -0
  206. package/node_modules/@nebula-spatial/cad-loader/dist/shared/constants.d.ts +11 -0
  207. package/node_modules/@nebula-spatial/cad-loader/dist/shared/display-color-buffer.d.ts +27 -0
  208. package/node_modules/@nebula-spatial/cad-loader/dist/shared/errors.d.ts +2 -0
  209. package/node_modules/@nebula-spatial/cad-loader/dist/shared/text-builder.d.ts +25 -0
  210. package/node_modules/@nebula-spatial/cad-loader/dist/shared/text-font.d.ts +12 -0
  211. package/node_modules/@nebula-spatial/cad-loader/dist/shared/types.d.ts +57 -0
  212. package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/insert-bbox.d.ts +1 -0
  213. package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/timing.d.ts +2 -0
  214. package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/viewport-rect.d.ts +1 -0
  215. package/node_modules/@nebula-spatial/cad-loader/dist/shared/viewer-theme.d.ts +2 -0
  216. package/node_modules/@nebula-spatial/cad-loader/dist/workers/geo-prepare.worker.js +2264 -0
  217. package/node_modules/@nebula-spatial/cad-loader/package.json +62 -0
  218. package/node_modules/@nebula-spatial/viewer/CHANGELOG.md +426 -0
  219. package/node_modules/@nebula-spatial/viewer/FBX-MATERIAL-CONVERSION.md +97 -0
  220. package/node_modules/@nebula-spatial/viewer/README.md +1056 -0
  221. package/node_modules/@nebula-spatial/viewer/USD-VISUAL-MATERIAL-SUPPORT.md +89 -0
  222. package/node_modules/@nebula-spatial/viewer/basis/basis_transcoder.js +19 -0
  223. package/node_modules/@nebula-spatial/viewer/basis/basis_transcoder.wasm +0 -0
  224. package/node_modules/@nebula-spatial/viewer/dist/asset-ir-DEOK9SqE.js +382 -0
  225. package/node_modules/@nebula-spatial/viewer/dist/assets/ground-grid.d.ts +6 -0
  226. package/node_modules/@nebula-spatial/viewer/dist/assets/source-types.d.ts +19 -0
  227. package/node_modules/@nebula-spatial/viewer/dist/assets/types.d.ts +393 -0
  228. package/node_modules/@nebula-spatial/viewer/dist/assets/usd-worker-Bom5cjz3.js +1392 -0
  229. package/node_modules/@nebula-spatial/viewer/dist/cad/text.d.ts +2 -0
  230. package/node_modules/@nebula-spatial/viewer/dist/cad/types.d.ts +368 -0
  231. package/node_modules/@nebula-spatial/viewer/dist/index-ByBlfVc0.js +12132 -0
  232. package/node_modules/@nebula-spatial/viewer/dist/index.d.ts +32 -0
  233. package/node_modules/@nebula-spatial/viewer/dist/index.js +26 -0
  234. package/node_modules/@nebula-spatial/viewer/dist/inspection/types.d.ts +112 -0
  235. package/node_modules/@nebula-spatial/viewer/dist/mjcf-visual-DVRa0w90.js +72 -0
  236. package/node_modules/@nebula-spatial/viewer/dist/mujoco-runtime-Dhx6Ua2u.js +463 -0
  237. package/node_modules/@nebula-spatial/viewer/dist/plugins.d.ts +179 -0
  238. package/node_modules/@nebula-spatial/viewer/dist/scene/instances.d.ts +36 -0
  239. package/node_modules/@nebula-spatial/viewer/dist/scene/types.d.ts +258 -0
  240. package/node_modules/@nebula-spatial/viewer/dist/session-B-j6KdA-.js +389 -0
  241. package/node_modules/@nebula-spatial/viewer/dist/session-B4AICTeJ.js +963 -0
  242. package/node_modules/@nebula-spatial/viewer/dist/session-BAG5cDYe.js +9153 -0
  243. package/node_modules/@nebula-spatial/viewer/dist/simulation/mujoco-runtime.d.ts +118 -0
  244. package/node_modules/@nebula-spatial/viewer/dist/simulation/mujoco-wasm-module.d.ts +11 -0
  245. package/node_modules/@nebula-spatial/viewer/dist/simulation/openusd-wasm-module.d.ts +10 -0
  246. package/node_modules/@nebula-spatial/viewer/dist/simulation/physics-runtime-state.d.ts +75 -0
  247. package/node_modules/@nebula-spatial/viewer/dist/simulation/types.d.ts +129 -0
  248. package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-inspection.d.ts +66 -0
  249. package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-query.d.ts +50 -0
  250. package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-resource-policy.d.ts +28 -0
  251. package/node_modules/@nebula-spatial/viewer/dist/types.d.ts +278 -0
  252. package/node_modules/@nebula-spatial/viewer/dist/ui/types.d.ts +48 -0
  253. package/node_modules/@nebula-spatial/viewer/dist/urdf-session-kemAnBn8.js +3231 -0
  254. package/node_modules/@nebula-spatial/viewer/dist/usd-session-QtwGKI7v.js +6771 -0
  255. package/node_modules/@nebula-spatial/viewer/dist/version.d.ts +5 -0
  256. package/node_modules/@nebula-spatial/viewer/dist/viewer.d.ts +2 -0
  257. package/node_modules/@nebula-spatial/viewer/dist/xacro-CYTPS7mh.js +1537 -0
  258. package/node_modules/@nebula-spatial/viewer/openusd/openusd-runtime-manifest.json +15 -0
  259. package/node_modules/@nebula-spatial/viewer/openusd/openusd_probe.js +14 -0
  260. package/node_modules/@nebula-spatial/viewer/openusd/openusd_probe.wasm +0 -0
  261. package/node_modules/@nebula-spatial/viewer/package.json +66 -0
  262. package/package.json +87 -6
@@ -0,0 +1,62 @@
1
+ {
2
+ "name": "@nebula-spatial/cad-loader",
3
+ "version": "0.3.1",
4
+ "description": "Browser-side DXB3/DXBS CAD pack loader runtime",
5
+ "license": "ISC",
6
+ "engines": {
7
+ "node": ">=18"
8
+ },
9
+ "type": "module",
10
+ "files": [
11
+ "dist",
12
+ "README.md",
13
+ "CHANGELOG.md",
14
+ "package.json"
15
+ ],
16
+ "main": "./dist/index.js",
17
+ "module": "./dist/index.js",
18
+ "types": "./dist/index.d.ts",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./dist/index.d.ts",
22
+ "import": "./dist/index.js",
23
+ "default": "./dist/index.js"
24
+ },
25
+ "./core": {
26
+ "types": "./dist/core/index.d.ts",
27
+ "import": "./dist/core/index.js",
28
+ "default": "./dist/core/index.js"
29
+ }
30
+ },
31
+ "sideEffects": false,
32
+ "scripts": {
33
+ "build": "npm run check:core-boundary && npm run check:core-types && npm run build:bundle && npm run build:types",
34
+ "build:bundle": "vite build --config vite.config.ts",
35
+ "build:types": "tsc --project tsconfig.build.json",
36
+ "check:core-boundary": "node scripts/check-core-boundary.mjs",
37
+ "check:core-types": "tsc --project tsconfig.core.json",
38
+ "typecheck": "tsc --project tsconfig.json --noEmit",
39
+ "test": "vitest run --config vitest.config.ts",
40
+ "pack:dry": "npm pack --dry-run",
41
+ "prepack": "npm run build"
42
+ },
43
+ "publishConfig": {
44
+ "access": "public"
45
+ },
46
+ "dependencies": {
47
+ "rbush": "^4.0.1",
48
+ "troika-three-text": "^0.52.3"
49
+ },
50
+ "peerDependencies": {
51
+ "three": "0.182.0"
52
+ },
53
+ "devDependencies": {
54
+ "@types/node": "^25.6.0",
55
+ "@types/rbush": "^4.0.0",
56
+ "@types/three": "0.182.0",
57
+ "three": "0.182.0",
58
+ "typescript": "^5.6.3",
59
+ "vite": "^5.4.10",
60
+ "vitest": "^2.1.8"
61
+ }
62
+ }
@@ -0,0 +1,426 @@
1
+ # Changelog
2
+
3
+ All notable changes to this package are documented in this file.
4
+
5
+ ## 0.5.7 (unreleased)
6
+
7
+ ### Added
8
+
9
+ - 新增 `compileOpenUsdWasmModule()`、`compileMujocoWasmModule()` 与 `assets.openUsdWasmModule`、`assets.mujocoWasmModule`:消费方可以自行保存编译 Promise,并在多个 Worker、Viewer 或仿真实例间复用同一个 `WebAssembly.Module`;Viewer 不增加全局 Module 缓存。
10
+
11
+ ### Behavior notes
12
+
13
+ - 未传入调用方 Module 时,OpenUSD Worker 和 MuJoCo runtime 仍各自获取 WASM,网络与缓存行为保持不变。传入 Module 后不再 fetch 对应 WASM;共享范围仅限编译产物,USD Worker、WASM Instance、线性内存、Stage,以及 MuJoCo Instance、`MjModel` 和 `MjData` 仍按模型隔离。
14
+ - 传入 Module 时改用异步 `WebAssembly.instantiate(module, imports)` 创建实例,避免 Chromium 禁止主线程同步实例化大于 8 MB WASM 内存而导致 MuJoCo 仿真无法启动。
15
+ - 使用 `assets.openUsdWasmModule` / `openAsset({ openUsdWasmModule })` 时不要调用 `prewarmUsdWorker()`;如果已有预热 Worker 与指定 Module 不匹配,Viewer 会终止预热 Worker 并按 Module 创建新 Worker。
16
+
17
+ ## 0.5.6
18
+
19
+ ### Added
20
+
21
+ - 接通 USD KTX2 解码链路:使用宿主 WebGL renderer 初始化 Three.js `KTX2Loader`,按纹理语义设置 sRGB/线性色彩空间,并提供与当前 Three.js 版本匹配的 Basis Universal Transcoder 发布文件(`basis/`)。
22
+ - OpenUSD 运行时新增内容寻址清单:JS 与 WASM 使用同一个 `runtimeId` 查询参数,清单同时记录两个文件的
23
+ SHA-256 和 Probe API 版本;Worker 初始化会拒绝缺少或不匹配 API 版本的运行时。
24
+ - 新增 `assets.ktx2TranscoderPath`、`assets.openUsdRuntimeId` 及单次 `openAsset` 覆盖项;新增 `AssetLoaderContext.getRenderer?()`,供需要宿主 renderer 的 loader 使用。
25
+ - 新增 USD variant 配置 `usdVariantSelections` 与 `usdVariantSelectionMode`(默认 `auto-mujoco`):在 composition 后、场景/物理提取前选择 `Physics` variant 的 Newton/Mjc/MuJoCo 分支,保留 authored grip 模式,无兼容分支时回退到 authored 选择。
26
+ - 新增 `prewarmUsdWorker()`、`preloadUsdViewer()` 与 `getUsdQuery(model)`,以及 `QueryableUsdModel`、`UsdQuery` 等类型:宿主可预热首个 USD Worker、预加载主线程模块图,并以同步(in-process)或异步(Worker)方式查询 live Stage 的 Prim/Attribute/Relationship/Metadata/Material。
27
+ - 统一资产提示模型:新增 `AssetNoticeKind`、`AssetNoticeSnapshot`,`AssetWarningSnapshot.notice` 为物理降级、无效资产、资源限制与运行时失败等警告提供稳定的标题、摘要与语气,内置状态层直接消费该提示。
28
+
29
+ ### Changed
30
+
31
+ - 本地 USD 包加载改为基于路径清单的按引用懒读取:不再把所有目录文件预写入 WASM,图片只映射纹理身份并由 Three.js 从原始 File Blob 解码;远程 URL 包仍按原策略预取。
32
+ - USD 改为“视觉优先、物理延后”的分阶段加载:Worker 内依次执行 `scene_visual` → 流式 `scene_geometry` → `scene_geometry_end` 释放 WASM 缓冲,主线程建树并完成材质适配后再发送 `extract-physics`;模型关闭时直接终止 Worker,整体回收几何、Stage 与线性内存。
33
+ - USD 视觉阶段按路径归一化材质输入图去重,只输出元素和 materialBind subset 实际引用的模板,并通过
34
+ `materialAliases` 保留原始路径;相同代表材质的 subset faces 合并后再进入拓扑修复。
35
+ - USD 视觉阶段现在同时输出继承后的 `purpose`、`doubleSidedAuthored` 和 UV 拓扑提示;purpose、
36
+ 透射材质双面策略不再逐 Mesh 查询 Worker,UV 修复也只在 `faceVarying + indexed` 且绑定材质需要纹理修复时进入。
37
+ - 大型 USD 资产默认启用渐进纹理加载:按入口实际引用的材质、纹理、顶点与元素规模判定,先以白膜预览,再由 Worker 缩放解码纹理、分帧上传并合并渲染;正常规模模型保持原有加载链路。
38
+ - 扩展 USD 物理语义:支持 Newton/PhysX mimic、惯量三角不等式修正、自碰撞过滤与碰撞 approximation 映射;URDF、USD 的物理降级与无效资产提示统一到同一套 notice。
39
+ - 物理仿真默认以静止姿态打开,播放后才允许拖拽施力;暂停会结束进行中的抓取。仅含 authored 动画片段、没有刚体的 USD 视觉场景仍按动画内容自动播放。
40
+ - 补充 USD 常见材质因子映射:glTF specular/clearcoat/IOR/anisotropy、OmniPBRBase 与 OmniSurfaceBase 的默认参数与可用粗糙度;高强度 glTF emission 保留降级诊断。
41
+
42
+ ### Fixed
43
+
44
+ - 修复 USD 标准 `<UDIM>` 纹理模板被当作字面文件名的问题:资源预取、单线程 Loader 与视觉材质适配现在会从包内实际文件枚举四位 UDIM tile;唯一 tile(包括非 `1001`)可直接绑定,多 tile 会按标准行列合成 atlas,并通过普通 Three.js 纹理矩阵采样,不再静默选错或整体丢失材质。
45
+ - 修复同时声明 `outputs:surface` 与 `outputs:mdl:surface` 的 USD 材质优先选择 MDL 终端的问题:现在优先使用 Loader 可渲染的 `UsdPreviewSurface`,避免材质 IR 丢失颜色、ORM 与法线连接。
46
+ - 修复重复材质实例分别解码同一 USD 纹理导致显存耗尽或部分 map 为空的问题:Viewer 内的单线程 Loader 现在共享源纹理缓存,材质槽继续保留各自采样配置。
47
+ - 修复 KTX2 被 USD 原生纹理构建器当作普通图片解码后留下空贴图、视觉适配层又拒绝接管的问题:KTX2 现在先保留可识别的同步占位,再由 renderer-aware 适配层完成转码与绑定。
48
+ - 修复聚合资产包中同名贴图的解析歧义:外部纹理改为以入口目录解析;并恢复 Worker 加载后的 USDZ 包内纹理 URL,避免贴图丢失。
49
+ - 修复旋转网格模型的地面贴齐与 MuJoCo 地面高度:网格 geom 使用编译后的顶点计算最低点,程序化几何继续按图元参数计算,避免旋转长条网格把地面放得过低。
50
+ - 修复抓取力线在拖拽中被过期包围球裁剪而消失:动态力线不再参与视锥裁剪;暂停或重置会可靠结束抓取,不再残留旧状态。
51
+
52
+ ### Behavior notes
53
+
54
+ - 多 tile UDIM 使用紧凑矩形 atlas,并保留 authored UV;atlas 依赖 clamp 采样,单张合成纹理超过运行时约束时会保留明确降级诊断,不会用单个 tile 冒充整套纹理。
55
+ - 每个 USD 模型独占一个 module Worker;`prewarmUsdWorker()` 创建的 Worker 会被第一次 USD 加载消费,关闭模型时仍按同一生命周期终止并回收。Node/非 Worker 宿主继续使用共享 in-process runtime。
56
+ - 自定义 CDN 托管另一份 OpenUSD 运行时时,必须通过 `assets.openUsdRuntimeId` 传入清单中的 `runtimeId`;带版本 URL 推荐 `Cache-Control: public, max-age=31536000, immutable`,无版本 URL 或清单文件使用 `no-cache`。
57
+ - 渐进纹理加载只在大型资产触发;中间帧可能显示占位/白膜材质,纹理提交后会刷新全部克隆。正常规模资产不进入该路径。
58
+ - PhysX cooking 结果不存储在 USD 中:triangle mesh、`sdf`、`convexDecomposition`、`meshSimplification` 使用碰撞源网格的凸包近似,`boundingCube`/`boundingSphere` 使用拟合图元;凹陷、内腔与分离区域可能丢失,并逐条记录诊断。
59
+ - `auto-mujoco` 只选择 Physics variant 中可识别的 Newton/Mjc/MuJoCo 分支,不改变 authored grip 模式;显式 `usdVariantSelections` 优先于自动选择,`authored` 模式完全沿用资产选择。
60
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
61
+
62
+ ## 0.5.5
63
+
64
+ ### Changed
65
+
66
+ - 更新单线程 OpenUSD WASM 运行时(`openusd_probe.js` / `openusd_probe.wasm`,WASM 体积由约 12.7 MB 降至约 11.2 MB);部署时仍需与 JS bundle 同步替换。
67
+ - USD 外部引用预取支持有界并发:底层单线程解析选项新增内部 `maxConcurrency`(缺省 `1`,保持原有串行语义),Viewer 加载 USD 时使用 `4`;依赖深度、数量上限与 package 模式策略不变。
68
+ - 对确认不含外部资源标识的 ASCII USDA 跳过整层外部引用扫描;二进制 crate 与任何含 `@` 的文本仍走 OpenUSD 权威扫描。
69
+ - 碰撞调试几何改为首次打开碰撞显示时才构建,首屏加载不再编译碰撞代理;延迟工厂存在时 `canToggleCollision` 仍为 `true`。
70
+ - USD purpose/可见性过滤提前到材质与拓扑适配之前:被隐藏的几何不再参与材质适配和拓扑修复;子集材质按路径复用,未引用纹理的材质不再执行面变化 ST 修复。
71
+
72
+ ### Fixed
73
+
74
+ - 修复 `UsdPreviewSurface` 的 `inputs:opacity` 存在但值为空(未连接)时被 three-loader 处理为 `0`,导致有效网格(含蒙皮网格)消失:现在按 USD 回退值 `opacity=1` 处理,并仅在有 `alphaMap` 时保持透明。
75
+ - 修复 USD purpose 过滤只隐藏 `guide` 的问题:普通模型视图现在只显示 `purpose=default` / `render` 的几何,`guide`、`proxy` 与无效或未知 purpose 默认隐藏(子节点显式声明可覆盖祖先);物理与独立碰撞调试覆盖层不受该过滤影响。
76
+
77
+ ### Behavior notes
78
+
79
+ - `maxConcurrency` 只影响独立引用的读取并发,不改变依赖深度、数量上限或 package 模式下的包边界判定;串行默认值适用于直接使用底层解析器的宿主。
80
+ - ASCII USDA 快路径是保守判断:只有确认数据中不存在 `@` 资源分隔符时才跳过扫描,否则保留 OpenUSD 对 layer 的完整解析。
81
+ - 更新运行时后必须同步部署 `openusd_probe.js` 与 `openusd_probe.wasm`;旧运行时缺少映射接口时报 `E_USD_RUNTIME_VERSION`,不会静默展示丢失引用的场景。
82
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
83
+
84
+ ## 0.5.4
85
+
86
+ ### Added
87
+
88
+ - USD 材质适配新增内部 `MaterialIR v1`:保留 shader 节点、连接、直接纹理语义、alpha、UV set/transform 与结构化 issue,作为逐材质诊断与确定性映射的基础(不从包入口导出)。
89
+ - 扩展 USD 材质模板映射:`UsdPreviewSurface` Material interface、OpenPBR 有界子集、`OmniPBRBase` + `core_definitions.mdl::file_texture`、connected `OmniSurfaceBase`,以及 `gltf_material` / `gltf_texture_lookup` / `gltf_normal_texture_lookup`(`gltf/pbr.mdl`)。
90
+ - 标量纹理支持 `luminance` 采样与 A 通道写入(用于 `sheenRoughnessMap` 等),并按源通道、`scale/bias`、wrap 与 IR 语义重排到目标通道。
91
+ - 场景工具栏新增地面比例尺 `ui.scene.parts.scaleRuler`(缺省开启):固定长度图例显示一个网格单元格的世界边长,随自适应网格与主题更新。
92
+ - 公开 `GroundGridScale`、`DEFAULT_GROUND_GRID_SCALE`、`chooseGroundGridScale()`、`formatGroundGridScale()`,以及 `AssetControlState.groundGridScale` 与 `AssetSession.getGroundGridScale?.()`。
93
+
94
+ ### Changed
95
+
96
+ - 地面网格按模型尺寸自适应选择 `1/2/2.5/5×10ⁿ` 的单元格边长(约 16–40 格覆盖模型);纯视觉预览把地面贴在模型最低点下方,可运行仿真的物理地面高度仍以接触求解为准。
97
+ - 地面光照区域改为跟随相机焦点与抓取中的刚体平滑移动,网格线本身保持世界空间固定;相机发生大跳变(如重置或切换视图)时直接对齐,不做插值。
98
+ - 碰撞代理可视化改为青绿色高亮轮廓加半透明体积填充;无法从 OpenUSD 唯一还原最终代理的碰撞源网格(`convexDecomposition`、`meshSimplification`、`sdf` 等)改用橙黄色显示,并保留近似诊断与工具栏颜色提示。
99
+ - 抓取物理调整:弹簧刚度保持与质量无关,默认阻尼比由 `1.15` 调整为 `0.7`,力上限改为按质量 `60 N/kg`(不再用固定最小力托住重物);对被抓住刚体按等效频率自适应细化物理步长(默认 `1/240`,最细 `1/960`),并加入角速度阻尼。
100
+ - 仿真 `reset()` 先结束当前抓取,再重置物理并重新落座地面,避免重置后地面停在旧位置或抓取状态残留。
101
+ - 降级警告徽标与浮层改用主题变量取色,并上移以避让新增的比例尺图例。
102
+
103
+ ### Fixed
104
+
105
+ - 修复 `mj_objectVelocity` 在 MuJoCo WASM 绑定下返回全零导致抓取阻尼失效:改用 `data.cvel` 读取被抓住刚体的空间速度,轻物体不再抖动,垂直拖拽可达目标。
106
+ - 修复 `GeomSubset` 全绑定材质槽时残留未引用的基础材质:所有面均有 subset 绑定时压缩材质槽并重映射 group 索引;部分绑定时保留 slot 0 承接未覆盖面。
107
+ - 修复 `UsdPreviewSurface` 的 Material interface 转发未被解析:常量、IOR、clearcoat、透明度与颜色/自发光/受支持标量纹理会落到目标材质;非标准 normal scale/bias、多 UV set 等无法确定的输入保留 gap。
108
+ - 修复 USDZ 包内非 `UsdPreviewSurface` 材质(`file_texture` 等)的纹理依赖 Loader 是否已创建贴图:视觉适配器现在可按 package specifier、逻辑路径、唯一后缀或唯一 basename 解析包内条目。
109
+ - 修复 `sourceColorSpace="auto"` 未按输入语义解析:颜色纹理按 sRGB,normal 与标量数据按 raw 处理。
110
+ - 修复降级警告徽标在浅色主题下对比度不足。
111
+
112
+ ### Behavior notes
113
+
114
+ - `MaterialIR` 是诊断与适配基础,不表示浏览器执行任意 MaterialX/MDL;复杂材质仍以逐材质报告和源渲染器对照为准。支持矩阵见 `USD-VISUAL-MATERIAL-SUPPORT.md`。
115
+ - 橙黄色碰撞代理只是作者提供的 collision source mesh 近似预览,不代表 PhysX/Isaac 最终求解器生成的代理形状;青绿色表示精确或已编译代理。
116
+ - 比例尺显示的是地面网格单元格边长,不是资产单位或测量结果;仅在资产 ready、`canToggleGround` 且地面可见时显示。
117
+ - 抓取步长细化只影响被抓住刚体期间的物理求解,松开或重置后恢复 `1/240`,不改变资产 authored 时间步或播放速度。
118
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
119
+
120
+ ## 0.5.3
121
+
122
+ ### Added
123
+
124
+ - 导出 USD 资源失败错误码常量:`USD_RESOURCE_NOT_FOUND`、`USD_RESOURCE_INVALID`、`USD_RESOURCE_FETCH`、`USD_RESOURCE_EXTERNAL_DENIED`、`USD_RESOURCE_AUTH`。宿主 `resourceResolver` 可把拒绝原因挂在这些稳定 `code` 上,使可降级的视觉资源缺失被识别为诊断而非加载失败。
125
+
126
+ ### Changed
127
+
128
+ - 统一模型预览与仿真预览的舞台曝光值(`STAGE_EXPOSURE` 的 `simulation` 由 `0.68`、`model` 由 `1.4` 一并调整为 `1.2`):环境贴图是唯一光源,两类预览现在以一致亮度呈现,仿真白色外壳不再被压暗、模型预览也不再过亮。
129
+
130
+ ### Fixed
131
+
132
+ - 修复 USD 预览在视觉资源(贴图、法线/粗糙度图、光照探针)缺失或不可用时整段加载失败:现在按宿主错误码与 HTTP 状态分类,仅 `missing` / `invalid` / `unavailable` 且扩展名可识别的视觉资源降级为诊断(`USD_VISUAL_RESOURCE_MISSING` / `USD_VISUAL_RESOURCE_INVALID` / `USD_VISUAL_RESOURCE_UNAVAILABLE`),被排除的引用指向刻意不存在的 MEMFS 目标,不再参与 composition,模型保留其余内容继续显示;宿主拒绝(denied)、鉴权失败、取消与未分类错误仍然按加载失败处理。
133
+ - 修复 2xx 状态但实为 SPA/HTML 兜底页或空响应的资源被当作有效内容:预取与直连读取都会按 content-type 与前缀校验,识别为无效资源并报 `USD_RESOURCE_INVALID`,不再作为 layer 或图像字节交给 OpenUSD。
134
+ - 修复已失败的资源被重复请求或回退直连:文件包会记住失败并在预取与视觉适配之间共享,宿主 resolver 保持唯一字节来源;取消属于瞬时状态,不写入失败记录。
135
+ - 修复 FBX 外置贴图缺失或加载失败导致整个模型加载失败:贴图失败降级为占位纹理并记录警告,几何照常显示,报告 `W_FBX_TEXTURE_UNAVAILABLE` 列出失败贴图(与材质近似警告可并存);取消仍按加载失败处理,不产生半成品模型。
136
+
137
+ ### Behavior notes
138
+
139
+ - USD 视觉资源降级只覆盖已识别的图像类资源;USD layer(usd/usda/usdc/usdz)、MDL 模块、未知类型资源、宿主拒绝与鉴权失败仍按加载失败处理,降级不代表资产自包含或已完整加载。
140
+ - FBX 贴图降级与 three.js 原生容忍一致:缺失、HTTP 错误与解码失败都只影响对应贴图;被取消的加载整体失败。
141
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
142
+
143
+ ## 0.5.2
144
+
145
+ ### Added
146
+
147
+ - 新增 `OpenAssetOptions.usdExternalReferenceMode`(`'package' | 'complete'`,公开类型 `UsdExternalReferenceMode`):控制 USD 入口包之外引用的处理策略,缺省为 `'package'`。切换模式需重新调用 `openAsset()`,不在已组合的 stage 上只隐藏或显示环境。
148
+
149
+ ### Changed
150
+
151
+ - USD 外部引用默认改为资产包模式(`package`):URL 入口以同 origin 的入口目录及其子目录为包边界;本地输入以实际选中的文件集合为边界,同目录或已选中的 `../` 依赖仍属包内。未选中的本地依赖、跨 origin 以及远端目录之外的资源不再请求,报告 `USD_EXTERNAL_REFERENCE_SKIPPED` 后继续显示包内内容;远端包内缺失资源、resolver 拒绝与解析失败仍按加载失败处理,不做 catch-all 降级。需要组合外部环境等场景依赖时显式传入 `usdExternalReferenceMode: 'complete'`。
152
+
153
+ ### Fixed
154
+
155
+ - 修复 USD 的 references、payloads 与 subLayers 的 URL 到 MEMFS 路径映射:远端或本地依赖取得后经 `usd_probe_stage_open_mapped` 映射到内存 Sdf Layer 再做 composition,以窗口路径隔离不同来源与带查询参数的同名资源,支持 USDA/USDC 的引用、payload 与子层,并保留目标 Prim、layer offset 等原始语义;每次加载使用独立目录,关闭或失败时清理临时资源。
156
+ - 修复恢复 2D 相机快照时的画布宽高比失配:快照只保存正交视锥(`left/right/top/bottom`)、中心与缩放,不保存视口尺寸,而 `OrthographicCamera` 没有 `aspect` 字段可供校正;当快照拍摄时的画布宽高比与本次打开不同(跨页面/跨会话,或图层、属性面板与窗口尺寸变化)时,图纸会被拉伸,直到有其他操作触发一次 `resize()`。现在快照应用后统一按当前视口重适配视锥(保留竖直跨度、水平中心与 `zoom`),规则与 `resize()` / `fitView()` 一致,`camera.setState()` 与 `camera.reset()` 一并覆盖。
157
+
158
+ ### Behavior notes
159
+
160
+ - 完整模式(`complete`)在没有 `resourceResolver` 时直接尝试浏览器可访问的 HTTP(S) 引用,仍受 CORS、鉴权、网络、依赖数量与深度限制;提供了 resolver 时它拥有最终决定权,包外资源必须经其解析,拒绝、401/403 或请求失败不会回退为直连。相对引用传给 resolver 时以入口目录为基准并保留必要的 `../`,绝对 URL 引用保留完整域名与 query。
161
+ - 资产包模式跳过包外依赖不代表资产自包含,也不表示原始场景已完整加载;完整预览应切换到完整模式并提供合法可解析的依赖或完整文件包。已依赖自动加载外部引用的宿主需显式传入 `usdExternalReferenceMode: 'complete'`。
162
+ - `openusd_probe.js` 与 `openusd_probe.wasm` 必须与 JS bundle 同步部署;旧运行时缺少映射接口时报 `E_USD_RUNTIME_VERSION`,不会静默展示丢失引用的场景。MDL 模块(如 `OmniPBR.mdl`)不按同目录 HTTP 文件预取,现有材质映射与降级不变。
163
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
164
+
165
+ ## 0.5.1
166
+
167
+ ### Changed
168
+
169
+ - 依赖 `@nebula-spatial/cad-loader` 升级到 `^0.3.1`:CAD pack 的外部依赖视口查询在异常视口下不再有卡死主线程的风险。
170
+
171
+ ### Fixed
172
+
173
+ - 修复恢复异常相机快照导致 CAD 预览崩溃或不可见:持久化快照可能来自旧版本或已失效的文档,恢复前按当前文档尺度校验;可见跨度超过文档尺度若干倍、或可见区域完全偏离文档的快照整条丢弃并回退到自动 `fit`,不再把天文数字视口传进 loader 的空间索引查询,也不再把图纸缩得几乎不可见。
174
+ - 修复发布产物缺失 `dist/assets/source-types.d.ts`:该声明被 `assets/types.d.ts` 与 `cad/types.d.ts` 引用,却被类型裁剪误删,消费方编译 `AssetSingleSource` 等类型时会报 TS2307;现已随包发布。
175
+
176
+ ### Behavior notes
177
+
178
+ - 恢复校验以当前文档 bounds 为准:跨度上限取文档跨度的 1024 倍(覆盖交互可达到的最大缩小比例),中心偏移上限取文档跨度的 16 倍;没有文档 bounds 时退化为 1e9 的绝对跨度上限。判定为异常时丢弃整条快照,而不是夹到边界继续显示。
179
+ - 本次发布同时更新 `@nebula-spatial/cad-loader`(0.3.1);私有 `scene-runtime` 版本不变。
180
+
181
+ ## 0.5.0
182
+
183
+ ### Changed
184
+
185
+ - USD 改用单线程 OpenUSD WASM 运行时(无 pthread、无 `SharedArrayBuffer`):浏览器不再需要 `Cross-Origin-Opener-Policy` / `Cross-Origin-Embedder-Policy` 跨源隔离响应头,也不再需要同源的 Blob 模块 Worker 入口;跨域 CDN 只需放行 CORS。
186
+ - USD 场景改用参考包纯 JS 的构建器,`USDSceneData` 抽取、引用发现与 Stage 生命周期由包内适配层负责。宿主提供的 `resourceResolver` 继续按引用逐项解析,语义与原先的引用预取一致。
187
+ - `@openusd-wasm/pxr` 不再是本包的直接依赖:Viewer 不再实例化 threaded PXR runtime,绕过 `USDSceneData` 的动态 Prim/Attribute 读取改由内置探针提供。
188
+ - 统一资产 source 类型:新增 `AssetSingleSource`,明确单源与 `{ kind: 'files' }` 文件包的区别;`Blob` 现已在公开类型中显式声明,CAD 的 `CadLoadSource` 与 `packFile` 兼容形态保留。
189
+
190
+ ### Added
191
+
192
+ - 新增 `openusd/` 运行时目录并随包发布:`openusd_probe.js` 与 `openusd_probe.wasm`,通过 `exports` 的 `./openusd/*` 暴露。`assets.openUsdBaseUrl` 缺省值改为 `/openusd/`(站点根绝对路径,不随页面所在子目录变化)。
193
+ - 新增单线程 USD 回归覆盖:真实关节资产(24 刚体 / 23 关节)走通 `compileUsdPhysics` → MuJoCo 的编译、步进与重置;GeomSubset 的 UV 重排与逐面子集材质分组与参考栈结果一致;引用解析的标识符归一、去重与 403 授权失败不再回退。
194
+ - 自动格式识别文档明确为“扩展名优先,loader `match()` 兜底”;无法从两者确定格式时,错误信息会提示提供入口文件名或显式 `format`。
195
+ - 新增 USD 骨骼动画播放:无刚体的 USD 视觉场景会保留其 authored 的骨骼/xform 动画片段,首帧即应用源姿态,并由内置 `AnimationMixer` 驱动播放/暂停/重置,无需物理运行时。蒙皮骨架的宿主矩阵按当前场景变换重对齐,避免场景单位缩放与 up 轴旋转被骨骼再作用一次、导致软管与线缆等蒙皮部件脱离骨架。
196
+ - 新增 `capabilities.hasAnimation`:区分“驱动 authored 动画片段”与“运行物理仿真”。仅带动画、无刚体的资产 `hasPhysics` 仍为 `false`,但 `canPlay` / `canPause` / `canReset` 为 `true`;内置工具栏据此把按钮文案切换为“播放动画 / 暂停动画 / 重置动画”。
197
+
198
+ ### Improved
199
+
200
+ - 优化 USD 纹理提取:贴图上传 GPU 按像素预算批处理,小图合并到同一帧、大图各自独占一帧,避免大量纹理同时解码与上传阻塞主线程。
201
+
202
+ ### Removed
203
+
204
+ - 移除 `resolveUsdResourcePackage`:它只服务 threaded PXR 运行时的引用预取,职责已并入包内适配层的引用解析。
205
+
206
+ ### Fixed
207
+
208
+ - 修复发布产物中丢失的 `viewerVersion`:包入口此前只做副作用导入、没有重新导出该常量,模块级版本 banner 会被打包器整块摇掉,消费方既看不到 banner 也无法 `import { viewerVersion }`。现在入口显式导出该常量,`sideEffects` 如实标记为含副作用,构建产物与独立消费方产物都会校验 banner 与导出仍在。
209
+ - 修复 USDZ 包内纹理在 URL + `resourceResolver` 场景下被错误当作包外依赖请求的问题;包内条目优先由 USDZ 包解析器提供,resolver 仅处理真正的包外资源。
210
+ - 修复 USD 原生纹理被重复应用 UV 变换的问题:three-loader 会把 `ComputeMaterialTextureInfo` 的 `uvTransform` 同时交给几何与每个原生 Three.js 纹理,几何侧已烘焙该变换,纹理矩阵因此被再次作用;材质适配现在保留几何侧结果,并把材质纹理槽的矩阵重置为单位矩阵。
211
+
212
+ ### Behavior notes
213
+
214
+ - 接入方需让 `openusd_probe.js` 与 `openusd_probe.wasm` 以同名同目录出现在站点可访问的路径下(拷入站点静态目录、由打包器的静态拷贝插件搬运,或上传到自有 CDN 后覆盖 `assets.openUsdBaseUrl`)。`assets.openUsdBaseUrl` 缺省为站点根下的 `/openusd/`,部署在子路径或 CDN 时需显式覆盖。
215
+ - 跨源隔离响应头不再是 USD 预览的必需项;playground / embed-viewer 的开发与预览服务器也不再发送它们,仓库内已无依赖 `SharedArrayBuffer` 的浏览器侧运行时代码。
216
+ - 无刚体的 USD 视觉场景现在是可播放的动画资产:播放与重置只驱动 authored 动画片段,不做物理步进,`physics` 状态仍为 `not-authored`。`hasAnimation` 为可选字段,缺省按 `false` 处理,第三方以字面量构造 `capabilities` 不受影响。
217
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
218
+
219
+ ## 0.4.6
220
+
221
+ ### Added
222
+
223
+ - URDF 内置工作台新增结构图弹窗:以只读 SVG 渲染 Link/Joint 拓扑,支持缩放、重置视图、最大化、拖动窗口与四角拖拽改尺寸,节点与场景选择、结构树双向联动。
224
+ - 新增预览拖拽预设 `ViewerOptions.previewDragPreset` 与 `viewer.setPreviewDragPreset()`:在 `left-rotate`(默认,左键旋转/右键平移)和 `left-pan`(左键平移/右键旋转)之间切换模型与仿真预览的指针映射。
225
+ - 仿真资产(URDF/XACRO/MJCF/USD)新增 `capabilities.canReorientUpAxis` 与 `preview.setUpAxis()` 重定向:运行时已就绪时旋转编译后的物理模型,顶层刚体的参考位姿、当前位姿与速度一并跟随。
226
+ - 新增 `viewerVersion` 导出:包入口在模块加载时打印一次版本 banner,`check-boundary` 校验它与 `package.json` 版本是否漂移。
227
+
228
+ ### Improved
229
+
230
+ - 内置 URDF UI 拆分为结构面板、属性面板、工具栏、状态栏与结构图组件,各自持有各自的 UI 状态;工具栏统一为覆盖层、名称、角度单位、地面、适应视图、主题、仿真与重置。
231
+ - 结构树在选中与关节控制刷新时保留滚动位置和焦点;mimic 联动关节按控制根分组展示,跟随关系与偏移量在同一分组内说明。
232
+ - 仿真上轴切换后按翻转后的包围盒重铺地面与反射,重力保持 -Z、物理地面保持水平;URDF 在运动学与动力学之间切换时上轴旋转不会叠加。
233
+ - GLB/glTF 按 glTF 规范默认使用 Y-up;FBX 仍优先读取文件内的正向 `UpAxis`/`UpAxisSign` 声明,USD/URDF/MJCF 保持默认 Z-up。
234
+
235
+ ### Fixed
236
+
237
+ - 结构图弹窗背景改为半透明,避免遮挡底层模型;四角拖拽限制最小 420×320,并防止窗口被拖出画布范围。
238
+
239
+ ### Behavior notes
240
+
241
+ - 结构图是只读拓扑视图,不编辑资产;不支持的语义仍以严格检查的错误列表为准。
242
+ - 仿真资产的上轴重定向移动的是编译后的物理模型:重力方向与查看器地面保持不变,固定基座机器人只会整体倾斜;无运行时(运动学预览、物理降级预览)退回纯场景图旋转。
243
+ - `left-pan` 仅为兼容 sim-studio 的既有映射,默认的 `left-rotate` 与 OrbitControls 约定一致。
244
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
245
+
246
+ ## 0.4.5
247
+
248
+ ### Added
249
+
250
+ - 新增 USD 视觉材质适配支持矩阵,明确 `UsdPreviewSurface`、MaterialX Standard Surface、OmniPBR 和 OmniGlass 的已转换、有界近似及未适配范围。
251
+ - 支持常量介质透明、`presence`、`opacityThreshold`、受限透明纹理、MaterialX 薄壁透射,以及 OmniGlass 的覆盖率、反射颜色、粗糙度和受限法线适配。
252
+ - 支持 USD 实例材质代理中的可确定常量 `UsdPreviewSurface` 输入恢复;保留循环、歧义、程序节点和体积光学语义的诊断。
253
+ - 本地 Viewer 文件包入口支持 `root.usd`、`root.usda`、`root.usdc` 和 `root.usdz`,不受上传顺序影响。
254
+ - 支持浏览器 Xacro 子集展开,包含宏、属性、参数、条件、块参数、嵌套 include 与 ROS package 映射;不支持的 Python/ROS 语义会显式失败。
255
+ - 支持 URDF mimic 联动、可行控制范围、浏览器 COLLADA 网格、内嵌材质,以及本地文件包目录浏览和入口切换。
256
+
257
+ ### Improved
258
+
259
+ - 统一 URDF/MJCF 视觉材质的线性颜色、粗糙度、金属度、法线、透明度、发光和纹理通道转换,并补充纹理资源释放与诊断。
260
+ - URDF 审查工作台补充惯性姿态、惯量信息展开、连续关节控制范围、关节扫描和侧栏交互保持。
261
+ - USD 视觉过滤按 `purpose` 隔离辅助几何;修正世界侧关节参考系、单位/up-axis 转换和显式惯性处理。
262
+ - 物理模型取景忽略环境平面,避免地面或辅助几何主导模型缩放;补充跨格式材质审计页面及 Chromium 验证脚本。
263
+ - 恢复分离 USD 视觉树到刚体的引用归属,支持显式引用 Prim 路径与 defaultPrim 引用,并对歧义、缺失和格式错误保留诊断。
264
+
265
+ ### Fixed
266
+
267
+ - 玻璃透射材质按 USD `doubleSided` 声明应用单面/双面策略,避免共享材质被错误修改;纯金属材质不被误判为玻璃。
268
+ - 修复 USD 透明度、覆盖率阈值、透明纹理、OmniGlass 法线与反射参数的边界转换;无法可靠表达的体积吸收、实体光程和复杂光学效果继续报告诊断,不生成猜测值。
269
+ - 允许具有完整显式质量、质心、惯量和主轴数据的 USD 刚体缺少碰撞几何;仅有不完整惯性时仍明确失败,不虚构碰撞形状。
270
+ - 修复 URDF 固定轴 RPY、惯性坐标旋转、mimic 初始姿态与 MuJoCo equality 约束;修复 USD 聚合视觉网格不随对应刚体更新的问题。
271
+
272
+ ### Behavior notes
273
+
274
+ - 本版本继续使用有边界的 Three.js 材质映射,不执行 MDL 或完整 MaterialX 节点网络,也不承诺与 Blender、Omniverse 或路径追踪渲染逐像素一致。
275
+ - `USD-VISUAL-MATERIAL-SUPPORT.md` 随 npm 包发布,记录具体支持矩阵;材质适配报告和诊断仍是判断单个资产结果的依据。
276
+ - Xacro 是受限浏览器预处理子集,不执行外部 ROS 命令或环境访问;复杂 Python/YAML 语义应先使用官方工具展开。
277
+ - 本次发布只更新 Viewer;`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
278
+
279
+ ## 0.4.4
280
+
281
+ ### Added
282
+
283
+ - 新增 URDF 审查工作台:模型结构树、搜索过滤、关节滑块与范围扫描、属性面板、XML 只读定位及仅报告确定错误的检查。
284
+ - 公开 `AssetPreview.getInspection()`、插件侧 `ctx.asset.$inspection()` 和 `UrdfInspection` 快照/命令契约;支持关闭内置 URDF UI 或完全 Headless 自定义。
285
+ - 增加关节轴与正转方向、质心、完整惯性张量对应的等效惯量盒可视化;选中部件的质心与惯量使用区别色,仿真运行时标记跟随实时位姿。
286
+ - 新增视角 gizmo、可拖拽调宽及折叠的侧栏、深浅主题切换和 URDF playground 入口。
287
+
288
+ ### Improved
289
+
290
+ - URDF 默认静止运动学预览,仅显式播放时懒初始化动力学;暂停后支持部件选择与关节控制,再次播放从当前姿态继续,重置恢复初始运动学状态。
291
+ - 支持按住 R 配合鼠标左右移动调节关节,根据相机朝向、关节世界轴及鼠标位置判断方向;不提供 Shift 精调。
292
+ - 使用模型局部 BVH 加速拾取,浅蓝材质高亮选中部件;优先定位关联关节,点击空白取消选择,自动展开选中项祖先并保留结构树滚动位置。
293
+ - 统一 SVG 场景工具栏、输入控件与主题样式,放开轨道相机俯仰范围;本地上传组件加载成功后收起为右上角悬浮按钮,支持手动展开和收起。
294
+
295
+ ### Fixed
296
+
297
+ - 修复关节滑块连续拖动和重建 UI 导致的结构树滚动跳变;仿真运行时禁用关节控制,保留物理拖拽。
298
+ - 加固物理懒初始化期间的取消与资源释放,初始化失败仍保留运动学审查。
299
+ - 初始化及手动调整姿态后检查实际碰撞边界,必要时下移查看器默认地面,避免初始穿透导致弹飞;不移动模型或资产自带地面,运行时地面保持固定。
300
+ - 重置恢复初始安全物理地面,URDF 返回初始预览地面,不保留临时下移高度;暂停保持当前地面。
301
+
302
+ ## 0.4.3
303
+
304
+ ### Added
305
+
306
+ - 公开 `AssetPhysicsState` 类型,在 `AssetPreviewSnapshot` 和 `AssetSession` 中增加可选 `physics` 状态,并提供可选 `AssetLoaderContext.reportSessionState()` 通知;现有 loader 无需实现这些新增成员。
307
+ - FBX 外置纹理接入本地文件包与异步 `resourceResolver`,增加受限 TGA/DDS 解码、命名 UV 集、二维纹理变换及受限颜色分层合成;具体边界见 `FBX-MATERIAL-CONVERSION.md`。
308
+
309
+ ### Improved
310
+
311
+ - 按 FBX 材质 ID、连接顺序及模板恢复材质参数,完善标量贴图通道、事务回滚、取消和资源释放;不支持或近似转换通过警告及诊断报告暴露。
312
+ - 改善 USD 的 OmniPBR/PxrSurface 材质适配、索引 UV、GeomSubset 材质绑定与粗糙度贴图通道,区分视觉适配警告和物理故障。
313
+ - 完善 URDF、MJCF、USD 碰撞几何与位姿同步,保留源格式碰撞定义,补充关节与运动学预览支持及回归测试。
314
+
315
+ ### Fixed
316
+
317
+ - 物理编译或初始化失败时,在能够独立构建视觉预览的前提下保留资产;运行中的 step/reset 失败停止仿真、保留最后显示的视觉位姿并刷新能力状态,不再自动重启物理。
318
+ - 物理不可用时保留置灰播放按钮,悬停显示物理故障原因并拦截播放,不被材质警告覆盖。
319
+
320
+ ### Behavior notes
321
+
322
+ - `phase === 'ready'` 仅表示资产预览就绪,不保证物理可运行。宿主应检查 `capabilities.canPlay`,并使用 `physics.status === 'unavailable'` 下的 `issue` 展示原因;未提供物理状态不等于 `not-authored`。
323
+ - FBX 加载完成等待纹理解码和转换;缺失、歧义、鉴权或解码失败按加载失败处理,不保证旧资产继续以缺贴图模型成功加载。
324
+ - 本版本不承诺任意 FBX/自定义着色器无损转换或 Blender 像素一致;USD/URDF/MJCF 物理降级不掩盖取消或视觉加载失败。
325
+
326
+ ## 0.4.2
327
+
328
+ ### Fixed
329
+
330
+ - 修复 `assets.openUsdBaseUrl` 指向跨域 runtime 时,OpenUSD pthread Worker 因入口同源限制抛出 `SecurityError` 的问题;通过 Blob 模块入口导入远端 runtime,保留同源与 Node 加载行为,并补充回归测试及 CORS、CSP 部署说明。
331
+
332
+ ## 0.4.1
333
+
334
+ ### Added
335
+
336
+ - 内置普通模型预览新增 FBX 格式,支持按 `.fbx` 扩展名自动识别,并复用模型舞台、相机适配、up-axis 切换和资源释放契约;FBX 优先按文件 `GlobalSettings` 的正向 Y/Z up-axis 声明转换到 Viewer 的 Z-up 世界,无法判断时回退 Y-up,并可由显式 `upAxis` 覆盖;FBXLoader 生成的传统 Lambert/Phong 材质会转换为可由 Viewer 环境光照明的 PBR 材质。
337
+
338
+ ## 0.4.0
339
+
340
+ 0.4.0 将 Viewer 从以 CAD 为主的 facade 扩展为统一资产预览器,并把 3D 模型与仿真资产接入同一个 Three.js 场景、相机、渲染器和帧循环。CAD 专属状态仍保留在 `viewer.cad`,但资产生命周期、内置 UI、加载状态和扩展机制已统一。
341
+
342
+ ### Breaking changes
343
+
344
+ - CAD、3D 模型和仿真资产统一使用 `viewer.openAsset()` / `viewer.closeAsset()` 管理生命周期。`viewer.cad.open()` / `viewer.cad.close()` 仅为迁移兼容保留并标记为 deprecated。
345
+ - `ui.preset` 默认值从仅 CAD UI 改为 `'auto'`,Viewer 会按活动资产在 CAD UI 与 model/simulation scene UI 之间切换;需要 0.3 CAD-only 行为时显式传 `preset: 'cad-readonly'`。
346
+ - CAD 专属 UI 配置由 `ui.parts`、`ui.persistence*`、`ui.stateStore`、`ui.keyboard`、`ui.unitFormatter` 迁移到 `ui.cad.*`;模型/仿真控件使用 `ui.scene.parts`。相关类型重命名为 `ViewerCadUi*` / `ViewerSceneUi*`,旧名称不保留别名。
347
+ - 主题只有一个初始配置来源 `ui.theme`;`ui.scene.parts.theme` 只控制主题按钮显隐。内置按钮在 Viewer 内部运行时切换主题,不再要求 Embed、URL 参数或宿主回调参与。
348
+ - 自动格式识别不再回退到 CAD。`unknownFormatPolicy` 已 deprecated;通用 `.xml`、无扩展名或目录 URL 必须由调用方显式指定 `format`。
349
+
350
+ ### Added
351
+
352
+ - 新增统一资产 API 与公开类型:`AssetSource`、`OpenAssetOptions`、`AssetPreview`、`AssetPreviewSnapshot`、`AssetPreviewCapabilities`、`AssetControlState`、`ViewerAssetOptions` 以及 `asset-change`、`asset-error`、`asset-control-change` 事件。
353
+ - 内置支持 CAD、GLB/glTF、URDF、MJCF、USD/USDA/USDC/USDZ;URDF/MJCF 通过 MuJoCo 运行,USD 支持静态视觉和可可靠映射的物理语义。
354
+ - 新增模型 authored up-axis 运行时切换、地面显隐、仿真播放/暂停/复位、碰撞代理、物理属性读取和物理抓取施力;普通/Shift 施力连线分别使用 `#21C7BE` / `#5B8DEF`。
355
+ - 新增 `asset-loader` 插件贡献点、`ctx.asset.$read()` / `$readControl()`、能力门控资产命令和权威控制态广播,第三方格式可沿统一会话契约扩展。
356
+ - 新增 `ViewerLayoutEngine`、五类 zone、`ui.insetTarget` 和内置 CAD/scene UI 插件组;loading、失败提示和 scene toolbar 由包内插件统一提供。
357
+ - 新增运行时 `viewer.setTheme(theme)` 作为可选的外部编程控制入口;常规内置主题切换无需宿主调用。
358
+ - 新增 `assets.dracoDecoderPath`、`assets.mujocoBaseUrl`、`assets.openUsdBaseUrl`,以及单次打开可覆盖的 `baseUrl` / `resourceResolver` 和对应 runtime URL。
359
+
360
+ ### Changed
361
+
362
+ - 3D 模型与仿真资产共享 Viewer 唯一的 SceneRuntime、Renderer、Camera、environment、预览导航、舞台光照/地面和 RAF;仿真 session 只向统一帧循环提供动态更新,不创建第二套渲染底层。
363
+ - 模型与仿真视觉对象统一通过受控 `Object3D` 挂载通道进入场景;GPU、WASM、object URL 和物理运行时由各资产 session 单一负责释放。
364
+ - 资产 presentation profile 受控应用 view mode、导航策略、clear color、stage theme、fit policy 和 UI profile;关闭或替换资产时恢复宿主默认展示状态。
365
+ - 内置 UI 统一位于 `ui.root` ShadowRoot,第三方贡献点位于 light DOM zone;insets、resize、pointer capture、cursor 和仿真抓取时的导航门控由 Viewer 管理。
366
+ - 远端 URDF/MJCF/glTF 依赖按入口 URL 与 `baseUrl` 解析;远端 USD 以根文件完整 URL 作为相对子层、纹理和引用的解析基址。远端多文件资产仍要求服务器保持路径结构、正确 CORS/MIME/鉴权配置,不能把 CDN 目录 URL 当作可枚举文件包。
367
+ - OpenUSD pthread WASM 仅在 USD 路径要求安全上下文与 COOP/COEP;MuJoCo/OpenUSD 继续动态加载,避免 CAD/普通模型入口提前加载仿真运行时。
368
+
369
+ ### Removed
370
+
371
+ - 从 Embed/业务壳移除重复的 GLTF 加载、preview toolbar、loading/failed overlay、资产类型 clearColor 分支、抓取 pointer 管线和 ResizeObserver/insets 状态机。
372
+ - 移除模型/仿真独立渲染循环与页面壳状态的设计需求;动态仿真更新现由 Viewer 主循环调度。
373
+
374
+ ### Migration summary
375
+
376
+ 1. 把 CAD 的 `viewer.cad.open/close` 改为 `viewer.openAsset(..., { format: 'cad', cad: {...} })` 与 `viewer.closeAsset()`;CAD 图层、选择和文档状态仍从 `viewer.cad` 读取。
377
+ 2. 把宿主自行加载并 `addObject()` 的常规 GLB/glTF 预览迁移到 `openAsset()`,并显式配置 Draco decoder 路径。
378
+ 3. 将旧 UI 配置移动到 `ui.cad` / `ui.scene`,删除 Embed 中与内置 UI 重复的 DOM、样式和事件状态机。
379
+ 4. 插件改读 `ctx.asset`,通过 `ctx.commands` 控制活动资产,并以 `asset-control-change` 作为按钮 pressed 状态的唯一真值来源。
380
+ 5. 为 URDF/MJCF/USD 部署 MuJoCo/OpenUSD runtime;远端资产配置 CORS、MIME、鉴权与相对资源路径,USD 页面同时满足 HTTPS 和 COOP/COEP。
381
+
382
+ ## 0.3.0
383
+
384
+ - 新增 `ViewerPlugin`、`ViewerPluginContext`、8 类贡献点及 `viewer.use()` / `viewer.plugins` 生命周期管理。
385
+ - 新增 `cadInteraction: 'managed' | 'manual' | 'disabled'`、统一 `hitTest/select/clearSelection`、overlay 原语和 camera state API。
386
+ - `camera.setState()` 当前只承诺立即应用经过校验的快照;动画相机切换保留到后续 P2 能力。
387
+ - **Breaking:** 删除 `pickTextAtScreen`、`selectInsert`、`setTextSelection` 三套旧选择入口;迁移为 `hitTest()` 获取 `CadHit`,再调用 `select(hit ? { kind: hit.kind, selection: hit.selection } : null)` 或 `clearSelection()`。
388
+ - 补齐 CAD 公共类型导出、状态 `revision`、图层确定性可见性命令、同步 `CameraStateStore`、加载进度/结构化错误事件。
389
+ - 无参 `fitView()` 现在适配全部内容;需要聚焦 CAD 选择时使用 `viewer.cad.fitSelection()`。
390
+ - `cad-readonly` UI 作为内置插件注册,并支持语义 tokens、style 逃生舱、实例隔离持久化和 `ui-layout-change` 事件。
391
+ - 内置 UI 文案支持 `locale`、`messages`、`messageResolver`,属性面板与比例尺支持 `unitFormatter`。
392
+ - `addObject(object, { ownership: 'borrowed' })` 明确由调用方持有并释放 Object3D 的 GPU 资源。
393
+
394
+ ## 0.2.4
395
+
396
+ - Keep `@nebula-spatial/cad-loader` as an external runtime dependency so compatible loader updates can be installed independently.
397
+ - Expose `configureViewerText()` as the explicit global Troika text-builder initialization entry point.
398
+ - Render staged external CAD block batches as they become available while preserving active downloads during interaction.
399
+
400
+ ## 0.2.3
401
+
402
+ - Start rendering base CAD geometry before external block sidecars finish loading.
403
+ - Reuse the CAD geometry Worker and retained main buffer during incremental variant loading.
404
+ - Expose CAD session load timing through the public viewer CAD document model.
405
+
406
+ ## 0.2.2
407
+
408
+ - Refreshed selected INSERT details and overlays when incremental CAD content expands their bounding boxes.
409
+
410
+ ## 0.2.1
411
+
412
+ - Resolved the geometry preparation Worker from the published package instead of the site root.
413
+ - Added `CadOpenOptions.workerUrl` and `workerFactory` for custom Worker hosting.
414
+ - Use the built-in room environment by default and support external HDR URLs through `ViewerOptions.environment`.
415
+
416
+ ## 0.2.0
417
+
418
+ - Added `viewer.cad` for opening, closing, and observing CAD documents.
419
+ - Added CAD document, layer, block, inspector, HUD, camera state, and optional read-only UI models.
420
+ - Added pointer, viewport, interaction, content, and camera lifecycle events.
421
+ - Added the runtime dependency on `@nebula-spatial/cad-loader` for CAD document support.
422
+ - Retained the existing generic Three.js object management and picking APIs.
423
+
424
+ ## 0.1.0
425
+
426
+ - Initial public release of the read-only Three.js Viewer facade.
@@ -0,0 +1,97 @@
1
+ # FBX 常规材质转换:当前契约与验收边界
2
+
3
+ 策略标识:`blender-compatible-v1`。这是导入兼容策略,不是无损 BRDF 转换,也不承诺与 Blender 像素一致。
4
+
5
+ ## 已实现的加固
6
+
7
+ - 材质声明按 shading model 选择对应模板,不把 Phong 模板套给 Lambert。
8
+ - 标量贴图当前明确采用原始 R 通道、identity 映射;复制至 RGBA 以适配不同目标槽位。此规则不推广为所有导出器的通用语义。
9
+ - 派生结果使用 DataTexture,避免再次经 Canvas 的预乘 Alpha 存储;按源 flipY 显式翻转行,保留 UV 与采样参数。
10
+ - 派生纹理按源纹理缓存。同一目标槽位多个输入采用连接顺序的首个可用输入,并报告冲突,不静默覆盖。
11
+ - 转换先准备全部替换对象,全部成功后才写入场景;失败释放新材质及派生纹理,保留原材质。
12
+ - 材质 userData.fbxConversionReport 与模型包装节点 userData.fbxConversionReports 保存策略、材质 ID、映射规则及近似/不支持项。这是内部诊断数据,不是新增的公共 Viewer API。
13
+ - 未解析的纹理连接明确报告。加载资源错误仍通过 opened rejection 传播,尚未统一成稳定的公共错误代码。
14
+ - 取消和首个加载失败触发同批请求取消;不等待不响应取消的 resolver/decode。晚到解码结果不写回场景,并释放纹理。
15
+ - 释放额外加载纹理时也处理可关闭的共享图像,避免遗漏或重复关闭。
16
+
17
+ ## 本轮自动化验证
18
+
19
+ 像素字节布局、R/Alpha 通道与反转、行翻转和采样状态;材质共享、转换回滚及派生纹理释放;模板选择;异步解析、取消、晚到解码结果;共享图像释放。
20
+
21
+ ## 初始阶段待验收项(后续进展见下文)
22
+
23
+ - 真实浏览器 PNG/JPEG 解码、GPU 采样读回与透明边缘测试。输入仍经过 Canvas 解码取样,完全透明像素的隐藏 RGB 以及浏览器色彩管理限制尚未解决。
24
+ - 不要求 Blender 逐像素对照;以真实浏览器的加载、显示、采样和异常恢复为验收依据。
25
+ - 通道选择、透明极性、颜色到标量转换与各导出器实物样本的完整对照;当前 R/identity 是已命名策略,不是这些差异已经解决。
26
+ - 全部 FBX 参数及资源错误的结构化诊断覆盖。
27
+ - FBXLoader 内部 parse 抛错前已构建且未返回的几何/材质,以及未使用内嵌 Video object URL 的所有权审计。
28
+ - 多 UV、复杂纹理变换、TGA/DDS 专用解码、分层贴图和自定义着色器。
29
+
30
+ 完成更广泛的真实解码/GPU 与资产回归后,再扩大多 UV 和纹理变换覆盖;不能仅凭单元测试宣称常规材质全量正确。
31
+
32
+
33
+ ## 2026-09-17 真实浏览器验证
34
+
35
+ 环境:Windows,Chromium 153,WebGL 2.0(OpenGL ES 3.0 Chromium)。
36
+
37
+ - PNG 编码 → HTMLImageElement 实际解码 → 生产标量转换 → WebGLRenderTarget 像素读回:通过。2×2 输入 R 值为 1/64/128/255,输出 RGBA 与行翻转后的预期完全一致。
38
+ - 货架 A:3 个网格、1 个材质、2 张内嵌纹理,加载并显示蓝色立柱和橙红横梁,无全黑现象。
39
+ - 工作台 A:1 个网格、5 个材质,显示灰绿色台面、白色框架和深色脚垫。窄视口下存在横向构图裁切,未归因于材质,也未在本轮修改相机适应逻辑。
40
+ - 料箱 a_1:1 个网格、1 个材质,灰色箱体及明暗层次可见。
41
+ - 货架 → 工作台 → 料箱 → 货架的加载/释放检查通过;货架的两张纹理分别只收到一次 dispose。此检查不是长时间 GPU 内存泄漏压力测试。
42
+ - 构造的无效纹理连接显示降级详情;含 Video 引用但图片不存在的样本进入失败状态。Vite fallback 返回非图片内容,实际覆盖的是图片解码失败,不是 HTTP 404 状态分支。
43
+ - 发现并修复图片解码错误显示为 `[object Event]` 的问题;现在显示 `FBX texture decode failed: missing.png`。
44
+ - 失败后重新打开货架,恢复正常显示,无残留错误提示。
45
+
46
+ 可复用浏览器验证入口见 `playground/fbx-validation/README.md`:TGA/DDS 与分层检查使用仓库内的合成夹具;真实 FBX 回归需自行准备本地模型,商业资产不随仓库分发。下述浏览器结果保留为此前阶段的验证记录,不代表每次提交都已重新执行。
47
+
48
+ 本轮未覆盖所有 PBR 槽位的完整着色器效果、半透明 PNG 隐藏 RGB、其他浏览器/显卡、长时间内存压力和真实网络取消;不将以上结果解释为任意 FBX 均转换正确。
49
+
50
+ ## 扩展第一阶段:多 UV 与二维纹理变换(2026-09-17)
51
+
52
+ - 读取 Geometry/LayerElementUV 的名称,按 FBXLoader r182 的连续层索引规则映射到 uv、uv1、uv2、uv3;不读取或解压几何 UV 数组。
53
+ - Texture.UVSet 按模型所连接的几何名称匹配;未知、重名、缺少属性或超出支持通道时明确报告。未声明 UVSet 或未匹配的 default 使用首通道。
54
+ - 同一材质被不同 UV 布局的网格使用时,仅对需要改变绑定的实例克隆材质与纹理;图像源仍共享,不修改原纹理。保留转换失败时的事务回滚。
55
+ - 支持平移和缩放;W 轴旋转采用显式二维兼容规则 T * Rccw * S,以 UV 原点为中心、角度单位为度。非等比缩放直接构造矩阵,避免矩阵组合顺序错误。
56
+ - 旋转仍标记为 TEXTURE_ROTATION_PROFILE 近似项,并在页面提示;尚无覆盖各导出器的旋转语义实物基准,不能宣称所有 FBX 旋转都精确还原。
57
+ - 三维旋转、非零 RotationPivot/ScalingPivot、三维平移/缩放分量不支持时报告,不把它们当成普通二维变换。
58
+ - 浏览器通过实际 MeshPhysicalMaterial 的 emissiveMap 着色器验证 uv1:输出绿色 [0,255,0,255];W 旋转和平移后输出红色 [255,0,0,255]。这是生产转换后 GPU 采样验证,而非只验证 JavaScript 数值。
59
+ - 货架/工作台/料箱/货架加载释放回归仍通过。多 UV 的专项样本为合成几何与声明,仍需后续增加真实导出器多 UV 文件。
60
+
61
+ ## 扩展第二阶段:TGA / DDS(2026-09-17)
62
+
63
+ - 新增按原始扩展名选择的专用解码器,保留 FBXLoader 同步返回纹理的身份、ID、色彩空间、UV 和包裹方式。已接入异步 resolver、fetch AbortSignal、失败释放流程。
64
+ - TGA:非交错 24/32 位真彩色、8/16 位灰度,未压缩及 RLE;调色板、16 位真彩色暂不支持。解析前校验头、数据长度、RLE 边界和尺寸。
65
+ - DDS:传统二维 DXT1/BC1、DXT3/BC2、DXT5/BC3,以及明确 RGB/BGR 24 位和 RGBA/BGRA 32 位掩码布局;支持未压缩行间距。DX10、BC4/5/6/7、立方体、体积及其他布局明确报错。
66
+ - DDS 在 CPU 解码为 RGBA8,不依赖 GPU 压缩纹理扩展;因此可以进入现有标量贴图转换。代价是更高的解码后内存占用,限制单图最多 16M 像素。
67
+ - 只读取 DDS 基础 mip,后续 mip 由 GPU 重建,不保留源文件手工制作的 mip 链。DDS 采用顶行优先、显式翻行为 GPU 行序的约定;不同生产管线仍需实物样本确认方向。
68
+ - TGA 原点标志由 TGALoader 归一化,再显式翻转 GPU 行序,避免 typed-array 上传依赖 flipY。
69
+ - 外部 TGA/DDS 已通过真实 ASCII FBXLoader、本地文件包、材质转换链路。handler 可接收 TGA 的 blob/data 地址;FBXLoader r182 本身不解析内嵌 DDS,因此不宣称内嵌 DDS 可用。
70
+ - 浏览器 Chromium 153 / WebGL2 对 TGA、TGA-RLE、DXT1、DXT3、DXT5、未压缩 BGRA 的颜色、Alpha、派生标量纹理逐字节 GPU 读回全部通过;真实 FBX 文件包加载也通过。
71
+ - 使用自编微型格式样本;尚未完成各导出器真实 TGA/DDS 资产验收。不把纹理 Alpha 保留等同于自动推断材质透明模式,也不把本轮结果解释为任意 DDS 都受支持。
72
+
73
+ ## 扩展第三阶段 A:分层贴图解析与诊断(2026-09-17)
74
+
75
+ - 新增 LayeredTexture 声明,保留 OO 源连接顺序、BlendModes 原始数值和 Alphas,不按 ID 排序、不猜测堆叠方向或混合方程。
76
+ - 支持 ASCII 数组、二进制 FBX 7400/7500 的整数/浮点数组和 zlib 压缩。仅解压层参数数组,不加载几何数组;单个数组限制 4096 元素。
77
+ - 检查空层、缺失源、嵌套、循环引用、参数数量不匹配、非法权重及 UV/变换差异,并设置图遍历深度和节点限制。
78
+ - 材质转换报告增加 layerStacks,细化每层 ID、模式、权重和诊断。所有分层仍报告 LAYERED_TEXTURE_NOT_COMPOSITED,经现有 session 警告链路传递。
79
+ - 本阶段尚未合成分层,保留 FBXLoader 的首层预览,不把该预览标为完整支持。诊断在材质转换阶段生成;FBXLoader 对畸形空层等文件可能提前抛错,不能保证所有坏文件都进入诊断阶段。
80
+ - 自动测试覆盖连接顺序、数量不匹配、权重越界、循环、缺失源、材质报告以及四种二进制版本/压缩组合。
81
+ - Chromium 153 实际 FBXLoader 文件包验证:两层 ID 4/6、模式 0/4、权重 1/0.5 被完整保留,明确返回未合成诊断。原 TGA/DDS GPU 回归全部通过。
82
+
83
+ 下一步为阶段 B:以经过确认的模式编号、层方向、线性色彩计算与 Alpha 规则实现受限合成;仅接受可证明兼容的 UV/采样配置,对不同 UV、嵌套、法线混合等继续明确拒绝或降级。
84
+
85
+ ## 常用范围收尾:受限颜色分层合成(2026-09-17)
86
+
87
+ 本节是当前状态,覆盖前述“尚未合成”的阶段记录。
88
+
89
+ - 仅 DiffuseColor / EmissiveColor;1–8 层,同尺寸、同 UV 声明/变换、同采样配置,单层最多 4M 像素。
90
+ - 首个连接为底层,要求底层完全不透明且权重为 1;后续层按连接顺序叠加。模式 0/4/5 按普通覆盖处理,1 为加法,2 为乘法。
91
+ - 在 linear RGB 中混合,层权重乘以该层像素 Alpha,输出 sRGB RGBA8。不声明不同导出器的任意堆叠语义都等价。
92
+ - 输出属于 linear-color-v1 烘焙兼容策略,记录 LAYERED_TEXTURE_BAKED 近似提示;烘焙后过滤与逐层实时采样不严格等价。源未声明色彩空间时按普通颜色 sRGB 解释。
93
+ - 不支持的模式、半透明底层、不同尺寸/UV、嵌套、法线及标量分层保留原预览并报告拒绝原因,不继续扩展。
94
+ - 合成纹理进入事务回滚与释放管理,并使用底层纹理声明进行多 UV 绑定。
95
+ - 验证:红/蓝 50% 线性混合得到 [188,0,188];普通覆盖/加法/乘法/层 Alpha/拒绝分支测试通过。真实浏览器的 FBX 文件包 → 分层合成 → GPU 读回通过;半透明底层拒绝诊断及 TGA/DDS 回归通过。
96
+
97
+ 当前按常用情况收口,不将任意 FBX/自定义着色器无损转换作为交付条件;不要求 Blender 像素对比。新增复杂需求以实际资产复现为驱动。