Mapview

`kivy_garden.mapview`

MapView

MapView is a Kivy widget that display maps.

class kivy_garden.mapview.Bbox(iterable=(), /)

Bases: tuple

collide(*args)

class kivy_garden.mapview.Coordinate(lat, lon)

Bases: tuple

lat: Alias for field number 0

lon: Alias for field number 1

class kivy_garden.mapview.MapLayer(**kwargs)

Bases: kivy.uix.widget.Widget

A map layer, that is repositionned everytime the MapView is moved.

reposition(): Function called when MapView is moved. You must recalculate the position of your children.

unload(): Called when the view want to completly unload the layer.

viewport_x

NumericProperty(defaultvalue=0, **kw) Property that represents a numeric value.

It only accepts the int or float numeric data type or a string that can be converted to a number as shown below. For other numeric types use ObjectProperty or use errorhandler to convert it to an int/float.

It does not support numpy numbers so they must be manually converted to int/float. E.g. widget.num = np.arange(4)[0] will raise an exception. Numpy arrays are not supported at all, even by ObjectProperty because their comparision does not return a bool. But if you must use a Kivy property, use a ObjectProperty with comparator set to np.array_equal. E.g.:
>>> class A(EventDispatcher):
...     data = ObjectProperty(comparator=np.array_equal)
>>> a = A()
>>> a.bind(data=print)
>>> a.data = np.arange(2)
<__main__.A object at 0x000001C839B50208> [0 1]
>>> a.data = np.arange(3)
<__main__.A object at 0x000001C839B50208> [0 1 2]
Parameters

defaultvalue: int or float, defaults to 0
Specifies the default value of the property.
>>> wid = Widget()
>>> wid.x = 42
>>> print(wid.x)
42
>>> wid.x = "plop"
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "properties.pyx", line 93, in kivy.properties.Property.__set__
   File "properties.pyx", line 111, in kivy.properties.Property.set
   File "properties.pyx", line 159, in kivy.properties.NumericProperty.check
 ValueError: NumericProperty accept only int/float
Changed in version 1.4.1: NumericProperty can now accept custom text and tuple value to indicate a type, like “in”, “pt”, “px”, “cm”, “mm”, in the format: ‘10pt’ or (10, ‘pt’).

viewport_y

NumericProperty(defaultvalue=0, **kw) Property that represents a numeric value.

It only accepts the int or float numeric data type or a string that can be converted to a number as shown below. For other numeric types use ObjectProperty or use errorhandler to convert it to an int/float.

It does not support numpy numbers so they must be manually converted to int/float. E.g. widget.num = np.arange(4)[0] will raise an exception. Numpy arrays are not supported at all, even by ObjectProperty because their comparision does not return a bool. But if you must use a Kivy property, use a ObjectProperty with comparator set to np.array_equal. E.g.:
>>> class A(EventDispatcher):
...     data = ObjectProperty(comparator=np.array_equal)
>>> a = A()
>>> a.bind(data=print)
>>> a.data = np.arange(2)
<__main__.A object at 0x000001C839B50208> [0 1]
>>> a.data = np.arange(3)
<__main__.A object at 0x000001C839B50208> [0 1 2]
Parameters

defaultvalue: int or float, defaults to 0
Specifies the default value of the property.
>>> wid = Widget()
>>> wid.x = 42
>>> print(wid.x)
42
>>> wid.x = "plop"
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "properties.pyx", line 93, in kivy.properties.Property.__set__
   File "properties.pyx", line 111, in kivy.properties.Property.set
   File "properties.pyx", line 159, in kivy.properties.NumericProperty.check
 ValueError: NumericProperty accept only int/float
Changed in version 1.4.1: NumericProperty can now accept custom text and tuple value to indicate a type, like “in”, “pt”, “px”, “cm”, “mm”, in the format: ‘10pt’ or (10, ‘pt’).

class kivy_garden.mapview.MapMarker(**kwargs)

Bases: kivy.uix.behaviors.button.ButtonBehavior, kivy.uix.image.Image

A marker on a map, that must be used on a MapMarker

anchor_x: Anchor of the marker on the X axis. Defaults to 0.5, mean the anchor will be at the X center of the image.

anchor_y: Anchor of the marker on the Y axis. Defaults to 0, mean the anchor will be at the Y bottom of the image.

