0
# Interactive Drawing Tools
1

2
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.
3

4
## Capabilities
5

6
### Drawing Layer Creation
7

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

10
```python { .api }
11
def drawing_layer(features=None, mode='MARKER', show_controls=True, marker_options=None, line_options=None, polygon_options=None, circle_options=None):
12
    """
13
    Create an interactive drawing layer.
14

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

24
    Returns:
25
    Drawing: Drawing layer instance
26
    """
27
```
28

29
### Drawing Layer Widget
30

31
Main widget for interactive drawing functionality with toolbar controls.
32

33
```python { .api }
34
class Drawing:
35
    """
36
    Interactive drawing layer widget.
37
    
38
    Attributes:
39
    - features (list): List of drawable features (Line, Polygon, Circle, Marker objects)
40
    - mode (str): Current drawing mode ('MARKER', 'LINE', 'POLYGON', 'CIRCLE', 'DELETE', 'DISABLED')
41
    - show_controls (bool): Whether drawing toolbar controls are visible
42
    """
43
```
44

45
### Line Feature
46

47
Drawable line feature connecting two or more points.
48

49
```python { .api }
50
class Line:
51
    """
52
    Line feature for drawing layer.
53
    
54
    Attributes:
55
    - start (tuple): Line start point (latitude, longitude)
56
    - end (tuple): Line end point (latitude, longitude)
57
    - stroke_color (str): Line color
58
    - stroke_weight (float): Line width in pixels
59
    - stroke_opacity (float): Line opacity (0.0-1.0)
60
    """
61
```
62

63
### Polygon Feature
64

65
Drawable polygon feature with fill and stroke styling.
66

67
```python { .api }
68
class Polygon:
69
    """
70
    Polygon feature for drawing layer.
71
    
72
    Attributes:
73
    - path (list): List of (latitude, longitude) vertices
74
    - stroke_color (str): Outline color
75
    - stroke_weight (float): Outline width in pixels
76
    - stroke_opacity (float): Outline opacity (0.0-1.0)
77
    - fill_color (str): Fill color
78
    - fill_opacity (float): Fill opacity (0.0-1.0)
79
    """
80
```
81

82
### Circle Feature
83

84
Drawable circle feature with radius and styling options.
85

86
```python { .api }
87
class Circle:
88
    """
89
    Circle feature for drawing layer.
90
    
91
    Attributes:
92
    - center (tuple): Circle center (latitude, longitude)
93
    - radius (float): Circle radius in meters
94
    - stroke_color (str): Outline color
95
    - stroke_weight (float): Outline width in pixels
96
    - stroke_opacity (float): Outline opacity (0.0-1.0)
97
    - fill_color (str): Fill color
98
    - fill_opacity (float): Fill opacity (0.0-1.0)
99
    """
100
```
101

102
### Drawing Options Classes
103

104
Default styling options for different drawing tools.
105

106
```python { .api }
107
class LineOptions:
108
    """
109
    Default styling for lines.
110
    
111
    Attributes:
112
    - stroke_color (str): Default line color
113
    - stroke_weight (float): Default line width
114
    - stroke_opacity (float): Default line opacity
115
    """
116

117
class PolygonOptions:
118
    """
119
    Default styling for polygons.
120
    
121
    Attributes:
122
    - stroke_color (str): Default outline color
123
    - stroke_weight (float): Default outline width
124
    - stroke_opacity (float): Default outline opacity
125
    - fill_color (str): Default fill color
126
    - fill_opacity (float): Default fill opacity
127
    """
128

129
class CircleOptions:
130
    """
131
    Default styling for circles.
132
    
133
    Attributes:
134
    - stroke_color (str): Default outline color
135
    - stroke_weight (float): Default outline width
136
    - stroke_opacity (float): Default outline opacity
137
    - fill_color (str): Default fill color
138
    - fill_opacity (float): Default fill opacity
139
    """
140
```
141

142
## Usage Examples
143

144
### Basic Drawing Layer
145

146
```python
147
import gmaps
148

149
gmaps.configure(api_key="YOUR_API_KEY")
150

151
# Create figure with drawing layer
152
fig = gmaps.figure()
153
drawing_layer = gmaps.drawing_layer()
154
fig.add_layer(drawing_layer)
155

156
# Users can now draw on the map interactively
157
fig
158
```
159

160
### Drawing Layer with Custom Styling
161

162
```python
163
import gmaps
164

165
gmaps.configure(api_key="YOUR_API_KEY")
166

167
# Define custom styling options
168
line_options = gmaps.LineOptions(
169
    stroke_color='red',
170
    stroke_weight=4.0,
171
    stroke_opacity=0.8
172
)
173

174
polygon_options = gmaps.PolygonOptions(
175
    stroke_color='blue',
176
    stroke_weight=2.0,
177
    stroke_opacity=1.0,
178
    fill_color='lightblue',
179
    fill_opacity=0.3
180
)
181

182
circle_options = gmaps.CircleOptions(
183
    stroke_color='green',
184
    stroke_weight=3.0,
185
    stroke_opacity=0.9,
186
    fill_color='lightgreen',
187
    fill_opacity=0.4
188
)
189

190
# Create drawing layer with custom options
191
fig = gmaps.figure()
192
drawing_layer = gmaps.drawing_layer(
193
    line_options=line_options,
194
    polygon_options=polygon_options
195
)
196
fig.add_layer(drawing_layer)
197
fig
198
```
199

