osm_maps_engine 0.0.1

A complete, plug-and-play mapping and routing engine for Flutter, powered entirely by OpenStreetMap (OSM) and Open Source Routing Machine (OSRM).

OSM Maps Engine

A complete, plug-and-play mapping and routing engine for Flutter, powered entirely by OpenStreetMap (OSM) and Open Source Routing Machine (OSRM).

This package provides a drop-in widget for real-time driver tracking, smooth marker animations, dynamic polyline rendering, and estimated time of arrival (ETA) calculation without relying on proprietary mapping APIs.

Key Features

• 100% Free & Open-Source Backend: Uses flutter_map (OpenStreetMap) and public OSRM API for routing. No API keys required for basic usage.
• Plug-and-Play UI Widget: Simply drop OsmMapWidget into your screen to get a fully functional navigation map.
• Real-Time Location Tracking: Automatically tracks the user's GPS location via geolocator.
• Smooth Marker Animation: Interpolates movement between GPS updates for a fluid 60FPS marker motion experience.
• Auto-Rerouting: Detects if the driver strays off the path (default threshold: 15 meters) and automatically recalculates the route.
• Modular Architecture: Decoupled state management using BLoC/Cubit pattern.

Installation

Add the package to your pubspec.yaml:

dependencies:
  osm_maps_engine:
    git:
      url: https://github.com/rayhanrwa1/osm_map_engine.git
      ref: main

Basic Usage

The easiest way to use the engine is through the OsmMapWidget. You only need to provide the starting location (origin) and the destination.

import 'package:flutter/material.dart';
import 'package:latlong2/latlong.dart';
import 'package:osm_maps_engine/osm_maps_engine.dart';

class DeliveryScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Live Tracking')),
      body: OsmMapWidget(
        origin: const LatLng(-6.2088, 106.8456), // Example: Jakarta
        destination: const LatLng(-6.2115, 106.8450),
        driverIconWidget: const Icon(Icons.local_shipping, color: Colors.blue, size: 40),
        destinationIconWidget: const Icon(Icons.flag, color: Colors.red, size: 40),
        onLocationUpdated: (position) {
          // Send to your backend (e.g., Firebase) if needed
        },
      ),
    );
  }
}

Core Services Overview

If you need deeper customization, you can directly access the core services:

1. RouteCalculationService: Communicates with the OSRM backend to fetch polyline geometries, distance, and duration.
2. MarkerMotionService: Calculates bearing and interpolates marker movement between location updates.
3. MapCameraService: Controls the flutter_map MapController for centering and bounding.
4. LocationTrackingService: A wrapper around geolocator to handle continuous background/foreground location streaming.

Platform Configuration

Since this package uses geolocator, you must configure your native platforms to allow location access.

iOS (ios/Runner/Info.plist)

Add the following keys to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location for live tracking.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs access to location when in the background.</string>

Android (android/app/src/main/AndroidManifest.xml)

Add the following permissions:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Customizing the Routing Server

By default, the engine uses the public OSRM demo server (router.project-osrm.org). For production applications with heavy traffic, it is highly recommended to host your own OSRM server or use a commercial provider like OpenRouteService or Mapbox.

You can modify the endpoint in lib/src/route_calculation_service.dart.

License

This project is licensed under the MIT License.