@realsee/five-webgpu 1.0.0-alpha.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 (674) hide show
  1. package/AGENTS_READ_ME.md +9 -0
  2. package/AI_CONTEXT.md +9 -0
  3. package/README.md +80 -0
  4. package/TERMS.txt +54 -0
  5. package/ai_guides/README.md +118 -0
  6. package/ai_guides/ai-doc-guidelines.md +102 -0
  7. package/ai_guides/api.md +274 -0
  8. package/ai_guides/features/3dtile.md +172 -0
  9. package/ai_guides/features/camera-animation.md +205 -0
  10. package/ai_guides/features/clipper.md +135 -0
  11. package/ai_guides/features/coordinate-system.md +128 -0
  12. package/ai_guides/features/event.md +154 -0
  13. package/ai_guides/features/five.md +184 -0
  14. package/ai_guides/features/gesture.md +181 -0
  15. package/ai_guides/features/get-screen-pixels.md +182 -0
  16. package/ai_guides/features/image-options.md +164 -0
  17. package/ai_guides/features/load-external-model.md +350 -0
  18. package/ai_guides/features/load-progress.md +140 -0
  19. package/ai_guides/features/material.md +153 -0
  20. package/ai_guides/features/mode.md +269 -0
  21. package/ai_guides/features/model.md +186 -0
  22. package/ai_guides/features/move-pano-effect.md +145 -0
  23. package/ai_guides/features/multi-work.md +146 -0
  24. package/ai_guides/features/pano-filter.md +144 -0
  25. package/ai_guides/features/pano-tile.md +132 -0
  26. package/ai_guides/features/pano-uv.md +131 -0
  27. package/ai_guides/features/parameter.md +153 -0
  28. package/ai_guides/features/raycast.md +175 -0
  29. package/ai_guides/features/request-proxy.md +112 -0
  30. package/ai_guides/features/screen-project.md +165 -0
  31. package/ai_guides/features/state.md +101 -0
  32. package/ai_guides/features/ultra-hdr.md +204 -0
  33. package/ai_guides/features/view-layer.md +187 -0
  34. package/ai_guides/features/work.md +303 -0
  35. package/ai_guides/glossary.md +93 -0
  36. package/ai_guides/intro.md +23 -0
  37. package/ai_guides/quick-start.md +69 -0
  38. package/ai_guides/release_notes/6.6.md +86 -0
  39. package/ai_guides/release_notes/6.7.md +401 -0
  40. package/ai_guides/release_notes/6.8.md +208 -0
  41. package/ai_guides/support.md +23 -0
  42. package/ai_guides/template.md +70 -0
  43. package/docs/.nojekyll +1 -0
  44. package/docs/00_FOR_AI_AGENTS.md +12 -0
  45. package/docs/README.md +12 -0
  46. package/docs/assets/hierarchy.js +1 -0
  47. package/docs/assets/highlight.css +134 -0
  48. package/docs/assets/icons.js +18 -0
  49. package/docs/assets/icons.svg +1 -0
  50. package/docs/assets/main.js +60 -0
  51. package/docs/assets/navigation.js +1 -0
  52. package/docs/assets/search.js +1 -0
  53. package/docs/assets/style.css +1633 -0
  54. package/docs/classes/index.AdaptiveLuminancePass.html +23 -0
  55. package/docs/classes/index.AnimationFrameLoop.html +18 -0
  56. package/docs/classes/index.BoundingMesh.html +4 -0
  57. package/docs/classes/index.Camera.html +42 -0
  58. package/docs/classes/index.EffectComposer.html +25 -0
  59. package/docs/classes/index.EyeDomeLightingPass.html +20 -0
  60. package/docs/classes/index.Fetcher.html +5 -0
  61. package/docs/classes/index.Five.html +311 -0
  62. package/docs/classes/index.FivePass.html +17 -0
  63. package/docs/classes/index.FiveRenderer.html +8 -0
  64. package/docs/classes/index.FlowingFireworks3DPass.html +22 -0
  65. package/docs/classes/index.FlowingLight2DPass.html +21 -0
  66. package/docs/classes/index.FlowingLight3DPass.html +23 -0
  67. package/docs/classes/index.FullScreenQuad.html +7 -0
  68. package/docs/classes/index.GaussianBlurPass.html +19 -0
  69. package/docs/classes/index.Histogram.html +19 -0
  70. package/docs/classes/index.InternalWebGPURenderer.html +4 -0
  71. package/docs/classes/index.Model.html +93 -0
  72. package/docs/classes/index.ModelScene.html +40 -0
  73. package/docs/classes/index.Motion.html +17 -0
  74. package/docs/classes/index.NetworkSubscribe.html +41 -0
  75. package/docs/classes/index.PBMGaussianSplattingNodeMaterial.html +37 -0
  76. package/docs/classes/index.PBMGaussianSplattingObject.html +32 -0
  77. package/docs/classes/index.PBMGaussianSplattingRenderMesh.html +19 -0
  78. package/docs/classes/index.PBMGroup.html +5 -0
  79. package/docs/classes/index.PBMMesh.html +2 -0
  80. package/docs/classes/index.PBMMeshBasicMaterial.html +70 -0
  81. package/docs/classes/index.PBMMeshBasicNodeMaterial.html +74 -0
  82. package/docs/classes/index.PBMMeshPanoOnlyMaterial.html +70 -0
  83. package/docs/classes/index.PBMMeshPanoOnlyNodeMaterial.html +74 -0
  84. package/docs/classes/index.PBMMeshPhongMaterial.html +69 -0
  85. package/docs/classes/index.PBMMeshPhongNodeMaterial.html +73 -0
  86. package/docs/classes/index.PBMMeshPhysicalMaterial.html +69 -0
  87. package/docs/classes/index.PBMMeshPhysicalNodeMaterial.html +73 -0
  88. package/docs/classes/index.PBMPanoFilter.html +61 -0
  89. package/docs/classes/index.PBMPointCloud.html +50 -0
  90. package/docs/classes/index.PBMSkinnedMesh.html +8 -0
  91. package/docs/classes/index.PBMUpdateable.html +41 -0
  92. package/docs/classes/index.PanoCircleMesh.html +30 -0
  93. package/docs/classes/index.PanoCircleMeshCustom.html +30 -0
  94. package/docs/classes/index.PanoCircleMeshSolid.html +30 -0
  95. package/docs/classes/index.Parameter.html +114 -0
  96. package/docs/classes/index.Scene.html +18 -0
  97. package/docs/classes/index.Subscribe.html +43 -0
  98. package/docs/classes/index.TextureLoader.html +4 -0
  99. package/docs/classes/index.Tile.html +34 -0
  100. package/docs/classes/index.Tile3D.html +98 -0
  101. package/docs/classes/index.TileCache.html +8 -0
  102. package/docs/classes/index.TileNode.html +14 -0
  103. package/docs/classes/index.TileRequestScheduler.html +4 -0
  104. package/docs/classes/index.Tileset.html +38 -0
  105. package/docs/classes/index.Trajectory.html +8 -0
  106. package/docs/classes/index.TrajectoryNode.html +8 -0
  107. package/docs/classes/index.Work.html +52 -0
  108. package/docs/classes/index.WorkResolvedObserver.html +68 -0
  109. package/docs/documents/README.html +134 -0
  110. package/docs/documents/ai-doc-guidelines.html +117 -0
  111. package/docs/documents/api.html +337 -0
  112. package/docs/documents/features_3dtile.html +216 -0
  113. package/docs/documents/features_camera-animation.html +157 -0
  114. package/docs/documents/features_clipper.html +80 -0
  115. package/docs/documents/features_coordinate-system.html +127 -0
  116. package/docs/documents/features_event.html +104 -0
  117. package/docs/documents/features_five.html +147 -0
  118. package/docs/documents/features_gesture.html +121 -0
  119. package/docs/documents/features_get-screen-pixels.html +88 -0
  120. package/docs/documents/features_image-options.html +108 -0
  121. package/docs/documents/features_load-external-model.html +600 -0
  122. package/docs/documents/features_load-progress.html +110 -0
  123. package/docs/documents/features_material.html +341 -0
  124. package/docs/documents/features_mode.html +114 -0
  125. package/docs/documents/features_model.html +141 -0
  126. package/docs/documents/features_move-pano-effect.html +110 -0
  127. package/docs/documents/features_multi-work.html +97 -0
  128. package/docs/documents/features_pano-filter.html +119 -0
  129. package/docs/documents/features_pano-tile.html +100 -0
  130. package/docs/documents/features_pano-uv.html +82 -0
  131. package/docs/documents/features_parameter.html +101 -0
  132. package/docs/documents/features_raycast.html +98 -0
  133. package/docs/documents/features_request-proxy.html +78 -0
  134. package/docs/documents/features_screen-project.html +112 -0
  135. package/docs/documents/features_state.html +71 -0
  136. package/docs/documents/features_ultra-hdr.html +188 -0
  137. package/docs/documents/features_view-layer.html +158 -0
  138. package/docs/documents/features_work.html +129 -0
  139. package/docs/documents/glossary.html +94 -0
  140. package/docs/documents/intro.html +24 -0
  141. package/docs/documents/quick-start.html +32 -0
  142. package/docs/documents/release_notes_6.6.html +79 -0
  143. package/docs/documents/release_notes_6.7.html +209 -0
  144. package/docs/documents/release_notes_6.8.html +189 -0
  145. package/docs/documents/support.html +49 -0
  146. package/docs/documents/template.html +80 -0
  147. package/docs/enums/index.VolumePlaneIntersect.html +4 -0
  148. package/docs/functions/index.coordinatesToVector.html +2 -0
  149. package/docs/functions/index.createDebugBoundingMesh.html +1 -0
  150. package/docs/functions/index.createWorks.html +1 -0
  151. package/docs/functions/index.defaultImageURLTransform.html +5 -0
  152. package/docs/functions/index.getViewportScale.html +1 -0
  153. package/docs/functions/index.headingToLongitude.html +4 -0
  154. package/docs/functions/index.imageSupport.html +1 -0
  155. package/docs/functions/index.isBoundingVolume.html +1 -0
  156. package/docs/functions/index.isPanoId.html +1 -0
  157. package/docs/functions/index.loadAt3d.html +1 -0
  158. package/docs/functions/index.loadDome.html +1 -0
  159. package/docs/functions/index.loadDomez.html +1 -0
  160. package/docs/functions/index.loadGltf.html +1 -0
  161. package/docs/functions/index.loadPbm.html +1 -0
  162. package/docs/functions/index.loadPly.html +1 -0
  163. package/docs/functions/index.longitudeToHeading.html +4 -0
  164. package/docs/functions/index.makeBoundingVolume.html +1 -0
  165. package/docs/functions/index.panoEqual.html +1 -0
  166. package/docs/functions/index.panoParse.html +1 -0
  167. package/docs/functions/index.panoStringify.html +1 -0
  168. package/docs/functions/index.parseWork.html +7 -0
  169. package/docs/functions/index.registerPBMMaterials.html +3 -0
  170. package/docs/functions/index.vectorToCoordinates.html +2 -0
  171. package/docs/functions/index.workToJson.html +1 -0
  172. package/docs/hierarchy.html +1 -0
  173. package/docs/index.html +134 -0
  174. package/docs/interfaces/index.AddableObject.html +9 -0
  175. package/docs/interfaces/index.AjaxOptions.html +9 -0
  176. package/docs/interfaces/index.AnimationFrame.html +6 -0
  177. package/docs/interfaces/index.AnimationFrameContext.html +3 -0
  178. package/docs/interfaces/index.BaseEvent.html +5 -0
  179. package/docs/interfaces/index.BoundingVolume.html +15 -0
  180. package/docs/interfaces/index.BoxBoundingVolume.html +18 -0
  181. package/docs/interfaces/index.CameraPose.html +6 -0
  182. package/docs/interfaces/index.CullingVolume.html +9 -0
  183. package/docs/interfaces/index.Draco.html +12 -0
  184. package/docs/interfaces/index.EventCallback.html +394 -0
  185. package/docs/interfaces/index.FiveInitArgs.html +104 -0
  186. package/docs/interfaces/index.FiveLoadOptions.html +12 -0
  187. package/docs/interfaces/index.FloorplanControllerCustomInitArgs.html +17 -0
  188. package/docs/interfaces/index.GestureEvent.html +19 -0
  189. package/docs/interfaces/index.IPBMMaterial.html +64 -0
  190. package/docs/interfaces/index.ImageOptions.html +21 -0
  191. package/docs/interfaces/index.ImageURLMappings.html +1 -0
  192. package/docs/interfaces/index.ImageURLOptions.html +17 -0
  193. package/docs/interfaces/index.IntersectEvent.html +8 -0
  194. package/docs/interfaces/index.IntersectMesh.html +2 -0
  195. package/docs/interfaces/index.IntersectMeshInterface.html +3 -0
  196. package/docs/interfaces/index.Intersection.html +9 -0
  197. package/docs/interfaces/index.LoosePanoWork.html +10 -0
  198. package/docs/interfaces/index.LooseWork.html +15 -0
  199. package/docs/interfaces/index.LooseWorkInitial.html +11 -0
  200. package/docs/interfaces/index.LooseWorkModel.html +8 -0
  201. package/docs/interfaces/index.LooseWorkObserver.html +17 -0
  202. package/docs/interfaces/index.LooseWorkPanorama.html +22 -0
  203. package/docs/interfaces/index.LooseWorkVideo.html +4 -0
  204. package/docs/interfaces/index.LooseWorkWithExtrinsics.html +15 -0
  205. package/docs/interfaces/index.MapviewControllerCustomInitArgs.html +20 -0
  206. package/docs/interfaces/index.ModeChangeEvent.html +9 -0
  207. package/docs/interfaces/index.ModelControllerCustomInitArgs.html +20 -0
  208. package/docs/interfaces/index.ModelEvent.html +8 -0
  209. package/docs/interfaces/index.ModelOptions.html +11 -0
  210. package/docs/interfaces/index.ModelSceneEvent.html +6 -0
  211. package/docs/interfaces/index.ModelTileEvent.html +8 -0
  212. package/docs/interfaces/index.MotionKeyframe.html +4 -0
  213. package/docs/interfaces/index.MovePanoOptions.html +35 -0
  214. package/docs/interfaces/index.NetworkAbortError.html +1 -0
  215. package/docs/interfaces/index.NetworkFirbiddenError.html +1 -0
  216. package/docs/interfaces/index.NetworkOptions.html +7 -0
  217. package/docs/interfaces/index.NetworkProxyError.html +1 -0
  218. package/docs/interfaces/index.NetworkResourceEvent.html +9 -0
  219. package/docs/interfaces/index.NetworkResponseError.html +2 -0
  220. package/docs/interfaces/index.NetworkTimeoutError.html +1 -0
  221. package/docs/interfaces/index.ObjectEvent.html +6 -0
  222. package/docs/interfaces/index.PBMClipperParameter.html +3 -0
  223. package/docs/interfaces/index.PBMHDRConfig.html +12 -0
  224. package/docs/interfaces/index.PBMPanoDepth.html +9 -0
  225. package/docs/interfaces/index.PBMPanoFilterValue.html +6 -0
  226. package/docs/interfaces/index.PBMPanoPicture.html +14 -0
  227. package/docs/interfaces/index.PBMRefinedScreen.html +6 -0
  228. package/docs/interfaces/index.PanoCircleMeshCustomOptions.html +9 -0
  229. package/docs/interfaces/index.PanoCircleMeshInterface.html +30 -0
  230. package/docs/interfaces/index.PanoCircleMeshOptions.html +3 -0
  231. package/docs/interfaces/index.PanoCircleMeshSolidOptions.html +3 -0
  232. package/docs/interfaces/index.PanoEvent.html +11 -0
  233. package/docs/interfaces/index.PanoTextureEvent.html +9 -0
  234. package/docs/interfaces/index.PanoramaControllerCustomInitArgs.html +41 -0
  235. package/docs/interfaces/index.PanoramaLikeControllerCustomInitArgs.html +20 -0
  236. package/docs/interfaces/index.ParameterMaterialValue.html +74 -0
  237. package/docs/interfaces/index.ParameterTilesetValue.html +30 -0
  238. package/docs/interfaces/index.ParameterValue.html +103 -0
  239. package/docs/interfaces/index.Pass.html +9 -0
  240. package/docs/interfaces/index.PointCloudData.html +6 -0
  241. package/docs/interfaces/index.Pose.html +12 -0
  242. package/docs/interfaces/index.RegionBoundingVolume.html +21 -0
  243. package/docs/interfaces/index.RenderEvent.html +6 -0
  244. package/docs/interfaces/index.ResolvedParameterValue.html +104 -0
  245. package/docs/interfaces/index.RgbaData.html +7 -0
  246. package/docs/interfaces/index.SphereBoundingVolume.html +17 -0
  247. package/docs/interfaces/index.SplatData.html +10 -0
  248. package/docs/interfaces/index.State.html +23 -0
  249. package/docs/interfaces/index.StateEvent.html +7 -0
  250. package/docs/interfaces/index.TextureOptions.html +23 -0
  251. package/docs/interfaces/index.Tile3DOptions.html +11 -0
  252. package/docs/interfaces/index.TileCoordinateSystem.html +3 -0
  253. package/docs/interfaces/index.TileHeader.html +9 -0
  254. package/docs/interfaces/index.TilesetHeader.html +20 -0
  255. package/docs/interfaces/index.TilesetOptions.html +7 -0
  256. package/docs/interfaces/index.TopviewControllerCustomInitArgs.html +13 -0
  257. package/docs/interfaces/index.TrajectoryHeader.html +5 -0
  258. package/docs/interfaces/index.ViewLayer.html +97 -0
  259. package/docs/interfaces/index.Viewport.html +13 -0
  260. package/docs/interfaces/index.WebXRAxesParams.html +4 -0
  261. package/docs/interfaces/index.WebXRControllerParams.html +2 -0
  262. package/docs/interfaces/index.WorkCubeImage.html +15 -0
  263. package/docs/interfaces/index.WorkImage.html +22 -0
  264. package/docs/interfaces/index.WorkInitial.html +17 -0
  265. package/docs/interfaces/index.WorkInitialJson.html +8 -0
  266. package/docs/interfaces/index.WorkJson.html +11 -0
  267. package/docs/interfaces/index.WorkModel.html +16 -0
  268. package/docs/interfaces/index.WorkModelJson.html +6 -0
  269. package/docs/interfaces/index.WorkModelLayer.html +11 -0
  270. package/docs/interfaces/index.WorkModelLayerJson.html +5 -0
  271. package/docs/interfaces/index.WorkObserver.html +63 -0
  272. package/docs/interfaces/index.WorkObserverJson.html +10 -0
  273. package/docs/interfaces/index.WorkPanoramaJson.html +14 -0
  274. package/docs/interfaces/index.WorkPanoramasJson.html +3 -0
  275. package/docs/interfaces/index.WorkTile.html +21 -0
  276. package/docs/interfaces/index.WorkVideo.html +9 -0
  277. package/docs/interfaces/index.WorksEvent.html +8 -0
  278. package/docs/interfaces/index.XRControllerEvent.html +8 -0
  279. package/docs/interfaces/index.XRGestureEvent.html +11 -0
  280. package/docs/interfaces/index.XRSessionEvent.html +7 -0
  281. package/docs/modules/index.html +1 -0
  282. package/docs/modules.html +1 -0
  283. package/docs/types/index.AjaxResponseType.html +1 -0
  284. package/docs/types/index.AjaxResponseTypeMapping.html +1 -0
  285. package/docs/types/index.AnimationFrameLoopType.html +1 -0
  286. package/docs/types/index.BoundingVolumeJson.html +1 -0
  287. package/docs/types/index.BoxBoundingVolumeJson.html +2 -0
  288. package/docs/types/index.ControllerCustomInitTypes.html +6 -0
  289. package/docs/types/index.ControllerEventTypes.html +68 -0
  290. package/docs/types/index.CubeFace.html +1 -0
  291. package/docs/types/index.EasingFunction.html +1 -0
  292. package/docs/types/index.EventTypes.html +28 -0
  293. package/docs/types/index.FivePlugin.html +4 -0
  294. package/docs/types/index.FivePluginInit.html +3 -0
  295. package/docs/types/index.FivePluginInstance.html +3 -0
  296. package/docs/types/index.FlowingFireworks3DPassLine.html +16 -0
  297. package/docs/types/index.FlowingLight2DPassLine.html +10 -0
  298. package/docs/types/index.FlowingLight3DPassLine.html +10 -0
  299. package/docs/types/index.GestureTypes.html +1 -0
  300. package/docs/types/index.LegacyEventType.html +282 -0
  301. package/docs/types/index.LoadResultType.html +12 -0
  302. package/docs/types/index.Mode.html +15 -0
  303. package/docs/types/index.Models.html +11 -0
  304. package/docs/types/index.MotionCircle.html +2 -0
  305. package/docs/types/index.MotionConfig.html +1 -0
  306. package/docs/types/index.MotionInitalValue.html +1 -0
  307. package/docs/types/index.MotionValue.html +1 -0
  308. package/docs/types/index.MovePanoEffect.html +12 -0
  309. package/docs/types/index.NetWorkMeta.html +8 -0
  310. package/docs/types/index.NetworkError.html +1 -0
  311. package/docs/types/index.NetworkErrorCallback.html +1 -0
  312. package/docs/types/index.NetworkProgressCallback.html +1 -0
  313. package/docs/types/index.NetworkResponse.html +3 -0
  314. package/docs/types/index.NetworkState.html +1 -0
  315. package/docs/types/index.NetworkSuccessCallback.html +1 -0
  316. package/docs/types/index.NetworkType.html +1 -0
  317. package/docs/types/index.OutputTextureDataType.html +1 -0
  318. package/docs/types/index.PBMAlphaMode.html +1 -0
  319. package/docs/types/index.PBMColorStyle.html +1 -0
  320. package/docs/types/index.PBMFloorStyle.html +1 -0
  321. package/docs/types/index.PBMMeshMaterial.html +1 -0
  322. package/docs/types/index.PBMPointBack.html +1 -0
  323. package/docs/types/index.PBMPointCloudShaderType.html +1 -0
  324. package/docs/types/index.PBMPointShape.html +1 -0
  325. package/docs/types/index.PBMPointSize.html +1 -0
  326. package/docs/types/index.PBMTransition.html +1 -0
  327. package/docs/types/index.Pano.html +3 -0
  328. package/docs/types/index.PanoId.html +1 -0
  329. package/docs/types/index.ParseOptions.html +13 -0
  330. package/docs/types/index.PostProcessingType.html +1 -0
  331. package/docs/types/index.RegionBoundingVolumeJson.html +2 -0
  332. package/docs/types/index.RequestAnimationFrameArgs.html +1 -0
  333. package/docs/types/index.Scissor.html +2 -0
  334. package/docs/types/index.SphereBoundingVolumeJson.html +2 -0
  335. package/docs/types/index.SubscribeEventMap.html +1 -0
  336. package/docs/types/index.TileCacheOptions.html +3 -0
  337. package/docs/types/index.TileContentData.html +6 -0
  338. package/docs/types/index.TileRequestOrder.html +1 -0
  339. package/docs/types/index.TileRequestSchedulerOptions.html +4 -0
  340. package/docs/types/index.TilesetFrameState.html +21 -0
  341. package/docs/types/index.TrajectoryContentData.html +7 -0
  342. package/docs/types/index.WebXRControllerKey.html +1 -0
  343. package/docs/types/index.WebXRControllerType.html +1 -0
  344. package/docs/types/index.Works.html +1 -0
  345. package/docs/variables/index.PROXY_CONTROLLER_EVENT_NAMES.html +1 -0
  346. package/docs/variables/index.controllersDefaultInitArgs.html +1 -0
  347. package/docs/variables/index.draco.html +1 -0
  348. package/five/application/analysis.d.ts +40 -0
  349. package/five/application/controllers.d.ts +33 -0
  350. package/five/application/events-legacy.d.ts +454 -0
  351. package/five/application/events.d.ts +69 -0
  352. package/five/application/five.d.ts +498 -0
  353. package/five/application/fiveInitArgs.d.ts +173 -0
  354. package/five/application/fiveLoadOptions.d.ts +21 -0
  355. package/five/application/generateDefaultVideoElement.d.ts +2 -0
  356. package/five/application/getViewportScale.d.ts +2 -0
  357. package/five/application/initLights.d.ts +3 -0
  358. package/five/application/mode.d.ts +24 -0
  359. package/five/application/renderPoweredByRealsee.d.ts +3 -0
  360. package/five/assets/cardboard-png-data-url.d.ts +2 -0
  361. package/five/assets/gradient-png-data-url.d.ts +2 -0
  362. package/five/assets/loading-png-data-url.d.ts +2 -0
  363. package/five/assets/phone-png-data-url.d.ts +2 -0
  364. package/five/assets/realsee-pmg-data-url.d.ts +2 -0
  365. package/five/bvh/bvhMath.d.ts +33 -0
  366. package/five/bvh/bvhMesh.d.ts +7 -0
  367. package/five/bvh/bvhNode.d.ts +29 -0
  368. package/five/bvh/bvhObject.d.ts +19 -0
  369. package/five/bvh/bvhPoints.d.ts +6 -0
  370. package/five/bvh/index.d.ts +14 -0
  371. package/five/bvh/type.d.ts +1 -0
  372. package/five/bvh/worker.d.ts +36 -0
  373. package/five/certificates/hardware.d.ts +1 -0
  374. package/five/controllers/base.d.ts +166 -0
  375. package/five/controllers/events.d.ts +71 -0
  376. package/five/controllers/floorplan.d.ts +119 -0
  377. package/five/controllers/mapview.d.ts +138 -0
  378. package/five/controllers/model.d.ts +57 -0
  379. package/five/controllers/panorama.d.ts +143 -0
  380. package/five/controllers/panoramaLike.d.ts +87 -0
  381. package/five/controllers/topview.d.ts +42 -0
  382. package/five/core/camera.d.ts +65 -0
  383. package/five/core/internalWebGPURenderer.d.ts +13 -0
  384. package/five/core/panoVideo.d.ts +18 -0
  385. package/five/core/scene.d.ts +10 -0
  386. package/five/core/tiling.d.ts +56 -0
  387. package/five/declare.d.ts +35 -0
  388. package/five/gaussian-splatting/util/renderData.d.ts +66 -0
  389. package/five/gaussian-splatting/wasm/data.d.ts +20 -0
  390. package/five/gaussian-splatting/wasm/sort.d.ts +18 -0
  391. package/five/gaussian-splatting/worker/dataWorker.d.ts +1 -0
  392. package/five/gaussian-splatting/worker/sortWorker.d.ts +1 -0
  393. package/five/index.d.ts +58 -0
  394. package/five/index.js +1179 -0
  395. package/five/index.mjs +25111 -0
  396. package/five/meshes/boundingMesh.d.ts +12 -0
  397. package/five/meshes/intersectMesh.d.ts +8 -0
  398. package/five/meshes/panoCircleMesh.d.ts +36 -0
  399. package/five/meshes/panoCircleMeshCustom.d.ts +40 -0
  400. package/five/meshes/panoCircleMeshSolid.d.ts +35 -0
  401. package/five/meshes/panoSphereMesh.d.ts +29 -0
  402. package/five/model/helpers/coordinate-transform.d.ts +3 -0
  403. package/five/model/helpers/ellipsoid-coordinates.d.ts +14 -0
  404. package/five/model/helpers/get-edges-by-sphere.d.ts +8 -0
  405. package/five/model/helpers/get-recommend-tile3d-parameters.d.ts +8 -0
  406. package/five/model/index.d.ts +55 -0
  407. package/five/model/intersection.d.ts +18 -0
  408. package/five/model/loaders/at3d.d.ts +12 -0
  409. package/five/model/loaders/b3dm.d.ts +10 -0
  410. package/five/model/loaders/dome.d.ts +22 -0
  411. package/five/model/loaders/domez.d.ts +11 -0
  412. package/five/model/loaders/fbx.d.ts +8 -0
  413. package/five/model/loaders/glTF-helpers/extensions/CESIUM_RTC.d.ts +9 -0
  414. package/five/model/loaders/glTF-helpers/extensions/EXT_meshopt_compression.d.ts +8 -0
  415. package/five/model/loaders/glTF-helpers/extensions/EXT_texture_webp.d.ts +11 -0
  416. package/five/model/loaders/glTF-helpers/extensions/KHR_animation_pointer.d.ts +6 -0
  417. package/five/model/loaders/glTF-helpers/extensions/KHR_binary_glTF.d.ts +25 -0
  418. package/five/model/loaders/glTF-helpers/extensions/KHR_draco_mesh_compression.d.ts +11 -0
  419. package/five/model/loaders/glTF-helpers/extensions/KHR_gaussian_splatting.d.ts +26 -0
  420. package/five/model/loaders/glTF-helpers/extensions/KHR_gaussian_splatting_compression_spz.d.ts +11 -0
  421. package/five/model/loaders/glTF-helpers/extensions/KHR_gaussian_splatting_compression_spz_2.d.ts +13 -0
  422. package/five/model/loaders/glTF-helpers/extensions/KHR_materials_clearcoat.d.ts +10 -0
  423. package/five/model/loaders/glTF-helpers/extensions/KHR_materials_emissive_strength.d.ts +10 -0
  424. package/five/model/loaders/glTF-helpers/extensions/KHR_materials_sheen.d.ts +10 -0
  425. package/five/model/loaders/glTF-helpers/extensions/KHR_materials_transmission.d.ts +10 -0
  426. package/five/model/loaders/glTF-helpers/extensions/KHR_materials_unlit.d.ts +12 -0
  427. package/five/model/loaders/glTF-helpers/extensions/KHR_mesh_quantization.d.ts +6 -0
  428. package/five/model/loaders/glTF-helpers/extensions/KHR_node_visibility.d.ts +10 -0
  429. package/five/model/loaders/glTF-helpers/extensions/KHR_texture_basisu.d.ts +9 -0
  430. package/five/model/loaders/glTF-helpers/extensions/KHR_texture_transform.d.ts +10 -0
  431. package/five/model/loaders/glTF-helpers/extensions/REALSEE_materials_lightmap.d.ts +7 -0
  432. package/five/model/loaders/glTF-helpers/extensions/base.d.ts +25 -0
  433. package/five/model/loaders/glTF-helpers/glTF.d.ts +713 -0
  434. package/five/model/loaders/glTF-helpers/index.d.ts +51 -0
  435. package/five/model/loaders/glTF-helpers/parser.d.ts +115 -0
  436. package/five/model/loaders/glTF-helpers/type.d.ts +14 -0
  437. package/five/model/loaders/gltf.d.ts +10 -0
  438. package/five/model/loaders/obj.d.ts +9 -0
  439. package/five/model/loaders/pbm.d.ts +26 -0
  440. package/five/model/loaders/ply.d.ts +24 -0
  441. package/five/model/loaders/pnts.d.ts +8 -0
  442. package/five/model/loaders/protobuf/dome.d.ts +540 -0
  443. package/five/model/loaders/protobuf/pbm.d.ts +203 -0
  444. package/five/model/loaders/shared.d.ts +16 -0
  445. package/five/model/loaders/splat.d.ts +8 -0
  446. package/five/model/loaders/spz.d.ts +14 -0
  447. package/five/model/loaders/tile3d-helpers/feature-table.d.ts +15 -0
  448. package/five/model/loaders/tile3d-helpers/gl-type.d.ts +20 -0
  449. package/five/model/loaders/tile3d-helpers/parse-gltf-array-buffer.d.ts +2 -0
  450. package/five/model/loaders/tile3d-helpers/parse-header.d.ts +2 -0
  451. package/five/model/loaders/tile3d-helpers/parse-point-cloud-attributes.d.ts +2 -0
  452. package/five/model/loaders/tile3d-helpers/parse-point-cloud-attributes.worker.d.ts +6 -0
  453. package/five/model/loaders/tile3d-helpers/parse-table.d.ts +3 -0
  454. package/five/model/loaders/tile3d-helpers/tile3d-type.d.ts +36 -0
  455. package/five/model/loaders/x3p.d.ts +22 -0
  456. package/five/model/materials/nodes/pbmMeshBasicNodeMaterial.d.ts +14 -0
  457. package/five/model/materials/nodes/pbmMeshPanoOnlyNodeMaterial.d.ts +14 -0
  458. package/five/model/materials/nodes/pbmMeshPhongNodeMaterial.d.ts +14 -0
  459. package/five/model/materials/nodes/pbmMeshPhysicalNodeMaterial.d.ts +14 -0
  460. package/five/model/materials/nodes/pbmPointCloudNodeMaterial.d.ts +22 -0
  461. package/five/model/materials/pbmGaussianSplattingNodeMaterial.d.ts +78 -0
  462. package/five/model/materials/pbmMaterial.d.ts +171 -0
  463. package/five/model/materials/pbmMaterialRegister.d.ts +6 -0
  464. package/five/model/materials/pbmMeshMaterial.d.ts +57 -0
  465. package/five/model/materials/pbmPointCloudMaterial.d.ts +20 -0
  466. package/five/model/materials/pbmPointCloudNodeMaterial.d.ts +46 -0
  467. package/five/model/materials/tsl/colorFilter.d.ts +9 -0
  468. package/five/model/materials/tsl/defines.d.ts +68 -0
  469. package/five/model/materials/tsl/nodeTypes.d.ts +12 -0
  470. package/five/model/materials/tsl/outputBuilder.d.ts +26 -0
  471. package/five/model/materials/tsl/panoColor.d.ts +17 -0
  472. package/five/model/materials/tsl/panoTransition.d.ts +8 -0
  473. package/five/model/materials/tsl/utils.d.ts +11 -0
  474. package/five/model/model-scene.d.ts +172 -0
  475. package/five/model/model.d.ts +203 -0
  476. package/five/model/objects/pbmGaussianSplattingObject.d.ts +47 -0
  477. package/five/model/objects/pbmGaussianSplattingRenderMesh.d.ts +73 -0
  478. package/five/model/objects/pbmGroup.d.ts +8 -0
  479. package/five/model/objects/pbmMesh.d.ts +10 -0
  480. package/five/model/objects/pbmPointCloud.d.ts +89 -0
  481. package/five/model/objects/pbmPointCloudObject.d.ts +81 -0
  482. package/five/model/parameter.d.ts +138 -0
  483. package/five/model/tile3d/header.d.ts +88 -0
  484. package/five/model/tile3d/index.d.ts +213 -0
  485. package/five/model/tile3d/tile-cache.d.ts +18 -0
  486. package/five/model/tile3d/tile-content.d.ts +10 -0
  487. package/five/model/tile3d/tile-node.d.ts +26 -0
  488. package/five/model/tile3d/tile-request-scheduler.d.ts +17 -0
  489. package/five/model/tile3d/tile.d.ts +79 -0
  490. package/five/model/tile3d/tileset-base-traverser.d.ts +59 -0
  491. package/five/model/tile3d/tileset-most-detail-traverser.d.ts +14 -0
  492. package/five/model/tile3d/tileset-normal-traverser.d.ts +15 -0
  493. package/five/model/tile3d/tileset-skip-traverser.d.ts +60 -0
  494. package/five/model/tile3d/tileset.d.ts +65 -0
  495. package/five/model/tile3d/trajectory-content.d.ts +0 -0
  496. package/five/model/tile3d/trajectory-node.d.ts +15 -0
  497. package/five/model/tile3d/trajectory.d.ts +30 -0
  498. package/five/model/tile3d/types.d.ts +33 -0
  499. package/five/model/view-layer.d.ts +20 -0
  500. package/five/renderer/compute-renderers/pointcloud-compute-renderer.d.ts +154 -0
  501. package/five/renderer/compute-renderers/rgb565.d.ts +45 -0
  502. package/five/renderer/compute-renderers/shaders/clear.d.ts +2 -0
  503. package/five/renderer/compute-renderers/shaders/fullscreenQuad.d.ts +2 -0
  504. package/five/renderer/compute-renderers/shaders/rasterize.d.ts +2 -0
  505. package/five/renderer/five-renderer.d.ts +33 -0
  506. package/five/renderer/index.d.ts +3 -0
  507. package/five/renderer/postprocessing/composer.d.ts +45 -0
  508. package/five/renderer/postprocessing/index.d.ts +8 -0
  509. package/five/renderer/postprocessing/passes/adaptive-luminance-pass.d.ts +27 -0
  510. package/five/renderer/postprocessing/passes/eye-dome-lighting-pass.d.ts +31 -0
  511. package/five/renderer/postprocessing/passes/flowing-fireworks-3d-pass.d.ts +71 -0
  512. package/five/renderer/postprocessing/passes/flowing-light-2d-pass.d.ts +26 -0
  513. package/five/renderer/postprocessing/passes/flowing-light-3d-pass.d.ts +75 -0
  514. package/five/renderer/postprocessing/passes/gaussian-blur-pass.d.ts +22 -0
  515. package/five/renderer/postprocessing/passes/pass.d.ts +38 -0
  516. package/five/renderer/scene-renderers/scene-renderer.d.ts +9 -0
  517. package/five/renderer/tools/full-screen-quad.d.ts +17 -0
  518. package/five/renderer/tools/postprocess-uv.d.ts +11 -0
  519. package/five/renderer/tools/render-cube-to-equirectangular.d.ts +7 -0
  520. package/five/renderer/tools/render-full-screen-depth.d.ts +2 -0
  521. package/five/renderer/tools/render-full-screen.d.ts +2 -0
  522. package/five/texture/histogram.d.ts +54 -0
  523. package/five/texture/imageBitmap.d.ts +13 -0
  524. package/five/texture/initTexture.d.ts +3 -0
  525. package/five/texture/loader.d.ts +39 -0
  526. package/five/texture/textureData.d.ts +11 -0
  527. package/five/thirdparty/fflate.d.ts +1407 -0
  528. package/five/thirdparty/hammer.d.ts +375 -0
  529. package/five/thirdparty/jsrsasign.d.ts +753 -0
  530. package/five/thirdparty/meshopt_decoder.d.ts +15 -0
  531. package/five/three-version-check.d.ts +1 -0
  532. package/five/types/addableObject.d.ts +12 -0
  533. package/five/types/cube.d.ts +2 -0
  534. package/five/types/gestureInput.d.ts +24 -0
  535. package/five/types/imageOptions.d.ts +20 -0
  536. package/five/types/intersectMeshInterface.d.ts +8 -0
  537. package/five/types/movePanoEffect.d.ts +13 -0
  538. package/five/types/movePanoOptions.d.ts +36 -0
  539. package/five/types/panoCircleMeshInterface.d.ts +34 -0
  540. package/five/types/plugin.d.ts +25 -0
  541. package/five/types/pose.d.ts +17 -0
  542. package/five/types/state.d.ts +20 -0
  543. package/five/types/viewport.d.ts +22 -0
  544. package/five/utils/ajax.d.ts +66 -0
  545. package/five/utils/animationFrameLoop.d.ts +45 -0
  546. package/five/utils/array.d.ts +31 -0
  547. package/five/utils/asyncTaskQueue.d.ts +8 -0
  548. package/five/utils/bufferGeometry.d.ts +33 -0
  549. package/five/utils/calculateProgress.d.ts +39 -0
  550. package/five/utils/calculateThreeMouse.d.ts +13 -0
  551. package/five/utils/canplayVideo.d.ts +2 -0
  552. package/five/utils/clamp.d.ts +2 -0
  553. package/five/utils/clock.d.ts +30 -0
  554. package/five/utils/createSymbol.d.ts +5 -0
  555. package/five/utils/decodeText.d.ts +2 -0
  556. package/five/utils/deepEqual.d.ts +2 -0
  557. package/five/utils/deepFreeze.d.ts +2 -0
  558. package/five/utils/defineProperty.d.ts +9 -0
  559. package/five/utils/detector.d.ts +14 -0
  560. package/five/utils/distance.d.ts +10 -0
  561. package/five/utils/draco.d.ts +26 -0
  562. package/five/utils/easing.d.ts +63 -0
  563. package/five/utils/event.d.ts +159 -0
  564. package/five/utils/face3.d.ts +12 -0
  565. package/five/utils/formatRad.d.ts +7 -0
  566. package/five/utils/hdr-data.d.ts +13 -0
  567. package/five/utils/imageSupport.d.ts +6 -0
  568. package/five/utils/imageURL.d.ts +42 -0
  569. package/five/utils/isEmptyObject.d.ts +2 -0
  570. package/five/utils/isNil.d.ts +6 -0
  571. package/five/utils/isNumber.d.ts +2 -0
  572. package/five/utils/isPowerOfTwo.d.ts +2 -0
  573. package/five/utils/isPromise.d.ts +2 -0
  574. package/five/utils/isSimilar.d.ts +6 -0
  575. package/five/utils/json.d.ts +7 -0
  576. package/five/utils/ktx2.d.ts +30 -0
  577. package/five/utils/lzma/index.d.ts +2 -0
  578. package/five/utils/lzma/lzma.d.ts +3 -0
  579. package/five/utils/lzma/lzmaWASM.d.ts +2 -0
  580. package/five/utils/lzma/lzmaWorker.d.ts +14 -0
  581. package/five/utils/memoryUsage.d.ts +37 -0
  582. package/five/utils/motion.d.ts +38 -0
  583. package/five/utils/noop.d.ts +6 -0
  584. package/five/utils/now.d.ts +7 -0
  585. package/five/utils/pano.d.ts +9 -0
  586. package/five/utils/pick.d.ts +3 -0
  587. package/five/utils/poseUtils.d.ts +5 -0
  588. package/five/utils/renderCubeTextureToCubeRenderTarget.d.ts +3 -0
  589. package/five/utils/renderDepth.d.ts +2 -0
  590. package/five/utils/renderTexturesToCubeRenderTarget.d.ts +10 -0
  591. package/five/utils/requestPermission.d.ts +3 -0
  592. package/five/utils/shaderContentFix.d.ts +7 -0
  593. package/five/utils/shaderMaterial.d.ts +20 -0
  594. package/five/utils/stateUtils.d.ts +5 -0
  595. package/five/utils/string-pattern.d.ts +8 -0
  596. package/five/utils/subscribe.d.ts +67 -0
  597. package/five/utils/tileCube.d.ts +19 -0
  598. package/five/utils/toFastProperties.d.ts +1 -0
  599. package/five/utils/typedCache.d.ts +10 -0
  600. package/five/utils/uniform.d.ts +15 -0
  601. package/five/utils/url.d.ts +35 -0
  602. package/five/utils/uuid.d.ts +5 -0
  603. package/five/utils/values.d.ts +2 -0
  604. package/five/utils/vectorCoordinates.d.ts +29 -0
  605. package/five/utils/volume.d.ts +111 -0
  606. package/five/utils/worker.d.ts +26 -0
  607. package/five/work/_ALLOW_HOST.d.ts +2 -0
  608. package/five/work/index.d.ts +6 -0
  609. package/five/work/keychain.d.ts +5 -0
  610. package/five/work/looseWorkType.d.ts +128 -0
  611. package/five/work/verify.d.ts +7 -0
  612. package/five/work/work.d.ts +246 -0
  613. package/five/work/workFetcher.d.ts +4 -0
  614. package/five/work/workJson.d.ts +3 -0
  615. package/five/work/workJsonType.d.ts +73 -0
  616. package/five/work/workObserverUtils.d.ts +36 -0
  617. package/five/work/workParser.d.ts +6 -0
  618. package/five/work/workResolvedObserver.d.ts +12 -0
  619. package/five/work/workVerify.d.ts +2 -0
  620. package/five/work/works.d.ts +10 -0
  621. package/llms.txt +66 -0
  622. package/package.json +56 -0
  623. package/plugins/BasePlugin/index.d.ts +96 -0
  624. package/plugins/GaussianSplattingEntranceAnimationPlugin/Controller.d.ts +66 -0
  625. package/plugins/GaussianSplattingEntranceAnimationPlugin/index.d.ts +5 -0
  626. package/plugins/GaussianSplattingEntranceAnimationPlugin/typing.d.ts +32 -0
  627. package/plugins/index.d.ts +2 -0
  628. package/plugins/index.js +255 -0
  629. package/plugins/index.mjs +539 -0
  630. package/plugins/utils/absoluteUrl.d.ts +5 -0
  631. package/react/autoCanvas.d.ts +9 -0
  632. package/react/canvas.d.ts +19 -0
  633. package/react/context.d.ts +12 -0
  634. package/react/createProvider.d.ts +98 -0
  635. package/react/createStore.d.ts +144 -0
  636. package/react/fiveApp.d.ts +22 -0
  637. package/react/hooks/unsafe__useFiveInstance.d.ts +9 -0
  638. package/react/hooks/useFiveAction.d.ts +147 -0
  639. package/react/hooks/useFiveCameraDirection.d.ts +7 -0
  640. package/react/hooks/useFiveCameraRaycaster.d.ts +7 -0
  641. package/react/hooks/useFiveCurrentObserver.d.ts +11 -0
  642. package/react/hooks/useFiveCurrentState.d.ts +15 -0
  643. package/react/hooks/useFiveEventCallback.d.ts +12 -0
  644. package/react/hooks/useFiveFloor.d.ts +15 -0
  645. package/react/hooks/useFiveHelper.d.ts +14 -0
  646. package/react/hooks/useFiveModelBounding.d.ts +5 -0
  647. package/react/hooks/useFiveModelEffect.d.ts +14 -0
  648. package/react/hooks/useFiveModelIntersectRaycaster.d.ts +22 -0
  649. package/react/hooks/useFiveModelReadyState.d.ts +8 -0
  650. package/react/hooks/useFivePlugin.d.ts +22 -0
  651. package/react/hooks/useFiveProject2d.d.ts +21 -0
  652. package/react/hooks/useFiveSceneEffect.d.ts +21 -0
  653. package/react/hooks/useFiveState.d.ts +6 -0
  654. package/react/hooks/useFiveWork.d.ts +29 -0
  655. package/react/index.d.ts +28 -0
  656. package/react/index.js +255 -0
  657. package/react/index.mjs +896 -0
  658. package/react/withFive.d.ts +213 -0
  659. package/resource/basis/1.16/basis_transcoder.js +22 -0
  660. package/resource/basis/1.16/basis_transcoder.wasm +0 -0
  661. package/resource/basis/README.md +5 -0
  662. package/resource/draco/1.5.6/draco_decoder.js +34 -0
  663. package/resource/draco/1.5.6/draco_decoder.wasm +0 -0
  664. package/resource/draco/1.5.6/draco_decoder_gltf.js +33 -0
  665. package/resource/draco/1.5.6/draco_decoder_gltf.wasm +0 -0
  666. package/resource/draco/1.5.6/draco_encoder.js +35 -0
  667. package/resource/draco/1.5.6/draco_encoder.wasm +0 -0
  668. package/resource/draco/1.5.6/draco_encoder_wrapper.js +97 -0
  669. package/resource/draco/1.5.6/draco_wasm_wrapper.js +117 -0
  670. package/resource/draco/1.5.6/draco_wasm_wrapper_gltf.js +116 -0
  671. package/resource/draco/README.md +5 -0
  672. package/umd/five-plugins.js +255 -0
  673. package/umd/five-react.js +255 -0
  674. package/umd/five.js +1579 -0
