[FEATURE] Provide an easy to use annotations API

[josxha]

Feature Description

We should provide an easy to use API for annotations to be added, red, updated or deleted.

Consider if this API should be imperative like in flutter-maplibre-gl or declarative like suggested in maplibre/flutter-maplibre-gl#292.

Describe alternatives you've considered

It is already possible to create annotations by creating a GeoJSON, add it as a source to the map style and then display the annotations via a SymbolLayer, LineLayer and FillLayer.

Additional context

• [FEATURE] Improvement suggestion for map annotations. maplibre/flutter-maplibre-gl#436
• MapLibre annotation plugin for android

[gabbopalma]

I think the declarative method is the best way to do this in Flutter. The flutter-maplibre-gl imperative method is too mechanical for Flutter's problems and requires a lot of extra and less readable code.
The declarative method is faster to code, but is probably less optimized and performance may be lower.
In any case, I would choose the declarative way to draw and handle GeoJSON sources.

[albertmoravec]

Just to add my 2 cents, while declarative API is nice to use, it might not always be the best one for some cases. Especially for applications where map provides real-time updates. Maybe this is a bit out of scope since this annotations API is supposed to be higher level, while lower level could still be available, but I'll just add it here for consideration.

Not speaking about annotations specifically, but one of the reasons why I had to switch from Google Maps to MapLibre was the fact that each map object change (even appending a single point to a line) would require serialization of the whole object before it is sent to native via method channel. This serialization would become a bottleneck, taking up to seconds for larger objects to serialize.

I would be really happy if there would be and API with support more advanced use-cases as well as simpler ones where declarative API definitely works better. Sorry if I went astray from the goal of this issue report 😅

For reference: maplibre/flutter-maplibre-gl#366

[josxha]

Maybe this is a bit out of scope since this annotations API is supposed to be higher level, while lower level could still be available, but I'll just add it here for consideration.

I would be really happy if there would be and API with support more advanced use-cases as well as simpler ones where declarative API definitely works better

Yes, the plan for this feature is to provide an easy to use high level API. It will be still possible to use sources and layers directly for better performance.

Not speaking about annotations specifically, but one of the reasons why I had to switch from Google Maps to MapLibre was the fact that each map object change (even appending a single point to a line) would require serialization of the whole object before it is sent to native via method channel. This serialization would become a bottleneck, taking up to seconds for larger objects to serialize.

I can understand that this could become a bottleneck. There are already some workarounds possible like splitting the features up into multiple sources but keeping users in mind that work with lots and lots of data is a good point. It could be that the jnigen/ffigen could improve the performance. There is a feature request #52 and an ongoing pull request #53 for it.

For reference: maplibre/flutter-maplibre-gl#366

An easy improvement for JSON serialization could be to provide an additional parameter if the heavy work should be done in an Insolate. The user probably knows best when to offload it and when only a small JSON needs serialization.