0
# Data Conversion and Utilities
1

2
Extensive collection of utility functions for data format conversion, file operations, geospatial data processing, and general-purpose utilities for working with various data formats and external services.
3

4
## Capabilities
5

6
### File Format Conversion
7

8
Convert between various geospatial and tabular data formats including CSV, GeoJSON, Shapefile, and KML.
9

10
```python { .api }
11
def csv_to_geojson(
12
    in_csv: str,
13
    out_geojson: str = None,
14
    latitude: str = "latitude",
15
    longitude: str = "longitude",
16
    encoding: str = "utf-8",
17
    **kwargs
18
) -> Union[Dict, None]:
19
    """
20
    Convert CSV file with coordinates to GeoJSON.
21
    
22
    Args:
23
        in_csv: Input CSV file path
24
        out_geojson: Output GeoJSON file path (optional)
25
        latitude: Column name for latitude values
26
        longitude: Column name for longitude values
27
        encoding: Character encoding for CSV file
28
        **kwargs: Additional conversion parameters
29
        
30
    Returns:
31
        GeoJSON dictionary if no output file specified
32
    """
33

34
def csv_to_shp(
35
    in_csv: str,
36
    out_shp: str,
37
    latitude: str = "latitude",
38
    longitude: str = "longitude",
39
    **kwargs
40
) -> None:
41
    """
42
    Convert CSV file to shapefile.
43
    
44
    Args:
45
        in_csv: Input CSV file path
46
        out_shp: Output shapefile path
47
        latitude: Column name for latitude values
48
        longitude: Column name for longitude values
49
        **kwargs: Additional parameters
50
    """
51

52
def shp_to_geojson(
53
    in_shp: str,
54
    out_geojson: str = None,
55
    **kwargs
56
) -> Union[Dict, None]:
57
    """
58
    Convert shapefile to GeoJSON.
59
    
60
    Args:
61
        in_shp: Input shapefile path
62
        out_geojson: Output GeoJSON path (optional)
63
        **kwargs: Additional parameters
64
        
65
    Returns:
66
        GeoJSON dictionary if no output file specified
67
    """
68

69
def csv_points_to_shp(
70
    in_csv: str,
71
    out_shp: str,
72
    latitude: str = "latitude", 
73
    longitude: str = "longitude",
74
    **kwargs
75
) -> None:
76
    """
77
    Convert CSV points to shapefile.
78
    
79
    Args:
80
        in_csv: Input CSV file path
81
        out_shp: Output shapefile path
82
        latitude: Column name for latitude
83
        longitude: Column name for longitude
84
        **kwargs: Additional parameters
85
    """
86
```
87

88
### Coordinate and Geometry Conversion
89

90
Convert between different coordinate systems and geometry representations.
91

92
```python { .api }
93
def xy_to_points(
94
    in_csv: str,
95
    out_shp: str,
96
    x_col: str = "x",
97
    y_col: str = "y",
98
    crs: str = "EPSG:4326",
99
    **kwargs
100
) -> None:
101
    """
102
    Convert XY coordinates to point shapefile.
103
    
104
    Args:
105
        in_csv: Input CSV file path
106
        out_shp: Output shapefile path
107
        x_col: X coordinate column name
108
        y_col: Y coordinate column name
109
        crs: Coordinate reference system
110
        **kwargs: Additional parameters
111
    """
112

113
def bbox_to_extent(bbox: List[float]) -> List[float]:
114
    """
115
    Convert bounding box to extent format.
116
    
117
    Args:
118
        bbox: Bounding box [minx, miny, maxx, maxy]
119
        
120
    Returns:
121
        Extent coordinates
122
    """
123
```
124

125
### File Download and Management
126

127
Download files from various sources including URLs, Google Drive, and cloud storage services.
128

129
```python { .api }
130
def download_from_url(
131
    url: str,
132
    out_file_name: str = None,
133
    out_dir: str = ".",
134
    unzip: bool = True,
135
    **kwargs
136
) -> str:
137
    """
138
    Download file from URL.
139
    
140
    Args:
141
        url: File URL
142
        out_file_name: Output filename (optional)
143
        out_dir: Output directory
144
        unzip: Whether to unzip downloaded file
145
        **kwargs: Additional parameters
146
        
147
    Returns:
148
        Path to downloaded file
149
    """
150

151
def download_from_gdrive(
152
    gfile_url: str,
153
    file_name: str,
154
    out_dir: str = ".",
155
    unzip: bool = True,
156
    **kwargs
157
) -> str:
158
    """
159
    Download file from Google Drive.
160
    
161
    Args:
162
        gfile_url: Google Drive file URL
163
        file_name: Output filename
164
        out_dir: Output directory
165
        unzip: Whether to unzip file
166
        **kwargs: Additional parameters
167
        
168
    Returns:
169
        Path to downloaded file
170
    """
171

172
def create_download_link(
173
    filename: str,
174
    title: str = "Click here to download: ",
175
    **kwargs
176
) -> str:
177
    """
178
    Create HTML download link for file.
179
    
180
    Args:
181
        filename: File path
182
        title: Link display text
183
        **kwargs: Additional parameters
184
        
185
    Returns:
186
        HTML download link string
187
    """
188
```
189

