@vctrl/hooks 0.9.5 → 0.11.1

package/src/use-load-model/utils/calculate-referenced-bytes.ts

@@ -0,0 +1,123 @@
+import {
+	buildAssetLookupKeys,
+	getSerializedAssetByteSize,
+	normalizeAssetUri
+} from '@vctrl/core'
+
+import type { ServerSceneData } from '../types'
+
+type ReferencedBytes = {
+	sourcePackageBytes: number
+	textureBytes: number
+}
+
+const resolveSizeFromAssets = (
+	uri: string,
+	assets: Array<{ fileName: string; size: number }>
+) => {
+	const normalizedUri = normalizeAssetUri(uri)
+	const uriBasename = normalizedUri.split('/').pop() || normalizedUri
+
+	for (const asset of assets) {
+		const assetKeys = buildAssetLookupKeys(asset.fileName)
+		if (assetKeys.has(normalizedUri) || assetKeys.has(uriBasename)) {
+			return asset.size
+		}
+	}
+
+	return 0
+}
+
+const collectReferencedUris = (gltfJson: unknown) => {
+	const bufferUris = new Set<string>()
+	const imageUris = new Set<string>()
+	const document = gltfJson as {
+		images?: Array<{ uri?: string }>
+		buffers?: Array<{ uri?: string }>
+	}
+
+	const images = Array.isArray(document.images)
+		? (document.images as Array<{ uri?: string }>)
+		: []
+	for (const image of images) {
+		if (typeof image.uri === 'string' && !image.uri.startsWith('data:')) {
+			imageUris.add(image.uri)
+		}
+	}
+
+	const buffers = Array.isArray(document.buffers)
+		? (document.buffers as Array<{ uri?: string }>)
+		: []
+	for (const buffer of buffers) {
+		if (typeof buffer.uri === 'string' && !buffer.uri.startsWith('data:')) {
+			bufferUris.add(buffer.uri)
+		}
+	}
+
+	return { bufferUris, imageUris }
+}
+
+export async function calculateReferencedBytesFromFiles(
+	gltfFile: File,
+	assetFiles: File[]
+): Promise<ReferencedBytes> {
+	const gltfText = await gltfFile.text()
+	let gltfJson: Record<string, unknown>
+
+	try {
+		gltfJson = JSON.parse(gltfText) as Record<string, unknown>
+	} catch {
+		return {
+			sourcePackageBytes: gltfFile.size,
+			textureBytes: 0
+		}
+	}
+
+	const assets = assetFiles.map((file) => ({
+		fileName: file.name,
+		size: file.size
+	}))
+
+	const { bufferUris, imageUris } = collectReferencedUris(gltfJson)
+
+	const bufferBytes = Array.from(bufferUris).reduce(
+		(total, uri) => total + resolveSizeFromAssets(uri, assets),
+		0
+	)
+	const textureBytes = Array.from(imageUris).reduce(
+		(total, uri) => total + resolveSizeFromAssets(uri, assets),
+		0
+	)
+
+	return {
+		sourcePackageBytes: gltfFile.size + bufferBytes + textureBytes,
+		textureBytes
+	}
+}
+
+export function calculateReferencedBytesFromServerScene(
+	data: ServerSceneData
+): ReferencedBytes {
+	const gltfJson = data.gltfJson
+	const assets = Object.values(data.assetData || {}).map((asset) => ({
+		fileName: asset.fileName,
+		size: getSerializedAssetByteSize(asset.data)
+	}))
+
+	const gltfSize = new TextEncoder().encode(JSON.stringify(gltfJson)).byteLength
+	const { bufferUris, imageUris } = collectReferencedUris(gltfJson)
+
+	const bufferBytes = Array.from(bufferUris).reduce(
+		(total, uri) => total + resolveSizeFromAssets(uri, assets),
+		0
+	)
+	const textureBytes = Array.from(imageUris).reduce(
+		(total, uri) => total + resolveSizeFromAssets(uri, assets),
+		0
+	)
+
+	return {
+		sourcePackageBytes: gltfSize + bufferBytes + textureBytes,
+		textureBytes
+	}
+}

package/src/use-load-model/utils/index.ts

@@ -0,0 +1,7 @@
+export { default as readDirectory } from './read-directory'
+export { reconstructGltfFiles } from './reconstruct-files'
+export {
+	calculateReferencedBytesFromFiles,
+	calculateReferencedBytesFromServerScene
+} from './calculate-referenced-bytes'
+export { resolveServerSceneDataContract } from './resolve-scene-payload'

