@mapcomponents/three 1.7.2

package/.babelrc

@@ -0,0 +1,12 @@
+{
+	"presets": [
+		[
+			"@nx/react/babel",
+			{
+				"runtime": "automatic",
+				"useBuiltIns": "usage"
+			}
+		]
+	],
+	"plugins": []
+}

package/.storybook/main.ts

@@ -0,0 +1,20 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+	stories: ['../src/**/*.@(mdx|stories.@(js|jsx|ts|tsx))'],
+	addons: [],
+	framework: {
+		name: '@storybook/react-vite',
+		options: {
+			builder: {
+				viteConfigPath: 'vite.config.ts',
+			},
+		},
+	},
+};
+
+export default config;
+
+// To customize your Vite configuration you can use the viteFinal field.
+// Check https://storybook.js.org/docs/react/builders/vite#configuration
+// and https://nx.dev/recipes/storybook/custom-builder-configs

package/README.md

@@ -0,0 +1,54 @@
+# @mapcomponents/three
+
+This library provides React components to easily integrate [Three.js](https://threejs.org/) 3D content into [MapLibre GL JS](https://maplibre.org/) maps using [@mapcomponents/react-maplibre](https://github.com/mapcomponents/react-map-components-maplibre).
+
+## Installation
+
+Install the package and its peer dependencies:
+
+```bash
+npm install @mapcomponents/three @mapcomponents/react-maplibre
+```
+
+## Getting Started
+
+To use `@mapcomponents/three`, you need to wrap your 3D layers with the `ThreeProvider` component. This provider initializes the Three.js scene, camera, and renderer, and registers a custom layer within the MapLibre map.
+
+### Basic Usage
+
+Here is a simple example of how to render a 3D model on a map:
+
+```tsx
+import React from 'react';
+import { MapComponentsProvider, MapLibreMap } from '@mapcomponents/react-maplibre';
+import { ThreeProvider, MlThreeModelLayer } from '@mapcomponents/three';
+
+const App = () => {
+  return (
+    <MapComponentsProvider>
+      <ThreeProvider id="three-scene-1">
+        <MapLibreMap
+          options={{
+            style: 'https://demotiles.maplibre.org/style.json',
+            center: [13.404954, 52.520008],
+            zoom: 15,
+            pitch: 60
+          }}
+        />
+      
+        <MlThreeModelLayer
+          url="https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Duck/glTF-Binary/Duck.glb"
+          mapPosition={[13.404954, 52.520008]}
+          scale={10}
+        />
+      </ThreeProvider>
+    </MapComponentsProvider>
+  );
+};
+
+export default App;
+```
+
+## Running unit tests
+
+Run `nx test @mapcomponents/three` to execute the unit tests via [Vitest](https://vitest.dev/).

package/cypress.config.ts

@@ -0,0 +1,13 @@
+import { nxComponentTestingPreset } from '@nx/react/plugins/component-testing';
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+	component: {
+		...nxComponentTestingPreset(__filename, {
+			bundler: 'vite',
+			buildTarget: '@mapcomponents/three:build',
+		}),
+		supportFile: 'src/cypress/support/component.ts',
+		indexHtmlFile: 'src/cypress/support/component-index.html',
+	},
+});

package/eslint.config.mjs

@@ -0,0 +1,12 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+	...baseConfig,
+	...nx.configs['flat/react'],
+	{
+		files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+		// Override or add rules here
+		rules: {},
+	},
+];

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@mapcomponents/three",
+  "version": "1.7.2",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mui/material": "^7.3.2",
+    "maplibre-gl": "^5.7.0",
+    "three": "^0.182.0",
+    "@mapcomponents/react-maplibre": "1.7.2"
+  },
+  "devDependencies": {
+    "@types/three": "^0.182.0"
+  }
+}

package/project.json

@@ -0,0 +1,15 @@
+{
+	"name": "@mapcomponents/three",
+	"$schema": "../../node_modules/nx/schemas/project-schema.json",
+	"sourceRoot": "packages/three/src",
+	"projectType": "library",
+	"tags": [],
+	"// targets": "to see all targets run: nx show project @mapcomponents/three --web",
+	"targets": {
+		"storybook": {
+			"options": {
+				"port": 4403
+			}
+		}
+	}
+}

package/src/components/MlThreeModelLayer/MlThreeModelLayer.cy.tsx

