@more-than-software/mapkit 0.1.0

package/dist/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@more-than-software/mapkit",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/more-than-software/citykit.git",
+    "directory": "packages/mapkit"
+  },
+  "keywords": ["react", "three.js", "3d-tiles", "google-maps", "geospatial", "globe", "map", "react-three-fiber"],
+  "scripts": {
+    "build": "vite build",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "3d-tiles-renderer": "0.4.21",
+    "@takram/three-atmosphere": "^0.16.0",
+    "@takram/three-clouds": "^0.16.0",
+    "@takram/three-geospatial": "^0.6.0",
+    "@takram/three-geospatial-effects": "^0.6.0",
+    "motion": "^12.34.2",
+    "postprocessing": "^6.38.2",
+    "react-merge-refs": "^3.0.2",
+    "tiny-invariant": "^1.3.3"
+  },
+  "peerDependencies": {
+    "@react-three/drei": "^10.0.0",
+    "@react-three/fiber": "^9.0.0",
+    "@react-three/postprocessing": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "three": "^0.180.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/dist/plugins/TileCreasedNormalsPlugin.d.ts

@@ -0,0 +1,11 @@
+import { Tile } from '3d-tiles-renderer';
+import { Object3D } from 'three';
+export interface TileCreasedNormalsPluginOptions {
+    creaseAngle?: number;
+}
+export declare class TileCreasedNormalsPlugin {
+    readonly options: TileCreasedNormalsPluginOptions;
+    constructor(options?: TileCreasedNormalsPluginOptions);
+    processTileModel(scene: Object3D, tile: Tile): Promise<void>;
+}
+//# sourceMappingURL=TileCreasedNormalsPlugin.d.ts.map

package/dist/plugins/TileCreasedNormalsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileCreasedNormalsPlugin.d.ts","sourceRoot":"","sources":["../../src/plugins/TileCreasedNormalsPlugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,OAAO,CAAA;AAE3D,MAAM,WAAW,+BAA+B;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAgCD,qBAAa,wBAAwB;IACnC,QAAQ,CAAC,OAAO,EAAE,+BAA+B,CAAA;gBAErC,OAAO,CAAC,EAAE,+BAA+B;IAK/C,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBnE"}

package/dist/src/components/MapEffectComposer.tsx

@@ -0,0 +1,39 @@
+import {
+  EffectComposer as WrappedEffectComposer,
+  type EffectComposerProps
+} from '@react-three/postprocessing'
+import {
+  NormalPass,
+  type EffectComposer as EffectComposerImpl
+} from 'postprocessing'
+import { useLayoutEffect, useRef, type FC, type RefAttributes } from 'react'
+import { mergeRefs } from 'react-merge-refs'
+import { HalfFloatType, type WebGLRenderTarget } from 'three'
+import invariant from 'tiny-invariant'
+
+import { reinterpretType } from '@takram/three-geospatial'
+
+// Provided for half-float normal buffer.
+export const MapEffectComposer: FC<
+  EffectComposerProps & RefAttributes<EffectComposerImpl>
+> = ({ ref: forwardedRef, enableNormalPass = true, ...props }) => {
+  const ref = useRef<EffectComposerImpl>(null)
+  useLayoutEffect(() => {
+    const composer = ref.current
+    invariant(ref.current != null)
+    const normalPass = composer?.passes.find(pass => pass instanceof NormalPass)
+    invariant(normalPass != null)
+    reinterpretType<NormalPass & { renderTarget: WebGLRenderTarget }>(
+      normalPass
+    )
+    normalPass.renderTarget.texture.type = HalfFloatType
+  }, [])
+
+  return (
+    <WrappedEffectComposer
+      ref={mergeRefs([ref, forwardedRef])}
+      {...props}
+      enableNormalPass={enableNormalPass}
+    />
+  )
+}

package/dist/src/components/MapEntity.tsx

@@ -0,0 +1,98 @@
+import { useGLTF } from '@react-three/drei'
+import { useFrame } from '@react-three/fiber'
+import { useMemo, type FC, type ReactNode } from 'react'
+import { Sprite, SpriteMaterial, TextureLoader } from 'three'
+import { EastNorthUpFrame } from '@takram/three-geospatial/r3f'
+
+import type { MapEntity as MapEntityType } from '../index'
+
+export interface MapEntityProps extends MapEntityType {
+  children?: ReactNode
+}
+
+const textureLoader = new TextureLoader()
+
+/**
+ * Render a GLB model at a geodetic location
+ */
+const ModelEntity: FC<{
+  url: string
+  position: [number, number, number]
+  rotation?: [number, number, number]
+  scale?: number
+}> = ({ url, position, rotation, scale = 1 }) => {
+  const gltf = useGLTF(url)
+  const model = useMemo(() => {
+    const cloned = gltf.scene.clone()
+    cloned.scale.setScalar(scale)
+    if (rotation) {
+      cloned.rotation.set(rotation[0], rotation[1], rotation[2])
+    }
+    return cloned
+  }, [gltf.scene, rotation, scale])
+
+  return <primitive object={model} position={position} />
+}
+
+/**
+ * Render a billboard sprite at a geodetic location
+ */
+const BillboardEntity: FC<{
+  url?: string
+  position: [number, number, number]
+  scale?: number
+}> = ({ url, position, scale = 1 }) => {
+  const sprite = useMemo(() => {
+    const material = new SpriteMaterial({
+      map: url ? textureLoader.load(url) : undefined,
+      color: url ? undefined : 0xffffff,
+      transparent: true
+    })
+    const sprite = new Sprite(material)
+    sprite.scale.setScalar(scale * 10) // Default billboard size
+    return sprite
+  }, [url, scale])
+
+  return <primitive object={sprite} position={position} />
+}
+
+/**
+ * MapEntity component - renders entities at geodetic coordinates
+ */
+export const MapEntity: FC<MapEntityProps> = ({
+  id,
+  type,
+  latitude,
+  longitude,
+  altitude = 0,
+  rotation,
+  scale = 1,
+  url,
+  children
+}) => {
+  const position: [number, number, number] = [longitude, latitude, altitude]
+
+  if (type === 'model') {
+    if (!url) {
+      console.warn(`MapEntity ${id}: model type requires url`)
+      return null
+    }
+    return (
+      <EastNorthUpFrame longitude={longitude} latitude={latitude} height={altitude}>
+        <ModelEntity url={url} position={[0, 0, 0]} rotation={rotation} scale={scale} />
+        {children}
+      </EastNorthUpFrame>
+    )
+  }
+
+  if (type === 'billboard') {
+    return (
+      <EastNorthUpFrame longitude={longitude} latitude={latitude} height={altitude}>
+        <BillboardEntity url={url} position={[0, 0, 0]} scale={scale} />
+        {children}
+      </EastNorthUpFrame>
+    )
+  }
+
+  return null
+}

package/dist/src/components/MapScene.tsx

@@ -0,0 +1,138 @@
+import { useFrame, useThree } from '@react-three/fiber'
+import { SMAA, ToneMapping } from '@react-three/postprocessing'
+import type { GlobeControls as GlobeControlsImpl } from '3d-tiles-renderer'
+import { GlobeControls } from '3d-tiles-renderer/r3f'
+import {
+  EffectMaterial,
+  type EffectComposer as EffectComposerImpl
+} from 'postprocessing'
+import { Fragment, useEffect, useRef, useState, type FC, type ReactNode } from 'react'
+
+import {
+  AerialPerspective,
+  Atmosphere,
+  type AtmosphereApi
+} from '@takram/three-atmosphere/r3f'
+import type { CloudsEffect } from '@takram/three-clouds'
+import { Clouds } from '@takram/three-clouds/r3f'
+
+import { MapEffectComposer } from './MapEffectComposer'
+import { MapViewport } from './MapViewport'
+
+export interface MapSceneProps {
+  apiKey: string
+  children?: ReactNode
+  enableClouds?: boolean
+  enableAerialPerspective?: boolean
+  enableToneMapping?: boolean
+  cloudsCoverage?: number
+  exposure?: number
+  correctAltitude?: boolean
+  correctGeometricError?: boolean
+  onLoadError?: () => void
+}
+
+export const MapScene: FC<MapSceneProps> = ({
+  apiKey,
+  children,
+  enableClouds = false,
+  enableAerialPerspective = true,
+  enableToneMapping = true,
+  cloudsCoverage = 0.3,
+  exposure = 10,
+  correctAltitude = true,
+  correctGeometricError = true,
+  onLoadError
+}) => {
+  const camera = useThree(({ camera }) => camera)
+  const controls = useThree(
+    ({ controls }) => controls as GlobeControlsImpl | null
+  )
+
+  // Enable adjustHeight when user first interacts
+  useEffect(() => {
+    if (controls != null) {
+      const callback = (): void => {
+        controls.adjustHeight = true
+        controls.removeEventListener('start', callback)
+      }
+      controls.addEventListener('start', callback)
+      return () => {
+        controls.removeEventListener('start', callback)
+      }
+    }
+  }, [controls])
+
+  // Effects must know the camera near/far changed by GlobeControls.
+  const composerRef = useRef<EffectComposerImpl>(null)
+  useFrame(() => {
+    const composer = composerRef.current
+    if (composer != null) {
+      composer.passes.forEach(pass => {
+        if (pass.fullscreenMaterial instanceof EffectMaterial) {
+          pass.fullscreenMaterial.adoptCameraSettings(camera)
+        }
+      })
+    }
+  })
+
+  const atmosphereRef = useRef<AtmosphereApi>(null)
+  useFrame(() => {
+    atmosphereRef.current?.updateByDate(new Date())
+  })
+
+  const [clouds, setClouds] = useState<CloudsEffect | null>(null)
+
+  return (
+    <Atmosphere ref={atmosphereRef} correctAltitude={correctAltitude}>
+      <MapViewport apiKey={apiKey} onLoadError={onLoadError}>
+        <GlobeControls
+          enableDamping
+          // Globe controls adjust the camera height based on very low LoD tiles
+          // during the initial load, causing the camera to unexpectedly jump to
+          // the sky when set to a low altitude.
+          // Re-enable it when the user first drags.
+          adjustHeight={false}
+          maxAltitude={Math.PI * 0.55} // Permit grazing angles
+        />
+      </MapViewport>
+      {children}
+      <MapEffectComposer ref={composerRef} multisampling={0}>
+        <Fragment
+          // Effects are order-dependant; we need to reconstruct the nodes.
+          key={JSON.stringify([
+            correctGeometricError,
+            enableClouds,
+            enableAerialPerspective,
+            enableToneMapping,
+            exposure
+          ])}
+        >
+          {enableClouds && (
+            <Clouds
+              ref={setClouds}
+              shadow-farScale={0.25}
+              coverage={cloudsCoverage}
+              animate
+            />
+          )}
+          {enableAerialPerspective && (
+            <AerialPerspective
+              sky
+              sunLight
+              skyLight
+              correctGeometricError={correctGeometricError}
+              albedoScale={2 / Math.PI}
+            />
+          )}
+          {enableToneMapping && (
+            <>
+              <ToneMapping mode={exposure > 5 ? 'reinhard' : 'aces'} />
+              <SMAA />
+            </>
+          )}
+        </Fragment>
+      </MapEffectComposer>
+    </Atmosphere>
+  )
+}

package/dist/src/components/MapViewport.tsx

@@ -0,0 +1,82 @@
+import type { TilesRenderer as TilesRendererImpl } from '3d-tiles-renderer'
+import {
+  GLTFExtensionsPlugin,
+  GoogleCloudAuthPlugin,
+  TileCompressionPlugin,
+  TilesFadePlugin,
+  UpdateOnChangePlugin
+} from '3d-tiles-renderer/plugins'
+import {
+  TilesAttributionOverlay,
+  TilesPlugin,
+  TilesRenderer
+} from '3d-tiles-renderer/r3f'
+import { useEffect, useState, type FC, type ReactNode, type Ref } from 'react'
+import { mergeRefs } from 'react-merge-refs'
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'
+
+import { radians } from '@takram/three-geospatial'
+
+import { TileCreasedNormalsPlugin } from '../plugins/TileCreasedNormalsPlugin'
+
+const dracoLoader = new DRACOLoader()
+dracoLoader.setDecoderPath('https://www.gstatic.com/draco/v1/decoders/')
+
+export interface MapViewportProps {
+  apiKey: string
+  ref?: Ref<TilesRendererImpl>
+  children?: ReactNode
+  onLoadError?: () => void
+}
+
+export const MapViewport: FC<MapViewportProps> = ({
+  apiKey,
+  ref,
+  children,
+  onLoadError
+}) => {
+  const [tiles, setTiles] = useState<TilesRendererImpl | null>(null)
+
+  useEffect(() => {
+    if (tiles == null) {
+      return
+    }
+    if (onLoadError) {
+      const callback = (): void => {
+        onLoadError()
+      }
+      tiles.addEventListener('load-error', callback)
+      return () => {
+        tiles.removeEventListener('load-error', callback)
+      }
+    }
+  }, [tiles, onLoadError])
+
+  return (
+    <TilesRenderer
+      ref={mergeRefs([ref, setTiles])}
+      // Reconstruct tiles when API key changes.
+      key={apiKey}
+      // The root URL sometimes becomes null without specifying the URL.
+      url={`https://tile.googleapis.com/v1/3dtiles/root.json?key=${apiKey}`}
+    >
+      <TilesPlugin
+        plugin={GoogleCloudAuthPlugin}
+        args={{
+          apiToken: apiKey,
+          autoRefreshToken: true
+        }}
+      />
+      <TilesPlugin plugin={GLTFExtensionsPlugin} dracoLoader={dracoLoader} />
+      <TilesPlugin plugin={TileCompressionPlugin} />
+      <TilesPlugin plugin={UpdateOnChangePlugin} />
+      <TilesPlugin plugin={TilesFadePlugin} />
+      <TilesPlugin
+        plugin={TileCreasedNormalsPlugin}
+        args={{ creaseAngle: radians(30) }}
+      />
+      {children}
+      <TilesAttributionOverlay />
+    </TilesRenderer>
+  )
+}

package/dist/src/hooks/useMapEvents.ts

@@ -0,0 +1,211 @@
+import { useThree } from '@react-three/fiber'
+import { useEffect, useRef, useState, type RefObject } from 'react'
+import type { TilesRenderer } from '3d-tiles-renderer'
+import { Ray, Vector2, Vector3, type Camera } from 'three'
+import { useFrame } from '@react-three/fiber'
+
+import { Ellipsoid, Geodetic, degrees } from '@takram/three-geospatial'
+
+import { getCameraView } from '../utils/camera'
+import type { CameraView, LatLng } from '../index'
+
+export interface MapClickEvent {
+  latlng: LatLng
+  point: { x: number; y: number }
+}
+
+export interface MapHoverEvent {
+  latlng: LatLng | null
+  point: { x: number; y: number } | null
+}
+
+/**
+ * Convert mouse event to geodetic coordinates by raycasting to ellipsoid
+ */
+function mouseEventToLatLng(
+  event: MouseEvent,
+  camera: Camera,
+  gl: { domElement: HTMLElement }
+): LatLng | null {
+  const rect = gl.domElement.getBoundingClientRect()
+  const x = ((event.clientX - rect.left) / rect.width) * 2 - 1
+  const y = -((event.clientY - rect.top) / rect.height) * 2 + 1
+
+  // Create ray from camera through mouse position
+  const pointer = new Vector2(x, y)
+  
+  // Get camera position and direction
+  const origin = new Vector3().setFromMatrixPosition(camera.matrixWorld)
+  
+  // Unproject mouse coordinates to get direction vector
+  // For perspective camera, use near plane (z = -1) and far plane (z = 1)
+  const nearPoint = new Vector3(pointer.x, pointer.y, -1)
+  const farPoint = new Vector3(pointer.x, pointer.y, 1)
+  
+  // Transform to world space
+  nearPoint.unproject(camera)
+  farPoint.unproject(camera)
+  
+  // Calculate direction vector
+  const direction = farPoint.sub(nearPoint).normalize()
+
+  // Create ray
+  const ray = new Ray(origin, direction)
+
+  // Find intersection with ellipsoid
+  const ellipsoid = Ellipsoid.WGS84
+  const intersection = ellipsoid.getIntersection(ray)
+  
+  if (intersection == null) {
+    return null
+  }
+
+  // Convert ECEF to geodetic coordinates
+  const geodetic = new Geodetic()
+  geodetic.setFromECEF(intersection, { ellipsoid })
+
+  return {
+    latitude: degrees(geodetic.latitude),
+    longitude: degrees(geodetic.longitude),
+    altitude: geodetic.height
+  }
+}
+
+/**
+ * Hook for handling map click events
+ */
+export function useMapClick(
+  tilesRenderer: RefObject<TilesRenderer | null>,
+  onClick?: (event: MapClickEvent) => void
+): {
+  handleClick: (event: MouseEvent) => void
+} {
+  const { camera, gl } = useThree()
+  const onClickRef = useRef(onClick)
+  onClickRef.current = onClick
+
+  const handleClick = (event: MouseEvent) => {
+    if (!onClickRef.current || !tilesRenderer.current) {
+      return
+    }
+
+    const latlng = mouseEventToLatLng(event, camera, gl)
+    
+    if (latlng == null) {
+      return
+    }
+
+    onClickRef.current({
+      latlng,
+      point: { x: event.clientX, y: event.clientY }
+    })
+  }
+
+  return { handleClick }
+}
+
+/**
+ * Hook for handling map hover events
+ */
+export function useMapHover(
+  tilesRenderer: RefObject<TilesRenderer | null>,
+  onHover?: (event: MapHoverEvent) => void
+): {
+  handleMouseMove: (event: MouseEvent) => void
+  handleMouseLeave: () => void
+  hoveredLatLng: LatLng | null
+} {
+  const { camera, gl } = useThree()
+  const onHoverRef = useRef(onHover)
+  onHoverRef.current = onHover
+  const [hoveredLatLng, setHoveredLatLng] = useState<LatLng | null>(null)
+
+  const handleMouseMove = (event: MouseEvent) => {
+    if (!tilesRenderer.current) {
+      return
+    }
+
+    const latlng = mouseEventToLatLng(event, camera, gl)
+
+    setHoveredLatLng(latlng)
+    if (onHoverRef.current) {
+      onHoverRef.current({
+        latlng,
+        point: { x: event.clientX, y: event.clientY }
+      })
+    }
+  }
+
+  const handleMouseLeave = () => {
+    setHoveredLatLng(null)
+    if (onHoverRef.current) {
+      onHoverRef.current({
+        latlng: null,
+        point: null
+      })
+    }
+  }
+
+  return { handleMouseMove, handleMouseLeave, hoveredLatLng }
+}
+
+/**
+ * Hook for listening to camera position changes
+ */
+export function useMapCameraChange(
+  onCameraChange?: (view: CameraView) => void
+): {
+  currentView: CameraView | null
+} {
+  const camera = useThree(({ camera }) => camera)
+  const onCameraChangeRef = useRef(onCameraChange)
+  onCameraChangeRef.current = onCameraChange
+  const [currentView, setCurrentView] = useState<CameraView | null>(null)
+
+  useFrame(() => {
+    const view = getCameraView(camera)
+    if (view) {
+      setCurrentView(view)
+      if (onCameraChangeRef.current) {
+        onCameraChangeRef.current(view)
+      }
+    }
+  })
+
+  return { currentView }
+}
+
+/**
+ * Hook for listening to tile loading events
+ */
+export function useMapTileLoad(
+  tilesRenderer: RefObject<TilesRenderer | null>,
+  onTileLoad?: () => void
+): {
+  tilesLoaded: boolean
+} {
+  const [tilesLoaded, setTilesLoaded] = useState(false)
+  const onTileLoadRef = useRef(onTileLoad)
+  onTileLoadRef.current = onTileLoad
+
+  useEffect(() => {
+    const tiles = tilesRenderer.current
+    if (!tiles) {
+      return
+    }
+
+    const handleLoadTileset = () => {
+      setTilesLoaded(true)
+      if (onTileLoadRef.current) {
+        onTileLoadRef.current()
+      }
+    }
+
+    tiles.addEventListener('load-tileset', handleLoadTileset)
+    return () => {
+      tiles.removeEventListener('load-tileset', handleLoadTileset)
+    }
+  }, [tilesRenderer])
+
+  return { tilesLoaded }
+}

package/dist/src/index.ts

@@ -0,0 +1,55 @@
+// MapKit Public API Surface (v0.1)
+
+export type LatLng = {
+  latitude: number
+  longitude: number
+  altitude?: number
+}
+
+export type CameraView = {
+  latitude: number
+  longitude: number
+  heading: number
+  pitch: number
+  distance: number
+  fov?: number
+}
+
+export type MapEntity = {
+  id: string
+  type: 'model' | 'billboard'
+  latitude: number
+  longitude: number
+  altitude?: number
+  rotation?: [number, number, number]
+  scale?: number
+  url?: string
+  metadata?: Record<string, unknown>
+}
+
+// Components
+export { MapViewport } from './components/MapViewport'
+export type { MapViewportProps } from './components/MapViewport'
+
+export { MapScene } from './components/MapScene'
+export type { MapSceneProps } from './components/MapScene'
+
+export { MapEntity } from './components/MapEntity'
+export type { MapEntityProps } from './components/MapEntity'
+
+// Utilities
+export { flyTo } from './utils/flyTo'
+export { setCameraView, getCameraView } from './utils/camera'
+export { createPreset, getPreset, commonPresets } from './utils/presets'
+
+// Hooks
+export {
+  useMapClick,
+  useMapHover,
+  useMapCameraChange,
+  useMapTileLoad
+} from './hooks/useMapEvents'
+export type {
+  MapClickEvent,
+  MapHoverEvent
+} from './hooks/useMapEvents'