react-babylon-map 0.0.1

package/src/core/events.ts

@@ -0,0 +1,55 @@
+import { Scene } from '@babylonjs/core';
+
+/**
+ * Pointer event handler that maps DOM pointer coordinates to Babylon.js scene picking.
+ * Used for both canvas-in-layer and canvas-overlay modes.
+ */
+export interface PointerEventHandler {
+  /** Attach pointer listeners to the given DOM element (usually the map canvas parent). */
+  connect(target: HTMLElement): void;
+  /** Detach listeners. */
+  disconnect(): void;
+}
+
+/**
+ * Create a pointer event handler that bridges map DOM events to Babylon scene picking.
+ */
+export function createPointerHandler(scene: Scene, canvas: HTMLCanvasElement): PointerEventHandler {
+  let target: HTMLElement | null = null;
+
+  const onPointerDown = (evt: PointerEvent) => {
+    const pickResult = scene.pick(
+      evt.offsetX * (canvas.width / canvas.clientWidth),
+      evt.offsetY * (canvas.height / canvas.clientHeight),
+    );
+    if (pickResult?.hit && pickResult.pickedMesh) {
+      const mesh = pickResult.pickedMesh;
+      mesh.metadata?.onPointerDown?.(evt, pickResult);
+    }
+  };
+
+  const onPointerMove = (evt: PointerEvent) => {
+    const pickResult = scene.pick(
+      evt.offsetX * (canvas.width / canvas.clientWidth),
+      evt.offsetY * (canvas.height / canvas.clientHeight),
+    );
+    if (pickResult?.hit && pickResult.pickedMesh) {
+      const mesh = pickResult.pickedMesh;
+      mesh.metadata?.onPointerMove?.(evt, pickResult);
+    }
+  };
+
+  return {
+    connect(el: HTMLElement) {
+      target = el;
+      target.addEventListener('pointerdown', onPointerDown as EventListener);
+      target.addEventListener('pointermove', onPointerMove as EventListener);
+    },
+    disconnect() {
+      if (!target) return;
+      target.removeEventListener('pointerdown', onPointerDown as EventListener);
+      target.removeEventListener('pointermove', onPointerMove as EventListener);
+      target = null;
+    },
+  };
+}

package/src/core/generic-map.ts

@@ -0,0 +1,59 @@
+// mock of functions used by `react-babylon-map` from `Maplibre` or `Mapbox`
+
+/** Generic interface of Mapbox/Maplibre `LayerProps` */
+export interface LayerProps {
+  id: string;
+  type: 'custom';
+  renderingMode: '3d';
+  onRemove?(map: MapInstance, gl: WebGLRenderingContext): void;
+  onAdd?(map: MapInstance, gl: WebGLRenderingContext): void;
+  prerender?(gl: WebGLRenderingContext, matrix: number[]): void;
+  render(gl: WebGLRenderingContext, matrix: number[]): void;
+}
+
+/** Generic interface of Mapbox/Maplibre `LngLatLike` */
+export type LngLatLike = {
+  lng: number;
+  lat: number;
+} | {
+  lon: number;
+  lat: number;
+} | [
+  number,
+  number
+];
+
+/** Generic interface of Mapbox/Maplibre `static MercatorCoordinate.fromLngLat` */
+export type FromLngLat = (lngLatLike: LngLatLike, altitude?: number) => MercatorCoordinate;
+
+/** Generic interface of Mapbox/Maplibre typeof `MercatorCoordinate` */
+export interface MercatorCoordinate {
+  x: number;
+  y: number;
+  z?: number;
+  meterInMercatorCoordinateUnits(): number;
+}
+
+/** Generic interface of Mapbox/Maplibre `Map` */
+export interface MapInstance {
+  getCanvas(): HTMLCanvasElement;
+  /** MapLibre only */
+  getPixelRatio?: ()=>number;
+  triggerRepaint(): void;
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  on<T extends keyof MapEventType>(type: T, listener: (ev: MapEventType[T] & Object) => void): void;
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  off<T extends keyof MapEventType>(type: T, listener: (ev: MapEventType[T] & Object) => void): void;
+}
+
+/** Generic interface of Mapbox/Maplibre `MapEventType` */
+export type MapEventType = {
+  resize: MapEvent;
+};
+
+/** Generic interface of `MapLibreEvent` or `MapBoxEvent` */
+export interface MapEvent<TOrig = unknown> {
+  type: string;
+  target: MapInstance;
+  originalEvent: TOrig;
+}

