Proposal: Simplifying the API – Your Feedback Needed

[mikes222]

Dear all,

As you’ve probably noticed, the current API of this Flutter library is not as intuitive as it could be – especially for first-time users. I’ve been considering a significant simplification of the API to make integration and usage much more straightforward and developer-friendly.

However, this would also mean breaking changes, requiring you – as users of the library – to adapt your existing code. Before I move forward with such a change, I’d love to get your feedback:

1. What aspects of the current API do you find confusing, repetitive, or overly complex?

2. Which features or behaviors would you like to see improved or simplified?

3. Would you prefer a more intuitive API even if it means some refactoring, or do you prefer keeping the current version for stability?

4. Would it help to provide migration tools, wrappers, or a transitional release to ease the switch?

Your input is highly valuable and will directly influence the next steps. If you have suggestions, concerns, or examples from your projects – please share them. My goal is to make the library better for everyone, but without breaking things that matter to you.

Looking forward to your feedback and ideas!

[moovida]

Dear @mikes222 , I am probably a bit out of line user, but if I may, I will add my 2 cents.
I would welcome a more intuitive and simple api (even if it breaks the api), but most of all I would love if you could consider the api to be open to use "just" the tile generation, i.e. with different map rendering libs than the one of mapsforge. I for example use flutter_map and have been using this library to produce the tiles, but they are not of the same quality as when using the mapsforge canvas.
So that would be overly cool. But as usual, thanks a ton for this important library.

[moovida]

I am having a hard time creating a useful testcase. My idea would have been to compare two regions of the monaco map and signal tiles that have issues. For that I am checking initially with the old version and looking for the same region:

The problem is that graphics is quite different from a scale point of view. The two images are supposed to be at the same zoomlevel.

I wanted to try to implement a branch using your new branch, but the maprenderer test case seems to be disabled?
I'ld need some hint on how to work now with deviceScaleFactor, since that seems to work differently than before?

[mikes222]

bug fixed.

[moovida]

Ah, nice thanks. It is also navigable now.

I am not able to do so right now, but will try to create asap a testcase for this trimmed label, if that is ok for you:

Also, I am wondering why the line's crossing are overlapped, since they used to be merged. Are you also working on making the rendering code more performant, apart of the big refactoring?

[mikes222]

This issue is solved already

[mikes222]

am having a hard time creating a useful testcase. My idea would have been to compare two regions of the monaco map and signal tiles that have issues. For that I am checking initially with the old version and looking for the same region

@moovida apps/complete_example/test/rendering/datastorerenderer_test does this exactly already.

[mikes222]

btw. I have already started with the refactoring.

• Using melos to split the different parts of the project into smaller distinctive parts.
• mapsfile_converter is now dart and hence does not start a ui anymore
• renaming files to the snake_case.dart naming format
• simplifying the structures
• much more unit-tests
• splitting classes so that they can be used independently from each other

The process can be examined in the branch refactoring_2025. Of course it is currently not production ready.

[mikes222]

Still open:

• transfer a few missing unittests to new codebase
• transfer complex example
• Markers
• Update documentation
• Update pubspec.yaml and describe new structure
• Working with large mapfiles in web browser (is that possible?)
• Make sure disposing of images (symbols, tiles) is working correctly
• Hillshading
• NoPositionView (maybe)
• Testing from an external project and making sure all necessary classes are exposed

[vasilevzhivko]

hey @mikes222 its amazing that you are putting the effort to refactor, my app already has 15k users with 1-2k daily active and its all thanks to your library.
The only error ive been getting from the library is:
Bad state: Cannot add new events after calling close. Error thrown .
happening on ViewModel.rotate (viewmodel.dart:238)

I would be happy to help you test/improve with whatever I can as I rely heavily on your library

[mikes222]

Would be great. Depending on your knowledge I am happy to get more unit tests (=isolating problems to a few lines of code) or finding performance issues or improving ui rendering or ... whatever improves the library.

Only for the refactored code please! I will not do any changes in the old codebase anymore.

[vasilevzhivko]

Would be great. Depending on your knowledge I am happy to get more unit tests (=isolating problems to a few lines of code) or finding performance issues or improving ui rendering or ... whatever improves the library.

Only for the refactored code please! I will not do any changes in the old codebase anymore.

here is an error that i got after merging latest changes:

══╡ EXCEPTION CAUGHT BY RENDERING LIBRARY ╞═════════════════════════════════════════════════════════
The following LateError was thrown during paint():
LateInitializationError: Field 'shapePaint' has not been initialized.

The relevant error-causing widget was:
  CustomPaint
  CustomPaint:file:///Users/zhivkovasilev/Development/flutter/mapsforge_flutter/lib/src/view/mapview_widget.dart:343:22

