tessl/pypi-gmaps

Google maps plugin for Jupyter notebooks with interactive visualization capabilities

—

Pending

Overview

Eval results

Files

Interactive Drawing Tools

Name: tessl/pypi-gmaps
Author: tessl

Enable users to draw and edit geometric features directly on the map including lines, polygons, circles, and markers with customizable styling. Perfect for creating interactive applications where users need to define areas or routes.

Capabilities

Drawing Layer Creation

Create interactive drawing layers with customizable tools and default styling options.

def drawing_layer(features=None, mode='MARKER', show_controls=True, marker_options=None, line_options=None, polygon_options=None, circle_options=None):
    """
    Create an interactive drawing layer.

    Parameters:
    - features (list, optional): Initial list of drawable features (Line, Polygon, Circle, Marker objects)
    - mode (str, optional): Initial drawing mode ('MARKER', 'LINE', 'POLYGON', 'CIRCLE', 'DELETE', 'DISABLED')
    - show_controls (bool, optional): Whether to show drawing toolbar controls
    - marker_options (MarkerOptions, optional): Default marker styling options
    - line_options (LineOptions, optional): Default line styling options  
    - polygon_options (PolygonOptions, optional): Default polygon styling options
    - circle_options (CircleOptions, optional): Default circle styling options

    Returns:
    Drawing: Drawing layer instance
    """

Drawing Layer Widget

Main widget for interactive drawing functionality with toolbar controls.

class Drawing:
    """
    Interactive drawing layer widget.
    
    Attributes:
    - features (list): List of drawable features (Line, Polygon, Circle, Marker objects)
    - mode (str): Current drawing mode ('MARKER', 'LINE', 'POLYGON', 'CIRCLE', 'DELETE', 'DISABLED')
    - show_controls (bool): Whether drawing toolbar controls are visible
    """

Line Feature

Drawable line feature connecting two or more points.

class Line:
    """
    Line feature for drawing layer.
    
    Attributes:
    - start (tuple): Line start point (latitude, longitude)
    - end (tuple): Line end point (latitude, longitude)
    - stroke_color (str): Line color
    - stroke_weight (float): Line width in pixels
    - stroke_opacity (float): Line opacity (0.0-1.0)
    """

Polygon Feature

Drawable polygon feature with fill and stroke styling.

class Polygon:
    """
    Polygon feature for drawing layer.
    
    Attributes:
    - path (list): List of (latitude, longitude) vertices
    - stroke_color (str): Outline color
    - stroke_weight (float): Outline width in pixels
    - stroke_opacity (float): Outline opacity (0.0-1.0)
    - fill_color (str): Fill color
    - fill_opacity (float): Fill opacity (0.0-1.0)
    """

Circle Feature

Drawable circle feature with radius and styling options.

class Circle:
    """
    Circle feature for drawing layer.
    
    Attributes:
    - center (tuple): Circle center (latitude, longitude)
    - radius (float): Circle radius in meters
    - stroke_color (str): Outline color
    - stroke_weight (float): Outline width in pixels
    - stroke_opacity (float): Outline opacity (0.0-1.0)
    - fill_color (str): Fill color
    - fill_opacity (float): Fill opacity (0.0-1.0)
    """

Drawing Options Classes

Default styling options for different drawing tools.

class LineOptions:
    """
    Default styling for lines.
    
    Attributes:
    - stroke_color (str): Default line color
    - stroke_weight (float): Default line width
    - stroke_opacity (float): Default line opacity
    """

class PolygonOptions:
    """
    Default styling for polygons.
    
    Attributes:
    - stroke_color (str): Default outline color
    - stroke_weight (float): Default outline width
    - stroke_opacity (float): Default outline opacity
    - fill_color (str): Default fill color
    - fill_opacity (float): Default fill opacity
    """

class CircleOptions:
    """
    Default styling for circles.
    
    Attributes:
    - stroke_color (str): Default outline color
    - stroke_weight (float): Default outline width
    - stroke_opacity (float): Default outline opacity
    - fill_color (str): Default fill color
    - fill_opacity (float): Default fill opacity
    """

Usage Examples

Basic Drawing Layer

import gmaps

gmaps.configure(api_key="YOUR_API_KEY")

# Create figure with drawing layer
fig = gmaps.figure()
drawing_layer = gmaps.drawing_layer()
fig.add_layer(drawing_layer)

# Users can now draw on the map interactively
fig

Drawing Layer with Custom Styling

import gmaps

gmaps.configure(api_key="YOUR_API_KEY")

# Define custom styling options
line_options = gmaps.LineOptions(
    stroke_color='red',
    stroke_weight=4.0,
    stroke_opacity=0.8
)

polygon_options = gmaps.PolygonOptions(
    stroke_color='blue',
    stroke_weight=2.0,
    stroke_opacity=1.0,
    fill_color='lightblue',
    fill_opacity=0.3
)