package/src/core/map-engine.tsx

@@ -0,0 +1,70 @@
+import { Color4, Engine, Scene } from '@babylonjs/core';
+import React, { useEffect, useRef, useState } from 'react';
+
+export interface MapEngineProps {
+  /** External WebGL rendering context (canvas-in-layer mode). */
+  externalContext?: WebGLRenderingContext;
+  /** Render mode: manual = external code triggers scene.render(), auto = engine runRenderLoop. */
+  renderMode?: 'auto' | 'manual';
+  children: React.ReactNode;
+}
+
+/**
+ * Wrapper that creates a Babylon Engine (optionally from an external GL context)
+ * and a Scene, then provides them to children.
+ *
+ * In *overlay* mode a new <canvas> is created.
+ * In *canvas-in-layer* mode the external MapLibre GL context is reused.
+ */
+export const MapEngine: React.FC<MapEngineProps> = ({
+  externalContext,
+  renderMode = 'manual',
+  children,
+}) => {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const [engine, setEngine] = useState<Engine | null>(null);
+  const [scene, setScene] = useState<Scene | null>(null);
+
+  useEffect(() => {
+    let eng: Engine;
+
+    if (externalContext) {
+      eng = new Engine(
+        externalContext as WebGL2RenderingContext,
+        false, // antialias
+        { preserveDrawingBuffer: true, stencil: true },
+        false, // adaptToDeviceRatio
+      );
+    } else {
+      eng = new Engine(canvasRef.current!, true);
+    }
+
+    const scn = new Scene(eng);
+    scn.useRightHandedSystem = true;
+    scn.autoClear = false;
+    scn.clearColor = new Color4(0, 0, 0, 0);
+
+    if (renderMode === 'auto') {
+      eng.runRenderLoop(() => scn.render());
+    }
+
+    setEngine(eng);
+    setScene(scn);
+
+    return () => {
+      scn.dispose();
+      eng.dispose();
+    };
+  }, [externalContext, renderMode]);
+
+  if (!engine || !scene) {
+    return externalContext ? null : <canvas ref={canvasRef} style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%' }} />;
+  }
+
+  return (
+    <>
+      {!externalContext && <canvas ref={canvasRef} style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%' }} />}
+      {children}
+    </>
+  );
+};

package/src/core/matrix-utils.ts

@@ -0,0 +1,22 @@
+import { Matrix } from '@babylonjs/core';
+
+/** Column-major (MapLibre) → transposed flat array (Babylon row-major layout) */
+export function transposeMatrix(m: number[]): number[] {
+  return [
+    m[0],  m[4],  m[8],  m[12],
+    m[1],  m[5],  m[9],  m[13],
+    m[2],  m[6],  m[10], m[14],
+    m[3],  m[7],  m[11], m[15],
+  ];
+}
+
+/** MapLibre column-major matrix → Babylon.js Matrix */
+export function columnMajorToBabylonMatrix(m: number[]): Matrix {
+  return Matrix.FromArray(transposeMatrix(m));
+}
+
+/** Extract a flat column-major array from a Babylon Matrix (for MapLibre interop) */
+export function babylonMatrixToColumnMajor(m: Matrix): number[] {
+  const a = m.toArray();
+  return transposeMatrix(Array.from(a));
+}

package/src/core/sync-camera.ts

@@ -0,0 +1,29 @@
+import { FreeCamera, Matrix } from '@babylonjs/core';
+
+const tmpCameraMx = Matrix.Identity();
+const tmpWvpMx = Matrix.Identity();
+
+/** Synchronise a Babylon camera with the map's view-projection matrix.
+ *  @param camera   The Babylon camera to update.
+ *  @param origin   Babylon world matrix for the Canvas origin.
+ *  @param mapCamMx Flat array from MapLibre's view-projection (column-major).
+ */
+export function syncCamera(
+  camera: FreeCamera,
+  origin: Matrix,
+  mapCamMx: number[],
+): void {
+
+  // Matrix.FromArray reads column-major data (same layout as MapLibre provides)
+  Matrix.FromArrayToRef(mapCamMx, 0, tmpCameraMx);
+
+  // world-view-projection = origin * camera (same as demo: worldMatrix.multiply(cameraMatrix))
+  origin.multiplyToRef(tmpCameraMx, tmpWvpMx);
+
+  // Freeze the projection to the composed matrix so Babylon's own
+  // projection math is bypassed.
+  camera.freezeProjectionMatrix(tmpWvpMx);
+
+  camera.minZ = 0;
+  camera.maxZ = 1e6;
+}

package/src/core/use-babylon-map.ts

@@ -0,0 +1,46 @@
+import { createContext, useContext } from 'react';
+import { Engine, Scene } from '@babylonjs/core';
+import { FromLngLat, MapInstance } from './generic-map';
+
+/** Context object shared between both rendering modes. */
+export interface BabylonMap<T extends MapInstance = MapInstance> {
+  /** Map provider instance */
+  map: T;
+  /** Column-major view-projection matrix from the map provider */
+  viewProjMx: number[];
+  /** Mercator coordinate factory */
+  fromLngLat: FromLngLat;
+  /** Babylon Engine (may be null during init) */
+  engine?: Engine;
+  /** Babylon Scene (may be null during init) */
+  scene?: Scene;
+  /** Current origin coordinates (set by Canvas) */
+  coords?: { longitude: number; latitude: number; altitude?: number };
+}
+
+// ── React context ──────────────────────────────────────────────────────
+
+export const BabylonMapContext = createContext<BabylonMap | null>(null);
+
+/** Access the current BabylonMap context (map, scene, engine, viewProjMx). */
+export function useBabylonMap<T extends MapInstance = MapInstance>(): BabylonMap<T> {
+  const ctx = useContext(BabylonMapContext);
+  if (!ctx) throw new Error('useBabylonMap must be used inside a <Canvas>');
+  return ctx as BabylonMap<T>;
+}
+
+/** Initialise / update the BabylonMap context value. */
+export function createBabylonMap<T extends MapInstance>(opts: {
+  map: T;
+  fromLngLat: FromLngLat;
+  engine?: Engine;
+  scene?: Scene;
+}): BabylonMap<T> {
+  return {
+    map: opts.map,
+    viewProjMx: new Array(16).fill(0) as number[],
+    fromLngLat: opts.fromLngLat,
+    engine: opts.engine,
+    scene: opts.scene,
+  };
+}

package/src/core/use-coords-to-matrix.ts

@@ -0,0 +1,13 @@
+import { useMemo } from 'react';
+import { Matrix } from '@babylonjs/core';
+import { coordsToMatrix } from './coords-to-matrix';
+
+type Props = Parameters<typeof coordsToMatrix>[0];
+
+/** Calculate a Babylon Matrix from coordinates (memoised). */
+export function useCoordsToMatrix({ latitude, longitude, altitude, fromLngLat }: Props): Matrix {
+  return useMemo(
+    () => coordsToMatrix({ latitude, longitude, altitude, fromLngLat }),
+    [latitude, longitude, altitude, fromLngLat],
+  );
+}

package/src/core/use-coords.tsx

@@ -0,0 +1,22 @@
+import { useContext, useMemo } from 'react';
+import { Coords } from '../api/coords';
+import { BabylonMapContext, BabylonMap } from './use-babylon-map';
+
+/** Read the current coordinates from context. */
+export function useCoords(): Coords {
+  const ctx = useContext(BabylonMapContext);
+  if (!ctx) throw new Error('useCoords must be used inside a <Canvas>');
+  return (ctx as any).coords as Coords; // eslint-disable-line @typescript-eslint/no-explicit-any
+}
+
+/** Update the coordinates stored on the context. */
+export function useSetCoords({ longitude, latitude, altitude }: Coords) {
+  // Coordinates are now stored directly on the BabylonMap context object
+  // so downstream hooks can read them.
+  useMemo(() => {
+    const ctx = (BabylonMapContext as any)._currentValue as BabylonMap | null; // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (ctx) {
+      (ctx as any).coords = { longitude, latitude, altitude }; // eslint-disable-line @typescript-eslint/no-explicit-any
+    }
+  }, [longitude, latitude, altitude]);
+}

