Skip to content

AVIATION_MAP_FEATURE.md

Latest commit

 

History

History
175 lines (138 loc) · 5.96 KB

AVIATION_MAP_FEATURE.md

File metadata and controls

175 lines (138 loc) · 5.96 KB

Aviation Map Integration - Implementation Summary

1. Map Tab Type

  • Extended TabManager with a new sealed class TabContent supporting both DocumentTab and MapTab
  • Added openMapTab() method to create/switch to the map
  • Map tabs appear alongside PDF/MD tabs with a map icon

2. MapViewer Component (ui/maps/MapViewer.kt)

  • Live Position Tracking: Subscribes to DataPad FlightData StateFlow
  • Aircraft Marker: Shows position with rotation based on heading
  • Info Display: Altitude, speed, and heading in marker popup
  • Auto-centering: Option to follow aircraft automatically
  • Multiple Layers: OpenStreetMap, Topographic, Satellite
  • Connection Status: Visual indicators for DataPad connection state

3. Integration Points

  • TabBar & QuickTabSwitcher: Updated to display map icon for map tabs
  • MainActivity: Renders MapViewer when map tab is active
  • InternalFilesScreen: Added map button (🗺️) in top bar

4. Dependencies

  • Added osmdroid-android:6.1.20 to build.gradle.kts
  • All required permissions already present in AndroidManifest.xml

🎯 How to Use

Opening the Map

  1. From the file list screen, click the Map icon (🗺️) in the top bar
  2. Map opens as a new tab, can be switched like any document tab

Map Controls

  • Center Button (🎯): Auto-center on aircraft position
  • Layers Button (🗂️): Switch between map tile sources
  • Pinch to Zoom: Standard map gesture controls
  • Drag to Pan: Manual navigation (disables auto-center)

Live Position Updates

  • Position updates automatically when DataPad receives UDP data
  • Marker shows aircraft heading via rotation
  • Info popup displays altitude (ft), speed (kts), heading (°)
  • Connection status indicators show DataPad state

📊 Data Flow

DCS UDP Stream → DataPadManager → FlightData StateFlow
                                        ↓
                                  MapViewer observes
                                        ↓
                                 Update marker position
                                        ↓
                                  Render on map

🔧 Technical Details

Position Format

The map uses the latitude and longitude fields from FlightData:

@SerialName("lat") val latitude: Double = 0.0
@SerialName("long") val longitude: Double = 0.0

Performance Optimizations

  • Marker updates triggered only on position changes
  • Tile caching handled automatically by osmdroid
  • DisposableEffect cleans up MapView on tab close
  • Smooth animations via animateTo()

Map Tile Sources

  1. OpenStreetMap (Default): Standard street map
  2. Topographic: Terrain and elevation
  3. Satellite (USGS): Aerial imagery

📝 Files Created/Modified

New Files

  • ui/maps/MapViewer.kt - Main map viewer component
  • docs/technical/AVIATION_MAPS.md - Complete technical documentation

Modified Files

  • app/build.gradle.kts - Added osmdroid dependency
  • data/tabs/TabManager.kt - Added MapTab support
  • ui/tabs/TabBar.kt - Added map icon
  • ui/tabs/QuickTabSwitcher.kt - Added map icon
  • ui/files/InternalFilesScreen.kt - Added map button
  • MainActivity.kt - Integrated MapViewer rendering

🚀 Next Steps (Optional Enhancements)

Flight Path Trail

Display historical position track on the map:

private val pathOverlay = Polyline().apply {
    outlinePaint.color = Color.BLUE
    outlinePaint.strokeWidth = 5f
}

Custom Aviation Layers

Add sectional charts or airspace boundaries:

  • OpenAIP aviation overlay
  • VFR/IFR charts
  • Airspace boundaries
  • Airport markers

Waypoint Display

Show flight plan waypoints from DataPad:

  • Distance/bearing calculations
  • ETA to next waypoint
  • Course line overlay

Threat Display

Visualize RWR data on map:

  • SAM/AAA threat circles
  • Color-coded by threat level
  • Bearing lines to threats

📚 Documentation

Full technical documentation available in:

  • docs/technical/AVIATION_MAPS.md

Related documentation:

  • docs/features/DATAPAD_FEATURE.md
  • docs/features/TAB_SYSTEM.md
  • docs/technical/DCS_EXPORT_API.md

🧪 Testing Checklist

To verify the implementation:

  1. ✅ Build project - Should compile without errors
  2. ⏳ Open map tab - Click map icon in file list
  3. ⏳ Check tile loading - Map should display base layer
  4. ⏳ Connect DataPad - Start DCS and forward_parsed_udp.py
  5. ⏳ Verify position - Marker should appear at aircraft position
  6. ⏳ Test auto-center - Map should follow aircraft movement
  7. ⏳ Try layer switching - Toggle between map types
  8. ⏳ Check info popup - Tap marker to see altitude/speed
  9. ⏳ Test tab switching - Switch between map and documents

🐛 Known Limitations

  1. Tile Downloads: Requires internet connection for first load
  2. Aviation Charts: Not included by default (requires custom tile source)
  3. Performance: Large position history trails may impact performance
  4. Offline Mode: Tiles must be pre-cached for offline use

💡 Tips

  • First Launch: Map tiles download on first use (requires internet)
  • Manual Navigation: Dragging the map disables auto-centering
  • Re-center: Tap the center button (🎯) to re-enable auto-center
  • Tile Cache: Located in device storage, cleared via osmdroid config
  • Custom Icons: Replace marker icon in MapViewer.kt factory function

🎉 Summary

The aviation map is now fully integrated into your tab system! The map:

  • ✅ Opens as a tab alongside PDF/MD documents
  • ✅ Shows live aircraft position from DataPad
  • ✅ Updates marker position and heading automatically
  • ✅ Supports multiple map layers
  • ✅ Includes auto-centering and manual controls
  • ✅ Shows connection status indicators
  • ✅ Integrates seamlessly with existing UI

The implementation follows Jetpack Compose best practices with reactive state management, proper lifecycle handling, and performance optimizations.

App Version: v1.0.25 Last Updated: 2026.01.19