@more-than-software/mapkit 0.1.0

package/README.md

@@ -0,0 +1,306 @@
+# @more-than-software/mapkit
+
+A React component library for rendering interactive 3D maps using Google 3D Tiles, React Three Fiber, and Three.js.
+
+## Features
+
+- 🌍 Interactive 3D globe rendering with Google Maps 3D Tiles
+- 🎨 Atmospheric effects and cloud rendering
+- 🎯 Camera controls and fly-to animations
+- 📍 Entity placement (models and billboards) at geodetic coordinates
+- 🎣 Event hooks for clicks, hover, camera changes, and tile loading
+- ⚡ Built on React Three Fiber for optimal performance
+
+## Requirements
+
+- React 19.0.0 or higher
+- React DOM 19.0.0 or higher
+- Three.js 0.182.0 or higher
+- A Google Maps API key with 3D Tiles enabled
+
+## Installation
+
+```bash
+npm install @more-than-software/mapkit
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies. Install them in your project:
+
+```bash
+npm install react react-dom three postprocessing @react-three/fiber @react-three/drei @react-three/postprocessing 3d-tiles-renderer motion react-merge-refs tiny-invariant
+
+npm install @takram/three-geospatial @takram/three-atmosphere @takram/three-clouds @takram/three-geospatial-effects
+```
+
+## Quick Start
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { MapScene, MapEntity } from '@more-than-software/mapkit'
+
+function App() {
+  return (
+    <Canvas>
+      <MapScene apiKey="YOUR_GOOGLE_MAPS_API_KEY">
+        <MapEntity
+          id="marker-1"
+          type="billboard"
+          latitude={37.7749}
+          longitude={-122.4194}
+          url="/marker.png"
+        />
+      </MapScene>
+    </Canvas>
+  )
+}
+```
+
+## Components
+
+### MapScene
+
+The main scene component that sets up the 3D map environment with atmosphere, lighting, and post-processing effects.
+
+```tsx
+import { MapScene } from '@more-than-software/mapkit'
+
+<MapScene
+  apiKey="YOUR_API_KEY"
+  enableClouds={true}
+  enableAerialPerspective={true}
+  enableToneMapping={true}
+  cloudsCoverage={0.3}
+  exposure={10}
+  correctAltitude={true}
+  correctGeometricError={true}
+  onLoadError={() => console.error('Failed to load tiles')}
+>
+  {/* Your map entities and other components */}
+</MapScene>
+```
+
+#### Props
+
+- `apiKey` (string, required): Your Google Maps API key
+- `children` (ReactNode, optional): Child components to render
+- `enableClouds` (boolean, default: `false`): Enable cloud rendering
+- `enableAerialPerspective` (boolean, default: `true`): Enable atmospheric perspective
+- `enableToneMapping` (boolean, default: `true`): Enable tone mapping
+- `cloudsCoverage` (number, default: `0.3`): Cloud coverage amount (0-1)
+- `exposure` (number, default: `10`): Scene exposure level
+- `correctAltitude` (boolean, default: `true`): Correct altitude calculations
+- `correctGeometricError` (boolean, default: `true`): Correct geometric error
+- `onLoadError` (function, optional): Callback when tile loading fails
+
+### MapViewport
+
+Lower-level component that handles the 3D Tiles rendering. Typically used internally by `MapScene`, but can be used directly for custom setups.
+
+```tsx
+import { MapViewport } from '@more-than-software/mapkit'
+
+<MapViewport
+  apiKey="YOUR_API_KEY"
+  onLoadError={() => console.error('Failed to load tiles')}
+>
+  {/* Custom controls and content */}
+</MapViewport>
+```
+
+### MapEntity
+
+Renders entities (models or billboards) at specific geodetic coordinates.
+
+```tsx
+import { MapEntity } from '@more-than-software/mapkit'
+
+// Render a 3D model
+<MapEntity
+  id="building-1"
+  type="model"
+  latitude={37.7749}
+  longitude={-122.4194}
+  altitude={0}
+  url="/models/building.glb"
+  rotation={[0, Math.PI / 4, 0]}
+  scale={1.0}
+/>
+
+// Render a billboard sprite
+<MapEntity
+  id="marker-1"
+  type="billboard"
+  latitude={37.7749}
+  longitude={-122.4194}
+  altitude={100}
+  url="/markers/pin.png"
+  scale={2.0}
+/>
+```
+
+#### Props
+
+- `id` (string, required): Unique identifier for the entity
+- `type` (`'model' | 'billboard'`, required): Type of entity to render
+- `latitude` (number, required): Latitude in degrees
+- `longitude` (number, required): Longitude in degrees
+- `altitude` (number, default: `0`): Altitude in meters
+- `url` (string, optional): URL to model (GLB) or image (for billboards)
+- `rotation` (`[number, number, number]`, optional): Rotation in radians [x, y, z]
+- `scale` (number, default: `1`): Scale factor
+- `metadata` (object, optional): Custom metadata
+- `children` (ReactNode, optional): Additional content to render with the entity
+
+## Hooks
+
+### useMapClick
+
+Handle click events on the map surface.
+
+```tsx
+import { useMapClick } from '@more-than-software/mapkit'
+import { useRef } from 'react'
+
+const tilesRef = useRef(null)
+
+const { handleClick } = useMapClick(tilesRef, (event) => {
+  console.log('Clicked at:', event.latlng)
+  console.log('Screen point:', event.point)
+})
+
+// Attach to canvas element
+<canvas onClick={handleClick} />
+```
+
+### useMapHover
+
+Handle hover events on the map surface.
+
+```tsx
+import { useMapHover } from '@more-than-software/mapkit'
+
+const { handleMouseMove, handleMouseLeave, hoveredLatLng } = useMapHover(
+  tilesRef,
+  (event) => {
+    if (event.latlng) {
+      console.log('Hovering at:', event.latlng)
+    }
+  }
+)
+
+<canvas
+  onMouseMove={handleMouseMove}
+  onMouseLeave={handleMouseLeave}
+/>
+```
+
+### useMapCameraChange
+
+Listen to camera position and orientation changes.
+
+```tsx
+import { useMapCameraChange } from '@more-than-software/mapkit'
+
+const { currentView } = useMapCameraChange((view) => {
+  console.log('Camera view:', view)
+  // view contains: latitude, longitude, heading, pitch, distance, fov
+})
+```
+
+### useMapTileLoad
+
+Monitor when tiles have finished loading.
+
+```tsx
+import { useMapTileLoad } from '@more-than-software/mapkit'
+
+const { tilesLoaded } = useMapTileLoad(tilesRef, () => {
+  console.log('Tiles loaded!')
+})
+```
+
+## Utilities
+
+### Camera Control
+
+```tsx
+import { setCameraView, getCameraView } from '@more-than-software/mapkit'
+import { useThree } from '@react-three/fiber'
+
+const { camera } = useThree()
+
+// Set camera to a specific view
+setCameraView(camera, {
+  latitude: 37.7749,
+  longitude: -122.4194,
+  heading: 0,
+  pitch: Math.PI / 4,
+  distance: 10000,
+  fov: 50
+})
+
+// Get current camera view
+const view = getCameraView(camera)
+```
+
+### Fly To Animation
+
+```tsx
+import { flyTo } from '@more-than-software/mapkit'
+import { useThree } from '@react-three/fiber'
+
+const { camera } = useThree()
+
+flyTo(camera, {
+  latitude: 40.7128,
+  longitude: -74.0060,
+  heading: 0,
+  pitch: Math.PI / 6,
+  distance: 5000
+}, {
+  duration: 2000 // milliseconds
+})
+```
+
+### Camera Presets
+
+```tsx
+import { createPreset, getPreset, commonPresets } from '@more-than-software/mapkit'
+
+// Use a common preset
+const view = getPreset(commonPresets.overview)
+
+// Create a custom preset
+const customPreset = createPreset({
+  latitude: 37.7749,
+  longitude: -122.4194,
+  heading: 0,
+  pitch: Math.PI / 4,
+  distance: 10000
+})
+```
+
+## Types
+
+```tsx
+import type {
+  LatLng,
+  CameraView,
+  MapEntity,
+  MapViewportProps,
+  MapSceneProps,
+  MapEntityProps,
+  MapClickEvent,
+  MapHoverEvent
+} from '@more-than-software/mapkit'
+```
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/more-than-software/citykit

