Mapview

kivy_garden.mapview

class mapview.Coordinate(lon, lat)

Named tuple that represent a geographic coordinate with latitude/longitude

Parameters
  • lon (float) – Longitude

  • lat (float) – Latitude

class mapview.MapSource(url, cache_key, min_zoom, max_zoom, tile_size, image_ext, attribution, subdomains)

Class that represent a map source. All the transformations from X/Y/Z to longitude, latitude, zoom, and limitations of the providers goes are stored here.

Parameters
  • url (str) – Tile’s url of the providers. Defaults to http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

  • cache_key (str) – Key for storing the tiles. Must be unique and not colliding with another providers, otherwise tiles will not be downloaded again. Defaults to “osm”

  • min_zoom (int) – Minimum zoom value acceptable for this provider. Defaults to 0.

  • max_zoom (int) – Maximum zoom value acceptable for this provider. Defaults to 19.

  • tile_size (int) – Size of a image tile returned by the provider. Defaults to 256.

  • attribution (str) – Attribution for this provider. Defaults to empty string

  • subdomains (str) – Domains substitutions for the {s} in the url. Defaults to “abc”

get_x(zoom, lon)

Get the x position to the longitude in the map source’s projection

Parameters
  • zoom (int) – Zoom level to look at

  • lon (float) – Longitude

Returns

X position

Return type

float

get_y(zoom, lat)

Get the y position to the latitude in the map source’s projection

Parameters
  • zoom (int) – Zoom level to look at

  • lat (float) – Latitude

Returns

Y position

Return type

float

get_lon(zoom, x)

Get the longitude to the x position in the map source’s projection

Parameters
  • zoom (int) – Zoom level to look at

  • x (float) – X position in the map

Returns

Longitude

Return type

float

get_lat(zoom, y)

Get the latitude to the y position in the map source’s projection

Parameters
  • zoom (int) – Zoom level to look at

  • y (float) – Y position in the map

Returns

Latitude

Return type

float

get_col_count(zoom)

Return the number of column for this provider at this zoom level.

Parameters

zoom (int) – Zoom level to look at

Returns

Number of column

Return type

int

get_row_count(zoom)

Return the number of row for this provider at this zoom level.

Parameters

zoom (int) – Zoom level to look at

Returns

Number of rows

Return type

int

get_max_zoom()

Return the maximum zoom of this source

Returns

Maximum zoom

Return type

int

get_min_zoom()

Return the minimum zoom of this source

Returns

Minimum zoom

Return type

int

class mapview.MapMarker

A marker on the map, that must be used on a MapMarker, or with MapView.add_marker() or with MapView.add_widget()

Events

on_press: Fired when the MapMarker is pressed on_release: Fired when the MapMarker is release

anchor_x

Anchor of the Marker on the X axis. Defaults to 0.5, means the anchor will be at the X center of the image

anchor_y

Anchor of the marker on the Y axis. Defaults to 0, means the anchor will be at the Y bottom of the image

lat

Latitude of the marker

lon

Longitude of the marker

source

Image source of the marker, defaults to marker.png within the mapview package.

class mapview.MapView

MapView is a widget that control the map displaying, navigation and layers management.

Available events

on_map_relocated: called everytime the MapView change location

lon

Longitude at the center of the widget, read-only.

lat

Latitude at the center of the widget, read-only.

zoom

Zoom of the MapView. Must be between MapSource.get_min_zoom() and MapSource.get_max_zoom(). Default to 0

map_source

Provider of the map, default to an empty MapSource

double_tap_zoom

If True, this will activate the double-tap to zoom.

Defaults to False.

pause_on_action

Pause on any loading / tiles loading when an action is done. This allow better performance on mobile, but can be safely deactivated on desktop.

Defaults to True.

scale

Current scale of the internal scatter, read-only. This is usually not used in user-side unless you’re hacking mapview.

snap_to_zoom

When the user initiate a zoom, it will snap to the closest zoom for better graphics. The map can be blur if the map is scaled between 2 zoom.

Defaults to True, even if it doesn’t fully working yet.

add_layer(layer)

Add a new layer to update at the same time than the base tile layer

Parameters

layer (MapLayer) – Map layer to add

add_marker(marker, layer=None)

Add a marker into a layer. If layer is None, it will be added in the default marker layer. If there is no default marker layer, a new one will be automatically created.

