feat(flet-map): add image overlay support

[ndonkoHenri]

Fix #6319

Test Code

import flet as ft
import flet_map as ftm

base64_image = "iVBORw0KGgoAAAANSUhEUgAAABkAAAAgCAYAAADnnNMGAAAACXBIWXMAAAORAAADkQFnq8zdAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAA6dJREFUSImllltoHFUYx3/fzOzm0lt23ZrQ1AQbtBehNpvQohgkBYVo410RwQctNE3Sh0IfiiBoIAjqi6TYrKnFy4O3oiiRavDJFi3mXomIBmOxNZe63ay52GR3Zj4f2sTEzmx3m//TYf7/c35zvgPnO6KqrESXqpq3muocAikv6m+/zytj3ejik1VN21G31YA9CgJ6xC+bMyQZPVCuarciPAMYC99V6Vw5pLbFSibHmlVoRVj9P3cmPBM8tSJI/M6mzabpfoAQ9fIF7WK4bd5vvuFnLGgy2vi0abg94A0AcJGvMq3hDxGRyar9r4F+iLAm0yIiRk8m37tctS1WsrIhhrI30+Srmg+J87OXUf3lWGS1q89dC6ltsSanxk4Aj2QBABii96300g87P/rtlrWr8l+vyDMfdlXSyyEikqxsiOUAQJCBhfHdXRfCq1LSsSlcWG+KBAGStvvrMkgiuv8lUc2mREukPwLUfHG+uTQv8Eown7VL3XlbBxYhf1c17hbVF3MDwA9bts280TnaU1YYqPby07aeFlUlHt27wSQ4CLo+F8AvoTCvHmyKF+ZbEb/M77P2LgvAwmrTHAHflN3KZxVbMC2jMFNOpgPnrMSOhvvFkMezXdwV4ePbtvHtxnJAMQ0j4JtVnO+eLb5oiSlt5HDbv7t1O90lpYCCCKbhfzW5kAIwUAazR0BlfII8Ow0I6uoVmI9MyAMwbMs8CExmDbk4zgu931MyO4OI4KrYflkRjOoTI+uM9d1vjotwKPu9QMk/sxzuO8POiVFcdZ1M2YBVsMEAKOqLvaPIe7mACuw0z/80SMH58SMplxlfiDhVi7dw2pltRhjKBQTQdrSja2KKTfE551NHuaZ0QVPvWYQUn31/Vm2nDvgjF4grVJx6suSvrvrSJ/6cSW2Oz9mf264uNrB806xZ1k/CZ49dUKgDEtlCROX2hfHpx8pGuuo3PpqYulw8fjndOp1yhgtNKRevJ1FyR2Ola+jXAjdnwTkZ6o896GdWdxDw7IxFg+0DpmXchTKSBWQnIuJn9u4j7dt+13UfHXEkXQOcuQ4kMhVtqsgUyPiQiPQfHw1NB2sRjmXKuTg1NwwBYLhtPtQX26eqTwGXPDOqvmcC4Hnwfrrad94GrVsOYTqUTkQY+iTlNe/6O1miSP/x0VB/+wMIDwHn/vtV1iQC4Xv95uUEWVCoL9Y5Z+gdovoyMHUFJHv88jmVy0vTuw7cZNv2YaA61Bfb7ZX5F8SaUv2xwZevAAAAAElFTkSuQmCC"  # noqa: E501