package/dist/README.md

@@ -0,0 +1,306 @@
+# @more-than-software/mapkit
+
+A React component library for rendering interactive 3D maps using Google 3D Tiles, React Three Fiber, and Three.js.
+
+## Features
+
+- 🌍 Interactive 3D globe rendering with Google Maps 3D Tiles
+- 🎨 Atmospheric effects and cloud rendering
+- 🎯 Camera controls and fly-to animations
+- 📍 Entity placement (models and billboards) at geodetic coordinates
+- 🎣 Event hooks for clicks, hover, camera changes, and tile loading
+- ⚡ Built on React Three Fiber for optimal performance
+
+## Requirements
+
+- React 19.0.0 or higher
+- React DOM 19.0.0 or higher
+- Three.js 0.182.0 or higher
+- A Google Maps API key with 3D Tiles enabled
+
+## Installation
+
+```bash
+npm install @more-than-software/mapkit
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies. Install them in your project:
+
+```bash
+npm install react react-dom three postprocessing @react-three/fiber @react-three/drei @react-three/postprocessing 3d-tiles-renderer motion react-merge-refs tiny-invariant
+
+npm install @takram/three-geospatial @takram/three-atmosphere @takram/three-clouds @takram/three-geospatial-effects
+```
+
+## Quick Start
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { MapScene, MapEntity } from '@more-than-software/mapkit'
+
+function App() {
+  return (
+    <Canvas>
+      <MapScene apiKey="YOUR_GOOGLE_MAPS_API_KEY">
+        <MapEntity
+          id="marker-1"
+          type="billboard"
+          latitude={37.7749}
+          longitude={-122.4194}
+          url="/marker.png"
+        />
+      </MapScene>
+    </Canvas>
+  )
+}
+```
+
+## Components
+
+### MapScene
+
+The main scene component that sets up the 3D map environment with atmosphere, lighting, and post-processing effects.
+
+```tsx
+import { MapScene } from '@more-than-software/mapkit'
+
+<MapScene
+  apiKey="YOUR_API_KEY"
+  enableClouds={true}
+  enableAerialPerspective={true}
+  enableToneMapping={true}
+  cloudsCoverage={0.3}
+  exposure={10}
+  correctAltitude={true}
+  correctGeometricError={true}
+  onLoadError={() => console.error('Failed to load tiles')}
+>
+  {/* Your map entities and other components */}
+</MapScene>
+```
+
+#### Props
+
+- `apiKey` (string, required): Your Google Maps API key
+- `children` (ReactNode, optional): Child components to render
+- `enableClouds` (boolean, default: `false`): Enable cloud rendering
+- `enableAerialPerspective` (boolean, default: `true`): Enable atmospheric perspective
+- `enableToneMapping` (boolean, default: `true`): Enable tone mapping
+- `cloudsCoverage` (number, default: `0.3`): Cloud coverage amount (0-1)
+- `exposure` (number, default: `10`): Scene exposure level
+- `correctAltitude` (boolean, default: `true`): Correct altitude calculations
+- `correctGeometricError` (boolean, default: `true`): Correct geometric error
+- `onLoadError` (function, optional): Callback when tile loading fails
+
+### MapViewport
+
+Lower-level component that handles the 3D Tiles rendering. Typically used internally by `MapScene`, but can be used directly for custom setups.
+
+```tsx
+import { MapViewport } from '@more-than-software/mapkit'
+
+<MapViewport
+  apiKey="YOUR_API_KEY"
+  onLoadError={() => console.error('Failed to load tiles')}
+>
+  {/* Custom controls and content */}
+</MapViewport>
+```
+
+### MapEntity
+
+Renders entities (models or billboards) at specific geodetic coordinates.
+
+```tsx
+import { MapEntity } from '@more-than-software/mapkit'
+
+// Render a 3D model
+<MapEntity
+  id="building-1"
+  type="model"
+  latitude={37.7749}
+  longitude={-122.4194}
+  altitude={0}
+  url="/models/building.glb"
+  rotation={[0, Math.PI / 4, 0]}
+  scale={1.0}
+/>
+
+// Render a billboard sprite
+<MapEntity
+  id="marker-1"
+  type="billboard"
+  latitude={37.7749}
+  longitude={-122.4194}
+  altitude={100}
+  url="/markers/pin.png"
+  scale={2.0}
+/>
+```
+
+#### Props
+
+- `id` (string, required): Unique identifier for the entity
+- `type` (`'model' | 'billboard'`, required): Type of entity to render
+- `latitude` (number, required): Latitude in degrees
+- `longitude` (number, required): Longitude in degrees
+- `altitude` (number, default: `0`): Altitude in meters
+- `url` (string, optional): URL to model (GLB) or image (for billboards)
+- `rotation` (`[number, number, number]`, optional): Rotation in radians [x, y, z]
+- `scale` (number, default: `1`): Scale factor
+- `metadata` (object, optional): Custom metadata
+- `children` (ReactNode, optional): Additional content to render with the entity
+
+## Hooks
+
+### useMapClick
+
+Handle click events on the map surface.
+
+```tsx
+import { useMapClick } from '@more-than-software/mapkit'
+import { useRef } from 'react'
+
+const tilesRef = useRef(null)
+
+const { handleClick } = useMapClick(tilesRef, (event) => {
+  console.log('Clicked at:', event.latlng)
+  console.log('Screen point:', event.point)
+})
+
+// Attach to canvas element
+<canvas onClick={handleClick} />
+```
+
+### useMapHover
+
+Handle hover events on the map surface.
+
+```tsx
+import { useMapHover } from '@more-than-software/mapkit'
+
+const { handleMouseMove, handleMouseLeave, hoveredLatLng } = useMapHover(
+  tilesRef,
+  (event) => {
+    if (event.latlng) {
+      console.log('Hovering at:', event.latlng)
+    }
+  }
+)
+
+<canvas
+  onMouseMove={handleMouseMove}
+  onMouseLeave={handleMouseLeave}
+/>
+```
+
+### useMapCameraChange
+
+Listen to camera position and orientation changes.
+
+```tsx
+import { useMapCameraChange } from '@more-than-software/mapkit'
+
+const { currentView } = useMapCameraChange((view) => {
+  console.log('Camera view:', view)
+  // view contains: latitude, longitude, heading, pitch, distance, fov
+})
+```
+
+### useMapTileLoad
+
+Monitor when tiles have finished loading.
+
+```tsx
+import { useMapTileLoad } from '@more-than-software/mapkit'
+
+const { tilesLoaded } = useMapTileLoad(tilesRef, () => {
+  console.log('Tiles loaded!')
+})
+```
+
+## Utilities
+
+### Camera Control
+
+```tsx
+import { setCameraView, getCameraView } from '@more-than-software/mapkit'
+import { useThree } from '@react-three/fiber'
+
+const { camera } = useThree()
+
+// Set camera to a specific view
+setCameraView(camera, {
+  latitude: 37.7749,
+  longitude: -122.4194,
+  heading: 0,
+  pitch: Math.PI / 4,
+  distance: 10000,
+  fov: 50
+})
+
+// Get current camera view
+const view = getCameraView(camera)
+```
+
+### Fly To Animation
+
+```tsx
+import { flyTo } from '@more-than-software/mapkit'
+import { useThree } from '@react-three/fiber'
+
+const { camera } = useThree()
+
+flyTo(camera, {
+  latitude: 40.7128,
+  longitude: -74.0060,
+  heading: 0,
+  pitch: Math.PI / 6,
+  distance: 5000
+}, {
+  duration: 2000 // milliseconds
+})
+```
+
+### Camera Presets
+
+```tsx
+import { createPreset, getPreset, commonPresets } from '@more-than-software/mapkit'
+
+// Use a common preset
+const view = getPreset(commonPresets.overview)
+
+// Create a custom preset
+const customPreset = createPreset({
+  latitude: 37.7749,
+  longitude: -122.4194,
+  heading: 0,
+  pitch: Math.PI / 4,
+  distance: 10000
+})
+```
+
+## Types
+
+```tsx
+import type {
+  LatLng,
+  CameraView,
+  MapEntity,
+  MapViewportProps,
+  MapSceneProps,
+  MapEntityProps,
+  MapClickEvent,
+  MapHoverEvent
+} from '@more-than-software/mapkit'
+```
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/more-than-software/citykit

