mapview

Map

A vector map you can pan, zoom and search, with markers and GPX/GeoJSON tracks. It needs no web view and is sized for phones. It runs on Linux and Android and needs OpenGL ES 3.

import "code.rbel.co/rubiojr/fade/components/mapview"

Use it in a Fade window

package main

import (
    "log"

    "fyne.io/fyne/v2"
    "fyne.io/fyne/v2/app"
    "fyne.io/fyne/v2/container"
    "fyne.io/fyne/v2/layout"

    "code.rbel.co/rubiojr/fade/components/mapview"
    "code.rbel.co/rubiojr/fade/components/mapview/oms"
    "code.rbel.co/rubiojr/fade/components/window"
    "code.rbel.co/rubiojr/fade/style"
)

func main() {
    a := app.NewWithID("com.example.places")
    a.Settings().SetTheme(style.NewTheme())

    server, err := oms.New("https://oms.rbel.co", oms.Options{
        Store: mapview.Keep(a, 256<<20),
    })
    if err != nil {
        log.Fatal(err)
    }
    madrid := mapview.Position{Latitude: 40.4168, Longitude: -3.7038, Zoom: 12}
    m := mapview.New(server, mapview.Options{Start: madrid})

    controls := mapview.NewControls(m)
    controls.SetHome(madrid)
    over := container.NewBorder(nil,
        container.NewHBox(mapview.NewNotice(m), layout.NewSpacer(), controls),
        nil, nil)

    w := window.New(a, "Places")
    w.SetContent(container.NewStack(m, container.New(layout.NewCustomPaddedLayout(12, 48, 12, 12), over)))
    w.SetOnClosed(m.Close)
    w.Resize(fyne.NewSize(420, 800))
    w.ShowAndRun()
}

Drag to pan. Pinch, scroll or double tap to zoom. Tap the map, then use the arrow keys and +/-. A map let go while it moves coasts to rest, and a zoom moves through the levels to its own.

Pinch needs a touch screen and Wayland. The zoom follows the fingers and settles on the nearest quarter level when they lift.

Create, use and close a map on Fyne's UI goroutine. Close it when its window or page goes away: a map holds its memory until then.

examples/mapdemo is a complete application with search, an Add bookmark button and a saved-bookmark list.

Parts

A search box reports what to search for; the search is yours:

box := mapview.NewSearchBox("Search places")
box.OnSearch = func(text string) { go find(text) }
box.OnCleared = hideResults

A panel pads its content by 12 px. Set Padding to zero for content that is a card itself, such as a boxed list of results.

Buttons added to the controls look like the zoom buttons. Give them an icon and no text:

locate := button.NewIcon(icons.Raw("mark-location"), showMe)
controls.Add(locate)

OnMoved and OnStatus report changes. Locate converts latitude and longitude to a position in the widget; CoordinateAt does the reverse.

The map shows its attribution in small print in the bottom right corner. CreditHeight tells how much room it takes, so your controls can stay above it. To show Attribution somewhere else, set Options.NoCredit.

Markers and bookmarks

Use Marker for places, bookmarks or waypoints. Markers follow the map and stay the same size as you zoom. Labels are optional; long labels are shortened.

err := m.SetMarkers(
    mapview.Marker{Latitude: 40.4138, Longitude: -3.6921, Label: "Prado"},
    mapview.Marker{Latitude: 40.4153, Longitude: -3.6844, Label: "Retiro"},
)
if err != nil {
    return err
}
m.OnMarkerTapped = func(index int) { showPlace(index) }

SetMarkers replaces the markers; m.SetMarkers() clears them. The callback receives the marker's index in that order. For overlapping markers, the last marker is on top and is picked first. With no marker callback, taps go to OnTapped.

To drop a marker with a tap:

m.OnTapped = func(at mapview.Coordinate) {
    if err := m.SetMarkers(mapview.Marker{
        Latitude: at.Latitude, Longitude: at.Longitude, Label: "Bookmark",
    }); err != nil {
        showError(err)
    }
}

Keep a slice in your application to accumulate bookmarks, edit them or save them between sessions. Set Marker.Color to override the theme's accent. The default Shape is mapview.Dot. Use Shape: mapview.Pin for a teardrop whose tip points to the coordinate, useful for bookmarks and waypoints.

Your position

SetHere draws where the device is: a dot, in a halo as wide as the accuracy when that is wider than the dot. Feed it from your location source, such as gogps:

