feat(`flet-map`): add image overlay support by ndonkoHenri · Pull Request #6421 · flet-dev/flet

ndonkoHenri · 2026-04-16T12:02:50Z

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 · 2026-04-16T12:03:44Z

Deploying flet-website-v2 with Cloudflare Pages

Latest commit:	`db25575`
Status:	✅ Deploy successful!
Preview URL:	https://ec2168a8.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 · 2026-04-16T12:06:31Z

Deploying flet-examples with Cloudflare Pages

Latest commit:	`db25575`
Status:	✅ Deploy successful!
Preview URL:	https://06d59fa4.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.

Copilot · 2026-04-16T12:12:07Z

+- Layers: [`TileLayer`](tilelayer.md), [`MarkerLayer`](markerlayer.md), [`OverlayImageLayer`](overlayimagelayer.md), [`CircleLayer`](circlelayer.md), [`PolygonLayer`](polygonlayer.md), [`PolylineLayer`](polylinelayer.md)
+- Markers and overlays: [`Marker`](marker.md), [`CircleMarker`](circlemarker.md), [`PolygonMarker`](polygonmarker.md), [`PolylineMarker`](polylinemarker.md), [`OverlayImage`](overlayimage.md), [`RotatedOverlayImage`](rotatedoverlayimage.md)
 - Attributions: [`SimpleAttribution`](simpleattribution.md), [`RichAttribution`](richattribution.md), [`SourceAttribution`](sourceattribution.md)


The "Reference" list formatting looks off: Layers, Markers and overlays, and Attributions are now top-level bullets instead of being nested under the Map entry. This changes the rendered structure and makes it harder to read. Consider nesting these items under the Map bullet (standard nested markdown list indentation) so the reference hierarchy is preserved.

Suggested change

- Layers: [`TileLayer`](tilelayer.md), [`MarkerLayer`](markerlayer.md), [`OverlayImageLayer`](overlayimagelayer.md), [`CircleLayer`](circlelayer.md), [`PolygonLayer`](polygonlayer.md), [`PolylineLayer`](polylinelayer.md)

- Markers and overlays: [`Marker`](marker.md), [`CircleMarker`](circlemarker.md), [`PolygonMarker`](polygonmarker.md), [`PolylineMarker`](polylinemarker.md), [`OverlayImage`](overlayimage.md), [`RotatedOverlayImage`](rotatedoverlayimage.md)

- Attributions: [`SimpleAttribution`](simpleattribution.md), [`RichAttribution`](richattribution.md), [`SourceAttribution`](sourceattribution.md)

- Layers: [`TileLayer`](tilelayer.md), [`MarkerLayer`](markerlayer.md), [`OverlayImageLayer`](overlayimagelayer.md), [`CircleLayer`](circlelayer.md), [`PolygonLayer`](polygonlayer.md), [`PolylineLayer`](polylinelayer.md)

- Markers and overlays: [`Marker`](marker.md), [`CircleMarker`](circlemarker.md), [`PolygonMarker`](polygonmarker.md), [`PolylineMarker`](polylinemarker.md), [`OverlayImage`](overlayimage.md), [`RotatedOverlayImage`](rotatedoverlayimage.md)

- Attributions: [`SimpleAttribution`](simpleattribution.md), [`RichAttribution`](richattribution.md), [`SourceAttribution`](sourceattribution.md)

Copilot · 2026-04-16T12:12:07Z

+@ft.control("BaseOverlayImage", kw_only=True)
+class BaseOverlayImage(ft.BaseControl):
+    """


New controls in this module are declared with kw_only=True, but the other flet_map controls use @ft.control(...) without kw_only. This creates an inconsistent public API (some map controls accept positional args, these do not). Either drop kw_only=True here for consistency, or migrate the rest of the package to keyword-only in a dedicated change so the behavior is uniform.

FeodorFitsner · 2026-04-21T20:50:31Z


 @ft.control("PolygonMarker")
-class PolygonMarker(ft.Control):
+class PolygonMarker(ft.BaseControl):


Changing to BaseControl removes .visible, no?

ndonkoHenri added 6 commits April 15, 2026 16:23

feat(flet-map): add overlay image layer

bb8a3d0

docs(flet-map): add overlay image example

ea944d0

fix(flet-map): align map control inheritance

360923f

fix(flet-map): use validation rule for overlay opacity

3459358

chore: clarify flet validation skill triggers

717d677

update changelog

c4689d1

ndonkoHenri requested review from FeodorFitsner and Copilot April 16, 2026 12:02

ndonkoHenri linked an issue Apr 16, 2026 that may be closed by this pull request

feature: Overlay Image Layer in flet-map #6319

Open

1 task

sourcery-ai Bot reviewed Apr 16, 2026

View reviewed changes

Copilot started reviewing on behalf of ndonkoHenri April 16, 2026 12:04 View session

docs(changelog): update with additional PR reference

db25575

Copilot AI reviewed Apr 16, 2026

View reviewed changes

FeodorFitsner reviewed Apr 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(`flet-map`): add image overlay support#6421

feat(`flet-map`): add image overlay support#6421
ndonkoHenri wants to merge 7 commits intorelease/v0.85.0from
map-overlay-images

ndonkoHenri commented Apr 16, 2026 •

edited by sourcery-ai Bot

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Apr 16, 2026 •

edited

Loading

Uh oh!

sourcery-ai Bot left a comment

Uh oh!

cloudflare-workers-and-pages Bot commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

FeodorFitsner Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

ndonkoHenri commented Apr 16, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Code

Summary by Sourcery

Uh oh!

cloudflare-workers-and-pages Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying flet-website-v2 with Cloudflare Pages

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cloudflare-workers-and-pages Bot commented Apr 16, 2026

Deploying flet-examples with Cloudflare Pages

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

FeodorFitsner Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ndonkoHenri commented Apr 16, 2026 •

edited by sourcery-ai Bot

Loading

cloudflare-workers-and-pages Bot commented Apr 16, 2026 •

edited

Loading