package/dist/components/MapEffectComposer.d.ts

@@ -0,0 +1,5 @@
+import { EffectComposerProps } from '@react-three/postprocessing';
+import { EffectComposer as EffectComposerImpl } from 'postprocessing';
+import { FC, RefAttributes } from 'react';
+export declare const MapEffectComposer: FC<EffectComposerProps & RefAttributes<EffectComposerImpl>>;
+//# sourceMappingURL=MapEffectComposer.d.ts.map

package/dist/components/MapEffectComposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapEffectComposer.d.ts","sourceRoot":"","sources":["../../src/components/MapEffectComposer.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAEL,KAAK,cAAc,IAAI,kBAAkB,EAC1C,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAA2B,KAAK,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAQ5E,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAChC,mBAAmB,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAqBxD,CAAA"}

package/dist/components/MapEntity.d.ts

@@ -0,0 +1,10 @@
+import { FC, ReactNode } from 'react';
+import { MapEntity as MapEntityType } from '../index';
+export interface MapEntityProps extends MapEntityType {
+    children?: ReactNode;
+}
+/**
+ * MapEntity component - renders entities at geodetic coordinates
+ */
+export declare const MapEntity: FC<MapEntityProps>;
+//# sourceMappingURL=MapEntity.d.ts.map

package/dist/components/MapEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapEntity.d.ts","sourceRoot":"","sources":["../../src/components/MapEntity.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIxD,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,UAAU,CAAA;AAE1D,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAgDD;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,cAAc,CAoCxC,CAAA"}

