0
# Geedim
1

2
A comprehensive Python toolkit for exporting and cloud masking Google Earth Engine (GEE) imagery. Geedim enables users to export GEE Image and ImageCollection data to multiple formats including GeoTIFF files, NumPy arrays, Xarray Datasets, and Google Cloud platforms. The library specializes in cloud masking for Landsat 4-9 collection 2 images and Sentinel-2 TOA and surface reflectance images, extending the GEE API through pandas-style accessors.
3

4
## Package Information
5

6
- **Package Name**: geedim
7
- **Language**: Python
8
- **Installation**: `pip install geedim`
9
- **Documentation**: https://geedim.readthedocs.io/
10

11
## Core Imports
12

13
```python
14
import geedim
15
```
16

17
Working with Earth Engine classes via accessors:
18

19
```python
20
import ee
21
import geedim
22

23
# Initialize Earth Engine
24
geedim.Initialize()
25

26
# Access via .gd accessor
27
image = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_173083_20160101')
28
collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2')
29
```
30

31
Legacy imports (deprecated):
32

33
```python
34
from geedim import MaskedImage, MaskedCollection
35
```
36

37
Enums and utilities:
38

39
```python
40
from geedim import (
41
    CloudMaskMethod,
42
    CloudScoreBand,
43
    CompositeMethod,
44
    ExportType,
45
    ResamplingMethod,
46
    Initialize
47
)
48

49
# Additional enums available from geedim.enums module
50
from geedim.enums import SpectralDistanceMetric, SplitType, Driver
51
```
52

53
## Basic Usage
54

55
```python
56
import ee
57
import geedim
58

59
# Initialize Earth Engine with high-volume endpoint
60
geedim.Initialize()
61

62
# Load a Landsat image with cloud masking
63
image = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_173083_20160101')
64
masked_image = image.gd.addMaskBands().maskClouds()
65

66
# Export to GeoTIFF
67
region = ee.Geometry.Point(-122.4194, 37.7749).buffer(10000)
68
masked_image.gd.export(
69
    filename='landsat_export',
70
    type=geedim.ExportType.drive,
71
    folder='my_exports',
72
    region=region,
73
    scale=30
74
)
75

76
# Create a composite from collection
77
collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2') \
78
    .filterDate('2020-01-01', '2020-12-31') \
79
    .filterBounds(region)
80

81
composite = collection.gd.composite(
82
    method=geedim.CompositeMethod.median,
83
    region=region,
84
    scale=30
85
)
86

87
# Download to NumPy array
88
array = composite.gd.download(filename=None, region=region, scale=30)
89
```
90

91
## Architecture
92

93
Geedim extends Google Earth Engine through pandas-style accessors registered on `ee.Image` and `ee.ImageCollection` classes:
94

95
- **Image Accessor (`.gd`)**: Provides cloud masking, export, and download capabilities for individual images
96
- **Collection Accessor (`.gd`)**: Enables filtering, compositing, and batch operations on image collections
97
- **Masking System**: Automatic cloud and shadow detection for Landsat and Sentinel-2 imagery
98
- **Export Engine**: Multi-format export supporting GeoTIFF, cloud storage, and in-memory formats
99
- **Async Downloads**: Parallel downloading with progress tracking and retry logic
100

101
The accessor pattern allows seamless integration with existing Earth Engine workflows while adding powerful cloud masking and export capabilities.
102

103
## Capabilities
104

105
### Earth Engine Initialization
106

107
Initialize Earth Engine with high-volume endpoint and credential management, including support for service account authentication via environment variables.
108

109
```python { .api }
110
def Initialize(
111
    opt_url: str = 'https://earthengine-highvolume.googleapis.com',
112
    **kwargs
113
) -> None: ...
114
```
115

116
[Initialization](./initialization.md)
117

118
### Image Processing
119

120
Process individual Earth Engine images with cloud masking, export, and download capabilities. Supports automatic cloud and shadow detection for Landsat 4-9 and Sentinel-2 imagery.
121