When the exception was thrown, this was the stack:
#0      PoiMarker.shapePaint (package:mapsforge_flutter/src/marker/poimarker.dart)
#1      PoiMarker.renderBitmap (package:mapsforge_flutter/src/marker/poimarker.dart:129:5)
#2      BasicMarker.render (package:mapsforge_flutter/src/marker/basicmarker.dart:93:5)
#3      BasicPointMarker.render (package:mapsforge_flutter/src/marker/basicmarker.dart:60:11)
#4      PoiMarker.render (package:mapsforge_flutter/src/marker/poimarker.dart:104:11)
#5      MarkerPainter.paint.<anonymous closure> (package:mapsforge_flutter/src/marker/markerpainter.dart:44:17)
#6      List.forEach (dart:core-patch/growable_array.dart:425:8)
#7      MarkerPainter.paint (package:mapsforge_flutter/src/marker/markerpainter.dart:43:15)
#8      RenderCustomPaint._paintWithPainter (package:flutter/src/rendering/custom_paint.dart:593:13)
#9      RenderCustomPaint.paint (package:flutter/src/rendering/custom_paint.dart:646:7)
#10     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3423:7)
#11     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#12     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#13     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3423:7)
#14     PaintingContext._repaintCompositedChild (package:flutter/src/rendering/object.dart:176:11)
#15     PaintingContext.repaintCompositedChild (package:flutter/src/rendering/object.dart:121:5)
#16     PipelineOwner.flushPaint (package:flutter/src/rendering/object.dart:1309:31)
#17     PipelineOwner.flushPaint (package:flutter/src/rendering/object.dart:1319:15)
#18     RendererBinding.drawFrame (package:flutter/src/rendering/binding.dart:631:23)
#19     WidgetsBinding.drawFrame (package:flutter/src/widgets/binding.dart:1261:13)
#20     RendererBinding._handlePersistentFrameCallback (package:flutter/src/rendering/binding.dart:495:5)
#21     SchedulerBinding._invokeFrameCallback (package:flutter/src/scheduler/binding.dart:1434:15)
#22     SchedulerBinding.handleDrawFrame (package:flutter/src/scheduler/binding.dart:1347:9)
#23     SchedulerBinding._handleDrawFrame (package:flutter/src/scheduler/binding.dart:1200:5)
#27     _invoke (dart:ui/hooks.dart:332:10)
#28     PlatformDispatcher._drawFrame (dart:ui/platform_dispatcher.dart:444:5)
#29     _drawFrame (dart:ui/hooks.dart:302:31)
(elided 3 frames from dart:async)

The following RenderObject was being processed when the exception was fired: RenderCustomPaint#4c451 relayoutBoundary=up16:
  creator: CustomPaint ← RepaintBoundary ← Stack ← Transform ← Transform ← Transform ← Transform ←
    Transform ← ClipRect ← TransformWidget ← StreamBuilder<MapViewPosition> ← _TileWidget ← ⋯
  parentData: <none> (can use size)
  constraints: BoxConstraints(0.0<=w<=440.0, 0.0<=h<=742.0)
  size: Size(440.0, 742.0)
  painter: null
  foregroundPainter: MarkerPainter#7b35f(Instance of 'MarkerByItemDataStore')
This RenderObject had the following child:
    child: RenderConstrainedBox#3ef4e relayoutBoundary=up17
════════════════════════════════════════════════════════════════════════════════════════════════════

[mikes222]

This is the old codebase. Sorry, I do not have the resources to support the old codebase anymore since the new one will be ready soon.

Markers are not yet done and will take 1-2 more days.

Please examine the branch refactoring_2025 for the new codebase.

[vasilevzhivko]

okay i will wait for you to finish then i will adapt the changes to my codebase and will let you know if i find something! thanks!

[mikes222]

Current open issues as far as I am aware of:

• scaling with 2 fingers not fully tested, not fully correct, but in principle working
• Water background in monaco.map. I want to check how to solve it
• Disposing of images not yet verified, possible memory leak
• Hillshading not yet tested ( I doubt it will work)
• Testing from external application not yet done, anyone willing to try it out with his/her own application?
• Tiles are not always fully updated, sometimes you need to move the map a bit to force update
• 2 more caches to implement/verify (renderinstructions and indoornotationMatcher)

Overall I want to know from you if you are willing to support me:

• how you like the new structure?
• any ideas how to improve/simplify the api?
• What is unclear?
• any problems integrating the new source into your applications?
• How can I make your (digital) life easier?
• If you find problems not mentioned above please create issues for them so that I can tackle them bit by bit before I merge the code to main (end of next week maybe)

Your support is appreciated!

[vasilevzhivko]

