Source code for bokeh.models.map_plots

#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2024, Anaconda, Inc., and Bokeh Contributors.
# All rights reserved.
#
# The full license is in the file LICENSE.txt, distributed with this software.
#-----------------------------------------------------------------------------
''' Models for displaying maps in Bokeh plots.

'''

#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
from __future__ import annotations

import logging # isort:skip
log = logging.getLogger(__name__)

#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------

# Bokeh imports
from ..core.enums import MapType
from ..core.has_props import abstract
from ..core.properties import (
    JSON,
    Bool,
    Bytes,
    Enum,
    Float,
    Instance,
    InstanceDefault,
    Int,
    Nullable,
    Override,
    Required,
    String,
)
from ..core.validation import error, warning
from ..core.validation.errors import INCOMPATIBLE_MAP_RANGE_TYPE, MISSING_GOOGLE_API_KEY, REQUIRED_RANGE
from ..core.validation.warnings import MISSING_RENDERERS
from ..model import Model
from ..models.ranges import Range1d
from .plots import Plot

#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------

__all__ = (
    'GMapOptions',
    'GMapPlot',
    'MapOptions',
    'MapPlot',
)

#-----------------------------------------------------------------------------
# General API
#-----------------------------------------------------------------------------

[docs] @abstract class MapOptions(Model): ''' Abstract base class for map options' models. ''' # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) lat = Required(Float, help=""" The latitude where the map should be centered. """) lng = Required(Float, help=""" The longitude where the map should be centered. """) zoom = Int(12, help=""" The initial zoom level to use when displaying the map. """)
[docs] @abstract class MapPlot(Plot): ''' Abstract base class for map plot models. ''' def __init__(self, *args, **kwargs) -> None: from ..models.ranges import Range1d for r in ('x_range', 'y_range'): if r in kwargs and not isinstance(kwargs.get(r), Range1d): raise ValueError(f"Invalid value for {r!r}, MapPlot ranges may only be Range1d, not data ranges") super().__init__(*args, **kwargs) @error(INCOMPATIBLE_MAP_RANGE_TYPE) def _check_incompatible_map_range_type(self): from ..models.ranges import Range1d if self.x_range is not None and not isinstance(self.x_range, Range1d): return "%s.x_range" % str(self) if self.y_range is not None and not isinstance(self.y_range, Range1d): return "%s.y_range" % str(self)
[docs] class GMapOptions(MapOptions): ''' Options for ``GMapPlot`` objects. ''' # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) map_type = Enum(MapType, default="roadmap", help=""" The `map type`_ to use for the ``GMapPlot``. .. _map type: https://developers.google.com/maps/documentation/javascript/reference#MapTypeId """) scale_control = Bool(default=False, help=""" Whether the Google map should display its distance scale control. """) styles = Nullable(JSON, default=None, help=""" A JSON array of `map styles`_ to use for the ``GMapPlot``. Many example styles can `be found here`_. .. _map styles: https://developers.google.com/maps/documentation/javascript/reference#MapTypeStyle .. _be found here: https://snazzymaps.com """) tilt = Int(default=45, help=""" `Tilt`_ angle of the map. The only allowed values are 0 and 45. Only has an effect on 'satellite' and 'hybrid' map types. A value of 0 causes the map to always use a 0 degree overhead view. A value of 45 causes the tilt angle to switch to 45 imagery if available. .. _Tilt: https://developers.google.com/maps/documentation/javascript/reference/3/map#MapOptions.tilt """)
[docs] class GMapPlot(MapPlot): ''' A Bokeh Plot with a `Google Map`_ displayed underneath. Data placed on this plot should be specified in decimal lat/lon coordinates e.g. ``(37.123, -122.404)``. It will be automatically converted into the web mercator projection to display properly over google maps tiles. The ``api_key`` property must be configured with a Google API Key in order for ``GMapPlot`` to function. The key will be stored in the Bokeh Document JSON. Note that Google Maps exert explicit control over aspect ratios at all times, which imposes some limitations on ``GMapPlot``: * Only ``Range1d`` ranges are supported. Attempting to use other range types will result in an error. * Usage of ``BoxZoomTool`` is incompatible with ``GMapPlot``. Adding a ``BoxZoomTool`` will have no effect. .. _Google Map: https://www.google.com/maps/ ''' # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) # TODO (bev) map plot might not have these @error(REQUIRED_RANGE) def _check_required_range(self): pass @warning(MISSING_RENDERERS) def _check_missing_renderers(self): pass @error(MISSING_GOOGLE_API_KEY) def _check_missing_google_api_key(self): if self.api_key is None: return str(self) map_options = Instance(GMapOptions, help=""" Options for displaying the plot. """) border_fill_color = Override(default="#ffffff") background_fill_alpha = Override(default=0.0) api_key = Required(Bytes, help=""" Google Maps API requires an API key. See https://developers.google.com/maps/documentation/javascript/get-api-key for more information on how to obtain your own. """).accepts(String, lambda val: val.encode("utf-8")) api_version = String(default="weekly", help=""" The version of Google Maps API to use. See https://developers.google.com/maps/documentation/javascript/versions for more information. .. note:: Changing this value may result in broken map rendering. """) x_range = Override(default=InstanceDefault(Range1d)) y_range = Override(default=InstanceDefault(Range1d))
#----------------------------------------------------------------------------- # Dev API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Private API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Code #-----------------------------------------------------------------------------