0
# Image Processing
1

2
Process individual Earth Engine images with cloud masking, export, and download capabilities. The image processing functionality is accessed through the `.gd` accessor on `ee.Image` objects, providing automatic cloud and shadow detection for Landsat 4-9 and Sentinel-2 imagery.
3

4
## Capabilities
5

6
### Image Accessor
7

8
The main accessor class for Earth Engine images, registered as `.gd` on `ee.Image` objects.
9

10
```python { .api }
11
class ImageAccessor:
12
    def __init__(self, ee_image: ee.Image): ...
13
```
14

15
### Add Mask Bands
16

17
Add cloud mask and related bands to an image. Mask bands are automatically determined based on the image collection type (Landsat or Sentinel-2).
18

19
```python { .api }
20
def addMaskBands(self, **kwargs) -> ee.Image:
21
    """
22
    Add mask and related bands to the image.
23
    
24
    Parameters:
25
    - **kwargs: Cloud masking parameters specific to the image collection
26
      - For Sentinel-2: method (CloudMaskMethod), prob (float), cloud_dist (float)
27
      - For Landsat: mask_cirrus (bool), mask_shadows (bool)
28
    
29
    Returns:
30
    ee.Image: Image with mask bands added
31
    """
32
```
33

34
### Mask Clouds
35

36
Apply cloud masking to an image using the mask bands added by `addMaskBands()`.
37

38
```python { .api }
39
def maskClouds(self) -> ee.Image:
40
    """
41
    Apply cloud mask to the image.
42
    
43
    Returns:
44
    ee.Image: Cloud-masked image
45
    """
46
```
47

48
### Export Image
49

50
Export an image to various destinations including Google Drive, Google Cloud Storage, or Earth Engine Assets.
51

52
```python { .api }
53
def export(
54
    self,
55
    filename: str,
56
    type: ExportType = ExportType.drive,
57
    folder: str = None,
58
    wait: bool = True,
59
    **export_kwargs
60
) -> ee.batch.Task:
61
    """
62
    Export the image to the specified destination using a batch task.
63
    
64
    Parameters:
65
    - filename (str): Destination file or asset name (excluding extension)
66
    - type (ExportType): Export destination type
67
    - folder (str, optional): Destination folder name
68
    - wait (bool): Whether to wait for export completion before returning
69
    - **export_kwargs: Additional export parameters for prepareForExport
70
    
71
    Returns:
72
    ee.batch.Task: Earth Engine export task
73
    """
74
```
75

76
### Download Image
77

78
Download an image to local memory as NumPy arrays, Xarray datasets, or save to local files.
79

80
```python { .api }
81
def download(
82
    self,
83
    region: dict | ee.Geometry = None,
84
    scale: float = None,
85
    crs: str = None,
86
    dtype: str = 'auto',
87
    resampling: ResamplingMethod = ResamplingMethod.near,
88
    **kwargs
89
):
90
    """
91
    Download the image to local memory or file.
92
    
93
    Parameters:
94
    - region (dict | ee.Geometry, optional): Download region
95
    - scale (float, optional): Download scale in meters
96
    - crs (str, optional): Coordinate reference system
97
    - dtype (str): Output data type ('auto', 'uint8', 'uint16', 'float32', etc.)
98
    - resampling (ResamplingMethod): Resampling method for reprojection
99
    - **kwargs: Additional download parameters
100
    
101
    Returns:
102
    numpy.ndarray | xarray.Dataset: Downloaded image data
103
    """
104
```
105

106
### Region Coverage
107

108
Calculate coverage statistics for an image over a specified region.
109

110
```python { .api }
111
def regionCoverage(
112
    self,
113
    region: dict | ee.Geometry = None,
114
    scale: float | ee.Number = None,
115
    maxPixels: int = 1e6,
116
    bestEffort: bool = True
117
) -> dict:
118
    """
119
    Calculate region coverage statistics.
120
    
121
    Parameters:
122
    - region (dict | ee.Geometry, optional): Region of interest
123
    - scale (float | ee.Number, optional): Analysis scale in meters  
124
    - maxPixels (int): Maximum pixels to analyze
125
    - bestEffort (bool): Use best effort for large regions
126
    
127
    Returns:
128
    dict: Coverage statistics by band
129
    """
130
```
131

132
### GeoTIFF Export
133

134
Export an image directly to a GeoTIFF file with configurable options.
135

136
```python { .api }
137
def toGeoTIFF(
138
    self,
139
    file: os.PathLike | str | OpenFile,
140
    overwrite: bool = False,
141
    nodata: bool | int | float = True,
142
    driver: str | Driver = Driver.gtiff,
143
    **kwargs
144
) -> None:
145
    """
146
    Download and save the image as a GeoTIFF file.
147
    
148
    Parameters:
149
    - file (os.PathLike | str | OpenFile): Output file path
150
    - overwrite (bool): Whether to overwrite existing files
151
    - nodata (bool | int | float): Nodata value handling
152
    - driver (str | Driver): Output file format driver
153
    - **kwargs: Additional parameters for prepareForExport
154
    
155
    Returns:
156
    None
157
    """
158
```
159

