feat(dees-geo-map): Add voice-guided navigation with TTS, navigation guide controller and mock GPS simulator
This commit is contained in:
135
readme.hints.md
135
readme.hints.md
@@ -26,6 +26,8 @@ Geospatial web components library using MapLibre GL JS for map rendering and ter
|
||||
| `showTraffic` | `boolean` | `false` | Enable traffic layer visualization |
|
||||
| `trafficApiKey` | `string` | `''` | HERE API key for traffic data |
|
||||
| `trafficProvider` | `ITrafficProvider` | `null` | Custom traffic data provider |
|
||||
| `enableGuidance` | `boolean` | `false` | Enable voice-guided navigation |
|
||||
| `voiceConfig` | `Partial<IVoiceConfig>` | `{}` | Voice synthesis configuration |
|
||||
|
||||
### Drawing Tools (TDrawTool)
|
||||
- `point` - Draw points
|
||||
@@ -45,6 +47,7 @@ Geospatial web components library using MapLibre GL JS for map rendering and ter
|
||||
- `address-selected` - Fired when a search result is selected
|
||||
- `route-calculated` - Fired when a navigation route is calculated (includes route, startPoint, endPoint, mode)
|
||||
- `traffic-updated` - Fired when traffic data is refreshed
|
||||
- `guidance-event` - Fired during voice-guided navigation (includes type, position, stepIndex, instruction)
|
||||
|
||||
### Public Methods
|
||||
- `getFeatures()` - Get all drawn features
|
||||
@@ -68,6 +71,22 @@ Geospatial web components library using MapLibre GL JS for map rendering and ter
|
||||
- `setTrafficProvider(provider)` - Set custom traffic provider
|
||||
- `supportsTrafficRouting()` - Check if traffic-aware routing is available
|
||||
- `getTrafficController()` - Get the TrafficController instance
|
||||
- `setPosition(coords, heading?, speed?)` - Set current GPS position for navigation guidance
|
||||
- `startGuidance()` - Start voice-guided navigation for the current route
|
||||
- `stopGuidance()` - Stop voice-guided navigation
|
||||
- `setVoiceEnabled(enabled)` - Enable/disable voice guidance
|
||||
- `isVoiceEnabled()` - Check if voice guidance is enabled
|
||||
- `getGuidanceState()` - Get current navigation guidance state
|
||||
- `isNavigating()` - Check if actively navigating
|
||||
- `createMockGPSSimulator(config?)` - Create a mock GPS simulator for testing/demo
|
||||
- `getMockGPSSimulator()` - Get the mock GPS simulator instance
|
||||
- `getGuidanceController()` - Get the NavigationGuideController instance
|
||||
- `setNavigationFollowPosition(enabled)` - Enable/disable camera following GPS position during navigation
|
||||
- `setNavigationFollowBearing(enabled)` - Enable/disable camera rotating with heading during navigation
|
||||
- `setNavigationPitch(pitch)` - Set navigation camera pitch (0-85 degrees, default 60)
|
||||
- `setNavigationZoom(zoom)` - Set navigation zoom level (default 17)
|
||||
- `getNavigationCameraConfig()` - Get full navigation camera configuration
|
||||
- `setNavigationCameraConfig(config)` - Set navigation camera configuration
|
||||
|
||||
### Context Menu
|
||||
Right-click on the map to access a context menu with the following options:
|
||||
@@ -148,7 +167,10 @@ ts_web/
|
||||
├── geo-map.search.ts # SearchController class
|
||||
├── geo-map.navigation.ts # NavigationController class
|
||||
├── geo-map.traffic.ts # TrafficController class
|
||||
└── geo-map.traffic.providers.ts # Traffic provider implementations
|
||||
├── geo-map.traffic.providers.ts # Traffic provider implementations
|
||||
├── geo-map.voice.ts # VoiceSynthesisManager class
|
||||
├── geo-map.navigation-guide.ts # NavigationGuideController class
|
||||
└── geo-map.mock-gps.ts # MockGPSSimulator class
|
||||
```
|
||||
|
||||
## Modular Architecture
|
||||
@@ -184,6 +206,34 @@ Traffic data provider implementations:
|
||||
- `HereTrafficProvider` - HERE Traffic API v7 (freemium)
|
||||
- `ValhallaTrafficProvider` - Self-hosted Valhalla server
|
||||
|
||||
### geo-map.voice.ts
|
||||
`VoiceSynthesisManager` class for voice-guided navigation:
|
||||
- Uses Web Speech API for text-to-speech
|
||||
- Queue-based speech with interrupt capability for urgent instructions
|
||||
- Configurable language, rate, pitch, volume
|
||||
- Navigation-specific methods: `speakApproach()`, `speakManeuver()`, `speakArrival()`, `speakOffRoute()`
|
||||
- Graceful fallback if speech synthesis not supported
|
||||
|
||||
### geo-map.navigation-guide.ts
|
||||
`NavigationGuideController` class for real-time GPS navigation guidance:
|
||||
- Position tracking with GPS updates via `updatePosition()` or `setPosition()`
|
||||
- Step progression tracking along route
|
||||
- Distance thresholds for voice announcements (500m, 200m, 50m, at maneuver)
|
||||
- Off-route detection (>50m from route line)
|
||||
- Arrival detection (within 30m of destination)
|
||||
- Renders GPS position marker on map with heading indicator
|
||||
- Emits guidance events: `approach-maneuver`, `execute-maneuver`, `step-change`, `off-route`, `arrived`
|
||||
- **Camera following**: Automatically moves camera to follow GPS position with smooth transitions
|
||||
- **Camera configuration**: Configurable pitch (60° default for 3D view), zoom (17 default), and bearing following
|
||||
|
||||
### geo-map.mock-gps.ts
|
||||
`MockGPSSimulator` class for testing/demo:
|
||||
- Interpolates positions along route geometry
|
||||
- Speed presets: Walking (5 km/h), Cycling (20 km/h), City (50 km/h), Highway (100 km/h)
|
||||
- Configurable update interval and GPS jitter
|
||||
- Calculates heading between consecutive points
|
||||
- Methods: `start()`, `pause()`, `stop()`, `jumpToProgress()`
|
||||
|
||||
### Usage of Controllers
|
||||
```typescript
|
||||
// SearchController is reusable
|
||||
@@ -287,3 +337,86 @@ Terra-draw's event listeners normally intercept map events through MapLibre's ca
|
||||
- When a drawing tool is active (`polygon`, `rectangle`, `point`, `linestring`, `circle`, `freehand`), MapLibre's `dragPan` and `dragRotate` are disabled
|
||||
- When `static` or `select` mode is active, dragging is re-enabled
|
||||
- The `TerraDrawMapLibreGLAdapter` does NOT accept a `lib` parameter - only `map` is required
|
||||
|
||||
### Voice-Guided Navigation Feature
|
||||
|
||||
Real-time GPS tracking with voice-guided turn-by-turn instructions:
|
||||
|
||||
#### How to Use
|
||||
1. Calculate a route using the navigation panel (set start and end points)
|
||||
2. Call `startGuidance()` to begin voice-guided navigation
|
||||
3. Update position with `setPosition([lng, lat], heading?, speed?)` or use `createMockGPSSimulator()` for testing
|
||||
4. Listen to `guidance-event` for navigation updates
|
||||
5. Call `stopGuidance()` when done
|
||||
|
||||
#### Example Usage
|
||||
```typescript
|
||||
const map = document.querySelector('dees-geo-map');
|
||||
|
||||
// 1. Set up route
|
||||
map.setNavigationStart([8.68, 50.11], 'Frankfurt');
|
||||
map.setNavigationEnd([8.75, 50.08], 'Sachsenhausen');
|
||||
await map.calculateRoute();
|
||||
|
||||
// 2. Listen to guidance events
|
||||
map.addEventListener('guidance-event', (e) => {
|
||||
console.log(e.detail.type, e.detail.instruction);
|
||||
});
|
||||
|
||||
// 3. Start guidance with mock GPS simulation
|
||||
const simulator = map.createMockGPSSimulator({ speed: 'city' });
|
||||
map.startGuidance();
|
||||
simulator.start();
|
||||
|
||||
// 4. Or use real GPS input
|
||||
navigator.geolocation.watchPosition((pos) => {
|
||||
map.setPosition([pos.coords.longitude, pos.coords.latitude], pos.coords.heading, pos.coords.speed);
|
||||
});
|
||||
```
|
||||
|
||||
#### Voice Announcements
|
||||
- **500m**: "In 500 meters, turn left onto Main Street"
|
||||
- **200m**: "In 200 meters, turn left"
|
||||
- **50m**: "Turn left ahead"
|
||||
- **At maneuver**: "Turn left now"
|
||||
- **Arrival**: "You have arrived at your destination"
|
||||
- **Off-route**: "You are off route. Recalculating."
|
||||
|
||||
#### Guidance Event Types
|
||||
- `approach-maneuver` - Approaching a turn/maneuver
|
||||
- `execute-maneuver` - At the maneuver point (urgent)
|
||||
- `step-change` - Advanced to next route step
|
||||
- `off-route` - Deviated more than 50m from route
|
||||
- `arrived` - Within 30m of destination
|
||||
- `position-updated` - Position was updated
|
||||
|
||||
#### Camera Following
|
||||
During navigation, the map camera automatically:
|
||||
- **Follows position**: Centers on current GPS location with smooth continuous transitions
|
||||
- **Follows bearing**: Rotates map to match driving direction (heading)
|
||||
- **3D tilt**: Uses 60° pitch by default for immersive driving view
|
||||
- **Street-level zoom**: Uses zoom level 17 for optimal route visibility
|
||||
- **Smooth animation**: Animation duration dynamically matches GPS update interval for fluid movement (no jerky pauses)
|
||||
|
||||
Camera behavior can be customized:
|
||||
```typescript
|
||||
// Disable camera following (user can pan freely)
|
||||
map.setNavigationFollowPosition(false);
|
||||
|
||||
// Disable bearing rotation (map stays north-up)
|
||||
map.setNavigationFollowBearing(false);
|
||||
|
||||
// Use flat (2D) view instead of tilted
|
||||
map.setNavigationPitch(0);
|
||||
|
||||
// Zoom out for wider view
|
||||
map.setNavigationZoom(15);
|
||||
|
||||
// Or set multiple options at once
|
||||
map.setNavigationCameraConfig({
|
||||
followPosition: true,
|
||||
followBearing: true,
|
||||
pitch: 60,
|
||||
zoom: 17,
|
||||
});
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user