200
### Pre-populated Drawing Layer
201

202
```python
203
import gmaps
204

205
gmaps.configure(api_key="YOUR_API_KEY")
206

207
# Create initial features
208
initial_line = gmaps.Line(
209
    start=(37.7749, -122.4194),
210
    end=(37.7849, -122.4094),
211
    stroke_color='purple',
212
    stroke_weight=5.0
213
)
214

215
initial_polygon = gmaps.Polygon(
216
    path=[
217
        (37.7649, -122.4294),
218
        (37.7749, -122.4194),
219
        (37.7849, -122.4094),
220
        (37.7649, -122.4294)  # Close the polygon
221
    ],
222
    stroke_color='orange',
223
    fill_color='yellow',
224
    fill_opacity=0.3
225
)
226

227
initial_circle = gmaps.Circle(
228
    center=(37.7949, -122.3994),
229
    radius=1000,  # 1km radius
230
    stroke_color='red',
231
    fill_color='pink',
232
    fill_opacity=0.2
233
)
234

235
# Create drawing layer with initial features
236
fig = gmaps.figure()
237
drawing_layer = gmaps.drawing_layer(
238
    features=[initial_line, initial_polygon, initial_circle]
239
)
240
fig.add_layer(drawing_layer)
241
fig
242
```
243

244
### Accessing Drawn Features
245

246
```python
247
import gmaps
248

249
gmaps.configure(api_key="YOUR_API_KEY")
250

251
# Create drawing layer
252
fig = gmaps.figure()
253
drawing_layer = gmaps.drawing_layer()
254
fig.add_layer(drawing_layer)
255

256
# Display the figure first
257
fig
258

259
# After user draws features, access them
260
def get_drawn_features():
261
    features = drawing_layer.features
262
    print(f"Number of features drawn: {len(features)}")
263
    
264
    for i, feature in enumerate(features):
265
        if isinstance(feature, gmaps.Line):
266
            print(f"Feature {i}: Line from {feature.start} to {feature.end}")
267
        elif isinstance(feature, gmaps.Polygon):
268
            print(f"Feature {i}: Polygon with {len(feature.path)} vertices")
269
        elif isinstance(feature, gmaps.Circle):
270
            print(f"Feature {i}: Circle at {feature.center} with radius {feature.radius}m")
271

272
# Call this function after user interaction
273
# get_drawn_features()
274
```
275

276
### Drawing with Event Handling
277

278
```python
279
import gmaps
280
from traitlets import observe
281

282
gmaps.configure(api_key="YOUR_API_KEY")
283

284
# Create drawing layer
285
drawing_layer = gmaps.drawing_layer()
286

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

300
fig = gmaps.figure()
301
fig.add_layer(drawing_layer)
302
fig
303
```
304

305
### Combining Drawing with Other Layers
306

307
```python
308
import gmaps
309
import gmaps.datasets
310

311
gmaps.configure(api_key="YOUR_API_KEY")
312

313
fig = gmaps.figure()
314

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

321
# Add markers for reference points
322
markers = gmaps.marker_layer(
323
    [(37.7749, -122.4194), (37.7849, -122.4094)],
324
    label=['A', 'B']
325
)
326
fig.add_layer(markers)
327

328
# Add drawing layer on top
329
drawing_layer = gmaps.drawing_layer()
330
fig.add_layer(drawing_layer)
331

332
fig
333
```
334

335
### Styled Individual Features
336

337
```python
338
import gmaps
339

340
gmaps.configure(api_key="YOUR_API_KEY")
341

342
# Create custom styled features
343
custom_line = gmaps.Line(
344
    start=(37.7749, -122.4194),
345
    end=(37.7849, -122.4094),
346
    stroke_color='#FF6B6B',  # Coral red
347
    stroke_weight=6.0,
348
    stroke_opacity=0.9
349
)
350

351
custom_polygon = gmaps.Polygon(
352
    path=[
353
        (37.7649, -122.4394),
354
        (37.7749, -122.4294),
355
        (37.7849, -122.4194),
356
        (37.7649, -122.4394)
357
    ],
358
    stroke_color='#4ECDC4',  # Teal
359
    stroke_weight=3.0,
360
    stroke_opacity=1.0,
361
    fill_color='#45B7D1',    # Light blue
362
    fill_opacity=0.4
363
)
364

365
custom_circle = gmaps.Circle(
366
    center=(37.7549, -122.4094),
367
    radius=500,
368
    stroke_color='#96CEB4',  # Mint green
369
    stroke_weight=4.0,
370
    stroke_opacity=0.8,
371
    fill_color='#FFEAA7',    # Light yellow
372
    fill_opacity=0.3
373
)
374

375
fig = gmaps.figure()
376
drawing_layer = gmaps.drawing_layer(
377
    features=[custom_line, custom_polygon, custom_circle]
378
)
379
fig.add_layer(drawing_layer)
380
fig
381
```