190
### Image Processing and Display
191

192
Handle image operations, display, and upload to external services.
193

194
```python { .api }
195
def open_image_from_url(url: str) -> Any:
196
    """
197
    Open image from URL.
198
    
199
    Args:
200
        url: Image URL
201
        
202
    Returns:
203
        Image object
204
    """
205

206
def show_image(
207
    img_path: str,
208
    width: int = None,
209
    height: int = None,
210
    **kwargs
211
) -> None:
212
    """
213
    Display image in Jupyter notebook.
214
    
215
    Args:
216
        img_path: Path to image file
217
        width: Display width in pixels
218
        height: Display height in pixels
219
        **kwargs: Additional display parameters
220
    """
221

222
def has_transparency(img_path: str) -> bool:
223
    """
224
    Check if image has transparency channel.
225
    
226
    Args:
227
        img_path: Path to image file
228
        
229
    Returns:
230
        True if image has transparency
231
    """
232

233
def upload_to_imgur(
234
    in_gif: str,
235
    client_id: str = None,
236
    **kwargs
237
) -> str:
238
    """
239
    Upload image/GIF to Imgur.
240
    
241
    Args:
242
        in_gif: Path to image/GIF file
243
        client_id: Imgur client ID
244
        **kwargs: Additional parameters
245
        
246
    Returns:
247
        Imgur URL
248
    """
249
```
250

251
### Package Management
252

253
Utilities for managing Python packages and dependencies.
254

255
```python { .api }
256
def check_install(package: str) -> bool:
257
    """
258
    Check if package is installed.
259
    
260
    Args:
261
        package: Package name
262
        
263
    Returns:
264
        True if package is installed
265
    """
266

267
def install_package(package: str, **kwargs) -> None:
268
    """
269
    Install Python package.
270
    
271
    Args:
272
        package: Package name to install
273
        **kwargs: Additional installation parameters
274
    """
275

276
def update_package() -> None:
277
    """Update geemap package to latest version."""
278

279
def check_package(name: str) -> Dict:
280
    """
281
    Check package information.
282
    
283
    Args:
284
        name: Package name
285
        
286
    Returns:
287
        Package information dictionary
288
    """
289
```
290

291
### Repository Management
292

293
Git repository cloning and management utilities.
294

295
```python { .api }
296
def clone_repo(
297
    out_dir: str = ".",
298
    unzip: bool = True,
299
    **kwargs
300
) -> str:
301
    """
302
    Clone repository.
303
    
304
    Args:
305
        out_dir: Output directory
306
        unzip: Whether to unzip
307
        **kwargs: Additional parameters
308
        
309
    Returns:
310
        Path to cloned repository
311
    """
312

313
def install_from_github(
314
    url: str,
315
    **kwargs
316
) -> None:
317
    """
318
    Install package from GitHub.
319
    
320
    Args:
321
        url: GitHub repository URL
322
        **kwargs: Additional parameters
323
    """
324

325
def check_git_install() -> bool:
326
    """
327
    Check if Git is installed.
328
    
329
    Returns:
330
        True if Git is available
331
    """
332

333
def clone_github_repo(
334
    url: str,
335
    out_dir: str = None,
336
    **kwargs
337
) -> str:
338
    """
339
    Clone GitHub repository.
340
    
341
    Args:
342
        url: GitHub repository URL
343
        out_dir: Output directory
344
        **kwargs: Additional parameters
345
        
346
    Returns:
347
        Path to cloned repository
348
    """
349

350
def open_github() -> None:
351
    """Open geemap GitHub repository."""
352

353
def open_youtube() -> None:
354
    """Open geemap YouTube channel."""
355
```
356

357
### System Utilities
358

359
System-level utilities and environment management functions.
360

361
```python { .api }
362
def is_tool(name: str) -> bool:
363
    """
364
    Check if command line tool exists.
365
    
366
    Args:
367
        name: Tool name
368
        
369
    Returns:
370
        True if tool is available
371
    """
372

373
def system_fonts() -> List[str]:
374
    """
375
    Get list of system fonts.
376
    
377
    Returns:
378
        List of available font names
379
    """
380

381
def show_html(
382
    html_string: str,
383
    width: int = 950,
384
    height: int = 600,
385
    **kwargs
386
) -> None:
387
    """
388
    Display HTML content in Jupyter notebook.
389
    
390
    Args:
391
        html_string: HTML content string
392
        width: Display width
393
        height: Display height
394
        **kwargs: Additional parameters
395
    """
396
```
397

398
### JavaScript to Python Conversion
399

400
Tools for converting Earth Engine JavaScript code to Python.
401