160
### Prepare for Export
161

162
Prepare an image for export by setting projection, resampling, and other parameters.
163

164
```python { .api }
165
def prepareForExport(
166
    self,
167
    crs: str = None,
168
    crs_transform: Sequence[float] = None, 
169
    shape: tuple[int, int] = None,
170
    region: dict | ee.Geometry = None,
171
    scale: float = None,
172
    dtype: str = 'auto',
173
    resampling: ResamplingMethod | str = ResamplingMethod.near,
174
    **kwargs
175
) -> ee.Image:
176
    """
177
    Prepare image for export with specified projection and parameters.
178
    
179
    Parameters:
180
    - crs (str, optional): Target coordinate reference system
181
    - crs_transform (Sequence[float], optional): Affine transform coefficients
182
    - shape (tuple[int, int], optional): Output image dimensions (height, width)
183
    - region (dict | ee.Geometry, optional): Clipping region
184
    - scale (float, optional): Output pixel size in CRS units
185
    - dtype (str): Output data type ('auto', 'uint8', 'uint16', 'float32', etc.)
186
    - resampling (ResamplingMethod | str): Resampling method
187
    - **kwargs: Additional parameters
188
    
189
    Returns:
190
    ee.Image: Prepared image ready for export
191
    """
192
```
193

194
### Projection
195

196
Get the projection of the minimum scale band.
197

198
```python { .api }
199
def projection(self, min_scale: bool = True) -> ee.Projection:
200
    """
201
    Get the projection of the minimum or first scale band.
202
    
203
    Parameters:
204
    - min_scale (bool): Whether to use minimum scale band (True) or first band (False)
205
    
206
    Returns:
207
    ee.Projection: Image projection
208
    """
209
```
210

211
### Fixed Projection Check
212

213
Check if the image has a fixed projection.
214

215
```python { .api }
216
def fixed(self) -> ee.Number:
217
    """
218
    Check if the image has a fixed projection.
219
    
220
    Returns:
221
    ee.Number: 1 if fixed projection, 0 otherwise
222
    """
223
```
224

225
### Resample
226

227
Resample the image using the specified method.
228

229
```python { .api }
230
def resample(self, method: ResamplingMethod | str) -> ee.Image:
231
    """
232
    Resample the image using the specified resampling method.
233
    
234
    Parameters:
235
    - method (ResamplingMethod | str): Resampling method
236
    
237
    Returns:
238
    ee.Image: Resampled image
239
    """
240
```
241

242
### Convert Data Type
243

244
Convert image to the specified data type.
245

246
```python { .api }
247
def toDType(self, dtype: str) -> ee.Image:
248
    """
249
    Convert the image to the specified data type.
250
    
251
    Parameters:
252
    - dtype (str): Target data type ('uint8', 'uint16', 'int16', 'float32', etc.)
253
    
254
    Returns:
255
    ee.Image: Image with converted data type
256
    """
257
```
258

259
### Scale and Offset Correction
260

261
Apply scale and offset corrections based on STAC metadata.
262

263
```python { .api }
264
def scaleOffset(self) -> ee.Image:
265
    """
266
    Apply scale and offset corrections from STAC metadata.
267
    
268
    Returns:
269
    ee.Image: Scale and offset corrected image
270
    """
271
```
272

273
## Usage Examples
274

275
### Basic Image Processing
276

277
```python
278
import ee
279
import geedim
280

281
geedim.Initialize()
282

283
# Load and process a Landsat image
284
image = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_173083_20160101')
285

286
# Add mask bands and apply cloud masking
287
masked_image = image.gd.addMaskBands(mask_cirrus=True, mask_shadows=True).maskClouds()
288

289
# Define region of interest
290
region = ee.Geometry.Point(-122.4194, 37.7749).buffer(10000)
291

292
# Export to Google Drive
293
task = masked_image.gd.export(
294
    filename='landsat_processed',
295
    folder='geedim_exports',
296
    region=region,
297
    scale=30,
298
    type=geedim.ExportType.drive
299
)
300
task.start()
301
```
302

303
### Sentinel-2 Processing
304

305
```python
306
# Load Sentinel-2 image
307
s2_image = ee.Image('COPERNICUS/S2_SR_HARMONIZED/20200101T185751_20200101T185931_T10SEG')
308

309
# Add mask bands with cloud score method
310
masked_s2 = s2_image.gd.addMaskBands(
311
    method=geedim.CloudMaskMethod.cloud_score,
312
    prob=0.6,
313
    cloud_dist=1000
314
).maskClouds()
315

316
# Download to NumPy array
317
region = ee.Geometry.Rectangle([-122.5, 37.7, -122.3, 37.8])
318
array = masked_s2.gd.download(
319
    region=region,
320
    scale=10,
321
    dtype='uint16'
322
)
323
```
324

325
### Image Information and Properties
326

327
```python
328
# Get image information
329
info = image.gd.info
330

331
# Check if image has fixed projection
332
is_fixed = image.gd.fixed()
333

334
# Get region coverage statistics
335
coverage = image.gd.regionCoverage(
336
    region=region,
337
    scale=30,
338
    maxPixels=1e6
339
)
340
```