gmaps_vehicle_tracker #

Smooth, road-aware live vehicle tracking (Uber / Rapido style) on Google Maps for Flutter.

You feed it timestamped location samples and, optionally, a route. It turns them into smooth motion that follows the road, with a stable heading, bounded prediction, freshness reporting, optional camera follow, built-in vehicle markers and route styling. Everything is drawn on google_maps_flutter, which this package re-exports.

• Copy-paste examples for every feature: EXAMPLE.md
• Runnable demo app: example/

Screenshots #

Ride selector + live tracking	Fleet on real roads	Close-up (debug: raw GPS dots)	Motion and feed settings	Built-in vehicle gallery

Contents #

1. Setup
2. Quick start
3. Concepts
4. Built-in vehicles
5. API reference
   • VehicleTracker
   • LocationSample
   • TrackingRoute / RouteStop
   • VehicleIcon
   • VehicleType / VehicleArt
   • VehicleSelector (Uber-style picker)
   • TrackingMap
   • TrackingMap.builder / TrackingMapHooks
   • TrackingLayer
   • CameraDirector / CameraFollowConfig
   • TrackingStyle and friends
   • TrackingMapStyles
   • TrackerConfig
   • TrackingStatus, phases, diagnostics
   • Events
   • RenderedVehicleState
   • PlaybackController (history)
   • Simulation
   • Utilities and pure-Dart core
6. How the motion works
7. Rendering and performance
8. Limitations
9. Costs, terms, privacy
10. Adding or replacing built-in art
11. Troubleshooting
12. Development

1. Setup #

dependencies:
  gmaps_vehicle_tracker:
    path: ../gmaps_vehicle_tracker   # or your git/pub source

One import gives you this package and all of google_maps_flutter:

import 'package:gmaps_vehicle_tracker/gmaps_vehicle_tracker.dart';

Google Maps keys. Enable Maps SDK for Android and Maps SDK for iOS in Google Cloud and restrict the key: Android package name + SHA-1, iOS bundle ID.

• Android: add the key to AndroidManifest.xml:

  <meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}"/>
  

  The example injects MAPS_API_KEY from android/local.properties, which is not committed.
• iOS: call GMSServices.provideAPIKey(key) in AppDelegate. The example reads GMSApiKey from Info.plist, which is filled from ios/Flutter/Secrets.xcconfig. The default google_maps_flutter_ios implementation is legacy; consider google_maps_flutter_ios_sdk10 (iOS 16+) or _sdk9 (iOS 15+).
• Android warm-up (optional): call GoogleMapsFlutterAndroid.warmup() early to avoid first-map jank.

2. Quick start #

final route = TrackingRoute.fromEncodedPolyline(encodedPolylineFromBackend);
final tracker = VehicleTracker(route: route, icon: const VehicleIcon.builtIn(VehicleType.car));
tracker.bindStream(myLocationStream); // Stream<LocationSample>

TrackingMap(
  trackers: [tracker],
  camera: CameraDirector(),           // follows north-up by default
  initialCameraPosition: CameraPosition(target: route.start.toLatLng(), zoom: 16),
  mapStyle: TrackingMapStyles.clean,  // less clutter
  padding: const EdgeInsets.only(bottom: 200),
);

// later: tracker.dispose();

3. Concepts #

4. Built-in vehicles #

12 top-down images ship with the package. Each is nose-up, transparent, has a soft rotation-invariant shadow, and comes in 1x–4x densities. Sizes follow real vehicle length, compressed so small vehicles stay visible. Size = whole image including shadow padding, in logical pixels (dp).

Image	VehicleArt	VehicleType	Type default	Marker size (dp)	displayName
	carWhite	car	yes	34 × 64	Cab
	carBlue	car		35 × 64	Cab Premium
	carTaxi	car		35 × 64	Taxi
	carHatchback	car		34 × 64	Mini
	motorcycleBlack	motorcycle	yes (also used for bicycle at 0.85×)	29 × 52	Bike
	motorcycleBlue	motorcycle		28 × 52	Bike Plus
	motorcycleTaxi	motorcycle		28 × 52	Bike Taxi
	busWhite	bus	yes	32 × 92	City Bus
	busBlue	bus		32 × 92	Coach
	busYellow	bus		32 × 92	School Bus
	autoRickshaw	autoRickshaw	yes	33 × 54	Auto
	eRickshaw	eRickshaw (toto)	yes	34 × 56	Toto

Body length (nose to tail): bike 40 dp, auto 42 dp, e-rickshaw 44 dp, car 52 dp, bus 80 dp. VehicleType.bicycle has no art yet and uses motorcycleBlack at 0.85× (≈ 24 × 44 dp).

const VehicleIcon.builtIn(VehicleType.bus);                    // default bus art, bus size
VehicleIcon.art(VehicleArt.carTaxi);                           // specific image
VehicleIcon.builtIn(VehicleType.car, art: VehicleArt.carBlue, scale: 1.2);
VehicleArt.setDefault(VehicleType.car, VehicleArt.carTaxi);    // app-wide default