@@ -0,0 +1,63 @@
+import React, { useEffect } from 'react';
+import { MapComponentsProvider, MapLibreMap, useMap } from '@mapcomponents/react-maplibre';
+import { ThreeProvider } from '../ThreeProvider';
+import MlThreeModelLayer from './MlThreeModelLayer';
+
+const MapExposer = () => {
+	const { map } = useMap({ mapId: 'map_1' });
+	useEffect(() => {
+		if (map) {
+			(window as any)._map = map;
+		}
+	}, [map]);
+	return null;
+};
+
+const TestComponent = ({ onDone }: { onDone: () => void }) => {
+	return (
+		<MapComponentsProvider>
+			<MapExposer />
+			<ThreeProvider id="three-provider" mapId="map_1">
+				<MlThreeModelLayer
+					url="assets/3D/godzilla_simple.glb"
+					mapPosition={[13.404954, 52.520008]}
+					scale={10}
+					onDone={onDone}
+				/>
+			</ThreeProvider>
+			<MapLibreMap
+				options={{
+					style: { version: 8, sources: {}, layers: [] },
+					center: [13.404954, 52.520008],
+					zoom: 15,
+					pitch: 60,
+				}}
+				mapId="map_1"
+			/>
+		</MapComponentsProvider>
+	);
+};
+
+describe('<MlThreeModelLayer />', () => {
+	it('renders', () => {
+		const onDoneSpy = cy.spy().as('onDoneSpy');
+		cy.mount(<TestComponent onDone={onDoneSpy} />);
+
+		// Wait for map to load
+		cy.get('.maplibregl-canvas').should('exist');
+
+		// Wait for the model to load first (this confirms map and three provider are working)
+		cy.get('@onDoneSpy', { timeout: 15000 }).should('have.been.called');
+
+		// Check if map instance is available and has the custom layer
+		cy.window().should('have.property', '_map');
+		cy.window().then((win: any) => {
+			const map = win._map;
+			// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+			expect(map).to.exist;
+			// Check for the layer added by ThreeProvider
+			// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+			expect(map.getLayer('three-provider')).to.exist;
+		});
+	});
+});

package/src/components/MlThreeModelLayer/MlThreeModelLayer.meta.json

@@ -0,0 +1,21 @@
+{
+	"name": "MlThreeModelLayer",
+	"title": "3D Model",
+	"description": "Layer Component, that makes it possible to show 3D Models on the map.",
+	"i18n": {
+		"de": {
+			"title": "3D Modelle",
+			"description": "Layer Component, das es ermöglicht 3D Modelle auf der Karte darzustellen."
+		}
+	},
+	"tags": ["Map layer"],
+	"category": "layer",
+	"type": "component",
+	"demos": [
+		{
+			"name": "Demo",
+			"url": "https://mapcomponents.github.io/react-map-components-maplibre/three/iframe.html?id=mapcomponents-mlthreemodellayer--example-config&viewMode=story"
+		}
+	],
+	"thumbnail": "https://mapcomponents.github.io/react-map-components-maplibre/three/thumbnails/MlThreeModelLayer.png"
+}

package/src/components/MlThreeModelLayer/MlThreeModelLayer.stories.tsx

@@ -0,0 +1,161 @@
+import { useRef, useState, useEffect } from 'react';
+import Button from '@mui/material/Button';
+import MlThreeModelLayer from './MlThreeModelLayer';
+import { useMap, TopToolbar, Sidebar } from '@mapcomponents/react-maplibre';
+import ThreejsContextDecorator from '../../decorators/ThreejsContextDecorator';
+import { useThree } from '../ThreeContext';
+import { ThreeObjectControls } from '../ThreeObjectControls';
+import ThreejsUtils from '../../lib/ThreejsUtils';
+import * as THREE from 'three';
+
+const storyoptions = {
+	title: 'MapComponents/MlThreeModelLayer',
+	component: MlThreeModelLayer,
+	argTypes: {
+		options: {
+			control: {
+				type: 'object',
+			},
+		},
+	},
+	decorators: ThreejsContextDecorator,
+};
+export default storyoptions;
+
+const Lights = () => {
+	const { scene } = useThree();
+	const lightsRef = useRef<THREE.Light[]>([]);
+
+	useEffect(() => {
+		if (!scene) return;
+
+		const directionalLight = new THREE.DirectionalLight(0xffffff);
+		directionalLight.position.set(0, -70, 100).normalize();
+		scene.add(directionalLight);
+
+		const directionalLight2 = new THREE.DirectionalLight(0xff2255);
+		directionalLight2.position.set(0, 70, 100).normalize();
+		scene.add(directionalLight2);
+
+		lightsRef.current = [directionalLight, directionalLight2];
+
+		return () => {
+			lightsRef.current.forEach((light) => scene.remove(light));
+		};
+	}, [scene]);
+
+	return null;
+};
+
+const Template: any = () => {
+	const { worldMatrix } = useThree();
+	const [showLayer, setShowLayer] = useState(true);
+	const [scale, setScale] = useState(1);
+	const [rotation, setRotation] = useState({ x: 90, y: 90, z: 0 });
+	const [useMapCoords, setUseMapCoords] = useState(true);
+	const [mapPosition, setMapPosition] = useState({ lng: 7.097, lat: 50.7355 });
+	const [altitude, setAltitude] = useState(0);
+	const [position, setPosition] = useState({ x: 0, y: 0, z: 0 });
+	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(15.5);
+		mapHook.map?.setPitch(44.5);
+		mapHook.map?.setCenter([7.097, 50.7355]);
+	}, [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(alt);
+		} else {
+			setPosition({ x: object.position.x, y: object.position.y, z: object.position.z });
+		}
+	};
+
+	return (
+		<>
+			<Lights />
+			{showLayer && (
+				<MlThreeModelLayer
+					url="assets/3D/godzilla_simple.glb"
+					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="3D Model 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="Model"
+				/>
+			</Sidebar>
+		</>
+	);
+};
+
+export const ExampleConfig = Template.bind({});
+ExampleConfig.parameters = {};

package/src/components/MlThreeModelLayer/MlThreeModelLayer.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useRef, useState } from 'react';
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+import { LngLatLike } from 'maplibre-gl';
+import { useThree } from '../ThreeContext';
+import ThreejsUtils from '../../lib/ThreejsUtils';
+import MlTransformControls from '../MlTransformControls';
+
+/**
+ * Renders obj or gltf 3D Models on the MapLibreMap referenced by props.mapId
+ *
+ * @component
+ */
+
+export interface MlThreeModelLayerProps {
+	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 MlThreeModelLayer = (props: MlThreeModelLayerProps) => {
+	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);
+				}
+			}
+
+			modelRef.current = object;
+			scene.add(object);
+			setModel(object);
+			if (typeof onDoneRef.current === 'function') {
+				onDoneRef.current();
+			}
+		};
+
+		if (extension === 'glb' || extension === 'gltf') {
+			const loader = new GLTFLoader();
+			loader.load(url, (gltf) => {
+				onLoad(gltf.scene);
+			});
+		} else if (extension === 'obj') {
+			const loader = new OBJLoader();
+			loader.load(url, (obj) => {
+				onLoad(obj);
+			});
+		} else {
+			console.warn('MlThreeModelLayer: Unsupported file extension', extension);
+		}
+
+		return () => {
+			if (modelRef.current) {
+				scene.remove(modelRef.current);
+				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, position, mapPosition, altitude, rotation, scale, worldMatrixInv]);
+
+	if (enableTransformControls && model) {
+		return (
+			<MlTransformControls target={model} mode={transformMode} onObjectChange={onTransformChange} />
+		);
+	}
+	return null;
+};
+
+export default MlThreeModelLayer;

