SVG as symbol source

[lepigocher]

I would love to be able to use SVG images as a symbol source. Moreover, if we had the possibility to colorize via the class names of objects, that would be perfect!

[wipfli]

Thanks for this suggestion. I think it would be best to open an issue in MapLibre GL JS and Native if there is not already one for this issue.

[lepigocher]

@louwers For now I use only Maplibre GL JS but this suggestion is valid for all libraries (JS or natives).

[ovivoda]

@lepigocher how do you envision this on native?

[lepigocher]

@ovivoda Can't tell you because I have not yet used the native libraries. In short it should works the same as with the JS library. For now, we can specify an image inside a symbol layer using the icon-image attribute. This image can come from the sprite file or from an image file added with the AddImage method.

My suggestion is to support the SVG file format as a valid format for icon-image attribute. To be able to use other icon-* attributes, this file format have to be managed as an SVG not as a bitmap file. In a SVG file you can specify the default rendering size and colors (to name a few). This should work the same as with a bitmap file, to avoid creation of many other attributes but we don't have to support all icon-* attributes because some of them do not make sens. As a sample, icon-halo-* attributes do not have to be supported (or could come later).
All modern browsers 'know' how to render an SVG inside a <img .../> tag so it should not to be a lot of work for the JS library. But the natives libraries do not have such internal features. So it will be probably required to use an already existing library from another project, may be ThorVG could be a good candidate (https://github.com/thorvg/thorvg)?

[louwers]

@HarelM Not that I am aware of. The feature may be cross-concern but the implementation details are not and should be discussed in the respective repos IMO.

[HarelM]

Agreed, but we need to decide collectively of this is something we want to support. That's all.

[rbrundritt]

I built this capability for a couple of map controls in the past. This eventually made it into Azure Maps which uses MapLibre under the hood. Happy to make a pull request for this, but want to outline how I think this should work and see if that aligns with your expectations:

The map control has the addImage method today. We could try and extend this, but to achieve this the SVG needs to be loaded asynchronously. So it might make sense to create a new method called addImageAsync of createFromTemplate which returns a promise. Adding such a function could have two purposes; support loading SVGs into the image sprite, and support loading images via a URL (jpg/png/bmp/gif/svg). An SVG can be converted to a data URI which can then be loaded using the javascript Image class, then the image can be added to the maps sprite.

With this in mind there are two methods we could use to add SVGs to the map:

Method 1: Add an SVG that already has style defined (colors):

With this method we could add the SVG to the image sprite and the user could use it as a static image. There would be a couple of constraints on the image that we would document, such as the SVG must have a viewBox defined. We could also allow width/height options to be passed into the add method in case the SVG being loaded doesn't have a width/height set on the root. The conversion

Method 2: Add an SVG Template framework

This would be more of an extension of method 1 and would provide an easy way to load an SVG template into a class that can set a primary and secondary color, and scale the SVG. Setting color and scale would be optional. For example, an SVG template might look like this:

'<svg xmlns="http://www.w3.org/2000/svg" width="calc(27 * {scale})" height="calc(39 * {scale})" viewBox="-1 -1 26 38"><path d="M12.25.25a12.254 12.254 0 0 0-12 12.494c0 6.444 6.488 12.109 11.059 22.564.549 1.256 1.333 1.256 1.882 0C17.762 24.853 24.25 19.186 24.25 12.744A12.254 12.254 0 0 0 12.25.25Z" style="fill:{color};stroke:{secondaryColor};stroke-width:1"/><text x="12.5" y="17.5" style="font-size:14px;fill:#fff;text-anchor:middle">{text}</text></svg>'

Notice the placeholders for scale and colors. The text placeholder is there to allow the template to also be reusable with HTML Markers.

With this framework, you could load a single template into framework, then loop through all the color combinations you want and generate and add the images to the maps image sprite quickly. You can also make use of the maps styleimagemissing event to dynamically load images on demand. A neat idea for that is to define a pattern for image template ID's like "[template name]-[primary hex color]-[secondary hex color]", then in the event handler a new image can be created using the color details. Using data driven styles you could create the ID string by concatenating strings, thus allowing for a more data driven approach that loads the images on demand.

In Azure Maps the methods for loading templates is in the root namespace and includes methods to add, get a single template, and get all templates. The map control then has a method to create and add an image from a template as documented here: https://learn.microsoft.com/en-us/javascript/api/azure-maps-control/atlas.imagespritemanager?view=azure-maps-typescript-latest#azure-maps-control-atlas-imagespritemanager-createfromtemplate

In Azure Maps we also preloaded a couple dozen templates to save developers time. Here are some samples:

• https://samples.azuremaps.com/?search=icon&sample=all-built-in-icon-templates-as-symbols (This one generates 42 images from templates in a few milliseconds)
• Here an HTML marker version of the above sample: https://samples.azuremaps.com/?search=icon&sample=all-built-in-icon-templates-as-html-markers
• https://samples.azuremaps.com/?search=icon&sample=icon-template-options
• https://samples.azuremaps.com/?search=icon&sample=add-custom-icon-template-to-atlas-namespace
• https://samples.azuremaps.com/?search=icon&sample=line-layer-with-built-in-icon-template
• https://samples.azuremaps.com/?search=icon&sample=fill-polygon-with-built-in-icon-template

With the methods I mentioned above there are some key constraints to know:

• The SVG's are converted to static images in browser DOM and not on the WebGL side of things. Trying to parse the SVG XML and convert it into something WebGL can draw on a canvas would require a ton of code, would be error prone, likely wouldn't support a big chunk of SVG or CSS features, and would likely be slower than the above solution since it would need to draw the complex geometry of the SVG rather than a single static image.
• I don't believe CSS classes would work here.
• The maps sprite sheet has a maximum size, so there are only so many SVGs that could be added before you run out of space. But this would depend on the static size of the SVG image that is specified to the added to the map. This would also depend on how many images are in the sprite sheet already from the map style. Here is a simple test app that loads different amounts of random points, each using a different SVG template and color combination. Note that this loads all the images/templates as part of the page load, which is the slowest way to do this. Loading the images as needed as the pins come into view is likely to be much faster (progressive loading). https://rbrundritt.azurewebsites.net/Demos/AzureMaps/SvgSymbolTest.html For me, loading 25 images took 225 ms, 100 took about 1 second, 500 took 5.5 seconds.

Does the above approach align with the functionality you are looking to achieve?

[rbrundritt]

Another nice thing about this approach is that a similar approach may also work for the native SDK.

[HarelM]

I would consider two approaches here:

1. Create a plugin that adds this functionality to maplibre-gl-js without needing to change anything in this library, this would be a very straightforward solution and can be improve over time.
2. Consider suggesting a style spec change to facilitate this.

I think the first approach is the best one to try things out, see how much code it involves, how many users this have, and later on decide if this should be part of the core.

I just finished a technical steering committee yesterday where the main argument was that adding more feature to this library (which is not tree shakeable) is problematic and should be well thought of. So a plugin, with an example in the examples pages would be a good middle ground I believe.

[rbrundritt]

I agree with breaking this out as a plugin/module. A growing code base of new features isn't great for those who have all they need with it already.

I'll have to think through the style spec potential here as WebGL side processing of SVG may cause more headaches than its worth. However, something as simple as passing an inline SVG string as the icon id and using the image missing event would likely make things a bit closer. Or, we could allow an object with settings to be passed returned by an expression, similar to https://maplibre.org/maplibre-style-spec/types/#formatted and then as part of the preprocessing/parsing step of the expression, this could be extracted.

[lepigocher]

Hi @rbrundritt ,

First, thanks for your interesting suggestions and share of your knowledge on this subject. As @HarelM explain, because we can't have tree shaking this could be more simple to make a plugin.

In this case, we could use the StyleImageInterface but for now maplibre DO NOT transmit a context while calling the render method, so this is not really usefull until we get at the minimum this context (image name, current layer, current feature, ...). To be usefull an SVG should be rendered at differents sizes and color depending on zoom (this is already possible because we have a map instance) and the layer requesting this image. If we got this we could make something similar to the existing layer style and properties to change color and size of an SVG image.

The async nature of the request should not be a problem because sprites and images have to be loaded and added to the map before any other source and style to be able to render those images. So we could preload all images before adding them to the map.

Of course, we could create something really basic and create an instance of a class for each image but this will not cover the more usefull use cases. In my current use case of maplibre, I can have ~100 images and they can have a different color or size depending of a metadata property of the current layer or depending of an expression using a property of the current feature. Such use case could require a lot of class instance to cover all possible cases. Having 'just' the possibility of loading an SVG in not an option for me because we can already do it by code as explained in my previous comment (here). That's why IMHO this should be part of maplibre and benefit of all the style an expression system.

[rbrundritt]

Agree on the plugin approach, was just talking out loud on ideas on how style spec integration might work, but would avoid that currently. If I get some time over the next month or two, I'll try and put a plugin together.

[rbrundritt]

I've created an initial proof of concept plugin that provides a manager or adding SVG images to the map sprite, and also provides a framework for templated SVG images. You can check it out here: https://github.com/rbrundritt/maplibre-gl-svg Have a look and see if this meets your needs. I haven't published an NPM package yet as I want to get feedback first and lock in the initial version.

[HarelM]

This looks nice! Thanks! Note that in maplibre v4 we have moved from callbacks to promises, so this might break if you upgrade once v4 is released, just FYI.

[rbrundritt]

Yes. I added a note in the source code on what will likely need to be updated. Once v4 is officially released I'll circle back and see if I can make the code handle both the old and new methods.

[rbrundritt]

Also, why I haven't hipped an npm package for this library yet.

[abdelhameedhamdy]

@rbrundritt Wondering, could the SVG plugin be adopted/integrated in maplibre-react-native ?

[cboone]

The @nationalparkservice / @jmcandrew-nps (/ others?) recently released an SVG plugin for Maplibre GL JS: https://github.com/nationalparkservice/npmap5-plugins/tree/main/svg-icons

It looks pretty promising, and supports CSS styling.

[rbrundritt]

I have seen that project before, it appears that it is parsing CSS and trying to styling it which could be error prone across browsers. It looks like animations are supported in that library when rendering is a custom webgl layer, not sure if it supports animations when rendered in a symbol layer. I guess technically CSS classes and animations would be supported in the library I provided when rendered as a HTML marker, but I'm sure that wouldn't support as large of a dataset as a custom webgl layer solution. Comparing the source code, I believe the approach I provided would have slightly better performance for the creation of an image for use with symbol layers, but you only do that once per SVG when your app loads typically, so not that big of a deal. Based on the samples of each project, the implementation of the library I provided requires less code and is a bit simpler to follow, especially if you use one of the built in templates. That said, both approaches have their merits. The solution I provided is one that I know is well tested, Bing Maps and Azure Maps have been using it for over a decade to support rendering SVG's in the HTML canvas.

In any case, no harm in having different solutions. I see there is a bounty for an SVG solution. If I was awarded it, my plan was to just donate it back, mainly since I've been meaning to submit this solution well before the bounty program existed (since the Mapbox fork), but just haven't had time.

[cboone]

That makes sense, thanks for explaining. I'll give your plugin a try, I'd definitely like to avoid the SVG to PNG translation dance.