hi @mikes222 , one more issue that i just thought of

when rotating the map, some of the symbols are staying in the initial position, but rotated as well and thats the result
if you can check it out that would be great, if not i will try to spend some time on it once you release the new version

[mikes222]

I have no clue. Try disabling the LabelView and see if any labeling remains. Or try disabling TileView and see what is rendered in the tiles and what is renderes as labels.

[mikes222]

Current open issues as far as I am aware of:

• scaling with 2 fingers not fully tested, not fully correct, but in principle working
• Water background in monaco.map. See doc/known_issues.md, I will update the monaco.map later on.
• Tiles are not always fully updated, sometimes you need to move the map a bit to force update
• Drag'n'drop of markers not yet implemented.

See doc/install.md on how to implement the library in your own project.

[mikes222]

It is PolylineMarker now for open path's. For closed path it is AreaMarker. I did the rework already for my project. Can you drop a few notes what has changed from your point of view so that I can provide a more concise changelog documentation? Would be nice. Also please provide all ideas to improve the quality/naming/usage of this library.

[vasilevzhivko]

hey @mikes222, one question, since we no longer have viewmodel, im using Bloc, and have this:

      _mapTapSub = _viewModel!.observeTap.listen((tapEvent) {
        add(MapTapReceived(tapEvent));
      });

What should I use with the new design?

I have 1k+ errors to resolve so I will need some time to adapt everything, but when i see something i will give you feedback

[mikes222]

MapModel.tapStream

[vasilevzhivko]

one thing i am noticing which is a bit odd is - before we had viewmodel.setmapviewposition and you pass lat and lng, now we have mapModel.setPosition with MapPosition. Can we make the zoom optional when passing MapPosition? if its not passed just keep the current zoom

[mikes222]

use MapModel.moveTo() or MapModel.setCenter()

[mikes222]

The library is almost complete. I want to update the documentation in the next days and then I will merge the code back to main and plan to publish to pub.dev by end of next week. There is still time for all of you to give me hints what can be improved, renamed, changed.

[moovida]

Hi @mikes222 , sorry for the late reply, I tried to put together a testcase, as discussed earlier.
Basically I wanted to target 2 coordinates that in the old library result into missing labels:

Having identified lat/lon: 43.73954/7.42238 as such a place, I tried to duplicate one of the testcases to generate that 9 tiles image and have a look at it:

Future<void> mergeFlatTilesAndSave(WidgetTester tester, {required List<dynamic> tiles, int cols = 3}) async {
    final int tileW = tiles.first.width;
    final int tileH = tiles.first.height;
    final int rows = (tiles.length + cols - 1) ~/ cols;
    final recorder = ui.PictureRecorder();
    final canvas = ui.Canvas(recorder);

    for (int i = 0; i < tiles.length; i++) {
      final ui.Image img = tiles[i];
      final int r = i ~/ cols;
      final int c = i % cols;
      canvas.drawImage(img, Offset(c * tileW.toDouble(), r * tileH.toDouble()), ui.Paint());
    }

    final int outW = cols * tileW;
    final int outH = rows * tileH;
    final ui.Image merged = await recorder.endRecording().toImage(outW, outH);

    final byteData = await merged.toByteData(format: ui.ImageByteFormat.png);
    if (byteData == null) throw StateError('Failed to encode PNG');
    final bytes = byteData.buffer.asUint8List();

    final file = File('./merged.png');
    await tester.runAsync(() async {
      await file.writeAsBytes(bytes);
    });
  }


testWidgets('Check labels test', (WidgetTester tester) async {
    int l = 0;
    int zoomlevel = 21;
    int x = MercatorProjection.fromZoomlevel(zoomlevel).longitudeToTileX(7.42238); // lat/lon: 43.73954/7.42238;
    int y = MercatorProjection.fromZoomlevel(zoomlevel).latitudeToTileY(43.73954);

    tester.binding.window.physicalSizeTestValue = Size(MapsforgeSettingsMgr().tileSize * 9, MapsforgeSettingsMgr().tileSize * 9);
    // resets the screen to its orinal size after the test end
    addTearDown(tester.binding.window.clearPhysicalSizeTestValue);

    List<Tile> tilesToLoad = [
      Tile(x - 1, y - 1, zoomlevel, l),
      Tile(x, y - 1, zoomlevel, l),
      Tile(x + 1, y - 1, zoomlevel, l),
      Tile(x - 1, y, zoomlevel, l),
      Tile(x, y, zoomlevel, l),
      Tile(x + 1, y, zoomlevel, l),
      Tile(x - 1, y + 1, zoomlevel, l),
      Tile(x, y + 1, zoomlevel, l),
      Tile(x + 1, y + 1, zoomlevel, l),
    ];

    List<dynamic>? imgs = await (tester.runAsync(() async {
      String renderthemeString = await rootBundle.loadString("assets/render_theme/defaultrender.xml");
      Rendertheme renderTheme = RenderThemeBuilder.createFromString(renderthemeString.toString());

      Datastore mapFile = await Mapfile.createFromFile(filename: 'test/rendering/monaco.map', preferredLanguage: null);

      Renderer dataStoreRenderer = DatastoreRenderer(mapFile, renderTheme, true);
      List imgs = [];
      for (Tile tile in tilesToLoad) {
        print("Calculating tile ${tile.toString()}");
        JobRequest mapGeneratorJob = JobRequest(tile);
        JobResult jobResult = await (dataStoreRenderer.executeJob(mapGeneratorJob));
        expect(jobResult.picture, isNotNull);
        imgs.add(await jobResult.picture!.convertPictureToImage());
      }

      return imgs;
    }));

    assert(imgs != null && imgs.length == tilesToLoad.length);

    await mergeFlatTilesAndSave(tester, tiles: imgs!, cols: 3);
  });