package/src/use-load-model/utils/read-directory.ts

@@ -0,0 +1,35 @@
+/**
+ * Recursively reads a directory
+ *
+ * @param directoryHandle - The directory handle to read
+ * @returns - An array of file objects
+ */
+async function readDirectory(
+	directoryHandle: FileSystemDirectoryHandle
+): Promise<File[]> {
+	const files: File[] = []
+
+	async function* getFilesRecursively(
+		entry: FileSystemDirectoryHandle
+	): AsyncGenerator<File> {
+		const asyncEntries = entry as unknown as AsyncIterable<
+			[string, FileSystemHandle]
+		>
+
+		for await (const [, handle] of asyncEntries) {
+			if (handle.kind === 'file') {
+				yield await (handle as FileSystemFileHandle).getFile()
+			} else if (handle.kind === 'directory') {
+				yield* getFilesRecursively(handle as FileSystemDirectoryHandle)
+			}
+		}
+	}
+
+	for await (const file of getFilesRecursively(directoryHandle)) {
+		files.push(file)
+	}
+
+	return files
+}
+
+export default readDirectory

package/src/use-load-model/utils/reconstruct-files.ts

@@ -0,0 +1,85 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>. */
+
+import { toSerializedAssetBytes } from '@vctrl/core'
+
+import type { InputFileOrDirectory, ServerSceneData } from '../types'
+
+/**
+ * Reconstructs GLTF and asset files from scene data received from the server.
+ *
+ * This function converts the server's scene data format (GLTF JSON + binary assets)
+ * back into File objects that can be loaded by the model loader. This is the reverse
+ * operation of what happens when a scene is saved to the server.
+ *
+ * The function:
+ * 1. Converts binary asset data (stored as number arrays) back into File objects
+ * 2. Creates a GLTF file from the JSON structure
+ * 3. Returns an array of files compatible with the model loading system
+ *
+ * @param data - Scene data from the server containing GLTF JSON and assets
+ * @returns Array of File objects ready to be loaded (GLTF file + asset files)
+ *
+ * @example
+ * ```typescript
+ * // Load scene data from server
+ * const sceneData = await ServerCommunicationService.loadScene('scene-123')
+ *
+ * // Reconstruct files
+ * const files = reconstructGltfFiles(sceneData)
+ *
+ * // Load into the viewer
+ * await modelLoader.load(files)
+ * ```
+ */
+export function reconstructGltfFiles(
+	data: ServerSceneData
+): InputFileOrDirectory {
+	const assetFiles: File[] = []
+
+	// Convert asset data back to File objects
+	if (data.assetData && typeof data.assetData === 'object') {
+		for (const [, assetInfo] of Object.entries(data.assetData)) {
+			const { fileName, mimeType } = assetInfo
+			const uint8Array = toSerializedAssetBytes(assetInfo)
+
+			// Create a Blob from the binary data
+			const blobBytes = new Uint8Array(uint8Array.byteLength)
+			blobBytes.set(uint8Array)
+			const blob = new Blob([blobBytes], { type: mimeType })
+
+			// Create a File object
+			const file = new File([blob], fileName, { type: mimeType })
+
+			assetFiles.push(file)
+		}
+	}
+
+	// Create GLTF file from JSON structure
+	const gltfJsonString = JSON.stringify(data.gltfJson)
+	const gltfBlob = new Blob([gltfJsonString], { type: 'model/gltf+json' })
+
+	// Determine filename from metadata or use default
+	const sceneName = data.meta?.name
+	const gltfFileName = sceneName ? `${sceneName}.gltf` : 'scene.gltf'
+
+	const gltfFile = new File([gltfBlob], gltfFileName, {
+		type: 'model/gltf+json'
+	})
+
+	// Return GLTF file first, followed by all asset files
+	return [gltfFile, ...assetFiles]
+}

package/src/use-load-model/utils/resolve-scene-payload.ts