package/src/core/use-function.ts

@@ -0,0 +1,10 @@
+import { useCallback, useRef } from 'react';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export const useFunction = <T extends (...args: any[]) => any>(callback: T): T => {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+  return useCallback((...args: any[]) => {
+    return callbackRef.current(...args);
+  }, []) as T;
+};

package/src/mapbox/canvas.tsx

@@ -0,0 +1,59 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+import { MercatorCoordinate } from 'mapbox-gl';
+import { memo, useState } from 'react';
+import { Layer, useMap } from 'react-map-gl/mapbox';
+import { CanvasProps } from '../api/canvas-props';
+import { useCanvasInLayer } from '../core/canvas-in-layer/use-canvas-in-layer';
+import { InitCanvasFC } from '../core/canvas-overlay/init-canvas-fc';
+import { Render } from '../core/canvas-overlay/render';
+import { MapInstance } from '../core/generic-map';
+import { useFunction } from '../core/use-function';
+
+const fromLngLat = MercatorCoordinate.fromLngLat;
+
+/** `react-babylon-map` canvas inside `Mapbox` */
+export const Canvas = memo<CanvasProps>(({ overlay, ...props }) => {
+  const map = useMap().current!.getMap(); // eslint-disable-line @typescript-eslint/no-non-null-assertion
+
+  return (
+    <>
+      {overlay && <CanvasOverlay map={map} {...props} />}
+      {!overlay && <CanvasInLayer map={map} {...props} />}
+    </>
+  );
+});
+Canvas.displayName = 'Canvas';
+
+interface CanvasPropsAndMap extends CanvasProps {
+  map: MapInstance;
+}
+
+const CanvasInLayer = memo<CanvasPropsAndMap>(({ map, ...props }) => {
+  const layerProps = useCanvasInLayer(props, fromLngLat, map);
+  /* @ts-ignore */
+  return <Layer {...layerProps} />;
+});
+CanvasInLayer.displayName = 'CanvasInLayer';
+
+const CanvasOverlay = memo<CanvasPropsAndMap>(({ map, id, beforeId, ...props }) => {
+  const [onRender, setOnRender] = useState<(mx: number[]) => void>();
+
+  const render = useFunction<Render>((_gl, mx) => {
+    if (!onRender) return;
+    onRender(mx as number[]);
+  });
+
+  return (
+    <>
+      {/* @ts-ignore */}
+      <Layer id={id} beforeId={beforeId} type="custom" render={render} />
+      <InitCanvasFC
+        {...props}
+        setOnRender={setOnRender}
+        map={map}
+        fromLngLat={fromLngLat}
+      />
+    </>
+  );
+});
+CanvasOverlay.displayName = 'CanvasOverlay';