Parameters
center_on(lat, lon)

Center the map on the coordinate (lat, lon)

Parameters
  • lat (float) – Latitude

  • lon (float) – Longitude

get_bbox(margin=0)

Returns the bounding box from the bottom-left to the top-right.

Parameters

margin (float) – Optionnal margin to extend the Bbox bounds

Returns

Bounding box

Return type

Bbox

get_latlon_at(x, y, zoom=None):

Return the current coordinate (lat, lon) at the (x, y) widget coordinate

Parameters
  • x (float) – X widget coordinate

  • y (float) – Y widget coordinate

Returns

lat/lon Coordinate

Return type

Coordinate

remove_layer(layer)

Remove a previously added MapLayer

Parameters

layer (MapLayer) – A map layer

remove_marker(marker)

Remove a previously added MarkerMap

Parameters

marker (MarkerMap) – The marker

set_zoom_at(zoom, x, y, scale=None)

Sets the zoom level, leaving the (x, y) at the exact same point in the view.

Parameters
  • zoom (float) – New zoom

  • x (float) – X coordinate to zoom at

  • y (float) – Y coordinate to zoom at

  • scale (float) – (internal) Scale to set on the scatter

unload()

Unload the view and all the layers. It also cancel all the remaining downloads. The map should not be used after this.

class mapview.MapLayer

A map layer. It is repositioned everytime the MapView is moved.

reposition()

Function called when the MapView is moved. You must recalculate the position of your children, and handle the visibility.

unload()

Called when the view want to completely unload the layer.

class mapview.MarkerMapLayer(MapLayer)

A map layer specialized for handling MapMarker.

class mapview.mbtsource.MBTilesMapSource(MapSource)

Use a Mbtiles as a source for a MapView

class mapview.geojson.GeoJsonMapLayer(MapLayer)

A Geojson MapLayer.

Experimental, only Polygon and LineString feature are supported. Marker are not yet implemented, due to lack of API for wiring Marker selection back to you.

source

A Geojson filename to load, defaults to None.

geojson

A dictionary structured as a Geojson. This attribute contain the content of a source if passed.

class mapview.clustered_marker_layer.ClusteredMarkerLayer(MapLayer)

Experimental Layout that implement marker clustering. It implement its own version of Super Cluster, based itself on a KD-tree.

Aka you can load like 2000 markers without issues. The cluster index is immutable, so if you add a new marker, it will be rebuild from scratch.

Please note that the widget creation is done on the fly by the layer, not by you.

DONT use add_widget, use add_marker()

Example:

layer = ClusteredMarkerLayer()
for i in range(2000):
    lon = random() * 360 - 180
    lat = random() * 180 - 90
    layer.add_marker(lon=lon, lat=lat, cls=MapMarker)

# then you can add the layer to your mapview
mapview = MapView()
mapview.add_widget(layer)
cluster_cls

Reference to the class widget for creating a cluster widget. Defaults to ClusterMapMarker

cluster_min_zoom

Minimum zoom level at which clusters are generated. Defaults to 0

cluster_max_zoom

Maximum zoom level at which clusters are generated. Defaults to 16

cluster_radius

Cluster radius, in pixels. Defaults to 40dp

cluster_extent

Tile extent. Radius is calculated relative to this value. Defaults to 512.

cluster_node_size

Size of the KD-tree leaf node. Affects performance. Defaults to 64.

add_marker(lon, lat, cls=MapMarker, options=None)

Method to add a marker to the layer.

Parameters
  • lon (float) – Longitude

  • lat (float) – Latitude

  • cls (object) – Widget class to use for creating this marker. Defaults to MapMarker

  • options (dict) – Options to pass to the widget at instanciation. Defaults to an empty dict.

Returns

The instance of a Marker (internal class, not the widget)

Method to call for building the cluster. It is done automatically at the first rendering. If you missed it, or need to rebuild after readding marker, just call this function.

class mapview.clustered_marker_layer.ClusterMapMarker(MapMarker)

Widget created for displaying a Cluster.

cluster

Reference to the Cluster used for this widget

num_points

Number of marker that the cluster contain.

text_color

Color used for the text, defaults to [.1, .1, .1, 1]. If you want others options, best is to do your own cluster widget including the label you want (font, size, etc) and customizing the background color.