@@ -0,0 +1,151 @@
+import {
+	buildAssetLookupKeys,
+	isValidBase64,
+	normalizeAssetUri
+} from '@vctrl/core'
+
+import type {
+	SceneSettings,
+	SerializedSceneAssetDataMap,
+	ServerSceneData,
+	ServerScenePayload
+} from '@vctrl/core'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function toSceneSettings(payload: ServerScenePayload): SceneSettings {
+	const nestedSettings = isRecord(payload.settings)
+		? (payload.settings as SceneSettings)
+		: {}
+
+	return {
+		...nestedSettings,
+		bounds: payload.bounds ?? nestedSettings.bounds,
+		camera: payload.camera ?? nestedSettings.camera,
+		controls: payload.controls ?? nestedSettings.controls,
+		environment: payload.environment ?? nestedSettings.environment,
+		shadows: payload.shadows ?? nestedSettings.shadows
+	}
+}
+
+function collectReferencedUris(gltfJson: unknown): Set<string> {
+	const referencedUris = new Set<string>()
+	const document = gltfJson as {
+		images?: Array<{ uri?: string }>
+		buffers?: Array<{ uri?: string }>
+	}
+
+	const images = Array.isArray(document.images)
+		? (document.images as Array<{ uri?: string }>)
+		: []
+	for (const image of images) {
+		if (typeof image.uri === 'string' && !image.uri.startsWith('data:')) {
+			referencedUris.add(image.uri)
+		}
+	}
+
+	const buffers = Array.isArray(document.buffers)
+		? (document.buffers as Array<{ uri?: string }>)
+		: []
+	for (const buffer of buffers) {
+		if (typeof buffer.uri === 'string' && !buffer.uri.startsWith('data:')) {
+			referencedUris.add(buffer.uri)
+		}
+	}
+
+	return referencedUris
+}
+
+function validateAssetDataMap(assetData: SerializedSceneAssetDataMap): void {
+	for (const [assetId, asset] of Object.entries(assetData)) {
+		if (!asset || typeof asset !== 'object') {
+			throw new Error(
+				`Scene payload contains invalid asset entry for ${assetId}`
+			)
+		}
+
+		if (
+			typeof asset.fileName !== 'string' ||
+			asset.fileName.trim().length === 0
+		) {
+			throw new Error(
+				`Scene payload asset ${assetId} is missing a valid fileName`
+			)
+		}
+
+		if (
+			typeof asset.mimeType !== 'string' ||
+			asset.mimeType.trim().length === 0
+		) {
+			throw new Error(
+				`Scene payload asset ${assetId} is missing a valid mimeType`
+			)
+		}
+
+		if (typeof asset.data === 'string' && asset.encoding === 'base64') {
+			if (!isValidBase64(asset.data)) {
+				throw new Error(
+					`Scene payload asset ${asset.fileName} has invalid base64 data`
+				)
+			}
+		}
+	}
+}
+
+function validateReferencedAssets(
+	gltfJson: ServerSceneData['gltfJson'],
+	assetData: SerializedSceneAssetDataMap
+): void {
+	const referencedUris = collectReferencedUris(gltfJson)
+
+	if (referencedUris.size === 0) {
+		return
+	}
+
+	const lookup = new Set<string>()
+	for (const asset of Object.values(assetData)) {
+		for (const key of buildAssetLookupKeys(asset.fileName)) {
+			lookup.add(key)
+		}
+	}
+
+	const missingUris: string[] = []
+	for (const uri of referencedUris) {
+		const normalized = normalizeAssetUri(uri)
+		const basename = normalized.split('/').pop() || normalized
+		if (!lookup.has(uri) && !lookup.has(normalized) && !lookup.has(basename)) {
+			missingUris.push(uri)
+		}
+	}
+
+	if (missingUris.length > 0) {
+		throw new Error(
+			`Scene payload is missing required referenced assets: ${missingUris.slice(0, 5).join(', ')}`
+		)
+	}
+}
+
+/**
+ * Resolves raw scene payload from the API into normalized scene data used by hooks.
+ * This keeps payload-shape adaptation in one explicit contract boundary.
+ */
+export function resolveServerSceneDataContract(
+	payload: ServerScenePayload
+): ServerSceneData {
+	if (!isRecord(payload.gltfJson)) {
+		throw new Error('Scene payload is missing a valid glTF document')
+	}
+
+	const assetData = payload.assetData ?? {}
+	validateAssetDataMap(assetData)
+	validateReferencedAssets(payload.gltfJson, assetData)
+
+	return {
+		meta: payload.meta,
+		gltfJson: payload.gltfJson,
+		assetData,
+		...toSceneSettings(payload)
+	}
+}

package/{use-optimize-model/index.d.ts → src/use-optimize-model/index.ts}

@@ -1 +1,2 @@
-export { default as useOptimizeModel } from './use-optimize-model';
+export { default as useOptimizeModel } from './use-optimize-model'
+export * from './types'

package/src/use-optimize-model/state.ts