package/src/mapbox.index.ts

@@ -0,0 +1,7 @@
+import type { Map } from 'mapbox-gl';
+import { useMap as useMapGeneric } from './api/use-map';
+
+export * from './api';
+export * from './mapbox/canvas';
+
+export const useMap = useMapGeneric<Map>;

package/src/maplibre/canvas.tsx

@@ -0,0 +1,59 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+import { MercatorCoordinate } from 'maplibre-gl';
+import { memo, useState } from 'react';
+import { Layer, useMap } from 'react-map-gl/maplibre';
+import { CanvasProps } from '../api/canvas-props';
+import { useCanvasInLayer } from '../core/canvas-in-layer/use-canvas-in-layer';
+import { InitCanvasFC } from '../core/canvas-overlay/init-canvas-fc';
+import { Render } from '../core/canvas-overlay/render';
+import { MapInstance } from '../core/generic-map';
+import { useFunction } from '../core/use-function';
+
+const fromLngLat = MercatorCoordinate.fromLngLat;
+
+/** `react-babylon-map` canvas inside `MapLibre` */
+export const Canvas = memo<CanvasProps>(({ overlay, ...props }) => {
+  const map = useMap().current!.getMap(); // eslint-disable-line @typescript-eslint/no-non-null-assertion
+
+  return (
+    <>
+      {overlay && <CanvasOverlay map={map} {...props} />}
+      {!overlay && <CanvasInLayer map={map} {...props} />}
+    </>
+  );
+});
+Canvas.displayName = 'Canvas';
+
+interface CanvasPropsAndMap extends CanvasProps {
+  map: MapInstance;
+}
+
+const CanvasInLayer = memo<CanvasPropsAndMap>(({ map, ...props }) => {
+  const layerProps = useCanvasInLayer(props, fromLngLat, map);
+  /* @ts-ignore */
+  return <Layer {...layerProps} />;
+});
+CanvasInLayer.displayName = 'CanvasInLayer';
+
+const CanvasOverlay = memo<CanvasPropsAndMap>(({ map, id, beforeId, ...props }) => {
+  const [onRender, setOnRender] = useState<(mx: number[]) => void>();
+
+  const render = useFunction<Render>((_gl, mx) => {
+    if (!onRender) return;
+    onRender(mx as number[]);
+  });
+
+  return (
+    <>
+      {/* @ts-ignore */}
+      <Layer id={id} beforeId={beforeId} type="custom" render={render} />
+      <InitCanvasFC
+        {...props}
+        setOnRender={setOnRender}
+        map={map}
+        fromLngLat={fromLngLat}
+      />
+    </>
+  );
+});
+CanvasOverlay.displayName = 'CanvasOverlay';