detach()

lat: Latitude of the marker

lon: Longitude of the marker

source: Source of the marker, defaults to our own marker.png

class kivy_garden.mapview.MapMarkerPopup(**kwargs)

Bases: kivy_garden.mapview.view.MapMarker

add_widget(widget)

Add a new widget as a child of this widget.

Parameters

widget: Widget
Widget to add to our list of children.

index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

is_open

BooleanProperty(defaultvalue=True, **kw) Property that represents only a boolean value.

Parameters

defaultvalue: boolean
Specifies the default value of the property.

on_is_open(*args)

on_release(*args)

placeholder

ObjectProperty(defaultvalue=None, rebind=False, **kw) Property that represents a Python object.

Parameters

defaultvalue: object type
Specifies the default value of the property.

rebind: bool, defaults to False
Whether kv rules using this object as an intermediate attribute in a kv rule, will update the bound property when this object changes.

That is the standard behavior is that if there’s a kv rule text: self.a.b.c.d, where a, b, and c are properties with rebind False and d is a StringProperty. Then when the rule is applied, text becomes bound only to d. If a, b, or c change, text still remains bound to d. Furthermore, if any of them were None when the rule was initially evaluated, e.g. b was None; then text is bound to b and will not become bound to d even when b is changed to not be None.

By setting rebind to True, however, the rule will be re-evaluated and all the properties rebound when that intermediate property changes. E.g. in the example above, whenever b changes or becomes not None if it was None before, text is evaluated again and becomes rebound to d. The overall result is that text is now bound to all the properties among a, b, or c that have rebind set to True.

**kwargs: a list of keyword arguments

baseclass
If kwargs includes a baseclass argument, this value will be used for validation: isinstance(value, kwargs[‘baseclass’]).

Warning

To mark the property as changed, you must reassign a new python object.

Changed in version 1.9.0: rebind has been introduced.

Changed in version 1.7.0: baseclass parameter added.

popup_size

ListProperty(defaultvalue=0, **kw) Property that represents a list.

Parameters

defaultvalue: list, defaults to []
Specifies the default value of the property.
Warning

When assigning a list to a ListProperty, the list stored in the property is a shallow copy of the list and not the original list. This can be demonstrated with the following example:
>>> class MyWidget(Widget):
>>>     my_list = ListProperty([])

>>> widget = MyWidget()
>>> my_list = [1, 5, {'hi': 'hello'}]
>>> widget.my_list = my_list
>>> print(my_list is widget.my_list)
False
>>> my_list.append(10)
>>> print(my_list, widget.my_list)
[1, 5, {'hi': 'hello'}, 10] [1, 5, {'hi': 'hello'}]
However, changes to nested levels will affect the property as well, since the property uses a shallow copy of my_list.
>>> my_list[2]['hi'] = 'bye'
>>> print(my_list, widget.my_list)
[1, 5, {'hi': 'bye'}, 10] [1, 5, {'hi': 'bye'}]

refresh_open_status()

remove_widget(widget)

Remove a widget from the children of this widget.

Parameters

widget: Widget
Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

class kivy_garden.mapview.MapSource(url='http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', cache_key=None, min_zoom=0, max_zoom=19, tile_size=256, image_ext='png', attribution='© OpenStreetMap contributors', subdomains='abc', **kwargs)

Bases: object

Base class for implementing a map source / provider

attribution_osm = 'Maps & Data © [i][ref=http://www.osm.org/copyright]OpenStreetMap contributors[/ref][/i]'

attribution_thunderforest = 'Maps © [i][ref=http://www.thunderforest.com]Thunderforest[/ref][/i], Data © [i][ref=http://www.osm.org/copyright]OpenStreetMap contributors[/ref][/i]'

fill_tile(tile): Add this tile to load within the downloader

static from_provider(key, **kwargs)

get_col_count(zoom): Get the number of tiles in a col at this zoom level

get_lat(zoom, y): Get the latitude to the y position in the map source’s projection

get_lon(zoom, x): Get the longitude to the x position in the map source’s projection

get_max_zoom(): Return the maximum zoom of this source

get_min_zoom(): Return the minimum zoom of this source

get_row_count(zoom): Get the number of tiles in a row at this zoom level

get_x(zoom, lon): Get the x position on the map using this map source’s projection (0, 0) is located at the top left.