402
```python { .api }
403
def js_to_python(
404
    in_js_file: str,
405
    out_py_file: str = None,
406
    use_qgis: bool = True,
407
    **kwargs
408
) -> str:
409
    """
410
    Convert JavaScript Earth Engine code to Python.
411
    
412
    Args:
413
        in_js_file: Input JavaScript file path
414
        out_py_file: Output Python file path
415
        use_qgis: Whether to use QGIS-compatible syntax
416
        **kwargs: Additional conversion parameters
417
        
418
    Returns:
419
        Converted Python code string
420
    """
421

422
def js_snippet_to_py(
423
    js_snippet: str,
424
    add_new_cell: bool = False,
425
    import_ee: bool = True,
426
    import_geemap: bool = True,
427
    show_map: bool = True,
428
    **kwargs
429
) -> str:
430
    """
431
    Convert JavaScript code snippet to Python.
432
    
433
    Args:
434
        js_snippet: JavaScript code snippet
435
        add_new_cell: Add as new Jupyter cell
436
        import_ee: Include Earth Engine import
437
        import_geemap: Include geemap import
438
        show_map: Add map display code
439
        **kwargs: Additional parameters
440
        
441
    Returns:
442
        Converted Python code
443
    """
444

445
def create_new_cell(
446
    contents: str = "",
447
    cell_type: str = "code",
448
    **kwargs
449
) -> None:
450
    """
451
    Create new Jupyter notebook cell.
452
    
453
    Args:
454
        contents: Cell contents
455
        cell_type: Cell type ('code' or 'markdown')
456
        **kwargs: Additional parameters
457
    """
458

459
def js_to_python_dir(
460
    in_dir: str,
461
    out_dir: str = None,
462
    use_qgis: bool = True,
463
    **kwargs
464
) -> None:
465
    """
466
    Convert directory of JavaScript files to Python.
467
    
468
    Args:
469
        in_dir: Input directory path
470
        out_dir: Output directory path
471
        use_qgis: Use QGIS-compatible syntax
472
        **kwargs: Additional parameters
473
    """
474
```
475

476
### TiTiler Integration
477

478
Integration with TiTiler for cloud-optimized geospatial tile serving.
479

480
```python { .api }
481
class TitilerEndpoint:
482
    """TiTiler endpoint configuration."""
483
    
484
    def __init__(
485
        self,
486
        endpoint: str,
487
        name: str = "TiTiler",
488
        **kwargs
489
    ) -> None:
490
        """
491
        Initialize TiTiler endpoint.
492
        
493
        Args:
494
            endpoint: TiTiler endpoint URL
495
            name: Endpoint name
496
            **kwargs: Additional parameters
497
        """
498

499
def check_titiler_endpoint(titiler_endpoint: str = None) -> bool:
500
    """
501
    Check TiTiler endpoint availability.
502
    
503
    Args:
504
        titiler_endpoint: TiTiler endpoint URL
505
        
506
    Returns:
507
        True if endpoint is accessible
508
    """
509
```
510

511
## Usage Examples
512

513
### Data Format Conversion
514

515
```python
516
import geemap
517

518
# Convert CSV to GeoJSON
519
geemap.csv_to_geojson(
520
    'points.csv',
521
    'points.geojson',
522
    latitude='lat',
523
    longitude='lon'
524
)
525

526
# Convert shapefile to GeoJSON
527
geojson_data = geemap.shp_to_geojson('boundaries.shp')
528

529
# Convert CSV to shapefile
530
geemap.csv_to_shp(
531
    'locations.csv',
532
    'locations.shp',
533
    latitude='y',
534
    longitude='x'
535
)
536
```
537

538
### File Downloads
539

540
```python
541
# Download from URL
542
file_path = geemap.download_from_url(
543
    'https://example.com/data.zip',
544
    out_dir='./downloads',
545
    unzip=True
546
)
547

548
# Download from Google Drive
549
geemap.download_from_gdrive(
550
    'https://drive.google.com/file/d/abc123/view',
551
    'dataset.zip',
552
    out_dir='./data'
553
)
554
```
555

556
### JavaScript to Python Conversion
557

558
```python
559
# Convert JavaScript file
560
geemap.js_to_python(
561
    'earth_engine_script.js',
562
    'earth_engine_script.py'
563
)
564

565
# Convert code snippet
566
js_code = """
567
var image = ee.Image('LANDSAT/LC08/C01/T1/LC08_044034_20140318');
568
Map.addLayer(image, {bands: ['B4', 'B3', 'B2']}, 'Landsat');
569
"""
570

571
python_code = geemap.js_snippet_to_py(js_code)
572
print(python_code)
573
```
574

575
### Package Management
576

577
```python
578
# Check if package is installed
579
if not geemap.check_install('folium'):
580
    geemap.install_package('folium')
581

582
# Update geemap
583
geemap.update_package()
584
```
585

586
## Types
587

588
```python { .api }
589
# File path type
590
FilePath = str
591

592
# Coordinate reference system
593
CRS = str
594

595
# Bounding box format [minx, miny, maxx, maxy]
596
BBox = List[float]
597

598
# Package information
599
PackageInfo = Dict[str, Union[str, bool, List[str]]]
600

601
# Download parameters
602
DownloadParams = Dict[str, Union[str, bool, int]]
603
```