Awesome

Xamarin.Forms.SKMaps

Map pins and overlays for Xamarin.Forms.Maps, drawn with SkiaSharp

Xamarin.Forms.SKMaps allows developers an easier integration of custom map features from a shared code base. Built over Xamarin.Forms.Maps and adding the strength of SkiaSharp rendering, you get easy and highly performant map drawing features from a single code base.

Build status

Nuget	iOS	Android

Documentation

Using Xamarin.Forms.SKMaps is as easy as using a regular Xamarin Forms Maps. You can use the map control in Xaml or code, following your preference:

if using Xaml, make sure to include the proper namespace in your root element :

<ContentPage xmlns:skmap="clr-namespace:Xamarin.Forms.SKMaps;assembly=Xamarin.Forms.SKMaps">
  ...
</ContentPage>

Pins

Adding a SKPin could not be easier. It uses the map's regular Pins property that you are used to.

Drawing your pin

The CustomPin class in the above example is the class responsible for rendering the pin marker. To do so, subclass SKPin and override the DrawPin method. You will receive a SKSurface to draw on. This surface will be sized according to its Width, Height and the device's screen density.

public override void DrawPin(SKSurface surface)
{
    SKCanvas canvas = surface.Canvas;

    if (_svgIcon != null)
    {
        SKMatrix fillMatrix = GetFillMatrix(canvas, _svgIcon.Picture.CullRect);

        canvas.DrawPicture(_svgIcon.Picture, ref fillMatrix);
    }
}

Other properties

SKPin provides other properties to modify it's behavior. As it subclasses the Pin class, you also have access to the regular pin properties.

Redrawing the pin

To force the pin to be redrawn, you can call the Invalidate method. Changing the Width or Height will also force a refresh of the pin graphics to accomodate the new size.

Overlays

The SKMapOverlay can be used to add custom "map tile" style overlays. To do so, add your overlays to the SKMap MapOverlaysproperty.

Drawing your overlay

Similar to the SKPin, the SKMapOverlay should be subclassed and the overlay is drawn within an override named DrawOnMap. To ease the drawing calculations, all drawing occurs in GPS coordinates through the SKMapCanvas class and other utility classes like SKMapPath. The SKPaint properties remain in pixels, for instance StrokeWidth.

public override void DrawOnMap(SKMapCanvas canvas, SKMapSpan canvasMapRect, double zoomScale)
{
    if (Route != null && Route.Points.Count() > 1)
    {
        Position firstPoint = Route.Points.FirstOrDefault();
        List<Position> currentRoute = new List<Position>(Route.Points.Skip(1));
        SKMapPath path = canvas.CreateEmptyMapPath();

        path.MoveTo(firstPoint);
        foreach (Position nextPoint in currentRoute)
        {
            path.LineTo(nextPoint);
        }

        using (SKPaint paint = new SKPaint())
        {
            paint.Color = LineColor.ToSKColor();
            paint.StrokeWidth = LineWidth;
            paint.Style = SKPaintStyle.Stroke;
            paint.IsAntialias = true;

            canvas.DrawPath(path, paint);
        }
    }
}

Notes

• You should always consider the canvasMapRect parameter when doing the render calls to avoid drawing outside of the current rendering area. Failure to do so could result in slower performance.
• This method might be called concurently for many tiles, your implementation therefore needs to be thread-safe.
• DrawOnMap will not be called for tiles outside of your overlay's GpsBounds.
• Drawing shapes across the 180th meridian will automatically handle the necessary wrap-around. To cross the 180th meridian, shapes require passing a MapSpan that goes across the 180th meridian, meaning that it would reach longitudes under -180 degrees or above 180 degrees (i.e. A rectangle centered at 179 degrees longitude with a span of 5 degrees).
• In the case of lines, the shortest route between the two provided coordinates is rendered by default. You can opt out and force the long route to be rendered by setting the shortLine parameter to false in the DrawLine calls.

Other properties

SKMapOverlay provides other properties to modify it's behavior.

Redrawing the overlay

To force the overlay to be redrawn, you can call the Invalidate method. Alternatively, changing the GPSBoundsproperty from within the child class will also force a full refresh of the overlay.

Converting coordinates and pixel sizes

Since the SKMapOverlay does all it's drawing operations in pixels but in a GPS coordinate space, you are likely to need to convert from pixel sizes to GPS spans. A common use-case is wanting to draw a line of a given GPS size (i.e. 100 meters wide) regardless of the zoom level and position. Xamarin.Forms.SKMaps provides utility methods to do those conversions. Those methods are available on the SKMapCanvas class.

Sample

The provided sample is abnormally large, it is more than a sample. This is due to the fact that this Nuget started as a Toptal certification project for Xamarin. I meant to use the project as a starting point for the Nuget but as I never had the time to fit the certification within my schedule, I forked the project into the current sample. The idea behind the project was to build a fully cross platform app, meaning I had the objective of doing 100% of the features, including the UI, in shared code. I still have the objective of writing a Toptal blog post on this as it was requested in my previous blog post.

I'm aware this might create a fair bit of confusion as the sample is not straight to the point, given the requirements of the certification on which I built the foundation. However, this is also a great opportunty to see different cross platform techniques in Xamarin Forms. The sample therefore introduces different Forms concepts like markup extensions, using MvvmCross value converters in Forms, Forms effects and behaviors, MvvmCross localization, shared project embedded resources accessed through a resource locator, rendering custom fonts in SkiaSharp, etc.

For those solely interested in the map overlay and pin samples, they can be found here and they are referenced in the ActivityPage.