@mapcomponents/three 1.7.2

package/src/components/MlThreeSplatLayer/MlThreeSplatLayer.stories.tsx

@@ -0,0 +1,151 @@
+import { useState, useEffect } from 'react';
+import Button from '@mui/material/Button';
+import Typography from '@mui/material/Typography';
+import Link from '@mui/material/Link';
+import MlThreeSplatLayer from './MlThreeSplatLayer';
+import { useMap, TopToolbar, Sidebar } from '@mapcomponents/react-maplibre';
+import MlThreeJsContextDecorator from '../../decorators/ThreejsContextDecorator';
+import { ThreeObjectControls } from '../ThreeObjectControls';
+import { useThree } from '../ThreeContext';
+import ThreejsUtils from '../../lib/ThreejsUtils';
+import * as THREE from 'three';
+
+const storyoptions = {
+	title: 'MapComponents/MlThreeSplatLayer',
+	component: MlThreeSplatLayer,
+	argTypes: {
+		options: {
+			control: {
+				type: 'object',
+			},
+		},
+	},
+	decorators: MlThreeJsContextDecorator,
+};
+export default storyoptions;
+
+const Template: any = () => {
+	const { worldMatrix } = useThree();
+	const [showLayer, setShowLayer] = useState(true);
+	const [scale, setScale] = useState(100);
+	const [rotation, setRotation] = useState({ x: 270, y: 0, z: 5 });
+	const [useMapCoords, setUseMapCoords] = useState(true);
+	const [mapPosition, setMapPosition] = useState({ lng: 7.0968, lat: 50.736 });
+	const [altitude, setAltitude] = useState(30);
+	const [position, setPosition] = useState({ x: 0, y: 0, z: 100 });
+	const [enableTransformControls, setEnableTransformControls] = useState(false);
+	const [transformMode, setTransformMode] = useState<'translate' | 'rotate' | 'scale'>('translate');
+	const [sidebarOpen, setSidebarOpen] = useState(true);
+
+	const mapHook = useMap({ mapId: 'map_1' });
+	useEffect(() => {
+		if (!mapHook.map) return;
+		mapHook.map?.setZoom(17.5);
+		mapHook.map?.setPitch(44.5);
+		mapHook.map?.setCenter([7.096614581535903, 50.736500960686556]);
+	}, [mapHook.map]);
+
+	// Center map on position when switching coordinate modes
+	useEffect(() => {
+		if (!mapHook.map) return;
+		if (useMapCoords) {
+			mapHook.map.setCenter([mapPosition.lng, mapPosition.lat]);
+		}
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [useMapCoords, mapHook.map]);
+
+	const handleTransformChange = (object: THREE.Object3D) => {
+		setRotation({
+			x: (object.rotation.x * 180) / Math.PI,
+			y: (object.rotation.y * 180) / Math.PI,
+			z: (object.rotation.z * 180) / Math.PI,
+		});
+		setScale(object.scale.x);
+
+		if (useMapCoords && worldMatrix) {
+			const [lng, lat, alt] = ThreejsUtils.toMapPosition(worldMatrix, object.position);
+			setMapPosition({ lng, lat });
+			setAltitude(parseFloat(alt.toFixed(2)));
+		} else {
+			setPosition({ x: object.position.x, y: object.position.y, z: object.position.z });
+		}
+	};
+
+	return (
+		<>
+			{showLayer && (
+				<MlThreeSplatLayer
+					url="assets/splats/output.splat"
+					rotation={{
+						x: (rotation.x * Math.PI) / 180,
+						y: (rotation.y * Math.PI) / 180,
+						z: (rotation.z * Math.PI) / 180,
+					}}
+					scale={scale}
+					enableTransformControls={enableTransformControls}
+					transformMode={transformMode}
+					onTransformChange={handleTransformChange}
+					{...(useMapCoords
+						? {
+								mapPosition: [mapPosition.lng, mapPosition.lat],
+								altitude: altitude,
+							}
+						: {
+								position: position,
+							})}
+				/>
+			)}
+
+			<TopToolbar
+				unmovableButtons={
+					<Button
+						variant={sidebarOpen ? 'contained' : 'outlined'}
+						onClick={() => setSidebarOpen(!sidebarOpen)}
+					>
+						Sidebar
+					</Button>
+				}
+			/>
+			<Sidebar open={sidebarOpen} setOpen={setSidebarOpen} name="Splat Config">
+				<ThreeObjectControls
+					showLayer={showLayer}
+					setShowLayer={setShowLayer}
+					scale={scale}
+					setScale={setScale}
+					rotation={rotation}
+					setRotation={setRotation}
+					useMapCoords={useMapCoords}
+					setUseMapCoords={setUseMapCoords}
+					mapPosition={mapPosition}
+					setMapPosition={setMapPosition}
+					altitude={altitude}
+					setAltitude={setAltitude}
+					position={position}
+					setPosition={setPosition}
+					enableTransformControls={enableTransformControls}
+					setEnableTransformControls={setEnableTransformControls}
+					transformMode={transformMode}
+					setTransformMode={setTransformMode}
+					layerName="Splat"
+				/>
+				<Typography
+					variant="body2"
+					sx={{ mt: 2, p: 1, backgroundColor: 'rgba(255,255,255,0.1)', borderRadius: 1 }}
+				>
+					The splat used is from{' '}
+					<Link
+						href="https://www.patreon.com/posts/cluster-fly-141866089"
+						target="_blank"
+						rel="noopener"
+					>
+						Cluster Fly
+					</Link>{' '}
+					by Dany Bittel published under CC.
+				</Typography>
+			</Sidebar>
+		</>
+	);
+};
+
+export const Default = Template.bind({});
+Default.parameters = {};

package/src/components/MlThreeSplatLayer/MlThreeSplatLayer.tsx

@@ -0,0 +1,158 @@
+import { useEffect, useRef, useState } from 'react';
+import * as THREE from 'three';
+import { LngLatLike } from 'maplibre-gl';
+import { useThree } from '../ThreeContext';
+import { SplatLoader } from '../../lib/splats/loaders/SplatLoader';
+import { PlySplatLoader } from '../../lib/splats/loaders/PlySplatLoader';
+import ThreejsUtils from '../../lib/ThreejsUtils';
+import MlTransformControls from '../MlTransformControls';
+
+/**
+ * Renders splat 3D Models on the MapLibreMap referenced by props.mapId
+ *
+ * @component
+ */
+
+export interface MlThreeSplatLayerProps {
+	mapId?: string;
+	url: string;
+	position?: { x: number; y: number; z: number };
+	mapPosition?: LngLatLike;
+	altitude?: number;
+	rotation?: { x: number; y: number; z: number };
+	scale?: { x: number; y: number; z: number } | number;
+	enableTransformControls?: boolean;
+	transformMode?: 'translate' | 'rotate' | 'scale';
+	onTransformChange?: (object: THREE.Object3D) => void;
+	init?: () => void;
+	onDone?: () => void;
+}
+
+const MlThreeSplatLayer = (props: MlThreeSplatLayerProps) => {
+	const {
+		url,
+		position,
+		mapPosition,
+		altitude,
+		rotation,
+		scale,
+		enableTransformControls,
+		transformMode,
+		onTransformChange,
+		init,
+		onDone,
+	} = props;
+	const { scene, worldMatrixInv } = useThree();
+	const modelRef = useRef<THREE.Object3D | undefined>(undefined);
+	const [model, setModel] = useState<THREE.Object3D | undefined>(undefined);
+
+	// Use refs for callbacks to avoid re-triggering the effect when they change
+	const initRef = useRef(init);
+	const onDoneRef = useRef(onDone);
+	initRef.current = init;
+	onDoneRef.current = onDone;
+
+	const transformRef = useRef({ position, mapPosition, altitude, rotation, scale });
+	transformRef.current = { position, mapPosition, altitude, rotation, scale };
+	const worldMatrixInvRef = useRef(worldMatrixInv);
+	worldMatrixInvRef.current = worldMatrixInv;
+
+	useEffect(() => {
+		if (!scene) return;
+
+		if (typeof initRef.current === 'function') {
+			initRef.current();
+		}
+
+		const extension = url.split('.').pop()?.toLowerCase();
+
+		const onLoad = (object: THREE.Object3D) => {
+			const { position, mapPosition, altitude, rotation, scale } = transformRef.current;
+			const worldMatrixInv = worldMatrixInvRef.current;
+
+			if (mapPosition && worldMatrixInv) {
+				const scenePos = ThreejsUtils.toScenePosition(worldMatrixInv, mapPosition, altitude);
+				object.position.set(scenePos.x, scenePos.y, scenePos.z);
+			} else if (position) {
+				object.position.set(position.x, position.y, position.z);
+			}
+
+			if (rotation) {
+				object.rotation.set(rotation.x, rotation.y, rotation.z);
+			}
+			if (scale) {
+				if (typeof scale === 'number') {
+					object.scale.set(scale, scale, scale);
+				} else {
+					object.scale.set(scale.x, scale.y, scale.z);
+				}
+			}
+			object.updateMatrixWorld(true);
+
+			modelRef.current = object;
+			scene.add(object);
+			setModel(object);
+			if (typeof onDoneRef.current === 'function') {
+				onDoneRef.current();
+			}
+		};
+
+		if (extension === 'splat') {
+			const loader = new SplatLoader();
+			loader.load(url, (splatMesh) => {
+				onLoad(splatMesh);
+			});
+		} else if (extension === 'ply') {
+			const loader = new PlySplatLoader();
+			loader.load(url, (splatMesh) => {
+				onLoad(splatMesh);
+			});
+		} else {
+			console.warn('MlThreeSplatLayer: Unsupported file extension', extension);
+		}
+
+		return () => {
+			if (modelRef.current) {
+				scene.remove(modelRef.current);
+				if ('dispose' in modelRef.current && typeof modelRef.current.dispose === 'function') {
+					(modelRef.current as any).dispose();
+				}
+				modelRef.current = undefined;
+				setModel(undefined);
+			}
+		};
+	}, [scene, url]);
+
+	useEffect(() => {
+		if (!model) return;
+
+		// Handle position: mapPosition takes precedence over position
+		if (mapPosition && worldMatrixInv) {
+			const scenePos = ThreejsUtils.toScenePosition(worldMatrixInv, mapPosition, altitude);
+			model.position.set(scenePos.x, scenePos.y, scenePos.z);
+		} else if (position) {
+			model.position.set(position.x, position.y, position.z);
+		}
+
+		if (rotation) {
+			model.rotation.set(rotation.x, rotation.y, rotation.z);
+		}
+		if (scale) {
+			if (typeof scale === 'number') {
+				model.scale.set(scale, scale, scale);
+			} else {
+				model.scale.set(scale.x, scale.y, scale.z);
+			}
+		}
+		model.updateMatrixWorld(true);
+	}, [model, position, mapPosition, altitude, rotation, scale, worldMatrixInv]);
+
+	if (enableTransformControls && model) {
+		return (
+			<MlTransformControls target={model} mode={transformMode} onObjectChange={onTransformChange} />
+		);
+	}
+	return null;
+};
+
+export default MlThreeSplatLayer;

package/src/components/MlTransformControls.tsx

@@ -0,0 +1,112 @@
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
+import { useThree } from './ThreeContext';
+
+export interface MlTransformControlsProps {
+	target?: THREE.Object3D;
+	mode?: 'translate' | 'rotate' | 'scale';
+	enabled?: boolean;
+	space?: 'world' | 'local';
+	size?: number;
+	onObjectChange?: (object: THREE.Object3D) => void;
+}
+
+const MlTransformControls = (props: MlTransformControlsProps) => {
+	const { target, mode, enabled, space, size, onObjectChange } = props;
+	const { scene, camera, renderer, map, sceneRoot } = useThree();
+	const controlsRef = useRef<TransformControls | null>(null);
+
+	useEffect(() => {
+		if (!scene || !camera || !renderer || !map || !sceneRoot) return;
+
+		const domElement = renderer.getRenderer().domElement;
+		const controls = new TransformControls(camera, domElement);
+		controlsRef.current = controls;
+
+		// Set initial mode
+		controls.setMode(mode || 'translate');
+		controls.setSpace(space || 'world');
+		if (size) {
+			controls.setSize(size);
+		}
+
+		// Add TransformControls root object to the sceneRoot
+		// TransformControls has an internal _root that is the actual Object3D
+		sceneRoot.add((controls as any)._root);
+
+		// When transform controls are active, disable map interaction
+		const onDraggingChanged = (event: any) => {
+			if (event.value) {
+				// Disable map dragging when using transform controls
+				map.dragPan.disable();
+				map.scrollZoom.disable();
+			} else {
+				// Re-enable map dragging
+				map.dragPan.enable();
+				map.scrollZoom.enable();
+			}
+		};
+
+		controls.addEventListener('dragging-changed', onDraggingChanged);
+
+		// Trigger callback on object change
+		if (onObjectChange) {
+			const handleObjectChange = () => {
+				if (controls.object) {
+					onObjectChange(controls.object);
+				}
+			};
+			controls.addEventListener('objectChange', handleObjectChange);
+		}
+
+		return () => {
+			controls.removeEventListener('dragging-changed', onDraggingChanged);
+			controls.detach();
+			sceneRoot.remove((controls as any)._root);
+			controls.dispose();
+			controlsRef.current = null;
+		};
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [scene, camera, renderer, map, sceneRoot]);
+
+	// Update target object
+	useEffect(() => {
+		if (!controlsRef.current) return;
+
+		if (target) {
+			controlsRef.current.attach(target);
+		} else {
+			controlsRef.current.detach();
+		}
+	}, [target]);
+
+	// Update mode
+	useEffect(() => {
+		if (!controlsRef.current) return;
+		// Directly set the mode to avoid detach/reattach cycle
+		(controlsRef.current as any).mode = mode || 'translate';
+	}, [mode]);
+
+	// Update enabled state
+	useEffect(() => {
+		if (!controlsRef.current) return;
+		controlsRef.current.enabled = enabled !== false;
+	}, [enabled]);
+
+	// Update space
+	useEffect(() => {
+		if (!controlsRef.current) return;
+		controlsRef.current.setSpace(space || 'world');
+	}, [space]);
+
+	// Update size
+	useEffect(() => {
+		if (!controlsRef.current || !size) return;
+		controlsRef.current.setSize(size);
+	}, [size]);
+
+	return null;
+};
+
+export default MlTransformControls;

package/src/components/ThreeContext.tsx

@@ -0,0 +1,26 @@
+import { createContext, useContext } from 'react';
+import { Scene, PerspectiveCamera, Group, Matrix4 } from 'three';
+import { Map as MapboxMap } from 'maplibre-gl';
+import ThreejsSceneRenderer from '../lib/ThreejsSceneRenderer';
+
+export interface ThreeContextType {
+	scene: Scene | undefined;
+	camera: PerspectiveCamera | undefined;
+	renderer: ThreejsSceneRenderer | undefined;
+	map: MapboxMap | undefined;
+	sceneRoot: Group | undefined;
+	worldMatrix: Matrix4 | undefined;
+	worldMatrixInv: Matrix4 | undefined;
+}
+
+export const ThreeContext = createContext<ThreeContextType>({
+	scene: undefined,
+	camera: undefined,
+	renderer: undefined,
+	map: undefined,
+	sceneRoot: undefined,
+	worldMatrix: undefined,
+	worldMatrixInv: undefined,
+});
+
+export const useThree = () => useContext(ThreeContext);

package/src/components/ThreeObjectControls.tsx

@@ -0,0 +1,197 @@
+import Button from '@mui/material/Button';
+import ButtonGroup from '@mui/material/ButtonGroup';
+import Slider from '@mui/material/Slider';
+import Typography from '@mui/material/Typography';
+import Box from '@mui/material/Box';
+
+export interface ThreeObjectControlsProps {
+	showLayer: boolean;
+	setShowLayer: (show: boolean) => void;
+	scale: number;
+	setScale: (scale: number) => void;
+	rotation: { x: number; y: number; z: number };
+	setRotation: (rotation: { x: number; y: number; z: number }) => void;
+	useMapCoords: boolean;
+	setUseMapCoords: (use: boolean) => void;
+	mapPosition: { lng: number; lat: number };
+	setMapPosition: (position: { lng: number; lat: number }) => void;
+	altitude: number;
+	setAltitude: (altitude: number) => void;
+	position: { x: number; y: number; z: number };
+	setPosition: (position: { x: number; y: number; z: number }) => void;
+	enableTransformControls?: boolean;
+	setEnableTransformControls?: (enable: boolean) => void;
+	transformMode?: 'translate' | 'rotate' | 'scale';
+	setTransformMode?: (mode: 'translate' | 'rotate' | 'scale') => void;
+	layerName?: string;
+}
+
+export const ThreeObjectControls = ({
+	showLayer,
+	setShowLayer,
+	scale,
+	setScale,
+	rotation,
+	setRotation,
+	useMapCoords,
+	setUseMapCoords,
+	mapPosition,
+	setMapPosition,
+	altitude,
+	setAltitude,
+	position,
+	setPosition,
+	enableTransformControls,
+	setEnableTransformControls,
+	transformMode,
+	setTransformMode,
+	layerName = 'Layer',
+}: ThreeObjectControlsProps) => {
+	return (
+		<Box sx={{ padding: '10px' }}>
+			<Box sx={{ display: 'flex', gap: 1, flexWrap: 'wrap', marginBottom: 2 }}>
+				<Button
+					color="primary"
+					variant={showLayer ? 'contained' : 'outlined'}
+					onClick={() => setShowLayer(!showLayer)}
+					size="small"
+				>
+					{showLayer ? 'Hide' : 'Show'} {layerName}
+				</Button>
+				<Button
+					color="secondary"
+					variant={useMapCoords ? 'contained' : 'outlined'}
+					onClick={() => setUseMapCoords(!useMapCoords)}
+					size="small"
+				>
+					{useMapCoords ? 'Map Coords' : 'Scene Coords'}
+				</Button>
+				{setEnableTransformControls && (
+					<Button
+						color="info"
+						variant={enableTransformControls ? 'contained' : 'outlined'}
+						onClick={() => setEnableTransformControls(!enableTransformControls)}
+						size="small"
+					>
+						3D Gizmo
+					</Button>
+				)}
+			</Box>
+
+			{setTransformMode && enableTransformControls && (
+				<Box sx={{ marginBottom: 2 }}>
+					<ButtonGroup variant="outlined" size="small" fullWidth aria-label="transform mode">
+						<Button
+							variant={transformMode === 'translate' ? 'contained' : 'outlined'}
+							onClick={() => setTransformMode('translate')}
+						>
+							Move
+						</Button>
+						<Button
+							variant={transformMode === 'rotate' ? 'contained' : 'outlined'}
+							onClick={() => setTransformMode('rotate')}
+						>
+							Rotate
+						</Button>
+						<Button
+							variant={transformMode === 'scale' ? 'contained' : 'outlined'}
+							onClick={() => setTransformMode('scale')}
+						>
+							Scale
+						</Button>
+					</ButtonGroup>
+				</Box>
+			)}
+			<Typography gutterBottom>Scale: {scale.toFixed(2)}</Typography>
+			<Slider
+				value={scale}
+				onChange={(e, newValue) => setScale(newValue as number)}
+				min={0.01}
+				max={150}
+				step={0.01}
+				valueLabelDisplay="auto"
+			/>
+			<Typography gutterBottom>Rotation X: {rotation.x}°</Typography>
+			<Slider
+				value={rotation.x}
+				onChange={(e, newValue) => setRotation({ ...rotation, x: newValue as number })}
+				min={0}
+				max={360}
+				valueLabelDisplay="auto"
+			/>
+			<Typography gutterBottom>Rotation Y: {rotation.y}°</Typography>
+			<Slider
+				value={rotation.y}
+				onChange={(e, newValue) => setRotation({ ...rotation, y: newValue as number })}
+				min={0}
+				max={360}
+				valueLabelDisplay="auto"
+			/>
+			<Typography gutterBottom>Rotation Z: {rotation.z}°</Typography>
+			<Slider
+				value={rotation.z}
+				onChange={(e, newValue) => setRotation({ ...rotation, z: newValue as number })}
+				min={0}
+				max={360}
+				valueLabelDisplay="auto"
+			/>
+			{useMapCoords ? (
+				<>
+					<Typography gutterBottom>Longitude: {mapPosition.lng.toFixed(6)}</Typography>
+					<Slider
+						value={mapPosition.lng}
+						onChange={(e, newValue) => setMapPosition({ ...mapPosition, lng: newValue as number })}
+						min={7.09}
+						max={7.11}
+						step={0.0001}
+						valueLabelDisplay="auto"
+					/>
+					<Typography gutterBottom>Latitude: {mapPosition.lat.toFixed(6)}</Typography>
+					<Slider
+						value={mapPosition.lat}
+						onChange={(e, newValue) => setMapPosition({ ...mapPosition, lat: newValue as number })}
+						min={50.73}
+						max={50.74}
+						step={0.0001}
+						valueLabelDisplay="auto"
+					/>
+					<Typography gutterBottom>Altitude: {altitude} m</Typography>
+					<Slider
+						value={altitude}
+						onChange={(e, newValue) => setAltitude(newValue as number)}
+						min={-100}
+						max={500}
+						valueLabelDisplay="auto"
+					/>
+				</>
+			) : (
+				<>
+					<Typography gutterBottom>Position X: {position.x}</Typography>
+					<Slider
+						value={position.x}
+						onChange={(e, newValue) => setPosition({ ...position, x: newValue as number })}
+						min={-100}
+						max={100}
+						valueLabelDisplay="auto"
+					/>
+					<Typography gutterBottom>Position Y: {position.y}</Typography>
+					<Slider
+						value={position.y}
+						onChange={(e, newValue) => setPosition({ ...position, y: newValue as number })}
+						min={-100}
+						max={100}
+						valueLabelDisplay="auto"
+					/>
+					<Typography gutterBottom>Position Z: {position.z}</Typography>
+					<Slider
+						value={position.z}
+						onChange={(e, newValue) => setPosition({ ...position, z: newValue as number })}
+						min={-500}
+						max={100}
+						valueLabelDisplay="auto"
+					/>
+				</>
+			)}
+		</Box>
+	);
+};