get_y(zoom, lat): Get the y position on the map using this map source’s projection (0, 0) is located at the top left.

providers = {'cyclemap': (0, 0, 17, 'http://{s}.tile.opencyclemap.org/cycle/{z}/{x}/{y}.png', 'Tiles @ Andy Allan'), 'osm': (0, 0, 19, 'http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', 'Maps & Data © [i][ref=http://www.osm.org/copyright]OpenStreetMap contributors[/ref][/i]'), 'osm-de': (0, 0, 18, 'http://{s}.tile.openstreetmap.de/tiles/osmde/{z}/{x}/{y}.png', 'Tiles @ OSM DE'), 'osm-fr': (0, 0, 20, 'http://{s}.tile.openstreetmap.fr/osmfr/{z}/{x}/{y}.png', 'Tiles @ OSM France'), 'osm-hot': (0, 0, 19, 'http://{s}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png', ''), 'thunderforest-cycle': (0, 0, 19, 'http://{s}.tile.thunderforest.com/cycle/{z}/{x}/{y}.png', 'Maps © [i][ref=http://www.thunderforest.com]Thunderforest[/ref][/i], Data © [i][ref=http://www.osm.org/copyright]OpenStreetMap contributors[/ref][/i]'), 'thunderforest-landscape': (0, 0, 19, 'http://{s}.tile.thunderforest.com/landscape/{z}/{x}/{y}.png', 'Maps © [i][ref=http://www.thunderforest.com]Thunderforest[/ref][/i], Data © [i][ref=http://www.osm.org/copyright]OpenStreetMap contributors[/ref][/i]'), 'thunderforest-outdoors': (0, 0, 19, 'http://{s}.tile.thunderforest.com/outdoors/{z}/{x}/{y}.png', 'Maps © [i][ref=http://www.thunderforest.com]Thunderforest[/ref][/i], Data © [i][ref=http://www.osm.org/copyright]OpenStreetMap contributors[/ref][/i]'), 'thunderforest-transport': (0, 0, 19, 'http://{s}.tile.thunderforest.com/transport/{z}/{x}/{y}.png', 'Maps © [i][ref=http://www.thunderforest.com]Thunderforest[/ref][/i], Data © [i][ref=http://www.osm.org/copyright]OpenStreetMap contributors[/ref][/i]')}

class kivy_garden.mapview.MapView(**kwargs)

Bases: kivy.uix.widget.Widget

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

add_layer(layer, mode='window'): Add a new layer to update at the same time the base tile layer. mode can be either “scatter” or “window”. If “scatter”, it means the layer will be within the scatter transformation. It’s perfect if you want to display path / shape, but not for text. If “window”, it will have no transformation. You need to position the widget yourself: think as Z-sprite / billboard. Defaults to “window”.

add_marker(marker, layer=None): Add a marker into the 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

add_widget(widget)

Add a new widget as a child of this widget.

Parameters

widget: Widget
Widget to add to our list of children.

index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

animated_diff_scale_at(d, x, y)

animation_duration: Duration to animate Tiles alpha from 0 to 1 when it’s ready to show. Default to 100 as 100ms. Use 0 to deactivate.

background_color

ListProperty(defaultvalue=0, **kw) Property that represents a list.

Parameters

defaultvalue: list, defaults to []
Specifies the default value of the property.
Warning

When assigning a list to a ListProperty, the list stored in the property is a shallow copy of the list and not the original list. This can be demonstrated with the following example:
>>> class MyWidget(Widget):
>>>     my_list = ListProperty([])

>>> widget = MyWidget()
>>> my_list = [1, 5, {'hi': 'hello'}]
>>> widget.my_list = my_list
>>> print(my_list is widget.my_list)
False
>>> my_list.append(10)
>>> print(my_list, widget.my_list)
[1, 5, {'hi': 'hello'}, 10] [1, 5, {'hi': 'hello'}]
However, changes to nested levels will affect the property as well, since the property uses a shallow copy of my_list.
>>> my_list[2]['hi'] = 'bye'
>>> print(my_list, widget.my_list)
[1, 5, {'hi': 'bye'}, 10] [1, 5, {'hi': 'bye'}]

bbox

AliasProperty(getter, setter=None, rebind=False, watch_before_use=True, **kwargs) Create a property with a custom getter and setter.

