GroundOverlay class

Ground overlay to be drawn on the map.

A ground overlay is an image that is fixed to a map. Unlike markers, ground overlays are oriented against the Earth's surface rather than the screen, so rotating, tilting, or zooming the map will change the orientation of the image. Ground overlays are useful for fixing a single image at one area on the map. For adding extensive imagery that covers a large portion of the map, a TileOverlay should be considered.

Because the overlay is automatically scaled to fit either a specified bounds or a position (combined with width, height, and zoomLevel), the image.bitmapScaling must be set to MapBitmapScaling.none.

Sizing and positioning can be defined in the following ways:

• Using bounds for exact corners in LatLngBounds. Recommended for precise placement.
• Using position with width and height in meters. If height is omitted, the image aspect ratio is preserved.
• Using position with zoomLevel to scale the image according to a chosen zoom level.

The anchor parameter defines the anchor’s relative location within the overlay. For example, an anchor of (0.5, 0.5) corresponds to the image’s center. When position is used, the overlay shifts so that this anchor aligns with the given position. When bounds is used, the anchor specifies the internal anchor position inside the bounds. If bearing is set, the image rotates around this anchor.

Platform behavior for sizing can vary, and not all sizing or positioning options may be supported equally across all platforms. Combining both width and zoomLevel can help achieve the desired effect across platforms. Using bounds is the most reliable way to position a ground overlay precisely.

Use either GroundOverlay.fromBounds or GroundOverlay.fromPosition to create a ground overlay.

Example of GroundOverlay.fromBounds method:

GroundOverlay.bounds(
  groundOverlayId: const GroundOverlayId('overlay_id'),
  image: await AssetMapBitmap.create(
    createLocalImageConfiguration(context),
    'assets/images/ground_overlay.png',
    bitmapScaling: MapBitmapScaling.none,
  ),
  bounds: LatLngBounds(
    southwest: LatLng(37.42, -122.08),
    northeast: LatLng(37.43, -122.09),
  ),
);

Example of GroundOverlay.fromPosition method:

GroundOverlay.position(
  groundOverlayId: const GroundOverlayId('overlay_id'),
  image: await AssetMapBitmap.create(
    createLocalImageConfiguration(context),
    'assets/images/ground_overlay.png',
    bitmapScaling: MapBitmapScaling.none,
  ),
  position: LatLng(37.42, -122.08),
  width: 100,
  height: 100,
  zoomLevel: 14,
);

Implemented types

• MapsObject<GroundOverlay>

Annotations

• @immutable

Constructors

GroundOverlay.fromBounds({required GroundOverlayId groundOverlayId, required MapBitmap image, required LatLngBounds bounds, Offset anchor = const Offset(0.5, 0.5), double bearing = 0.0, double transparency = 0.0, int zIndex = 0, bool visible = true, bool clickable = true, VoidCallback? onTap})

Creates a GroundOverlay fitted to the specified bounds with the provided image.

factory

GroundOverlay.fromPosition({required GroundOverlayId groundOverlayId, required MapBitmap image, required LatLng position, double? width, double? height, Offset anchor = const Offset(0.5, 0.5), double bearing = 0.0, double transparency = 0.0, int zIndex = 0, bool visible = true, bool clickable = true, VoidCallback? onTap, double? zoomLevel})

Creates a GroundOverlay to given position with the given image.

factory

Properties

anchor → Offset?

The anchor in normalized coordinates specifying the anchor point of the overlay.

final

bearing → double

The amount that the image should be rotated in a clockwise direction.

final

bounds → LatLngBounds?

Bounds which will contain the image.

final

clickable → bool

Controls if click events are handled for this ground overlay.

final

groundOverlayId → GroundOverlayId

Uniquely identifies a GroundOverlay.

final

hashCode → int

The hash code for this object.

no setter, override

height → double?

Height of the ground overlay in meters.

final

image → MapBitmap

A description of the bitmap used to draw the ground overlay.

final

mapsId → GroundOverlayId

A identifier for this object.

no setter, override

onTap → VoidCallback?

Callbacks to receive tap events for ground overlay placed on this map.

final

position → LatLng?

Geographical location to which the anchor will be fixed.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

transparency → double

The transparency of the ground overlay.

final

visible → bool

Whether the ground overlay is visible (true) or hidden (false).

final

width → double?

Width of the ground overlay in meters.

final

zIndex → int

The ground overlay's zIndex.

final

zoomLevel → double?

The map zoom level used when setting a ground overlay with a position.

final

Methods

clone() → GroundOverlay

Returns a duplicate of this object.

override

copyWith({double? bearingParam, double? transparencyParam, int? zIndexParam, bool? visibleParam, bool? clickableParam, VoidCallback? onTapParam}) → GroundOverlay

Creates a new GroundOverlay object whose values are the same as this instance, unless overwritten by the specified parameters.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toJson() → Object

Converts this object to something serializable in JSON.

override

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

override