circle_options = gmaps.CircleOptions(
    stroke_color='green',
    stroke_weight=3.0,
    stroke_opacity=0.9,
    fill_color='lightgreen',
    fill_opacity=0.4
)

# Create drawing layer with custom options
fig = gmaps.figure()
drawing_layer = gmaps.drawing_layer(
    line_options=line_options,
    polygon_options=polygon_options
)
fig.add_layer(drawing_layer)
fig

Pre-populated Drawing Layer

import gmaps

gmaps.configure(api_key="YOUR_API_KEY")

# Create initial features
initial_line = gmaps.Line(
    start=(37.7749, -122.4194),
    end=(37.7849, -122.4094),
    stroke_color='purple',
    stroke_weight=5.0
)

initial_polygon = gmaps.Polygon(
    path=[
        (37.7649, -122.4294),
        (37.7749, -122.4194),
        (37.7849, -122.4094),
        (37.7649, -122.4294)  # Close the polygon
    ],
    stroke_color='orange',
    fill_color='yellow',
    fill_opacity=0.3
)

initial_circle = gmaps.Circle(
    center=(37.7949, -122.3994),
    radius=1000,  # 1km radius
    stroke_color='red',
    fill_color='pink',
    fill_opacity=0.2
)

# Create drawing layer with initial features
fig = gmaps.figure()
drawing_layer = gmaps.drawing_layer(
    features=[initial_line, initial_polygon, initial_circle]
)
fig.add_layer(drawing_layer)
fig

Accessing Drawn Features

import gmaps

gmaps.configure(api_key="YOUR_API_KEY")

# Create drawing layer
fig = gmaps.figure()
drawing_layer = gmaps.drawing_layer()
fig.add_layer(drawing_layer)

# Display the figure first
fig

# After user draws features, access them
def get_drawn_features():
    features = drawing_layer.features
    print(f"Number of features drawn: {len(features)}")
    
    for i, feature in enumerate(features):
        if isinstance(feature, gmaps.Line):
            print(f"Feature {i}: Line from {feature.start} to {feature.end}")
        elif isinstance(feature, gmaps.Polygon):
            print(f"Feature {i}: Polygon with {len(feature.path)} vertices")
        elif isinstance(feature, gmaps.Circle):
            print(f"Feature {i}: Circle at {feature.center} with radius {feature.radius}m")

# Call this function after user interaction
# get_drawn_features()

Drawing with Event Handling

import gmaps
from traitlets import observe

gmaps.configure(api_key="YOUR_API_KEY")

# Create drawing layer
drawing_layer = gmaps.drawing_layer()

# Set up event handler for when features change
@observe(drawing_layer, 'features')
def handle_draw(change):
    features = change['new']
    print(f"Features updated! Now have {len(features)} features")
    
    # Process the latest feature
    if features:
        latest_feature = features[-1]
        if isinstance(latest_feature, gmaps.Polygon):
            # Calculate area or perform other operations
            print(f"New polygon drawn with {len(latest_feature.path)} vertices")

fig = gmaps.figure()
fig.add_layer(drawing_layer)
fig

Combining Drawing with Other Layers

import gmaps
import gmaps.datasets

gmaps.configure(api_key="YOUR_API_KEY")

fig = gmaps.figure()

# Add a heatmap layer as background
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')
locations = earthquake_data[['latitude', 'longitude']]
heatmap = gmaps.heatmap_layer(locations, opacity=0.4)
fig.add_layer(heatmap)

# Add markers for reference points
markers = gmaps.marker_layer(
    [(37.7749, -122.4194), (37.7849, -122.4094)],
    label=['A', 'B']
)
fig.add_layer(markers)

# Add drawing layer on top
drawing_layer = gmaps.drawing_layer()
fig.add_layer(drawing_layer)

fig

Styled Individual Features

import gmaps

gmaps.configure(api_key="YOUR_API_KEY")

# Create custom styled features
custom_line = gmaps.Line(
    start=(37.7749, -122.4194),
    end=(37.7849, -122.4094),
    stroke_color='#FF6B6B',  # Coral red
    stroke_weight=6.0,
    stroke_opacity=0.9
)

custom_polygon = gmaps.Polygon(
    path=[
        (37.7649, -122.4394),
        (37.7749, -122.4294),
        (37.7849, -122.4194),
        (37.7649, -122.4394)
    ],
    stroke_color='#4ECDC4',  # Teal
    stroke_weight=3.0,
    stroke_opacity=1.0,
    fill_color='#45B7D1',    # Light blue
    fill_opacity=0.4
)

custom_circle = gmaps.Circle(
    center=(37.7549, -122.4094),
    radius=500,
    stroke_color='#96CEB4',  # Mint green
    stroke_weight=4.0,
    stroke_opacity=0.8,
    fill_color='#FFEAA7',    # Light yellow
    fill_opacity=0.3
)

fig = gmaps.figure()
drawing_layer = gmaps.drawing_layer(
    features=[custom_line, custom_polygon, custom_circle]
)
fig.add_layer(drawing_layer)
fig

Install with Tessl CLI