If you don’t find a Property class that fits to your needs, you can make your own by creating custom Python getter and setter methods.

Example from kivy/uix/widget.py where x and width are instances of NumericProperty:
def get_right(self):
    return self.x + self.width
def set_right(self, value):
    self.x = value - self.width
right = AliasProperty(get_right, set_right, bind=['x', 'width'])
If x were a non Kivy property then you have to return True from setter to dispatch new value of right:
def set_right(self, value):
    self.x = value - self.width
    return True
Usually bind list should contain all Kivy properties used in getter method. If you return True it will cause a dispatch which one should do when the property value has changed, but keep in mind that the property could already have dispatched the changed value if a kivy property the alias property is bound was set in the setter, causing a second dispatch if the setter returns True.

If you want to cache the value returned by getter then pass cache=True. This way getter will only be called if new value is set or one of the binded properties changes. In both cases new value of alias property will be cached again.

To make property readonly pass None as setter. This way AttributeError will be raised on every set attempt:
right = AliasProperty(get_right, None, bind=['x', 'width'], cache=True)
Parameters

getter: function
Function to use as a property getter.

setter: function
Function to use as a property setter. Callbacks bound to the alias property won’t be called when the property is set (e.g. right = 10), unless the setter returns True.

bind: list/tuple
Properties to observe for changes as property name strings. Changing values of this properties will dispatch value of the alias property.

cache: boolean
If True, the value will be cached until one of the binded elements changes or if setter returns True.

rebind: bool, defaults to False
See ObjectProperty for details.

watch_before_use: bool, defaults to True
Whether the bind properties are tracked (bound) before this property is used in any way.

By default, the getter is called if the bind properties update or if the property value (unless cached) is read. As an optimization to speed up widget creation, when watch_before_use is False, we only track the bound properties once this property is used in any way (i.e. it is bound, it was set/read, etc).

The property value read/set/bound will be correct as expected in both cases. The difference is only that when False, any side effects from the getter would not occur until this property is interacted with in any way because the getter won’t be called early.

Changed in version 1.9.0: rebind has been introduced.

Changed in version 1.4.0: Parameter cache added.

bbox_for_zoom(vx, vy, w, h, zoom)

cache_dir

StringProperty(defaultvalue=u’’, **kw) Property that represents a string value.

Parameters

defaultvalue: string, defaults to ‘’
Specifies the default value of the property.

center_on(*args): Center the map on the coordinate Coordinate, or a (lat, lon)

delta_x

NumericProperty(defaultvalue=0, **kw) Property that represents a numeric value.

It only accepts the int or float numeric data type or a string that can be converted to a number as shown below. For other numeric types use ObjectProperty or use errorhandler to convert it to an int/float.

It does not support numpy numbers so they must be manually converted to int/float. E.g. widget.num = np.arange(4)[0] will raise an exception. Numpy arrays are not supported at all, even by ObjectProperty because their comparision does not return a bool. But if you must use a Kivy property, use a ObjectProperty with comparator set to np.array_equal. E.g.:
>>> class A(EventDispatcher):
...     data = ObjectProperty(comparator=np.array_equal)
>>> a = A()
>>> a.bind(data=print)
>>> a.data = np.arange(2)
<__main__.A object at 0x000001C839B50208> [0 1]
>>> a.data = np.arange(3)
<__main__.A object at 0x000001C839B50208> [0 1 2]
Parameters

defaultvalue: int or float, defaults to 0
Specifies the default value of the property.
>>> wid = Widget()
>>> wid.x = 42
>>> print(wid.x)
42
>>> wid.x = "plop"
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "properties.pyx", line 93, in kivy.properties.Property.__set__
   File "properties.pyx", line 111, in kivy.properties.Property.set
   File "properties.pyx", line 159, in kivy.properties.NumericProperty.check
 ValueError: NumericProperty accept only int/float
Changed in version 1.4.1: NumericProperty can now accept custom text and tuple value to indicate a type, like “in”, “pt”, “px”, “cm”, “mm”, in the format: ‘10pt’ or (10, ‘pt’).

delta_y

NumericProperty(defaultvalue=0, **kw) Property that represents a numeric value.

It only accepts the int or float numeric data type or a string that can be converted to a number as shown below. For other numeric types use ObjectProperty or use errorhandler to convert it to an int/float.