package/dist/components/MapScene.d.ts

@@ -0,0 +1,15 @@
+import { FC, ReactNode } from 'react';
+export interface MapSceneProps {
+    apiKey: string;
+    children?: ReactNode;
+    enableClouds?: boolean;
+    enableAerialPerspective?: boolean;
+    enableToneMapping?: boolean;
+    cloudsCoverage?: number;
+    exposure?: number;
+    correctAltitude?: boolean;
+    correctGeometricError?: boolean;
+    onLoadError?: () => void;
+}
+export declare const MapScene: FC<MapSceneProps>;
+//# sourceMappingURL=MapScene.d.ts.map

package/dist/components/MapScene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapScene.d.ts","sourceRoot":"","sources":["../../src/components/MapScene.tsx"],"names":[],"mappings":"AAQA,OAAO,EAAyC,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAatF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;CACzB;AAED,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,aAAa,CAuGtC,CAAA"}

package/dist/components/MapViewport.d.ts

@@ -0,0 +1,10 @@
+import { TilesRenderer as TilesRendererImpl } from '3d-tiles-renderer';
+import { FC, ReactNode, Ref } from 'react';
+export interface MapViewportProps {
+    apiKey: string;
+    ref?: Ref<TilesRendererImpl>;
+    children?: ReactNode;
+    onLoadError?: () => void;
+}
+export declare const MapViewport: FC<MapViewportProps>;
+//# sourceMappingURL=MapViewport.d.ts.map

package/dist/components/MapViewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapViewport.d.ts","sourceRoot":"","sources":["../../src/components/MapViewport.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAa3E,OAAO,EAAuB,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,KAAK,GAAG,EAAE,MAAM,OAAO,CAAA;AAW9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAA;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;CACzB;AAED,eAAO,MAAM,WAAW,EAAE,EAAE,CAAC,gBAAgB,CAkD5C,CAAA"}