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 withMapView.add_marker()
or withMapView.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()
andMapSource.get_max_zoom()
. Default to 0
-
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
-
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.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.
-