for fix := range session.Fixes() {
    fyne.Do(func() {
        m.SetHere(mapview.Here{Latitude: fix.Latitude, Longitude: fix.Longitude, Accuracy: fix.Accuracy})
    })
}

SetFollowing(true) keeps the position in the middle of the map as it moves. Dragging the map or calling MoveTo ends that, zooming doesn't; OnFollowing reports both, for a button that shows the state. ClearHere takes the position off the map.

Tracks and files

Read GPX or GeoJSON from an io.Reader, then apply the returned features:

features, err := mapview.ReadGPX(reader) // or mapview.ReadGeoJSON(reader)
if err != nil {
    return err
}
if err := m.SetFeatures(features); err != nil {
    return err
}

The readers can run in a worker goroutine; apply the result on the UI goroutine with fyne.Do. They leave closing the reader to you. SetFeatures replaces both markers and tracks. It leaves the map's position and zoom alone.

• GPX: waypoints become markers; routes and tracks become tracks. Names and separate track segments are preserved. Elevation, times and extensions are ignored.
• GeoJSON: Point/MultiPoint become markers; LineString/MultiLineString become tracks. Feature, FeatureCollection and GeometryCollection are supported. A string properties.name supplies a label or name. Coordinates use GeoJSON's [longitude, latitude] order; extra ordinates are ignored. Null feature geometries are skipped; unsupported geometries, including polygons, return an error.

You can also supply coordinates directly:

err := m.SetTracks(mapview.Track{
    Name: "Walk",
    Segments: [][]mapview.Coordinate{{
        {Latitude: 40.4138, Longitude: -3.6921},
        {Latitude: 40.4153, Longitude: -3.6844},
    }},
    Width: 4,
})
if err != nil {
    return err
}

SetTracks replaces only tracks; m.SetTracks() clears them. Each segment is a separate line; segments with fewer than two points draw nothing. Set Color to override the accent and Width for a stroke of 0–64 logical units (0 uses 4). Track names are metadata, not map labels. Tracks draw below markers and attribution.

Setters copy their input and reject invalid data without changing the map. The limits are 1,000 markers, 1,000 tracks, 10,000 segments and 100,000 track points; names and labels may contain up to 4,096 bytes. Readers accept files up to 16 MiB; GeoJSON allows 32 nested levels and 10,000 objects. Coordinates must be finite, with latitude in −90…90 and longitude in −180…180; the view clips polar latitudes to Web Mercator's range (about ±85.05°).

Map data

oms.Client reads vector tiles, fonts and place search from an OMS server:

places, err := server.Search(ctx, "gas station", &oms.Near{Latitude: 40.74, Longitude: -4.06}, 6)

Search uses the network. Call it from a goroutine and return to the UI with fyne.Do.

Downloads are kept in a store.Store. mapview.Keep picks a directory in the user's cache for your application. store.OpenDir and store.NewMemory give you the choice, and anything with Get and Put works as a store. Set oms.Options.Offline to use stored data only.

Another tile server works through source.Source: three methods that return OpenMapTiles vector tiles and SDF glyphs. When the server asks to wait, return a source.BusyError with the time it gives: the map stops asking until then and loads the rest on its own.

Devices

A map sizes itself for the device it runs on. Its memory budgets follow the device's memory, and a view too big for them, a 4K screen at scale 1 say, is drawn with coarser tiles. On a phone or tablet the picture has narrower margins, tiles load without previews, and big pictures are antialiased with two samples rather than four, which phone GPUs draw many times slower.

mapview.MemoryLimit() is a soft limit for the whole program that leaves the map room:

debug.SetMemoryLimit(mapview.MemoryLimit())

Requirements

The map is drawn with OpenGL ES 3 and runs on Linux and Android. Building an application with a map needs cgo and the EGL development library (mesa-libEGL-devel on Fedora, libegl-dev on Debian, mesa-dev on Alpine). On Android the NDK has it; build with -tags egl, and a PKG_CONFIG that answers nothing, since the OpenGL bindings ask pkg-config for a library the NDK links anyway.

On a device without a driver for it, the map shows a message in place of its picture and Map.Status() reports mapview.Unavailable.

Limits

• Linux and Android only.
• One style, OpenFreeMap Liberty, in its light colors. It doesn't follow the dark scheme.
• North is up. There is no rotation or tilt.
• Labels in Latin script only.
• No routing or track editing. Supply paths with SetTracks, GPX or GeoJSON.