It does not support numpy numbers so they must be manually converted to int/float. E.g. widget.num = np.arange(4)[0] will raise an exception. Numpy arrays are not supported at all, even by ObjectProperty because their comparision does not return a bool. But if you must use a Kivy property, use a ObjectProperty with comparator set to np.array_equal. E.g.:
>>> class A(EventDispatcher):
...     data = ObjectProperty(comparator=np.array_equal)
>>> a = A()
>>> a.bind(data=print)
>>> a.data = np.arange(2)
<__main__.A object at 0x000001C839B50208> [0 1]
>>> a.data = np.arange(3)
<__main__.A object at 0x000001C839B50208> [0 1 2]
Parameters

defaultvalue: int or float, defaults to 0
Specifies the default value of the property.
>>> wid = Widget()
>>> wid.x = 42
>>> print(wid.x)
42
>>> wid.x = "plop"
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "properties.pyx", line 93, in kivy.properties.Property.__set__
   File "properties.pyx", line 111, in kivy.properties.Property.set
   File "properties.pyx", line 159, in kivy.properties.NumericProperty.check
 ValueError: NumericProperty accept only int/float
Changed in version 1.4.1: NumericProperty can now accept custom text and tuple value to indicate a type, like “in”, “pt”, “px”, “cm”, “mm”, in the format: ‘10pt’ or (10, ‘pt’).

diff_scale_at(d, x, y)

do_update(dt)

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

get_bbox(margin=0): Returns the bounding box from the bottom/left (lat1, lon1) to top/right (lat2, lon2).

get_latlon_at(x, y, zoom=None): Return the current Coordinate within the (x, y) widget coordinate.

get_window_xy_from(lat, lon, zoom): Returns the x/y position in the widget absolute coordinates from a lat/lon

lat: Latitude at the center of the widget

load_tile(x, y, size, zoom)

load_tile_for_source(map_source, opacity, size, x, y, zoom)

load_visible_tiles()

lon: Longitude at the center of the widget

map_source: Provider of the map, default to a empty MapSource.

move_tiles_to_background()

on__pause(instance, value)

on_map_relocated(zoom, coord)

on_map_source(instance, source)

on_pos(instance, pos)

on_size(instance, size)

on_touch_down(touch)

Receive a touch down event.

Parameters

touch: MotionEvent class: Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_up(touch)

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_transform(*args)

on_zoom(instance, zoom)

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

remove_all_tiles()

remove_layer(layer): Remove the layer

remove_marker(marker): Remove a marker from its layer

remove_widget(widget)

Remove a widget from the children of this widget.

Parameters

widget: Widget
Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

property scale

scale_at(scale, x, y)

set_zoom_at(zoom, x, y, scale=None): Sets the zoom level, leaving the (x, y) at the exact same point in the view.

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. Default to True, even if it doesn’t fully working yet.

sync_to(other): Reflect the lat/lon/zoom of the other MapView to the current one.

tile_in_tile_map(tile_x, tile_y)

tile_map_set(tile_x, tile_y, value)

trigger_update(full)

unload(): Unload the view and all the layers. It also cancel all the remaining downloads.

property viewport_pos

zoom: Zoom of the widget. Must be between MapSource.get_min_zoom() and MapSource.get_max_zoom(). Default to 0.

class kivy_garden.mapview.MarkerMapLayer(**kwargs)

Bases: kivy_garden.mapview.view.MapLayer

A map layer for MapMarker

add_widget(marker)

Add a new widget as a child of this widget.

Parameters

widget: Widget
Widget to add to our list of children.

index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

insert_marker(marker, **kwargs)

order_marker_by_latitude

BooleanProperty(defaultvalue=True, **kw) Property that represents only a boolean value.

Parameters

defaultvalue: boolean
Specifies the default value of the property.

remove_widget(marker)

Remove a widget from the children of this widget.

Parameters

widget: Widget
Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

reposition(): Function called when MapView is moved. You must recalculate the position of your children.

set_marker_position(mapview, marker)

unload(): Called when the view want to completly unload the layer.

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

marker (MapMarker) – The marker to add
layer (MarkerMapLayer) – The layer to use

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.

Mapview

kivy_garden.mapview

MapView

`kivy_garden.mapview`