buggy wip

Author: rafaellehmkuhl

DYNAMIC_POI_FEATURE.md

@@ -0,0 +1,90 @@
+# Dynamic Point of Interest (POI) Feature
+
+## Overview
+
+The Point of Interest system now supports dynamic positioning using data-lake syntax, allowing POIs to track live objects by referencing real-time data variables.
+
+## Key Features
+
+### 1. Dynamic Positioning
+- Use data-lake expressions like `{{ mavlink/buoy/latitude }}` for live position tracking
+- Automatic updates when data variables change
+- Fallback to last known position when data is unavailable
+
+### 2. Visual Status Indicators
+- **Live tracking**: Normal POI color indicates real-time position data
+- **No position data**: Grayed-out markers show last known location
+- **Enhanced tooltips**: Display tracking status and data availability
+
+### 3. Mixed Mode Support
+- Static POIs continue to work as before
+- Dynamic POIs can use expressions for one or both coordinates
+- Seamless integration with existing POI functionality
+
+## Usage
+
+### Creating Dynamic POIs
+
+1. **Open POI Dialog**: Right-click on map and select "Place point of interest"
+2. **Enable Dynamic Mode**: Toggle the "Dynamic positioning" switch
+3. **Enter Expressions**: Use data-lake syntax in coordinate fields:
+   - Latitude: `{{ mavlink/buoy/latitude }}`
+   - Longitude: `{{ mavlink/buoy/longitude }}`
+4. **Save**: The POI will automatically track the specified data variables
+
+### Supported Expression Formats
+
+- **Full expressions**: `{{ mavlink/buoy/latitude }}`
+- **Static values**: `37.7749` (when dynamic mode is off)
+- **Mixed mode**: Dynamic latitude with static longitude, or vice versa
+
+### Data Variable Examples
+
+- `{{ mavlink/buoy/latitude }}` - Buoy position from MAVLink
+- `{{ GLOBAL_POSITION_INT/lat }}` - Vehicle position latitude
+- `{{ NAMED_VALUE_FLOAT/target_lat }}` - Custom named value
+- `{{ compass/heading }}` - Any numeric data lake variable
+
+## Visual Feedback
+
+### POI Marker Colors
+- **Normal color**: POI has valid position data
+- **Gray**: POI has no current data, showing last known position
+
+### Tooltip Information
+- Static POIs: Standard location info
+- Dynamic POIs with data: "Live tracking" + coordinates
+- Dynamic POIs without data: "No position data - showing last known location"
+
+## Technical Implementation
+
+### Data Storage
+- Static coordinates: Stored in `coordinates` field
+- Dynamic expressions: Stored in `latitudeExpression` and `longitudeExpression` fields
+- Last known positions: Cached in `lastKnownCoordinates` field
+- Status tracking: `isDynamic` and `hasValidPosition` flags
+
+### Real-time Updates
+- Automatic data-lake variable listeners for dynamic POIs
+- Coordinate re-evaluation when source data changes
+- Marker updates and re-styling based on data availability
+
+### Backward Compatibility
+- Existing static POIs continue to work unchanged
+- New fields are optional and don't affect legacy POIs
+- Graceful handling of missing or invalid expressions
+
+## Use Cases
+
+1. **Tracking Vehicles**: Monitor other vehicles, boats, or drones
+2. **Environmental Monitoring**: Track buoys, sensors, or weather stations
+3. **Mission Targets**: Follow dynamic waypoints or objectives
+4. **Search and Rescue**: Track personnel or assets with GPS transmitters
+5. **Fleet Management**: Monitor multiple assets with live position feeds
+
+## Error Handling
+
+- Invalid expressions default to [0, 0] with warning message
+- Missing data variables show last known position in gray
+- Malformed coordinates are handled gracefully
+- Users receive clear feedback about data availability status