The example app's Built-in vehicle gallery screen shows every image at its real marker size.

5. API reference #

5.1 VehicleTracker #

One tracked vehicle. You own it: call dispose().

Constructors

Common constructor parameters

Members

5.2 LocationSample #

Validation.

• Rejected: invalid or NaN coordinates, (0, 0) unless allowed, and accuracy worse than maxAccuracy.
• Dropped: duplicates (same sequence, or same time and position) and samples older than what is already shown (late).
• Physically impossible jumps are rejected, unless 3 consecutive samples agree; then the vehicle relocates (snaps).
• Out-of-order samples newer than the shown time are re-ordered.

5.3 TrackingRoute / RouteStop #

Use real road geometry. The vehicle follows the route exactly. A hand-made polyline won't line up with the streets Google draws.

5.4 VehicleIcon #

All variants are rasterized once per (icon, size, pixel ratio) and cached. Rotation is a marker property, so images are never rebuilt per frame.

Getters: resolvedArt, builtInSize, cacheKey, isBuiltIn, isAsset, isBytes, isProvider, isPicture.

Custom art should be top-down with the nose pointing up (or set noseHeadingOffset), have a transparent background, and have any shadow baked in. Live widgets, animated images and shaders are not possible with map markers.

5.5 VehicleType / VehicleArt #

5.5b VehicleSelector / VehicleOption / VehicleIconImage #

An Uber-style picker that shows each vehicle's image and name. It's purely presentational: keep the selection in your state.

VehicleIconImage(VehicleIcon icon, {width, height, rotationDegrees = 0, fit = BoxFit.contain}) renders any vehicle icon as a normal Flutter widget.

5.6 TrackingMap #

A GoogleMap that draws and animates the trackers. It passes through every GoogleMap option. It does not dispose trackers.

5.7 TrackingMap.builder / TrackingMapHooks #

Build the GoogleMap yourself for complete control.

TrackingMap.builder(
  trackers: [...], camera: camera, style: style, padding: padding,
  builder: (context, hooks) => GoogleMap(
    markers: hooks.mergeMarkers(myMarkers), // required
    onMapCreated: hooks.onMapCreated,       // required
    onCameraMove: hooks.onCameraMove,       // required
    ...
  ),
)

5.8 TrackingLayer #

The engine behind TrackingMap. Use it directly only with a completely custom map widget.

5.9 CameraDirector / CameraFollowConfig #

Touching the map switches to free (if interruptOnGesture).

5.10 TrackingStyle and friends #

TrackingStyle({RouteStyle route, StopMarkerStyle stops, VehicleMarkerStyle vehicle}). Presets: TrackingStyle.standard() and TrackingStyle.minimal() (thin line, no casing or completed part).

Polyline styling is limited to what google_maps_flutter exposes: solid colour, width, dash pattern, joints, caps. Gradients and per-segment colours are not available.

5.11 TrackingMapStyles #

Use these with mapStyle: (or GoogleMap.style:). Combine with buildingsEnabled: false.

5.12 TrackerConfig #

Presets:

• TrackerConfig.balanced() (default): visual delay about 0.6–3 s.
• .smooth(): about 1–4 s, softest motion.
• .responsive(): about 0.25–1.5 s, closest to real time, relies more on prediction.

Each takes {VehicleProfile profile}. Change fields with copyWith(...).

MotionConfig

PredictionConfig

MatchingConfig

ValidationConfig

BufferConfig: maxSamples 512, maxAge 10 min (live mode; history keeps all).

VehicleProfile (maxSpeed m/s, maxAcceleration m/s²):

Custom profiles: VehicleProfile(maxSpeed: .., maxAcceleration: ..).

5.13 TrackingStatus, phases, diagnostics #

RejectionReason: invalidCoordinate, nullIsland, lowAccuracy, duplicate, late, implausibleJump.

5.14 Events #

tracker.events emits a sealed TrackingEvent:

5.15 RenderedVehicleState #

position, heading, speed, mode (interpolating / extrapolating / holding), renderTime, progress (m along route), routeGeneration, onRoute, alpha, correcting, snapped, predictionExhausted.

It's a visual estimate only. Don't store it or upload it as the real location.

5.16 PlaybackController (history) #

play(), pause(), seek(Duration), setSpeed(double) (0.25–64×), isPlaying, speed, position, duration, positionSeconds. It's a ChangeNotifier, so you can drive UI with ListenableBuilder.

5.17 Simulation #

SimulationProfile (all optional):

RouteSimulator(RouteIndex, SimulationProfile, {DateTime? startTime}) exposes duration, truthAt(t) (ground truth) and deliveries() (samples with delivery times), for your own tests.

5.18 Utilities and pure-Dart core #