package/src/components/MlThreeSplatLayer/MlThreeSplatLayer.cy.tsx

@@ -0,0 +1,62 @@
+import React, { useEffect } from 'react';
+import { MapComponentsProvider, MapLibreMap, useMap } from '@mapcomponents/react-maplibre';
+import { ThreeProvider } from '../ThreeProvider';
+import MlThreeSplatLayer from './MlThreeSplatLayer';
+
+const MapExposer = () => {
+	const { map } = useMap({ mapId: 'map_1' });
+	useEffect(() => {
+		if (map) {
+			(window as any)._map = map;
+		}
+	}, [map]);
+	return null;
+};
+
+const TestComponent = ({ onDone }: { onDone: () => void }) => {
+	return (
+		<MapComponentsProvider>
+			<MapExposer />
+			<ThreeProvider id="three-provider" mapId="map_1">
+				<MlThreeSplatLayer
+					url="assets/splats/output.splat"
+					mapPosition={[13.404954, 52.520008]}
+					scale={1}
+					onDone={onDone}
+				/>
+			</ThreeProvider>
+			<MapLibreMap
+				options={{
+					style: { version: 8, sources: {}, layers: [] },
+					center: [13.404954, 52.520008],
+					zoom: 15,
+					pitch: 60,
+				}}
+				mapId="map_1"
+			/>
+		</MapComponentsProvider>
+	);
+};
+
+describe('<MlThreeSplatLayer />', () => {
+	it('renders', () => {
+		const onDoneSpy = cy.spy().as('onDoneSpy');
+		cy.mount(<TestComponent onDone={onDoneSpy} />);
+
+		// Wait for map to load
+		cy.get('.maplibregl-canvas').should('exist');
+
+		// Wait for the splat to load first
+		cy.get('@onDoneSpy', { timeout: 15000 }).should('have.been.called');
+
+		// Check if map instance is available and has the custom layer
+		cy.window().should('have.property', '_map');
+		cy.window().then((win: any) => {
+			const map = win._map;
+			// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+			expect(map).to.exist;
+			// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+			expect(map.getLayer('three-provider')).to.exist;
+		});
+	});
+});

package/src/components/MlThreeSplatLayer/MlThreeSplatLayer.meta.json

@@ -0,0 +1,21 @@
+{
+	"name": "MlThreeSplatLayer",
+	"title": "3D Splat Model",
+	"description": "Layer Component, that makes it possible to show 3D Gaussian Splatting Models on the map.",
+	"i18n": {
+		"de": {
+			"title": "3D Splat Modelle",
+			"description": "Layer Component, das es ermöglicht 3D Gaussian Splatting Modelle auf der Karte darzustellen."
+		}
+	},
+	"tags": ["Map layer", "3D", "Splat"],
+	"category": "layer",
+	"type": "component",
+	"demos": [
+		{
+			"name": "Demo",
+			"url": "https://mapcomponents.github.io/react-map-components-maplibre/three/iframe.html?id=mapcomponents-mlthreesplatlayer--default&viewMode=story"
+		}
+	],
+	"thumbnail": "https://mapcomponents.github.io/react-map-components-maplibre/three/thumbnails/MlThreeSplatLayer.png"
+}