122
```python { .api }
123
# Accessed via ee.Image.gd
124
class ImageAccessor:
125
    def addMaskBands(self, **kwargs) -> ee.Image: ...
126
    def maskClouds(self) -> ee.Image: ...
127
    def export(self, filename: str, type: ExportType = ExportType.drive, **kwargs) -> ee.batch.Task: ...
128
    def download(self, filename: str | None = None, **kwargs): ...
129
```
130

131
[Image Processing](./image-processing.md)
132

133
### Collection Operations
134

135
Advanced operations on Earth Engine image collections including filtering, compositing, and batch processing with cloud masking support.
136

137
```python { .api }
138
# Accessed via ee.ImageCollection.gd
139
class ImageCollectionAccessor:
140
    def filter(self, start_date: str = None, end_date: str = None, **kwargs) -> ee.ImageCollection: ...
141
    def composite(self, method: CompositeMethod = None, **kwargs) -> ee.Image: ...
142
    def export(self, filename: str, **kwargs) -> list[ee.batch.Task]: ...
143
    def download(self, filename: str | None = None, **kwargs): ...
144
```
145

146
[Collection Operations](./collection-operations.md)
147

148
### Cloud Masking
149

150
Specialized cloud and shadow masking for Landsat and Sentinel-2 imagery with configurable algorithms and thresholds.
151

152
```python { .api }
153
class CloudMaskMethod(Enum):
154
    cloud_prob = 'cloud-prob'  # Deprecated
155
    qa = 'qa'  # Deprecated  
156
    cloud_score = 'cloud-score'
157

158
class CloudScoreBand(Enum):
159
    cs = 'cs'
160
    cs_cdf = 'cs_cdf'
161
```
162

163
[Cloud Masking](./cloud-masking.md)
164

165
### Export and Download
166

167
Export images and collections to various formats including GeoTIFF, Google Drive, Cloud Storage, and in-memory arrays with configurable parameters.
168

169
```python { .api }
170
class ExportType(Enum):
171
    drive = 'drive'
172
    asset = 'asset'
173
    cloud = 'cloud'
174

175
class ResamplingMethod(Enum):
176
    near = 'near'
177
    bilinear = 'bilinear'
178
    bicubic = 'bicubic'
179
    average = 'average'
180
```
181

182
[Export and Download](./export-download.md)
183

184
### Compositing
185

186
Create temporal composites from image collections using various algorithms including median, medoid, q-mosaic, and statistical methods.
187

188
```python { .api }
189
class CompositeMethod(Enum):
190
    q_mosaic = 'q-mosaic'
191
    mosaic = 'mosaic'
192
    medoid = 'medoid'
193
    median = 'median'
194
    mode = 'mode'
195
    mean = 'mean'
196

197
class SpectralDistanceMetric(Enum):
198
    sam = 'sam'  # Spectral angle mapper
199
    sid = 'sid'  # Spectral information divergence
200
    sed = 'sed'  # Squared euclidean distance
201
    emd = 'emd'  # Earth movers distance
202

203
class SplitType(Enum):
204
    bands = 'bands'  # Split collection by band
205
    images = 'images'  # Split collection by image
206

207
class Driver(Enum):
208
    gtiff = 'gtiff'  # GeoTIFF
209
    cog = 'cog'  # Cloud Optimised GeoTIFF
210
```
211

212
[Compositing](./compositing.md)
213

214
## Types
215

216
```python { .api }
217
# Core version identifier
218
__version__: str
219

220
# Legacy classes (deprecated in 2.0.0)
221
class MaskedImage:
222
    def __init__(self, ee_image: ee.Image, mask: bool = False, **kwargs): ...
223
    @staticmethod
224
    def from_id(image_id: str, **kwargs) -> MaskedImage: ...
225

226
class MaskedCollection:
227
    def __init__(self, ee_collection: ee.ImageCollection, add_props: list[str] | None = None): ...
228
    @classmethod
229
    def from_name(cls, name: str, **kwargs) -> MaskedCollection: ...
230
```