MarkerDatastoreOverlay class

A Flutter widget overlay that renders markers from a MarkerDatastore on a map.

This overlay provides an efficient way to display large numbers of markers by:

• Automatically managing marker visibility based on zoom level and viewport
• Caching marker queries to minimize datastore requests
• Using intelligent bounding box extension to reduce query frequency
• Integrating with the map's transformation system for smooth rendering

The overlay works by:

1. Listening to map position changes via MapModel.positionStream
2. Calculating the visible screen area as a BoundingBox
3. Extending the bounding box by extendMargin to create a buffer zone
4. Requesting markers from the datastore only when needed
5. Rendering markers using MarkerDatastorePainter with proper transformations

Performance Optimizations

• Zoom Level Caching: Avoids redundant datastore queries at the same zoom level
• Bounding Box Extension: Uses extendMargin to create a buffer, reducing queries during small map movements
• Conditional Updates: Only updates markers when the view moves outside the cached bounding box
• Transform Integration: Leverages TransformWidget for efficient coordinate transformations

Usage Example

// Create a marker datastore
final markerDatastore = DefaultMarkerDatastore();
markerDatastore.addMarker(PoiMarker(
  position: LatLong(52.5200, 13.4050), // Berlin
  displayName: 'Berlin',
));

// Add overlay to map
Stack(
  children: [
    MapsforgeView(mapModel: mapModel),
    MarkerDatastoreOverlay(
      mapModel: mapModel,
      datastore: markerDatastore,
      zoomlevelRange: ZoomlevelRange(5, 18),
      extendMargin: 1.5, // 50% buffer around visible area
    ),
  ],
)

Best Practices

• Use extendMargin values between 1.2-2.0 for optimal performance
• Implement efficient marker filtering in your datastore based on zoom level
• Consider marker clustering for high-density datasets
• Use appropriate ZoomlevelRange to control marker visibility

See also:

• MarkerDatastore for implementing custom marker data sources
• DefaultMarkerDatastore for a ready-to-use marker container
• SingleMarkerOverlay for displaying individual markers