The result is this:

which to my surprise has no labels at all.
Any idea what I might be doing wrong?

[mikes222]

I hope that your testcase works and provides the same glitches to the labels. Then I can tackle down the issue and solve it.

[moovida]

I tried to change this to false but for some reason the labels are not rendered anyways.
Btw, the doc seems to suggest the inverse: /// [renderLabels] Whether to render labels onto tile images

It seems to have taken the boolean properly, but no labels rendered anyways. Sicne they do work in the example app, whcih also uses "false", I am wondering what is different in the testcase.

[mikes222]

let me check this tonight. Also @vasilevzhivko please be patient. I have to examine it more throroughly.

[vasilevzhivko]

No worries @mikes222 i have the stable version running 🙂 my project could be a good benchmark since its quite big

[mikes222]

Parameters of datastorerenderer now changed to make the meaning clearer. I have also added your test to the testsuite, can now reproduce the missing text but it is too late today to tackle the problem.

I will also create a documentation how to create unit tests and how to work with golden in the next days.

[vasilevzhivko]

hey @mikes222 im still not able to get the new library running..
here:

Future<SymbolImage> _createSymbol(String src, int width, int height) async {
    // we need to hash with the width/height included as the same symbol could be required
    // in a different size and must be cached with a size-specific hash
    var session = PerformanceProfiler().startSession(
      category: "FileSymbolCache.createSymbol",
    );
    Uint8List? byteData = await _loadResource(src);
    if (byteData == null) throw SymbolNotFoundException(src);
    if (src.toLowerCase().endsWith(".svg")) {
      SymbolImage result = await imageBuilder.createSvgSymbol(
        byteData,
        width,
        height,
      );
      session.complete();
      return result;
    } else if (src.toLowerCase().endsWith(".png")) {
      SymbolImage result = await imageBuilder.createPngSymbol(
        byteData,
        width,
        height,
      );
      session.complete();
      return result;
    } else {
      throw Exception("Unknown resource fileformat $src");
    }
  }

i get an exception thrown that it cannot find an SVG file, but the SVG file is there 100% and its defined in pubspec.yaml.. what could be causing that?

[mikes222]

1. The assertion occurs when we try to render a text. Seems the y-coordinate is less than 0 which should not happen at this zoomlevel, no clue what causes it. Send me the mapfile, the renderfile and the coordinates and I will try to reproduce and fix it.

2. I see a white (non-processed) tile in your map and assume that the lag is because of this tile, the system tries to reproduce it for each movement.

3. The disappearing marker towards the border of the view should be solved with the next commit.

btw. Hillshading is already supported, the example works.

[vasilevzhivko]

hi @mikes222,
the map can be found here
the render file is here
The map is about 1GB so it might be a good benchmark.
I am using IsolateMapfile

note: you have to set your location to somewhere in Bulgaria the validation error was happening somewhere around here: 42.578619, 23.238831

EDIT 2: the hillshading looks quite nice!

[mikes222]

Your problem is solved now.

[vasilevzhivko]

amazing @mikes222 , if you have a buymeacoffee account or any other way to contribute to the project (besides PRs :D) please let me know

[mikes222]

wow, so kind! Thanks! I will consider it.

[mikes222]

Finally! I have now merged the code from refactoring_2025 to master. From now on all changes will be done in master again. Please do not forget to switch your projects.
A few more updates and afterwards I will publish the projects to pub.dev with version 4.0.0

[mikes222]

Mapsforge is now live with version 4.0.0 on pub.dev!

[vasilevzhivko]

@mikes222 any update on the sync between marker / map

[mikes222]

Not yet but I have an idea which I must first validate.