@mapcomponents/three 1.7.2

package/src/components/ThreeProvider.tsx

@@ -0,0 +1,149 @@
+import React, { useEffect, useState, useRef } from 'react';
+import { useMap } from '@mapcomponents/react-maplibre';
+import { Scene, PerspectiveCamera, Group, Matrix4 } from 'three';
+import { LngLatLike, CustomLayerInterface } from 'maplibre-gl';
+import ThreejsSceneHelper from '../lib/ThreejsSceneHelper';
+import ThreejsSceneRenderer from '../lib/ThreejsSceneRenderer';
+import ThreejsUtils from '../lib/ThreejsUtils';
+import { ThreeContext } from './ThreeContext';
+
+export interface ThreeProviderProps {
+	mapId?: string;
+	id: string;
+	refCenter?: LngLatLike;
+	envTexture?: string;
+	envIntensity?: number;
+	createLight?: boolean;
+	children?: React.ReactNode;
+	/**
+	 * Id of an existing layer in the MapLibre instance to help specify the layer order.
+	 * The Three.js layer will be rendered visually beneath the layer with the specified id.
+	 */
+	beforeId?: string;
+}
+
+export const ThreeProvider: React.FC<ThreeProviderProps> = ({
+	mapId,
+	id,
+	refCenter,
+	envTexture,
+	envIntensity = 1,
+	createLight = true,
+	children,
+	beforeId,
+}) => {
+	const { map } = useMap({ mapId, waitForLayer: beforeId });
+	const [scene, setScene] = useState<Scene>();
+	const [camera, setCamera] = useState<PerspectiveCamera>();
+	const [renderer, setRenderer] = useState<ThreejsSceneRenderer>();
+	const [sceneRoot, setSceneRoot] = useState<Group>();
+	const [worldMatrix, setWorldMatrix] = useState<Matrix4>();
+	const [worldMatrixInv, setWorldMatrixInv] = useState<Matrix4>();
+
+	const helperRef = useRef(new ThreejsSceneHelper());
+	const worldMatrixRef = useRef<Matrix4>(new Matrix4());
+	const worldMatrixInvRef = useRef<Matrix4>(new Matrix4());
+	const rendererRef = useRef<ThreejsSceneRenderer | undefined>(undefined);
+
+	useEffect(() => {
+		if (!map) return;
+
+		const helper = helperRef.current;
+		const threeScene = helper.createScene(createLight);
+		const root = helper.createGroup(threeScene, 'scene-root');
+		const threeCamera = helper.createCamera(root, 'camera-for-render');
+
+		const customLayer: CustomLayerInterface = {
+			id: id,
+			type: 'custom',
+			renderingMode: '3d',
+			onAdd: (mapInstance, gl) => {
+				const threeRenderer = new ThreejsSceneRenderer(mapInstance, gl as WebGL2RenderingContext);
+				rendererRef.current = threeRenderer;
+				setRenderer(threeRenderer);
+
+				const center = refCenter || mapInstance.getCenter();
+				worldMatrixRef.current = ThreejsUtils.updateWorldMatrix(mapInstance, center);
+				worldMatrixInvRef.current = worldMatrixRef.current.clone().invert();
+				setWorldMatrix(worldMatrixRef.current);
+				setWorldMatrixInv(worldMatrixInvRef.current);
+
+				if (envTexture) {
+					helper.createEnvTexture(envTexture, threeScene);
+				}
+				threeScene.environmentIntensity = envIntensity;
+
+				mapInstance.triggerRepaint();
+			},
+			render: (gl, matrix) => {
+				if (!rendererRef.current || !threeScene || !threeCamera) return;
+
+				helper.updateCameraForRender(
+					threeCamera,
+					map.map,
+					matrix,
+					worldMatrixRef.current,
+					worldMatrixInvRef.current
+				);
+
+				rendererRef.current.render(threeScene, threeCamera);
+				map.triggerRepaint();
+			},
+			onRemove: () => {
+				if (rendererRef.current) {
+					rendererRef.current.dispose();
+					rendererRef.current = undefined;
+				}
+				setRenderer(undefined);
+			},
+		};
+
+		if (!map.getLayer(id)) {
+			map.addLayer(customLayer, beforeId);
+		}
+
+		setScene(threeScene);
+		setCamera(threeCamera);
+		setSceneRoot(root);
+
+		return () => {
+			if (map.getLayer(id)) {
+				map.removeLayer(id);
+			}
+			// Cleanup is handled in onRemove
+		};
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [map, id]); // Re-run if map or id changes.
+
+	// Handle dynamic prop changes
+	useEffect(() => {
+		if (scene && envTexture) {
+			helperRef.current.createEnvTexture(envTexture, scene);
+		}
+	}, [scene, envTexture]);
+
+	useEffect(() => {
+		if (scene) {
+			scene.environmentIntensity = envIntensity;
+		}
+	}, [scene, envIntensity]);
+
+	// Handle refCenter change
+	useEffect(() => {
+		if (map && refCenter) {
+			worldMatrixRef.current = ThreejsUtils.updateWorldMatrix(map.map, refCenter);
+			worldMatrixInvRef.current = worldMatrixRef.current.clone().invert();
+			setWorldMatrix(worldMatrixRef.current);
+			setWorldMatrixInv(worldMatrixInvRef.current);
+			map.triggerRepaint();
+		}
+	}, [map, refCenter]);
+
+	return (
+		<ThreeContext.Provider
+			value={{ scene, camera, renderer, map: map?.map, sceneRoot, worldMatrix, worldMatrixInv }}
+		>
+			{children}
+		</ThreeContext.Provider>
+	);
+};

package/src/cypress/support/commands.ts

@@ -0,0 +1 @@
+/// <reference types="cypress" />

package/src/cypress/support/component-index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="utf-8" />
+		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
+		<meta name="viewport" content="width=device-width,initial-scale=1.0" />
+		<title>@mapcomponents/three Components App</title>
+		<link href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css" rel="stylesheet" />
+	</head>
+	<body>
+		<div data-cy-root></div>
+	</body>
+</html>

package/src/cypress/support/component.ts

@@ -0,0 +1,13 @@
+import { mount } from 'cypress/react';
+import './commands';
+
+declare global {
+	// eslint-disable-next-line @typescript-eslint/no-namespace
+	namespace Cypress {
+		interface Chainable {
+			mount: typeof mount;
+		}
+	}
+}
+
+Cypress.Commands.add('mount', mount);

package/src/decorators/ThreejsContextDecorator.tsx

@@ -0,0 +1,42 @@
+import React, { useMemo } from 'react';
+import { ThreeProvider } from '../components/ThreeProvider';
+import {
+	MapComponentsProvider,
+	MapLibreMap,
+	MlNavigationTools,
+	getTheme,
+} from '@mapcomponents/react-maplibre';
+import { ThemeProvider as MUIThemeProvider } from '@mui/material/styles';
+import './style.css';
+
+const decorators = [
+	(Story: any, context: any) => {
+		const theme = useMemo(() => getTheme(context?.globals?.theme), [context?.globals?.theme]);
+		return (
+			<div className="fullscreen_map">
+				<MapComponentsProvider>
+					<MUIThemeProvider theme={theme}>
+						<ThreeProvider mapId="map_1" id="three-scene-layer" beforeId="water_name_line">
+							<Story />
+						</ThreeProvider>
+						<MapLibreMap
+							options={{
+								zoom: 14.5,
+								style: 'https://wms.wheregroup.com/tileserver/style/osm-liberty.json',
+								center: [7.099771581806502, 50.73395746209983],
+							}}
+							mapId="map_1"
+						/>
+						<MlNavigationTools
+							sx={{ bottom: '25px', right: '5px' }}
+							showZoomButtons={false}
+							mapId="map_1"
+						/>
+					</MUIThemeProvider>
+				</MapComponentsProvider>
+			</div>
+		);
+	},
+];
+
+export default decorators;

package/src/decorators/style.css

@@ -0,0 +1,33 @@
+#root {
+	background-color: #000;
+	position: absolute;
+	min-height: 400px;
+	top: 0;
+	bottom: 0;
+	left: 0;
+	right: 0;
+}
+.docs-story {
+	min-height: 400px;
+	display: flex;
+	align-items: stretch;
+}
+.docs-story > div:first-child {
+	width: 100%;
+}
+
+.App {
+	position: absolute;
+	top: 0;
+	right: 0;
+	bottom: 0;
+	left: 0;
+}
+.fullscreen_map .mapContainer {
+	position: absolute;
+	top: 0;
+	right: 0;
+	left: 0;
+	bottom: 0;
+	z-index: 100;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './lib/ThreejsUtils';
+export * from './lib/ThreejsSceneHelper';
+export * from './lib/ThreejsSceneRenderer';
+export * from './components/ThreeContext';
+export * from './components/ThreeProvider';
+export { default as MlThreeModelLayer } from './components/MlThreeModelLayer/MlThreeModelLayer';
+export { default as MlThreeSplatLayer } from './components/MlThreeSplatLayer/MlThreeSplatLayer';

package/src/lib/ThreejsSceneHelper.ts

@@ -0,0 +1,250 @@
+/**
+ * Derived from mapbox-3d-tiles by Jianshun Yang (MIT License)
+ * https://github.com/yangjs6/mapbox-3d-tiles
+ */
+
+import { type Map as MaplibreMap } from 'maplibre-gl';
+import {
+	Scene,
+	PerspectiveCamera,
+	Matrix4,
+	Group,
+	EquirectangularReflectionMapping,
+	DirectionalLight,
+	AmbientLight,
+	Vector3,
+	Quaternion,
+	Euler,
+} from 'three';
+import { HDRLoader } from 'three/examples/jsm/loaders/HDRLoader.js';
+import ThreejsUtils from './ThreejsUtils';
+
+export default class ThreejsSceneHelper {
+	createScene(createLight = true): Scene {
+		const scene = new Scene();
+
+		if (createLight) {
+			const dirLight = new DirectionalLight(0xffffff, 4);
+			dirLight.position.set(1, 2, 3);
+			scene.add(dirLight);
+
+			const ambLight = new AmbientLight(0xffffff, 0.2);
+			scene.add(ambLight);
+		}
+
+		return scene;
+	}
+
+	createGroup(parent: Scene | Group, name: string): Group {
+		const group = new Group();
+		group.name = name;
+		parent.add(group);
+		return group;
+	}
+
+	createCamera(sceneRoot: Group, name: string): PerspectiveCamera {
+		const camera = new PerspectiveCamera();
+		camera.name = name;
+
+		const group = new Group();
+		group.name = `${name}-parent`;
+		group.add(camera);
+
+		sceneRoot.add(group);
+		return camera;
+	}
+
+	private buildPerspectiveMatrix(
+		fov: number,
+		aspect: number,
+		near: number,
+		far: number
+	): Float64Array {
+		const f = 1.0 / Math.tan(fov / 2);
+		const nf = 1.0 / (near - far);
+
+		return new Float64Array([
+			f / aspect,
+			0,
+			0,
+			0,
+			0,
+			f,
+			0,
+			0,
+			0,
+			0,
+			(far + near) * nf,
+			-1,
+			0,
+			0,
+			2 * far * near * nf,
+			0,
+		]);
+	}
+
+	private buildOrthographicMatrix(
+		left: number,
+		right: number,
+		bottom: number,
+		top: number,
+		near: number,
+		far: number
+	): Float64Array {
+		const lr = 1 / (left - right);
+		const bt = 1 / (bottom - top);
+		const nf = 1 / (near - far);
+
+		return new Float64Array([
+			-2 * lr,
+			0,
+			0,
+			0,
+			0,
+			-2 * bt,
+			0,
+			0,
+			0,
+			0,
+			2 * nf,
+			0,
+			(left + right) * lr,
+			(top + bottom) * bt,
+			(far + near) * nf,
+			1,
+		]);
+	}
+
+	private calcProjectionMatrix(transform: any, fov: number, nearZ: number, farZ: number): Matrix4 {
+		const offset = transform.centerOffset;
+		const aspect = transform.width / transform.height;
+
+		const perspective = this.buildPerspectiveMatrix(fov, aspect, nearZ, farZ);
+		perspective[8] = (-offset.x * 2) / transform.width;
+		perspective[9] = (offset.y * 2) / transform.height;
+
+		if (!transform.isOrthographic) {
+			return new Matrix4().fromArray(perspective);
+		}
+
+		const cameraToCenterDistance = (0.5 * transform.height) / Math.tan(fov / 2.0);
+		const halfHeight = cameraToCenterDistance * Math.tan(fov * 0.5);
+		const halfWidth = halfHeight * aspect;
+
+		const ortho = this.buildOrthographicMatrix(
+			-halfWidth - offset.x,
+			halfWidth - offset.x,
+			-halfHeight + offset.y,
+			halfHeight + offset.y,
+			nearZ,
+			farZ
+		);
+
+		const transitionPitch = 15;
+		const t = Math.min(transform.pitch / transitionPitch, 1.0);
+		const eased = t * t * t * t * t;
+
+		const blended = new Float64Array(16);
+		for (let i = 0; i < 16; i++) {
+			blended[i] = (1 - eased) * ortho[i] + eased * perspective[i];
+		}
+
+		return new Matrix4().fromArray(blended);
+	}
+
+	updateCameraForRender(
+		camera: PerspectiveCamera,
+		map: MaplibreMap,
+		matrix: any,
+		worldMatrix: Matrix4,
+		worldMatrixInv: Matrix4
+	): void {
+		const transform = map.transform;
+
+		const { fov, nearZ, farZ, aspect } = this.extractCameraParams(matrix, transform);
+
+		camera.fov = ThreejsUtils.radToDeg(fov);
+		camera.aspect = aspect;
+		camera.near = nearZ;
+		camera.far = farZ;
+
+		const cleanProjection = this.buildPerspectiveMatrix(fov, aspect, nearZ, farZ);
+		(camera as any)._cleanProjectionMatrix = cleanProjection;
+
+		const mvpMatrix = this.extractMVPMatrix(matrix, worldMatrix);
+		const projectionMatrix = this.calcProjectionMatrix(transform, fov, nearZ, farZ);
+
+		camera.projectionMatrix.copy(projectionMatrix);
+		camera.projectionMatrixInverse.copy(projectionMatrix).invert();
+
+		const viewMatrix = new Matrix4().multiplyMatrices(camera.projectionMatrixInverse, mvpMatrix);
+
+		camera.matrixWorld.copy(viewMatrix).invert();
+		camera.matrixWorldInverse.copy(viewMatrix);
+		camera.matrixAutoUpdate = false;
+		camera.matrixWorldAutoUpdate = false;
+
+		this.updateCameraTransform(camera);
+	}
+
+	private extractCameraParams(matrix: any, transform: any) {
+		const aspect = transform.width / transform.height;
+
+		if (matrix.fov !== undefined) {
+			return {
+				fov: matrix.fov,
+				nearZ: matrix.nearZ,
+				farZ: matrix.farZ,
+				aspect,
+			};
+		}
+
+		const cameraToCenterDistance = transform.cameraToCenterDistance;
+		const fov =
+			cameraToCenterDistance && transform.height
+				? 2 * Math.atan(transform.height / 2 / cameraToCenterDistance)
+				: 0.6435;
+
+		return {
+			fov,
+			nearZ: transform.nearZ || 0.1,
+			farZ: transform.farZ || 10000,
+			aspect,
+		};
+	}
+
+	private extractMVPMatrix(matrix: any, worldMatrix: Matrix4): Matrix4 {
+		let baseMatrix: Matrix4;
+
+		if (matrix.defaultProjectionData?.mainMatrix) {
+			baseMatrix = new Matrix4().fromArray(Object.values(matrix.defaultProjectionData.mainMatrix));
+		} else if (matrix.modelViewProjectionMatrix) {
+			baseMatrix = new Matrix4().fromArray(matrix.modelViewProjectionMatrix);
+		} else {
+			const arr = Array.isArray(matrix) ? matrix : Array.from(matrix);
+			baseMatrix = new Matrix4().fromArray(arr);
+		}
+
+		return new Matrix4().multiplyMatrices(baseMatrix, worldMatrix);
+	}
+
+	private updateCameraTransform(camera: PerspectiveCamera): void {
+		const position = new Vector3();
+		const quaternion = new Quaternion();
+		const scale = new Vector3();
+
+		camera.matrixWorld.decompose(position, quaternion, scale);
+		camera.position.copy(position);
+		camera.rotation.copy(new Euler().setFromQuaternion(quaternion, 'YXZ'));
+	}
+
+	createEnvTexture(envTexture: string, scene: Scene): void {
+		if (!envTexture?.endsWith('.hdr')) return;
+
+		new HDRLoader().load(envTexture, (texture) => {
+			texture.mapping = EquirectangularReflectionMapping;
+			scene.environment = texture;
+			scene.environmentRotation.x = Math.PI / 2;
+		});
+	}
+}

package/src/lib/ThreejsSceneRenderer.ts

@@ -0,0 +1,73 @@
+/**
+ * Derived from mapbox-3d-tiles by Jianshun Yang (MIT License)
+ * https://github.com/yangjs6/mapbox-3d-tiles
+ */
+
+import { type Map as MaplibreMap } from 'maplibre-gl';
+import { WebGLRenderer, Scene, Camera } from 'three';
+import { CSS2DRenderer } from 'three/examples/jsm/renderers/CSS2DRenderer.js';
+
+export default class ThreejsSceneRenderer {
+	private renderer: WebGLRenderer;
+	private labelRenderer: CSS2DRenderer;
+
+	/**
+	 * Creates a ThreejsSceneRenderer instance.
+	 *
+	 * @param map - The MapLibre map instance
+	 * @param gl - The WebGL2 rendering context from MapLibre
+	 */
+	constructor(map: MaplibreMap, gl: WebGL2RenderingContext) {
+		if (!gl || gl.isContextLost()) {
+			throw new Error('WebGL context is lost or invalid');
+		}
+
+		this.renderer = new WebGLRenderer({
+			alpha: true,
+			antialias: true,
+			canvas: map.getCanvas(),
+			context: gl,
+		});
+		this.renderer.autoClear = false;
+
+		this.renderer.shadowMap.enabled = true;
+		this.labelRenderer = this.createLabelRenderer(map);
+	}
+
+	private createLabelRenderer(map: MaplibreMap): CSS2DRenderer {
+		const container = map.getContainer();
+		const labelRenderer = new CSS2DRenderer();
+
+		labelRenderer.setSize(container.clientWidth, container.clientHeight);
+		labelRenderer.domElement.style.position = 'absolute';
+		labelRenderer.domElement.style.top = '0px';
+		labelRenderer.domElement.style.pointerEvents = 'none';
+
+		map._container.appendChild(labelRenderer.domElement);
+		map.on('resize', () => {
+			const { clientWidth, clientHeight } = map.getContainer();
+			labelRenderer.setSize(clientWidth, clientHeight);
+		});
+
+		return labelRenderer;
+	}
+
+	getRenderer(): WebGLRenderer {
+		return this.renderer;
+	}
+
+	render(scene: Scene, camera: Camera): void {
+		// Reset WebGL state to avoid conflicts with MapLibre
+		// but DO NOT clear the depth buffer - we want to preserve MapLibre's depth
+		// information so Three.js objects can be properly occluded by MapLibre 3D
+		// content (fill-extrusion buildings, terrain, etc.) and vice versa.
+		this.renderer.resetState();
+		this.renderer.render(scene, camera);
+		this.labelRenderer.render(scene, camera);
+	}
+
+	dispose(): void {
+		this.labelRenderer.domElement?.parentNode?.removeChild(this.labelRenderer.domElement);
+		this.renderer?.dispose();
+	}
+}

package/src/lib/ThreejsUtils.ts

@@ -0,0 +1,62 @@
+/**
+ * Derived from mapbox-3d-tiles by Jianshun Yang (MIT License)
+ * https://github.com/yangjs6/mapbox-3d-tiles
+ */
+
+import { type Map as MaplibreMap, MercatorCoordinate, LngLatLike } from 'maplibre-gl';
+import { Vector3, Quaternion, Matrix4 } from 'three';
+
+type Position = number[];
+
+const DEG_TO_RAD = Math.PI / 180;
+const RAD_TO_DEG = 180 / Math.PI;
+
+export default class ThreejsUtils {
+	static updateWorldMatrix(map: MaplibreMap | null, refCenter: LngLatLike | null = null): Matrix4 {
+		if (!map) return new Matrix4();
+
+		const center = refCenter ?? map.getCenter();
+		const origin = MercatorCoordinate.fromLngLat(center);
+		const scale = origin.meterInMercatorCoordinateUnits();
+
+		return new Matrix4().compose(
+			new Vector3(origin.x, origin.y, origin.z),
+			new Quaternion(),
+			new Vector3(scale, -scale, scale)
+		);
+	}
+
+	static toScenePositionMercator(worldMatrixInv: Matrix4, mercator: MercatorCoordinate): Vector3 {
+		return new Vector3(mercator.x, mercator.y, mercator.z).applyMatrix4(worldMatrixInv);
+	}
+
+	static toMapPositionMercator(worldMatrix: Matrix4, position: Vector3): MercatorCoordinate {
+		const transformed = position.clone().applyMatrix4(worldMatrix);
+		return new MercatorCoordinate(transformed.x, transformed.y, transformed.z);
+	}
+
+	static toScenePosition(
+		worldMatrixInv: Matrix4,
+		position: LngLatLike,
+		altitude?: number
+	): Vector3 {
+		return this.toScenePositionMercator(
+			worldMatrixInv,
+			MercatorCoordinate.fromLngLat(position, altitude)
+		);
+	}
+
+	static toMapPosition(worldMatrix: Matrix4, position: Vector3): Position {
+		const mercator = this.toMapPositionMercator(worldMatrix, position);
+		const lngLat = mercator.toLngLat();
+		return [lngLat.lng, lngLat.lat, mercator.toAltitude()];
+	}
+
+	static degToRad(degrees: number): number {
+		return degrees * DEG_TO_RAD;
+	}
+
+	static radToDeg(radians: number): number {
+		return radians * RAD_TO_DEG;
+	}
+}