• Geo: GeoPoint, distanceMeters, initialBearing, destinationPoint, shortestAngleDelta, normalizeDegrees, LocalFrame.
• Polyline: PolylineCodec.decode/encode (precision 1–7).
• Route: RouteIndex.build(points) gives length, pointAt(s), smoothedBearing(s), candidates(...), subPath(s0, s1).
• Conversions: GeoPoint.toLatLng() and LatLng.toGeoPoint().
• Icons: MarkerIconFactory.instance (resolve, resolvePng, clear).
• Engine: import 'package:gmaps_vehicle_tracker/core.dart' gives the engine (TrackingEngine) without Flutter or Google Maps, for tests or server-side replays.

6. How the motion works #

1. Validate and align time. Samples are checked, de-duplicated and re-ordered. Device clock skew and network delay are estimated (minimum-delay window) so data age is accurate.
2. Match to route. Candidates near the sample are scored by distance, heading agreement, progress continuity and backward motion, within a window around the previous progress. This handles loops, parallel roads and hairpins. Leaving the route needs confirmation (3 samples and 5 s), after which the vehicle is shown at its true position.
3. Filter. A constant-velocity Kalman filter runs along the route, or in 2-D off route. Stop detection uses reported speed or a regression over recent fixes, so GPS jitter at pickup doesn't move the marker.
4. Render. At now − renderDelay, progress is interpolated with monotone cubic Hermite, so it never reverses or overshoots. Heading is the route tangent with a speed-scaled look-ahead, smoothed with a turn-rate cap.
5. Predict. Past the newest sample, speed decays: up to 8 s / 150 m on route, 3 s / 60 m off route. The vehicle then holds and the phase becomes stale.
6. Correct. New data that disagrees with what is shown is blended out with a speed cap. Very large errors snap with a short fade.

7. Rendering and performance #

• Vehicle motion never rebuilds the GoogleMap widget.
• Android: a small native component creates vehicle markers directly on the plugin's native map and only moves or rotates them. That's one platform message per frame for all vehicles, with no icon re-upload, which avoids the plugin's per-update icon re-decode that causes flicker.
• Other platforms: plugin markers are updated directly through the platform interface.
• Updates are skipped when the movement is under a third of a pixel. Primary vehicles update at up to 60 Hz, adapting down to 30 / 20 Hz if frames get slow; secondary vehicles at 15 Hz.
• Route polylines are sent only when the route changes, plus the completed part at ≤ 2 Hz.
• The ticker sleeps when nothing moves and stops in the background.
• Measured on an Android 16 phone with 8 moving vehicles and camera follow: p50 5 ms, p90 9 ms frame time, 2 % janky frames.

8. Limitations #

• Road shape: the route must come from a router. Without a route, motion between samples is unconstrained.
• Polylines: no gradients or per-segment colours (plugin limitation).
• Markers: no live widgets or animated images; SVG must be rasterized.
• Taps: vehicle tap events aren't available on the Android native path.
• Bicycle art: not bundled yet; the motorcycle image is used at 0.85×.
• iOS: not yet device-verified; it uses the plugin marker path, which may flicker under frequent updates.

9. Costs, terms, privacy #

• No billable calls from the library. Mobile map loads (Maps SDK) are free and unlimited. Routes API calls made by your app are billed: Essentials 10k/month free; traffic-aware routing is Pro; two-wheeler routing is Enterprise.
• Attribution: don't cover the Google logo; use padding.
• Caching: Google's terms limit how long route coordinates may be cached. Fetch routes when needed rather than shipping them.
• Privacy: all data stays in memory in bounded buffers. Nothing is persisted or transmitted. reset() and dispose() clear everything.

10. Adding or replacing built-in art #

Art lives in assets/raw_images/ (sources) and assets/vehicles/ (generated 1x–4x PNGs).

1. Put a top-down source image in assets/raw_images/. Any orientation works. It can have real transparency, a baked-in checkerboard, or a solid black background.
2. Add a line to the table in tool/export_icons/export_all.dart:

   _Art('bicycle_red', '$_raw/My Bicycle.png', 34, 'checkerboard'), // body length dp, background mode
   

3. Run dart run tool/export_icons/export_all.dart (or pass names to export only those). This writes the PNGs and regenerates lib/src/flutter/icons/vehicle_art_sizes.g.dart.
4. Add the enum value in VehicleArt (lib/src/flutter/icons/vehicle_icon.dart), e.g. bicycleRed('bicycle_red', VehicleType.bicycle), and update the type's default if wanted.
5. Run flutter test (test/flutter/vehicle_art_test.dart checks files, sizes and proportions). tool/export_icons/contact_sheet.dart renders a QA sheet.

11. Troubleshooting #

12. Development #

• flutter test: unit tests plus scenario replays (noisy, irregular, delayed, reordered, duplicated and dropped GPS against ground truth, with road-adherence, smoothness, reversing and stop-jitter metrics).
• example/: Live tracking, History replay, Fleet & full map control, Built-in vehicle gallery. Run it with:

  flutter run --dart-define-from-file=secrets.json
  

  secrets.json is {"MAPS_API_KEY": "..."} and is not committed. It enables real road routes from the Routes API; without it the demo uses an approximate offline route.
• tool/: icon exporter, contact sheet, image inspection (dev only; excluded by .pubignore).