package/docs/documents/features_raycast.html ADDED
@@ -0,0 +1,98 @@
1
+ <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/raycast | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/raycast</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="raycast-射线检测" class="tsd-anchor-link">Raycast (射线检测)<a href="#raycast-射线检测" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
2
+ <ul>
3
+ <li><strong>Summary</strong>: Five 提供了增强版的射线检测机制，内置 BVH 加速，并扩展了 Three.js Raycaster 以支持更灵活的过滤和性能优化。</li>
4
+ <li><strong>Schema</strong>: 参见下方 <code>Three.js Raycaster Extensions</code>。</li>
5
+ <li><strong>Concepts</strong>: BVH, IntersectRaycaster, Raycaster Extensions。</li>
6
+ <li><strong>Examples</strong>: 提供基础检测与性能优化示例。</li>
7
+ </ul>
8
+ <h2 id="schema-threejs-raycaster-extensions" class="tsd-anchor-link">Schema: Three.js Raycaster Extensions<a href="#schema-threejs-raycaster-extensions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
9
+ <blockquote>
10
+ <p><strong>Definition</strong>: <a href="../../five/declare.d.ts">Raycaster</a></p>
11
+ </blockquote>
12
+ <p>Five 对 Three.js 的 <code>Raycaster</code> 进行了扩展，在 <code>declare module 'three'</code> 中增加了以下属性：</p>
13
+ <pre><code class="typescript"><span class="hl-8">// defined in five/declare.d.ts</span><br/><span class="hl-3">declare</span><span class="hl-1"> </span><span class="hl-3">module</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Raycaster</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 只捕获第一个焦点 (性能优化)</span><br/><span class="hl-8"> * - true: 找到第一个交点后立即停止检测，返回结果。</span><br/><span class="hl-8"> * - false (默认): 检测所有可能的交点。</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-6">firstHitOnly</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 自定义交点过滤器</span><br/><span class="hl-8"> * - 回调函数，返回 boolean。</span><br/><span class="hl-8"> * - true: 保留该交点。</span><br/><span class="hl-8"> * - false: 丢弃该交点。</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-5">hitFilter</span><span class="hl-1">?: (</span><span class="hl-6">intersect</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Intersection</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 是否由近及远排序</span><br/><span class="hl-8"> * - true (默认): 返回的结果数组按距离摄像机从近到远排序。</span><br/><span class="hl-8"> * - false: 结果顺序不确定（通常按遍历顺序）。</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-6">sortByDistance</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 作用楼层 (Five 特有逻辑)</span><br/><span class="hl-8"> * - 用于多楼层场景过滤。</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-6">floorIndex</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Intersection</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 命中的具体 Tile 对象 (仅 3DTiles) */</span><br/><span class="hl-1"> </span><span class="hl-6">tile</span><span class="hl-1">?: </span><span class="hl-7">Tile</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 命中的 ViewLayer 对象 */</span><br/><span class="hl-1"> </span><span class="hl-6">viewLayer</span><span class="hl-1">?: </span><span class="hl-7">ViewLayer</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 命中的 Model 对象 */</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">?: </span><span class="hl-7">Model</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
14
+ </code><button type="button">Copy</button></pre>
15
+
16
+ <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
17
+ <h3 id="1-five-内置-bvh-bounding-volume-hierarchy" class="tsd-anchor-link">1. Five 内置 BVH (Bounding Volume Hierarchy)<a href="#1-five-内置-bvh-bounding-volume-hierarchy" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
18
+ <p>Five 内置了一套高效的 BVH 实现，用于优化 <code>Mesh</code> 和 <code>Points</code> 的射线检测。</p>
19
+ <ul>
20
+ <li><strong>作用</strong>: 在进行射线检测时，不直接遍历所有三角形或点，而是先与构建好的 BVH 树（包围盒层次结构）进行相交测试。只有当射线穿过包围盒时，才进一步检测内部的几何体。</li>
21
+ <li><strong>优势</strong>: 极大提升了复杂模型（如数十万面的 Mesh 或百万级 Points）的碰撞检测性能。</li>
22
+ <li><strong>透明性</strong>: 开发者通常无需手动操作 BVH，Five 在加载模型时会自动构建，并在调用 <code>intersectRaycaster</code> 时自动应用。</li>
23
+ </ul>
24
+ <h3 id="2-modelsintersectraycaster-modelintersectraycaster-vs-原生-intersectobject" class="tsd-anchor-link">2. models.intersectRaycaster / model.intersectRaycaster vs 原生 intersectObject<a href="#2-modelsintersectraycaster-modelintersectraycaster-vs-原生-intersectobject" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
25
+ <p>Five 提供了 <code>model.intersectRaycaster</code> 方法，与 Three.js 原生的 <code>raycaster.intersectObject</code> 有显著区别：</p>
26
+ <table>
27
+ <thead>
28
+ <tr>
29
+ <th style="text-align:left">特性</th>
30
+ <th style="text-align:left"><code>five.model.intersectRaycaster</code></th>
31
+ <th style="text-align:left"><code>raycaster.intersectObject</code> (Three.js 原生)</th>
32
+ </tr>
33
+ </thead>
34
+ <tbody>
35
+ <tr>
36
+ <td style="text-align:left"><strong>检测范围</strong></td>
37
+ <td style="text-align:left">聚合检测 <code>five.model.shownModels</code> 中所有可见模型。</td>
38
+ <td style="text-align:left">仅检测指定的单个 Object3D 及其子节点。</td>
39
+ </tr>
40
+ <tr>
41
+ <td style="text-align:left"><strong>结果排序</strong></td>
42
+ <td style="text-align:left">自动合并所有模型的检测结果，并根据 <code>raycaster.sortByDistance</code> 排序。</td>
43
+ <td style="text-align:left">仅对当前 Object 及其子节点的结果排序。</td>
44
+ </tr>
45
+ <tr>
46
+ <td style="text-align:left"><strong>扩展支持</strong></td>
47
+ <td style="text-align:left"><strong>支持</strong> <code>firstHitOnly</code>, <code>hitFilter</code>, <code>sortByDistance</code> 等扩展属性。</td>
48
+ <td style="text-align:left">不支持 Five 的扩展属性（需手动实现）。</td>
49
+ </tr>
50
+ <tr>
51
+ <td style="text-align:left"><strong>内部优化</strong></td>
52
+ <td style="text-align:left">自动调用模型内部的优化逻辑（如 BVH, Tile3D 的空间索引）。</td>
53
+ <td style="text-align:left">仅进行标准的场景图遍历检测。</td>
54
+ </tr>
55
+ <tr>
56
+ <td style="text-align:left"><strong>使用场景</strong></td>
57
+ <td style="text-align:left"><strong>推荐</strong>。适用于全局点击、地板检测、物体拾取等业务场景。</td>
58
+ <td style="text-align:left">仅在需要检测特定原生 Object3D 时使用。</td>
59
+ </tr>
60
+ </tbody>
61
+ </table>
62
+ <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
63
+ <h3 id="基础用法：检测点击位置" class="tsd-anchor-link">基础用法：检测点击位置<a href="#基础用法：检测点击位置" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
64
+ <p>最常见的场景是将鼠标点击的屏幕坐标转换为 3D 空间中的点。</p>
65
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><span class="hl-8">// ... 初始化 ...</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">vector</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 假设 onTap 是点击事件处理函数</span><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">onTap</span><span class="hl-1">(</span><span class="hl-6">event</span><span class="hl-1">: { </span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">, </span><span class="hl-6">y</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 将屏幕坐标转换为归一化设备坐标 (NDC)</span><br/><span class="hl-1"> </span><span class="hl-8">// 注意：five.getElement() 获取 canvas 容器</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">element</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getElement</span><span class="hl-1">();</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (!</span><span class="hl-6">element</span><span class="hl-1">) </span><span class="hl-10">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">rect</span><span class="hl-1"> = </span><span class="hl-6">element</span><span class="hl-1">.</span><span class="hl-5">getBoundingClientRect</span><span class="hl-1">();</span><br/><span class="hl-1"> </span><span class="hl-6">vector</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> = ((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1">) * </span><span class="hl-11">2</span><span class="hl-1"> - </span><span class="hl-11">1</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">vector</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> = -((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1">) * </span><span class="hl-11">2</span><span class="hl-1"> + </span><span class="hl-11">1</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 设置射线</span><br/><span class="hl-1"> </span><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">setFromCamera</span><span class="hl-1">(</span><span class="hl-6">vector</span><span class="hl-1">, </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 调用 Five 的检测方法</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">firstHit</span><span class="hl-1"> = </span><span class="hl-6">intersects</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">];</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&#39;点击到了模型:&#39;</span><span class="hl-1">, </span><span class="hl-6">firstHit</span><span class="hl-1">.</span><span class="hl-6">object</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&#39;交点坐标 (世界坐标):&#39;</span><span class="hl-1">, </span><span class="hl-6">firstHit</span><span class="hl-1">.</span><span class="hl-6">point</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
66
+ </code><button type="button">Copy</button></pre>
67
+
68
+ <h3 id="性能优化：只获取第一个交点" class="tsd-anchor-link">性能优化：只获取第一个交点<a href="#性能优化：只获取第一个交点" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
69
+ <p>在进行如“地面检测”或“视线遮挡检测”时，通常只需要知道最近的交点。此时开启 <code>firstHitOnly</code> 可以显著提升性能。</p>
70
+ <pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">setFromCamera</span><span class="hl-1">(</span><span class="hl-6">mouseVector</span><span class="hl-1">, </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 开启性能优化：找到最近的一个交点后立即停止</span><br/><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-6">firstHitOnly</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 结果数组长度最多为 1</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-8">// 处理最近的交点</span><br/><span class="hl-1">}</span>
71
+ </code><button type="button">Copy</button></pre>
72
+
73
+ <h3 id="高级用法：使用过滤器" class="tsd-anchor-link">高级用法：使用过滤器<a href="#高级用法：使用过滤器" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
74
+ <p>如果你只想检测特定类型的物体（例如只检测地板，忽略天花板），可以使用 <code>hitFilter</code>。</p>
75
+ <pre><code class="typescript"><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">hitFilter</span><span class="hl-1"> = (</span><span class="hl-6">intersect</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 示例：假设地板的法线是向上的 (0, 1, 0)</span><br/><span class="hl-1"> </span><span class="hl-8">// 只保留法线朝上的交点（地板）</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">face</span><span class="hl-1"> &amp;&amp; </span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">face</span><span class="hl-1">.</span><span class="hl-6">normal</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> &gt; </span><span class="hl-11">0.5</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">; </span><span class="hl-8">// 保留</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">; </span><span class="hl-8">// 丢弃</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span>
76
+ </code><button type="button">Copy</button></pre>
77
+
78
+ <h2 id="debugging" class="tsd-anchor-link">Debugging<a href="#debugging" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
79
+ <ul>
80
+ <li><strong>验证交点</strong>: 在开发阶段，可以在交点处添加一个临时的红色小球 <code>THREE.Mesh</code>，直观地确认检测位置是否正确。</li>
81
+ <li><strong>检查模型可见性</strong>: <code>intersectRaycaster</code> 只会检测 <code>visible = true</code> 的模型。如果检测不到，请检查模型的可见性状态。</li>
82
+ <li><strong>Performance</strong>: 如果射线检测导致掉帧，检查是否频繁调用了全场景检测。尝试使用 <code>firstHitOnly</code> 或减小检测频率（如节流）。</li>
83
+ </ul>
84
+ <h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
85
+ <ol>
86
+ <li><strong>混淆 API</strong>: 错误地使用 <code>raycaster.intersectObject(five.scene)</code>。虽然这也能工作，但会失去 Five 的 BVH 优化和多模型聚合能力，导致性能下降或漏检。请始终优先使用 <code>five.model.intersectRaycaster(raycaster)</code>。</li>
87
+ <li><strong>忽略坐标系</strong>: <code>raycaster.setFromCamera</code> 需要 NDC 坐标（-1 到 1），而不是像素坐标。务必进行正确的坐标转换。</li>
88
+ <li><strong>Tile3D 模型的特殊性</strong>: 对于大型 Tile3D 场景，射线检测可能涉及动态加载的瓦片。Five 内部已处理这些逻辑，外部调用方式不变，但返回的 <code>object</code> 可能是某个具体的 Tile 节点。</li>
89
+ </ol>
90
+ <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
91
+ <ul>
92
+ <li><a href="features_parameter.html">parameter.md</a>: 了解模型参数配置。</li>
93
+ </ul>
94
+ <hr>
95
+ <pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">raycast</span><span class="hl-1">, </span><span class="hl-2">bvh</span><span class="hl-1">, </span><span class="hl-2">interaction</span><span class="hl-1">, </span><span class="hl-2">performance</span><span class="hl-1">]</span>
96
+ </code><button type="button">Copy</button></pre>
97
+
98
+ </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#raycast-射线检测"><span>Raycast (射线检测)</span></a><ul><li><a href="#schema-threejs-raycaster-extensions"><span>Schema: <wbr/>Three.js <wbr/>Raycaster <wbr/>Extensions</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#1-five-内置-bvh-bounding-volume-hierarchy"><span>1. <wbr/>Five 内置 <wbr/>BVH (<wbr/>Bounding <wbr/>Volume <wbr/>Hierarchy)</span></a></li><li><a href="#2-modelsintersectraycaster-modelintersectraycaster-vs-原生-intersectobject"><span>2. models.intersect<wbr/>Raycaster / model.intersect<wbr/>Raycaster vs 原生 intersect<wbr/>Object</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#基础用法：检测点击位置"><span>基础用法：检测点击位置</span></a></li><li><a href="#性能优化：只获取第一个交点"><span>性能优化：只获取第一个交点</span></a></li><li><a href="#高级用法：使用过滤器"><span>高级用法：使用过滤器</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
package/docs/documents/features_request-proxy.html ADDED
@@ -0,0 +1,78 @@
1
+ <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/request-proxy | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/request-proxy</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="request-proxy-请求代理" class="tsd-anchor-link">Request Proxy (请求代理)<a href="#request-proxy-请求代理" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
2
+ <ul>
3
+ <li><strong>Summary</strong>: <code>requestProxy</code> 是 Five 初始化时的关键参数，用于在发起网络请求前对 URL 进行拦截和修改，常用于鉴权、资源重定向或 CDN 域名替换。</li>
4
+ <li><strong>Schema</strong>: <code>(url: string) =&gt; string | Promise&lt;string&gt;</code></li>
5
+ <li><strong>Concepts</strong>: 请求拦截、资源重定向、鉴权签名。</li>
6
+ <li><strong>Configuration</strong>: <code>FiveInitArgs.requestProxy</code>。</li>
7
+ <li><strong>Examples</strong>: CDN 替换、私有化部署鉴权、调试模式。</li>
8
+ </ul>
9
+ <h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
10
+ <blockquote>
11
+ <p><strong>Definition</strong>: <a href="../../five/application/fiveInitArgs.d.ts">FiveInitArgs</a></p>
12
+ </blockquote>
13
+ <pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 请求代理函数</span><br/><span class="hl-8"> * </span><span class="hl-3">@description</span><span class="hl-8"> 在 Five 内部发起任何网络请求（如加载图片、模型、配置）之前调用。</span><br/><span class="hl-8"> * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">url</span><span class="hl-8"> - 原始请求 URL</span><br/><span class="hl-8"> * </span><span class="hl-3">@returns</span><span class="hl-8"> 修改后的 URL (string) 或异步返回修改后的 URL (Promise&lt;string&gt;)</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-1">?: (</span><span class="hl-6">url</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">string</span><span class="hl-1"> | </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-7">string</span><span class="hl-1">&gt;;</span><br/><span class="hl-1">}</span>
14
+ </code><button type="button">Copy</button></pre>
15
+
16
+ <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
17
+ <h3 id="拦截时机" class="tsd-anchor-link">拦截时机<a href="#拦截时机" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
18
+ <p>Five 内部加载资源（全景图瓦片、3D 模型、纹理贴图等）时，会通过统一的 Fetcher 层发起请求。<code>requestProxy</code> 钩子函数会在每次请求发起<strong>前</strong>被触发。</p>
19
+ <h3 id="核心用途" class="tsd-anchor-link">核心用途<a href="#核心用途" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
20
+ <ol>
21
+ <li><strong>域名替换 (CDN Domain Sharding)</strong>: 将资源请求分散到多个 CDN 域名以突破浏览器并发限制。</li>
22
+ <li><strong>鉴权签名 (Authentication)</strong>: 针对私有化部署或受保护资源，在 URL 后追加鉴权 Token (如 SAS Token)。</li>
23
+ <li><strong>资源重定向 (Redirection)</strong>: 在开发环境下将线上资源重定向到本地或测试环境。</li>
24
+ <li><strong>协议适配</strong>: 强制将 <code>http</code> 协议升级为 <code>https</code>。</li>
25
+ </ol>
26
+ <h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
27
+ <p><code>requestProxy</code> 是 <code>Five</code> 构造函数的配置项之一。</p>
28
+ <table>
29
+ <thead>
30
+ <tr>
31
+ <th style="text-align:left">参数</th>
32
+ <th style="text-align:left">类型</th>
33
+ <th style="text-align:left">默认值</th>
34
+ <th style="text-align:left">说明</th>
35
+ </tr>
36
+ </thead>
37
+ <tbody>
38
+ <tr>
39
+ <td style="text-align:left"><code>requestProxy</code></td>
40
+ <td style="text-align:left"><code>(url: string) =&gt; string | Promise&lt;string&gt;</code></td>
41
+ <td style="text-align:left"><code>undefined</code></td>
42
+ <td style="text-align:left">代理函数，返回修改后的 URL。支持同步或异步返回。</td>
43
+ </tr>
44
+ </tbody>
45
+ </table>
46
+ <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
47
+ <h3 id="1-基础用法：cdn-域名替换" class="tsd-anchor-link">1. 基础用法：CDN 域名替换<a href="#1-基础用法：cdn-域名替换" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
48
+ <p>将图片资源请求分散到不同的 CDN 节点，加速加载。</p>
49
+ <pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 简单的字符串替换示例</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">replace</span><span class="hl-1">(</span><span class="hl-9">&#39;//vrlab-public.ljcdn.com/&#39;</span><span class="hl-1">, </span><span class="hl-9">&#39;//vr-public.realsee-cdn.cn/&#39;</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
50
+ </code><button type="button">Copy</button></pre>
51
+
52
+ <h3 id="2-进阶用法：异步鉴权-async-auth" class="tsd-anchor-link">2. 进阶用法：异步鉴权 (Async Auth)<a href="#2-进阶用法：异步鉴权-async-auth" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
53
+ <p>对于需要动态获取 Token 的场景，可以使用 <code>Promise</code> 异步返回 URL。</p>
54
+ <pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> </span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 仅对私有桶资源进行签名</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">includes</span><span class="hl-1">(</span><span class="hl-9">&#39;private-bucket&#39;</span><span class="hl-1">)) {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">token</span><span class="hl-1"> = </span><span class="hl-10">await</span><span class="hl-1"> </span><span class="hl-5">fetchToken</span><span class="hl-1">(); </span><span class="hl-8">// 假设 fetchToken 是一个获取鉴权的异步函数</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">separator</span><span class="hl-1"> = </span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">includes</span><span class="hl-1">(</span><span class="hl-9">&#39;?&#39;</span><span class="hl-1">) ? </span><span class="hl-9">&#39;&amp;&#39;</span><span class="hl-1"> : </span><span class="hl-9">&#39;?&#39;</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">url</span><span class="hl-3">}${</span><span class="hl-6">separator</span><span class="hl-3">}</span><span class="hl-9">token=</span><span class="hl-3">${</span><span class="hl-6">token</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
55
+ </code><button type="button">Copy</button></pre>
56
+
57
+ <h3 id="3-开发调试：本地资源代理" class="tsd-anchor-link">3. 开发调试：本地资源代理<a href="#3-开发调试：本地资源代理" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
58
+ <p>在开发阶段，将特定资源重定向到本地文件。</p>
59
+ <pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">proxyMap</span><span class="hl-1">: </span><span class="hl-7">Record</span><span class="hl-1">&lt;</span><span class="hl-7">string</span><span class="hl-1">, </span><span class="hl-7">string</span><span class="hl-1">&gt; = {};</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 如果该 URL 在映射表中存在（例如通过 &lt;input type=&quot;file&quot;&gt; 加载的本地 Blob URL），则使用映射值</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">proxyMap</span><span class="hl-1">[</span><span class="hl-6">url</span><span class="hl-1">]) {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`[Proxy] Redirecting </span><span class="hl-3">${</span><span class="hl-6">url</span><span class="hl-3">}</span><span class="hl-9"> -&gt; </span><span class="hl-3">${</span><span class="hl-6">proxyMap</span><span class="hl-12">[</span><span class="hl-6">url</span><span class="hl-12">]</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">proxyMap</span><span class="hl-1">[</span><span class="hl-6">url</span><span class="hl-1">];</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
60
+ </code><button type="button">Copy</button></pre>
61
+
62
+ <h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
63
+ <ol>
64
+ <li><strong>死循环风险</strong>: 不要在 <code>requestProxy</code> 内部再次发起会导致 <code>requestProxy</code> 触发的 Five 资源请求，否则可能导致递归调用。</li>
65
+ <li><strong>性能损耗</strong>: <code>requestProxy</code> 会在<strong>所有</strong>资源请求前触发（包括成百上千个瓦片请求）。请确保该函数执行效率极高，避免进行耗时的同步操作。如果是异步操作，应做好缓存。</li>
66
+ <li><strong>URL 格式</strong>: 确保返回的 URL 格式正确。如果原 URL 包含 Query 参数，拼接 Token 时要注意判断是使用 <code>?</code> 还是 <code>&amp;</code>。</li>
67
+ <li><strong>缓存一致性</strong>: 如果修改了 URL（例如加了 Token），可能会影响浏览器的缓存命中策略。</li>
68
+ </ol>
69
+ <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
70
+ <ul>
71
+ <li><a href="features_parameter.html">Parameter</a>: Five 初始化参数总览。</li>
72
+ <li><a href="features_load-external-model.html">Load External Model</a>: 加载外部模型时也会触发 requestProxy。</li>
73
+ </ul>
74
+ <hr>
75
+ <pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">configuration</span><span class="hl-1">, </span><span class="hl-2">network</span><span class="hl-1">, </span><span class="hl-2">proxy</span><span class="hl-1">, </span><span class="hl-2">authentication</span><span class="hl-1">]</span>
76
+ </code><button type="button">Copy</button></pre>
77
+
78
+ </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#request-proxy-请求代理"><span>Request <wbr/>Proxy (请求代理)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#拦截时机"><span>拦截时机</span></a></li><li><a href="#核心用途"><span>核心用途</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-基础用法：cdn-域名替换"><span>1. 基础用法：<wbr/>CDN 域名替换</span></a></li><li><a href="#2-进阶用法：异步鉴权-async-auth"><span>2. 进阶用法：异步鉴权 (<wbr/>Async <wbr/>Auth)</span></a></li><li><a href="#3-开发调试：本地资源代理"><span>3. 开发调试：本地资源代理</span></a></li></ul></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
package/docs/documents/features_screen-project.html ADDED
@@ -0,0 +1,112 @@
1
+ <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/screen-project | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/screen-project</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="screen-space-projection-屏幕与空间坐标转换" class="tsd-anchor-link">Screen &amp; Space Projection (屏幕与空间坐标转换)<a href="#screen-space-projection-屏幕与空间坐标转换" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
2
+ <ul>
3
+ <li><strong>Summary</strong>: 详解屏幕二维坐标与三维空间坐标/射线之间的相互转换关系，以及如何在 DOM 层与 3D 场景进行联动（如显示标签）。</li>
4
+ <li><strong>Schema</strong>: <code>five.project2d</code> 接口定义。</li>
5
+ <li><strong>Concepts</strong>: World Space, Screen Space, NDC, Raycasting.</li>
6
+ <li><strong>Examples</strong>: 空间点位转屏幕坐标 (标签功能)、屏幕坐标转空间射线。</li>
7
+ </ul>
8
+ <h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
9
+ <blockquote>
10
+ <p><strong>Definition</strong>: <a href="../../five/application/five.d.ts">Five</a></p>
11
+ </blockquote>
12
+ <pre><code class="typescript"><span class="hl-8">// defined in Five class</span><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Five</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 计算三维坐标对应到屏幕的二维坐标</span><br/><span class="hl-8"> * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">vector</span><span class="hl-8"> - 三维空间坐标 (World Space)</span><br/><span class="hl-8"> * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">testModel</span><span class="hl-8"> - 是否进行模型遮挡检测 (默认 false)。如果为 true，且该点被模型遮挡，则返回 null。</span><br/><span class="hl-8"> * </span><span class="hl-3">@returns</span><span class="hl-8"> 二维屏幕坐标 (相对于 Canvas 左上角) 或 null (如果点在视野外或被遮挡)</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-5">project2d</span><span class="hl-1">(</span><span class="hl-6">vector</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">, </span><span class="hl-6">testModel</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">): </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</span><span class="hl-1"> | </span><span class="hl-7">null</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
13
+ </code><button type="button">Copy</button></pre>
14
+
15
+ <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
16
+ <h3 id="1-坐标系转换流程" class="tsd-anchor-link">1. 坐标系转换流程<a href="#1-坐标系转换流程" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
17
+ <p>在 Five (Three.js) 中，坐标转换通常遵循以下流程：</p>
18
+ <ul>
19
+ <li><strong>World Space (世界坐标)</strong>: 三维场景中的绝对坐标 (x, y, z)，单位通常为米。</li>
20
+ <li><strong>Camera Space (相机坐标)</strong>: 相对于相机的坐标。</li>
21
+ <li><strong>NDC (Normalized Device Coordinates)</strong>: 归一化设备坐标，x, y, z 范围均为 [-1, 1]。</li>
22
+ <li><strong>Screen Space (屏幕坐标)</strong>: 对应 Canvas 画布的像素坐标。原点 (0, 0) 在左上角，x 向右增加，y 向下增加。</li>
23
+ </ul>
24
+ <h3 id="2-转换关系" class="tsd-anchor-link">2. 转换关系<a href="#2-转换关系" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
25
+ <table>
26
+ <thead>
27
+ <tr>
28
+ <th style="text-align:left">方向</th>
29
+ <th style="text-align:left">方法</th>
30
+ <th style="text-align:left">核心逻辑</th>
31
+ <th style="text-align:left">用途</th>
32
+ </tr>
33
+ </thead>
34
+ <tbody>
35
+ <tr>
36
+ <td style="text-align:left"><strong>3D ➔ 2D</strong></td>
37
+ <td style="text-align:left"><code>five.project2d(vector)</code></td>
38
+ <td style="text-align:left">World ➔ NDC ➔ Screen</td>
39
+ <td style="text-align:left">标签 (Tag)、HUD、跟随 3D 物体的 UI</td>
40
+ </tr>
41
+ <tr>
42
+ <td style="text-align:left"><strong>2D ➔ 3D</strong></td>
43
+ <td style="text-align:left"><code>Raycaster</code></td>
44
+ <td style="text-align:left">Screen ➔ NDC ➔ Ray</td>
45
+ <td style="text-align:left">点击拾取 (Picking)、地面检测、放置物体</td>
46
+ </tr>
47
+ </tbody>
48
+ </table>
49
+ <h3 id="3-fiveproject2d" class="tsd-anchor-link">3. five.project2d<a href="#3-fiveproject2d" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
50
+ <p><code>five.project2d</code> 是 Five 提供的便捷方法，它封装了以下逻辑：</p>
51
+ <ol>
52
+ <li>将世界坐标投影 (Project) 到相机的 NDC 空间。</li>
53
+ <li>判断点是否在视锥体 (Frustum) 内（即是否在视野范围内）。</li>
54
+ <li>(可选) 发射射线检测该点与相机之间是否有模型遮挡。</li>
55
+ <li>将 NDC 坐标转换为相对于 Canvas 左上角的像素坐标 (px)。</li>
56
+ </ol>
57
+ <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
58
+ <h3 id="1-空间标签-3d-point-to-dom-label" class="tsd-anchor-link">1. 空间标签 (3D Point to DOM Label)<a href="#1-空间标签-3d-point-to-dom-label" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
59
+ <p>最典型的应用场景是在 3D 场景中的某个物体上方显示一个 HTML 标签。</p>
60
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">Mode</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><span class="hl-8">// ... 初始化 five ...</span><br/><br/><span class="hl-8">// 1. 创建标签 DOM 元素</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">label</span><span class="hl-1"> = </span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">createElement</span><span class="hl-1">(</span><span class="hl-9">&quot;div&quot;</span><span class="hl-1">);</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">textContent</span><span class="hl-1"> = </span><span class="hl-9">&quot;Living Room&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1"> = </span><span class="hl-9">&quot;absolute&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">padding</span><span class="hl-1"> = </span><span class="hl-9">&quot;4px 8px&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">background</span><span class="hl-1"> = </span><span class="hl-9">&quot;rgba(0, 0, 0, 0.6)&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">color</span><span class="hl-1"> = </span><span class="hl-9">&quot;white&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">borderRadius</span><span class="hl-1"> = </span><span class="hl-9">&quot;4px&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">pointerEvents</span><span class="hl-1"> = </span><span class="hl-9">&quot;none&quot;</span><span class="hl-1">; </span><span class="hl-8">// 避免阻挡鼠标事件</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">transform</span><span class="hl-1"> = </span><span class="hl-9">&quot;translate(-50%, -100%)&quot;</span><span class="hl-1">; </span><span class="hl-8">// 居中并显示在点上方</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">display</span><span class="hl-1"> = </span><span class="hl-9">&quot;none&quot;</span><span class="hl-1">; </span><span class="hl-8">// 默认隐藏</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">label</span><span class="hl-1">); </span><span class="hl-8">// 添加到 container (注意 container 的定位 context)</span><br/><br/><span class="hl-8">// 2. 定义目标空间坐标 (例如客厅中心)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">targetPosition</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">1.5</span><span class="hl-1">, </span><span class="hl-11">2.0</span><span class="hl-1">, -</span><span class="hl-11">3.0</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 3. 在每一帧渲染时更新标签位置</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;render.prepare&quot;</span><span class="hl-1">, () </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 计算屏幕坐标</span><br/><span class="hl-1"> </span><span class="hl-8">// 参数2: false 表示不检测遮挡 (性能更好)；true 表示如果被墙挡住则隐藏</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">screenPos</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">project2d</span><span class="hl-1">(</span><span class="hl-6">targetPosition</span><span class="hl-1">, </span><span class="hl-3">true</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">screenPos</span><span class="hl-1"> === </span><span class="hl-3">null</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-8">// 如果返回 null，说明点在相机背面，或者被遮挡（如果开启了 testModel）</span><br/><span class="hl-1"> </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">display</span><span class="hl-1"> = </span><span class="hl-9">&quot;none&quot;</span><span class="hl-1">;</span><br/><span class="hl-1"> } </span><span class="hl-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">display</span><span class="hl-1"> = </span><span class="hl-9">&quot;block&quot;</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">// 更新 DOM 位置</span><br/><span class="hl-1"> </span><span class="hl-8">// 注意：screenPos 是相对于 Canvas 的坐标。</span><br/><span class="hl-1"> </span><span class="hl-8">// 如果 Canvas 占满全屏，直接使用即可。</span><br/><span class="hl-1"> </span><span class="hl-8">// 如果 Canvas 有偏移，需加上 Canvas 的 offset。</span><br/><span class="hl-1"> </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">screenPos</span><span class="hl-12">.</span><span class="hl-6">x</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">screenPos</span><span class="hl-12">.</span><span class="hl-6">y</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
61
+ </code><button type="button">Copy</button></pre>
62
+
63
+ <h3 id="2-屏幕点击转射线-screen-to-ray" class="tsd-anchor-link">2. 屏幕点击转射线 (Screen to Ray)<a href="#2-屏幕点击转射线-screen-to-ray" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
64
+ <p>将鼠标点击的屏幕坐标转换为 3D 射线，用于检测物体。</p>
65
+ <blockquote>
66
+ <p><strong>注意</strong>: 更多射线检测细节请参考 <a href="features_raycast.html">Raycast</a>。</p>
67
+ </blockquote>
68
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 假设 container 是 five 的容器元素</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">container</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getElement</span><span class="hl-1">()!.</span><span class="hl-6">parentElement</span><span class="hl-1">!;</span><br/><br/><span class="hl-6">container</span><span class="hl-1">.</span><span class="hl-5">addEventListener</span><span class="hl-1">(</span><span class="hl-9">&quot;click&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">mouse</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">();</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 1. 计算 NDC 坐标 (x, y 范围 [-1, 1])</span><br/><span class="hl-1"> </span><span class="hl-8">// event.clientX/Y 是相对于视口的坐标</span><br/><span class="hl-1"> </span><span class="hl-8">// getBoundingClientRect 用于获取容器的位置</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">rect</span><span class="hl-1"> = </span><span class="hl-6">container</span><span class="hl-1">.</span><span class="hl-5">getBoundingClientRect</span><span class="hl-1">();</span><br/><br/><span class="hl-1"> </span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> = ((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">clientX</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1">) * </span><span class="hl-11">2</span><span class="hl-1"> - </span><span class="hl-11">1</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> = -((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">clientY</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1">) * </span><span class="hl-11">2</span><span class="hl-1"> + </span><span class="hl-11">1</span><span class="hl-1">; </span><span class="hl-8">// 注意 Y 轴翻转</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 从相机发射射线</span><br/><span class="hl-1"> </span><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">setFromCamera</span><span class="hl-1">(</span><span class="hl-6">mouse</span><span class="hl-1">, </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 进行相交检测</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Hit point:&quot;</span><span class="hl-1">, </span><span class="hl-6">intersects</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">].</span><span class="hl-6">point</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
69
+ </code><button type="button">Copy</button></pre>
70
+
71
+ <h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
72
+ <ol>
73
+ <li>
74
+ <p><strong>坐标系原点</strong>:</p>
75
+ <ul>
76
+ <li>DOM/CSS 坐标系原点在左上角，Y 轴向下。</li>
77
+ <li>NDC/WebGL 坐标系原点在中心，Y 轴向上。</li>
78
+ <li><code>project2d</code> 返回的是 <strong>DOM 风格</strong> 的坐标 (左上角原点)，可以直接赋给 CSS <code>left</code>/<code>top</code>。</li>
79
+ <li>但在进行 Raycaster 转换时，需要手动将 DOM 坐标转换为 NDC (Y 轴翻转)。</li>
80
+ </ul>
81
+ </li>
82
+ <li>
83
+ <p><strong>性能开销</strong>:</p>
84
+ <ul>
85
+ <li><code>project2d(pos, true)</code> 开启 <code>testModel</code> 会进行射线检测，性能开销较大。如果在 <code>render.prepare</code> 中对大量点进行检测，可能会导致掉帧。</li>
86
+ <li>建议：对于大量标签，默认使用 <code>false</code>；或者仅对可视范围内的关键标签进行遮挡检测；或者限制检测频率（如每 10 帧检测一次）。</li>
87
+ </ul>
88
+ </li>
89
+ <li>
90
+ <p><strong>Canvas 尺寸</strong>:</p>
91
+ <ul>
92
+ <li><code>project2d</code> 内部使用 <code>five.renderer.getSize()</code> 和 <code>five.viewport</code> 计算。确保 Canvas 尺寸与 DOM 显示尺寸一致 (通常 Five 会自动处理，但如果使用了 CSS 缩放需注意)。</li>
93
+ </ul>
94
+ </li>
95
+ <li>
96
+ <p><strong>Null 返回值</strong>:</p>
97
+ <ul>
98
+ <li>务必检查 <code>project2d</code> 的返回值是否为 <code>null</code>。点在相机背面、超出视锥体裁剪范围、或被遮挡（开启 testModel 时）都会返回 <code>null</code>。</li>
99
+ </ul>
100
+ </li>
101
+ </ol>
102
+ <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
103
+ <ul>
104
+ <li><a href="features_raycast.html">Raycast</a>: 详细的射线检测文档。</li>
105
+ <li><a href="features_five.html">Five</a>: Five 核心类说明。</li>
106
+ <li><a href="features_state.html">State</a>: 了解相机位姿 (Pose)。</li>
107
+ </ul>
108
+ <hr>
109
+ <pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">coordinate</span><span class="hl-1">, </span><span class="hl-2">screen</span><span class="hl-1">, </span><span class="hl-2">project</span><span class="hl-1">, </span><span class="hl-2">label</span><span class="hl-1">, </span><span class="hl-2">ui</span><span class="hl-1">]</span>
110
+ </code><button type="button">Copy</button></pre>
111
+
112
+ </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#screen-space-projection-屏幕与空间坐标转换"><span>Screen &amp; <wbr/>Space <wbr/>Projection (屏幕与空间坐标转换)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#1-坐标系转换流程"><span>1. 坐标系转换流程</span></a></li><li><a href="#2-转换关系"><span>2. 转换关系</span></a></li><li><a href="#3-fiveproject2d"><span>3. five.project2d</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-空间标签-3d-point-to-dom-label"><span>1. 空间标签 (3<wbr/>D <wbr/>Point to <wbr/>DOM <wbr/>Label)</span></a></li><li><a href="#2-屏幕点击转射线-screen-to-ray"><span>2. 屏幕点击转射线 (<wbr/>Screen to <wbr/>Ray)</span></a></li></ul></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>