Line data Source code
1 : import type * as THREE from 'three'
2 : import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader'
3 :
4 : import type { Load3dHost, MaterialMode } from './interfaces'
5 :
6 : export interface ModelLoadContext {
7 : setOriginalModel(model: THREE.Object3D | THREE.BufferGeometry | GLTF): void
8 : registerOriginalMaterial(
9 : mesh: THREE.Mesh,
10 : material: THREE.Material | THREE.Material[]
11 : ): void
12 : readonly standardMaterial: THREE.MeshStandardMaterial
13 : readonly materialMode: MaterialMode
14 : }
15 :
16 : type ModelAdapterKind = 'mesh' | 'pointCloud' | 'splat'
17 :
18 : export interface ModelAdapterCapabilities {
19 : /**
20 : * Whether auto-normalize/centering on load and the explicit fit-to-viewer
21 : * action should run. Splats render self-sized and are placed at a fixed
22 : * camera distance instead.
23 : */
24 : fitToViewer: boolean
25 : /**
26 : * Whether a material mode change must rebuild the scene object instead of
27 : * traversing the existing mesh tree. True for point-cloud PLY (Mesh <->
28 : * Points swap); false for regular meshes and self-rendering splats.
29 : */
30 : requiresMaterialRebuild: boolean
31 : /**
32 : * Whether the gizmo transform UI (translate/rotate/scale) should be
33 : * exposed for this model type. False for adapters whose already-normalized
34 : * output makes user transforms meaningless (PLY point cloud).
35 : */
36 : gizmoTransform: boolean
37 : /** Whether scene-lighting controls apply. False for self-lit formats. */
38 : lighting: boolean
39 : /** Whether the model can be exported (GLB/OBJ/STL). */
40 : exportable: boolean
41 : /**
42 : * Material modes offered in the UI for this format. An empty array hides
43 : * the material-mode dropdown entirely.
44 : */
45 : materialModes: readonly MaterialMode[]
46 : /**
47 : * World-space target size along the largest dimension after
48 : * fit-to-viewer normalization. Controls how large the model ends up
49 : * relative to the 20-unit scene grid; splats use a larger value so they
50 : * don't shrink to a quarter of the floor.
51 : */
52 : fitTargetSize: number
53 : }
54 :
55 24 : export const DEFAULT_MODEL_CAPABILITIES: ModelAdapterCapabilities = {
56 : fitToViewer: true,
57 : requiresMaterialRebuild: false,
58 : gizmoTransform: true,
59 : lighting: true,
60 : exportable: true,
61 : materialModes: ['original', 'clay', 'normal', 'wireframe'],
62 : fitTargetSize: 5
63 : }
64 :
65 : /**
66 : * Result returned by `ModelAdapter.load()`. Capabilities ride with the model
67 : * because some adapters (notably PLY) produce different capability sets
68 : * depending on the file contents — face-less point clouds expose only the
69 : * 'pointCloud' material mode, indexed meshes expose the full set. Keeping
70 : * capabilities per-load (not per-adapter) prevents stale state on the
71 : * adapter instance between two successive loads.
72 : */
73 : export type ModelLoadResult = {
74 : object: THREE.Object3D
75 : capabilities: ModelAdapterCapabilities
76 : }
77 :
78 : /**
79 : * Mutable handle to the currently active ModelAdapter plus the capabilities
80 : * reported by its most recent load. A single ref is created in `createLoad3d`
81 : * and shared between LoaderManager (writer) and SceneModelManager + Load3d
82 : * (readers), so capability/bounds/dispose lookups don't depend on
83 : * construction order between those collaborators.
84 : */
85 : export type AdapterRef = {
86 : current: ModelAdapter | null
87 : capabilities: ModelAdapterCapabilities | null
88 : }
89 :
90 24 : export const createAdapterRef = (): AdapterRef => ({
91 : current: null,
92 : capabilities: null
93 : })
94 :
95 : export interface ModelAdapter {
96 : readonly kind: ModelAdapterKind
97 : readonly extensions: readonly string[]
98 : /**
99 : * Default capabilities for this adapter family. `load()` may return a
100 : * narrowed set for a specific model — read `adapterRef.capabilities` for
101 : * the live per-model value rather than this.
102 : */
103 : readonly capabilities: ModelAdapterCapabilities
104 : /**
105 : * Async tiebreaker when multiple adapters claim the same extension
106 : * (e.g. .ply is shared by Gaussian splats and classic point clouds).
107 : * Adapters that uniquely own their extensions can omit this.
108 : */
109 : matches?(
110 : extension: string,
111 : fetchBytes: () => Promise<ArrayBuffer>
112 : ): Promise<boolean>
113 : load(
114 : ctx: ModelLoadContext,
115 : path: string,
116 : filename: string,
117 : fetchBytes: () => Promise<ArrayBuffer>
118 : ): Promise<ModelLoadResult | null>
119 : /**
120 : * Optional. Return a world-space AABB for the given model. Adapters for
121 : * renderers whose geometry is not walked by `Box3.setFromObject` (e.g.
122 : * Gaussian splats) implement this; the default path uses
123 : * `Box3.setFromObject` when this is absent.
124 : */
125 : computeBounds?(model: THREE.Object3D): THREE.Box3 | null
126 : /**
127 : * Optional. Release renderer-owned resources on this model beyond what
128 : * THREE's geometry/material.dispose covers (e.g. sparkjs SplatMesh
129 : * internal GPU/worker state). Called when the model is removed from the
130 : * scene due to a reload or teardown. Missing for adapters whose models
131 : * the default traversal already handles.
132 : */
133 : disposeModel?(model: THREE.Object3D): void
134 : /**
135 : * Optional. Default camera placement for adapters that opt out of
136 : * fit-to-viewer (capabilities.fitToViewer === false). The size/center
137 : * pair is forwarded to CameraManager.setupForModel as if the model had
138 : * been normalized. Splat geometry is self-sized and uses this to seat
139 : * the camera at a known-good distance.
140 : */
141 : defaultCameraPose?(): { size: THREE.Vector3; center: THREE.Vector3 }
142 : }
143 :
144 19 : export async function fetchModelData(
145 : fetchApi: Load3dHost['fetchApi'],
146 : path: string,
147 : filename: string,
148 : signal?: AbortSignal
149 : ): Promise<ArrayBuffer> {
150 : const route = '/' + path.replace(/^api\//, '') + encodeURIComponent(filename)
151 19 : const response = await fetchApi(route, { signal })
152 19 : if (!response.ok) {
153 2 : throw new Error(`Failed to fetch model: ${response.status}`)
154 : }
155 17 : return response.arrayBuffer()
156 : }
|