package/src/maplibre.index.ts

@@ -0,0 +1,7 @@
+import type { Map } from 'maplibre-gl';
+import { useMap as useMapGeneric } from './api/use-map';
+
+export * from './api';
+export * from './maplibre/canvas';
+
+export const useMap = useMapGeneric<Map>;

package/src/vite-env.d.ts

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

package/stories/.ladle/components.tsx

@@ -0,0 +1,50 @@
+import { GlobalProvider } from "@ladle/react";
+import './style.css';
+import React, { memo, useCallback, useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+export const Provider: GlobalProvider = ({ children }) => {
+  const [header] = useState(() => document.createElement('div'));
+
+  const toggle = useCallback(() => {
+    if (!header.parentElement) return;
+    header.parentElement.classList.toggle('hide')
+  }, [])
+
+  const hide = useCallback((e: any)=>{ // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!header.parentElement) return;
+    if(e.target.nodeName !== 'A') return;
+    header.parentElement.classList.add('hide')
+  }, [])
+
+  useEffect(() => {
+    const container = document.querySelector('.ladle-aside');
+    if (!container) return;
+    container.prepend(header);
+    container.classList.add('hide');
+    container.addEventListener('click', hide)
+    return () => {
+      header.remove();
+      container.removeEventListener('click', hide)
+    }
+  }, [])
+  return <>
+    {createPortal(<Header toggle={toggle} />, header)}
+    {children}
+  </>
+}
+
+interface HeaderProps {
+  toggle: () => void;
+}
+
+const Header = memo<HeaderProps>(({ toggle }) => {
+  return <>
+    <button className="story-menu-btn" onClick={toggle}>&#9776;</button>
+    <h1>react-babylon-map</h1>
+    <div style={{ paddingBottom: 15 }} className="story-header">
+      <p>Babylon.js inside Mapbox & Maplibre</p>
+    </div>
+  </>
+})
+Header.displayName = 'Header';

package/stories/.ladle/style.css

@@ -0,0 +1,63 @@
+.ladle-main {
+  padding: 0;
+}
+
+.ladle-aside {
+  order: -1;
+  padding: 1em 1.5em;
+}
+
+header.ladle-addons {
+  max-width: 18em
+}
+
+header.ladle-addons ul {
+  flex-wrap: wrap;
+}
+
+header.ladle-addons li {
+  margin: 0.35em;
+}
+
+header.ladle-addons li:nth-of-type(4) {
+  display: none;
+}
+
+.story-menu-btn {
+  border: none;
+  background: none;
+  position: fixed;
+  right: 1rem;
+}
+
+.story-menu-btn img {
+  width: 2rem;
+  height: 2rem;
+}
+
+@media (max-width: 767px) {
+  .ladle-aside h1 {
+    margin: 0;
+  }
+
+  .ladle-aside {
+    position: fixed;
+    left: 0;
+    right: 0;
+    top: 0;
+  }
+
+  .hide.ladle-aside>*:not(:first-child) {
+    display: none;
+  }
+
+  .hide .story-header {
+    display: none;
+  }
+}
+
+@media (min-width: 768px) {
+  .story-menu-btn {
+    display: none;
+  }
+}

package/stories/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "stories",
+  "version": "0.0.0",
+  "license": "MIT",
+  "scripts": {
+    "dev": "ladle serve"
+  },
+  "dependencies": {
+    "@babylonjs/core": "^9.0.0",
+    "@babylonjs/materials": "^9.0.0",
+    "@ifc-lite/geometry": "^1.16.5",
+    "@ladle/react": "^4.0.2",
+    "leva": "^0.9.35",
+    "luxon": "^3.7.2",
+    "mapbox-gl": "^3.9.4",
+    "maplibre-gl": "^5.4.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-map-gl": "^8.0.1",
+    "suncalc": "^1.9.0",
+    "suspend-react": "^0.1.3",
+    "tz-lookup": "^6.1.25"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.15",
+    "@types/react-dom": "^18.2.7",
+    "@vitejs/plugin-react": "^4.0.3",
+    "typescript": "^5.1.6",
+    "vite": "^4.4.4"
+  }
+}