def main(page: ft.Page):
    page.add(
        ft.SafeArea(
            expand=True,
            content=ftm.Map(
                expand=True,
                initial_center=ftm.MapLatitudeLongitude(51.5, -0.09),
                initial_zoom=6,
                layers=[
                    ftm.TileLayer(
                        url_template="https://tile.memomaps.de/tilegen/{z}/{x}/{y}.png"
                    ),
                    ftm.OverlayImageLayer(
                        overlay_images=[
                            ftm.OverlayImage(
                                src=base64_image,
                                bounds=ftm.MapLatitudeLongitudeBounds(
                                    corner_1=ftm.MapLatitudeLongitude(51.5, -0.09),
                                    corner_2=ftm.MapLatitudeLongitude(48.8566, 2.3522),
                                ),
                                opacity=0.8,
                            ),
                            ftm.RotatedOverlayImage(
                                src=base64_image,
                                top_left_corner=ftm.MapLatitudeLongitude(
                                    53.377, -2.999
                                ),
                                bottom_left_corner=ftm.MapLatitudeLongitude(
                                    52.503, -1.868
                                ),
                                bottom_right_corner=ftm.MapLatitudeLongitude(
                                    53.475, 0.275
                                ),
                                opacity=0.8,
                            ),
                        ]
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Summary by Sourcery

Add map image overlay support and refactor map control parsing/utilities while wrapping more layers in BaseControl for consistency.

New Features:

• Introduce OverlayImageLayer, OverlayImage, RotatedOverlayImage, and BaseOverlayImage controls to render rectangular and rotated image overlays on maps.
• Expose new overlay-related controls from the flet-map Python package and register the OverlayImageLayer Flutter control with the extension system.
• Add a new overlay images gallery/example demonstrating usage of the new map overlay controls.

Enhancements:

• Refactor map option parsing into reusable Control extension helpers for coordinates, bounds, interaction options, camera fit, stroke patterns, tile display, keyboard options, and WMS tile options.
• Wrap circle, marker, polygon, polyline, and attribution layers in BaseControl for more consistent behavior and lifecycle management.
• Add a Control extension for attribution alignment parsing and use it in rich attribution controls.
• Update CircleMarker, Marker, PolygonMarker, and PolylineMarker Python controls to inherit from BaseControl instead of Control.

Documentation:

• Document overlay image map functionality with new pages for OverlayImageLayer, OverlayImage, RotatedOverlayImage, and BaseOverlayImage, and link them from the map docs and sidebar navigation.
• Extend map documentation with an Overlay Images section and reference entries for new overlay controls.

Chores:

• Update the flet-map changelog with version 0.85.0 and the new image overlay feature entry.
• Clarify the internal flet-validation skill description regarding when to use validation tooling.

[cloudflare-workers-and-pages]

Deploying flet-website-v2 with    Cloudflare Pages

Latest commit:	2a794af
Status:	✅  Deploy successful!
Preview URL:	https://d9767946.flet-website-v2.pages.dev
Branch Preview URL:	https://map-overlay-images.flet-website-v2.pages.dev

View logs

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[cloudflare-workers-and-pages]

Deploying flet-examples with    Cloudflare Pages

Latest commit:	2a794af
Status:	✅  Deploy successful!
Preview URL:	https://8bc90a47.flet-examples.pages.dev
Branch Preview URL:	https://map-overlay-images.flet-examples.pages.dev

View logs

[Copilot]

Pull request overview

Adds image overlay capabilities to flet-map, enabling both axis-aligned and rotated image overlays on top of flutter_map.

Changes:

• Introduces OverlayImageLayer with OverlayImage and RotatedOverlayImage controls (Python + Flutter/Dart).
• Refactors several Flutter-side parsers to Control extension helpers and wraps more layer widgets with BaseControl.
• Adds documentation pages, sidebar entries, and a runnable Python example for overlay images.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
website/sidebars.yml	Adds new Map docs entries for overlay image layer + overlay types.
website/sidebars.js	Adds the same overlay docs to the JS sidebar structure.
website/docs/controls/map/rotatedoverlayimage.md	New API doc page for RotatedOverlayImage.
website/docs/controls/map/overlayimagelayer.md	New API doc page for OverlayImageLayer.
website/docs/controls/map/overlayimage.md	New API doc page for OverlayImage.
website/docs/controls/map/index.md	Adds overlay-images example section and updates reference links.
website/docs/controls/map/baseoverlayimage.md	New API doc page for BaseOverlayImage.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/utils/map.dart	Refactors map parsing via new Control extension helpers.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/utils/attribution_alignment.dart	Adds Control extension getter for AttributionAlignment.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/tile_layer.dart	Uses new parsing extension helpers for tile layer configuration.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/simple_attribution.dart	Wraps attribution widget in BaseControl.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/rich_attribution.dart	Wraps widget in BaseControl and uses new alignment getter.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/polyline_layer.dart	Uses new parsing extension helpers and wraps in BaseControl.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/polygon_layer.dart	Uses new parsing extension helpers and wraps in BaseControl.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/overlay_image_layer.dart	New Flutter implementation mapping controls to flutter_map overlay image types.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/marker_layer.dart	Uses new parsing helper and wraps in BaseControl.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/extension.dart	Registers OverlayImageLayer control with the extension factory.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/circle_layer.dart	Uses new parsing helper and wraps in BaseControl.
sdk/python/packages/flet-map/src/flet_map/polyline_layer.py	Makes PolylineMarker a ft.BaseControl.
sdk/python/packages/flet-map/src/flet_map/polygon_layer.py	Makes PolygonMarker a ft.BaseControl.
sdk/python/packages/flet-map/src/flet_map/overlay_image_layer.py	Adds Python API for overlay images + layer.
sdk/python/packages/flet-map/src/flet_map/marker_layer.py	Makes Marker a ft.BaseControl.
sdk/python/packages/flet-map/src/flet_map/map_layer.py	Documents OverlayImageLayer as a supported layer type.
sdk/python/packages/flet-map/src/flet_map/circle_layer.py	Makes CircleMarker a ft.BaseControl.
sdk/python/packages/flet-map/src/flet_map/init.py	Re-exports overlay-image classes and updates __all__.
sdk/python/packages/flet-map/CHANGELOG.md	Adds release note entry for overlay image support.
sdk/python/examples/controls/map/overlay_images/pyproject.toml	New example project metadata for overlay images gallery entry.
sdk/python/examples/controls/map/overlay_images/main.py	New runnable example demonstrating overlay images.
client/pubspec.lock	Updates locked Dart dependencies (incl. flet path package version).
.agents/skills/flet-validation/SKILL.md	Updates internal skill description text.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.