@@ -0,0 +1,40 @@
+import { Action, OptimizationState } from './types'
+
+/**
+ * Initial state for the reducer.
+ */
+export const initialState: OptimizationState = {
+	info: null,
+	error: null,
+	loading: false,
+	report: null
+}
+
+/**
+ * Reducer function to manage state transitions.
+ *
+ * @param state - Current state.
+ * @param action - Action to perform.
+ * @returns New state after applying the action.
+ */
+export const reducer = (
+	state: OptimizationState,
+	action: Action
+): OptimizationState => {
+	switch (action.type) {
+		case 'LOAD_START':
+			return { ...state, loading: true, error: null }
+		case 'LOAD_SUCCESS':
+			return {
+				...state,
+				loading: false,
+				report: action.payload.report
+			}
+		case 'LOAD_ERROR':
+			return { ...state, loading: false, error: action.payload }
+		case 'RESET':
+			return { ...initialState }
+		default:
+			return state
+	}
+}

package/src/use-optimize-model/types.ts

@@ -0,0 +1,37 @@
+import type { OptimizationReport } from '@vctrl/core/model-optimizer'
+
+interface ModelTotals {
+	verticesCount: number
+	primitivesCount: number
+	texturesCount: number
+	meshesCount: number
+	sceneBytes: number
+}
+
+export interface OptimizationInfo {
+	initial: ModelTotals
+	optimized: ModelTotals
+	improvement: ModelTotals
+}
+
+/**
+ * Interface representing the state of the model optimizer.
+ */
+export interface OptimizationState {
+	report: OptimizationReport | null
+	info: OptimizationInfo | null
+	error: Error | null
+	loading: boolean
+}
+
+/**
+ * Types of actions for the reducer.
+ */
+export type Action =
+	| { type: 'LOAD_START' }
+	| {
+			type: 'LOAD_SUCCESS'
+			payload: { report: OptimizationReport }
+	  }
+	| { type: 'LOAD_ERROR'; payload: Error }
+	| { type: 'RESET' }

package/src/use-optimize-model/use-calc-optimization-info.ts

@@ -0,0 +1,97 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+import { OptimizationInfo, OptimizationState } from './types'
+
+import type { OptimizationReport } from '@vctrl/core/model-optimizer'
+
+/**
+ * Helper function to safely get stats from optimization report.
+ */
+function getStatsFromReport(report: OptimizationReport | null): {
+	vertices: number
+	primitives: number
+	meshes: number
+	textures: number
+	materials: number
+	totalSize: number
+} {
+	if (!report) {
+		return {
+			vertices: 0,
+			primitives: 0,
+			meshes: 0,
+			textures: 0,
+			materials: 0,
+			totalSize: 0
+		}
+	}
+
+	return {
+		vertices: report.stats.vertices.after || 0,
+		primitives: report.stats.triangles.after || 0,
+		meshes: report.stats.meshes.after || 0,
+		textures: report.stats.textures.after || 0,
+		materials: report.stats.materials.after || 0,
+		totalSize: report.optimizedSize || 0
+	}
+}
+
+export interface OptimizationInfoData {
+	info: OptimizationInfo
+	reset: () => void
+}
+
+export const useCalcOptimizationInfo = (
+	state: OptimizationState
+): OptimizationInfoData => {
+	const initialReport = useRef<OptimizationReport | null>(null)
+	const [initialCaptured, setInitialCaptured] = useState<boolean>(false)
+	const report = state.report
+
+	// Capture initial state
+	useEffect(() => {
+		if (!initialCaptured && report) {
+			initialReport.current = report
+			setInitialCaptured(true)
+		}
+	}, [initialCaptured, report])
+
+	const info = useMemo(() => {
+		const initial = getStatsFromReport(initialReport.current)
+		const current = getStatsFromReport(report)
+
+		return {
+			initial: {
+				verticesCount: initial.vertices,
+				primitivesCount: initial.primitives,
+				meshesCount: initial.meshes,
+				texturesCount: initial.textures,
+				sceneBytes: initial.totalSize
+			},
+			optimized: {
+				verticesCount: current.vertices,
+				primitivesCount: current.primitives,
+				meshesCount: current.meshes,
+				texturesCount: current.textures,
+				sceneBytes: current.totalSize
+			},
+			improvement: {
+				verticesCount: initial.vertices - current.vertices,
+				primitivesCount: initial.primitives - current.primitives,
+				meshesCount: initial.meshes - current.meshes,
+				texturesCount: initial.textures - current.textures,
+				sceneBytes: initial.totalSize - current.totalSize
+			}
+		}
+	}, [report])
+
+	const reset = useCallback(() => {
+		initialReport.current = null
+		setInitialCaptured(false)
+	}, [])
+
+	return {
+		info,
+		reset
+	}
+}