0
# Collection Operations
1

2
Advanced operations on Earth Engine image collections including filtering, compositing, and batch processing with cloud masking support. The collection functionality is accessed through the `.gd` accessor on `ee.ImageCollection` objects.
3

4
## Capabilities
5

6
### Image Collection Accessor
7

8
The main accessor class for Earth Engine image collections, registered as `.gd` on `ee.ImageCollection` objects.
9

10
```python { .api }
11
class ImageCollectionAccessor:
12
    def __init__(self, ee_coll: ee.ImageCollection): ...
13
```
14

15
### Filter Collection
16

17
Filter image collections based on various criteria including cloud coverage, date ranges, and geographic regions.
18

19
```python { .api }
20
def filter(
21
    self,
22
    start_date: str | datetime | ee.Date = None,
23
    end_date: str | datetime | ee.Date = None,
24
    region: dict | ee.Geometry = None,
25
    fill_portion: float | ee.Number = None,
26
    cloudless_portion: float | ee.Number = None,
27
    custom_filter: str = None,
28
    **kwargs
29
) -> ee.ImageCollection:
30
    """
31
    Filter the collection on date, region, filled/cloud-free portion, and custom criteria.
32
    
33
    Parameters:
34
    - start_date (str | datetime | ee.Date, optional): Start date, in ISO format if string
35
    - end_date (str | datetime | ee.Date, optional): End date, in ISO format if string
36
    - region (dict | ee.Geometry, optional): Geographic region filter
37
    - fill_portion (float | ee.Number, optional): Minimum fill percentage (0-100)
38
    - cloudless_portion (float | ee.Number, optional): Minimum cloudless percentage (0-100)
39
    - custom_filter (str, optional): Custom filter expression
40
    - **kwargs: Additional filter parameters
41
    
42
    Returns:
43
    ee.ImageCollection: Filtered collection
44
    """
45
```
46

47
### Create Composite
48

49
Create temporal composites from image collections using various algorithms.
50

51
```python { .api }
52
def composite(
53
    self,
54
    method: CompositeMethod = CompositeMethod.median,
55
    region: dict | ee.Geometry = None,
56
    scale: float = None,
57
    date_range: tuple = None,
58
    **kwargs
59
) -> ee.Image:
60
    """
61
    Create a composite image from the collection.
62
    
63
    Parameters:
64
    - method (CompositeMethod): Compositing algorithm
65
    - region (dict | ee.Geometry, optional): Composite region
66
    - scale (float, optional): Composite scale in meters
67
    - date_range (tuple, optional): Date range for temporal filtering
68
    - **kwargs: Additional compositing parameters
69
    
70
    Returns:
71
    ee.Image: Composite image
72
    """
73
```
74

75
### Export Collection
76

77
Export an entire image collection with various splitting and organization options.
78

79
```python { .api }
80
def export(
81
    self,
82
    description: str,
83
    folder: str = None,
84
    region: dict | ee.Geometry = None,
85
    scale: float = None,
86
    split: str = 'images',
87
    export_type: ExportType = ExportType.drive,
88
    **kwargs
89
) -> list[ee.batch.Task]:
90
    """
91
    Export the image collection.
92
    
93
    Parameters:
94
    - description (str): Base description for export tasks
95
    - folder (str, optional): Destination folder name
96
    - region (dict | ee.Geometry, optional): Export region
97
    - scale (float, optional): Export scale in meters
98
    - split (str): Split method ('images' or 'bands')
99
    - export_type (ExportType): Export destination type
100
    - **kwargs: Additional export parameters
101
    
102
    Returns:
103
    list[ee.batch.Task]: List of export tasks
104
    """
105
```
106

107
### Download Collection
108

109
Download an entire collection to local storage with parallel processing.
110

111
```python { .api }
112
def download(
113
    self,
114
    region: dict | ee.Geometry = None,
115
    scale: float = None,
116
    max_images: int = None,
117
    concurrent: int = 4,
118
    **kwargs
119
) -> list:
120
    """
121
    Download the image collection.
122
    
123
    Parameters:
124
    - region (dict | ee.Geometry, optional): Download region
125
    - scale (float, optional): Download scale in meters
126
    - max_images (int, optional): Maximum number of images to download
127
    - concurrent (int): Number of concurrent downloads
128
    - **kwargs: Additional download parameters
129
    
130
    Returns:
131
    list: List of downloaded image data
132
    """
133
```
134

135
### Add Mask Bands to Collection
136

137
Add cloud mask bands to all images in a collection.
138

139
```python { .api }
140
def addMaskBands(self, **kwargs) -> ee.ImageCollection:
141
    """
142
    Add mask bands to all images in the collection.
143
    
144
    Parameters:
145
    - **kwargs: Cloud masking parameters applied to all images
146
    
147
    Returns:
148
    ee.ImageCollection: Collection with mask bands added
149
    """
150
```
151

152
### Mask Clouds in Collection
153

154
Apply cloud masking to all images in a collection.
155

156
```python { .api }
157
def maskClouds(self) -> ee.ImageCollection:
158
    """
159
    Apply cloud masking to all images in the collection.
160
    
161
    Returns:
162
    ee.ImageCollection: Cloud-masked collection
163
    """
164
```
165

166
### Create Collection from Images
167

168
Create a new collection from a list of images with cloud masking support.
169

170
```python { .api }
171
@staticmethod
172
def fromImages(images: list | ee.List) -> ee.ImageCollection:
173
    """
174
    Create an image collection with cloud masking support.
175
    
176
    Parameters:
177
    - images: Sequence of images or anything that can construct an image
178
    
179
    Returns:
180
    ee.ImageCollection: Collection with cloud masking support
181
    """
182
```
183

184
### Collection Properties and Schema
185

186
Access collection metadata, properties, and schema information.
187

188
```python { .api }
189
@property
190
def properties(self) -> dict:
191
    """Get collection properties as a dictionary."""
192

193
@property  
194
def schema(self) -> dict:
195
    """Get collection schema information."""
196

197
@property
198
def info(self) -> dict:
199
    """Get collection info including size and date range."""
200

201
@property
202
def schemaPropertyNames(self) -> tuple[str]:
203
    """Get names of properties to include in schema."""
204

205
@property
206
def schemaTable(self) -> str:
207
    """Get formatted table of schema information."""
208

209
@property  
210
def propertiesTable(self) -> str:
211
    """Get formatted table of collection properties."""
212
```
213

214
### Medoid Composite
215

216
Create a medoid composite from the collection using spectral distance metrics.
217

218
```python { .api }
219
def medoid(self, bands: list | ee.List = None) -> ee.Image:
220
    """
221
    Create a medoid composite using spectral distance metrics.
222
    
223
    Parameters:
224
    - bands (list | ee.List, optional): Bands to use for medoid calculation
225
    
226
    Returns:
227
    ee.Image: Medoid composite image
228
    """
229
```
230

231
## Usage Examples
232

233
### Basic Collection Processing
234

235
```python
236
import ee
237
import geedim
238
from datetime import datetime
239

240
geedim.Initialize()
241

242
# Load and filter a Landsat collection
243
collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2') \
244
    .filterDate('2020-01-01', '2020-12-31') \
245
    .filterBounds(ee.Geometry.Point(-122.4194, 37.7749).buffer(50000))
246

247
# Search with cloud filtering
248
filtered = collection.gd.search(
249
    start_date='2020-06-01',
250
    end_date='2020-09-30',
251
    cloudless_portion=75,
252
    fill_portion=90
253
)
254

255
print(f"Found {filtered.size().getInfo()} images")
256
```
257

258
### Create Composites
259

260
```python
261
# Create median composite
262
region = ee.Geometry.Rectangle([-122.5, 37.7, -122.3, 37.8])
263

264
median_composite = collection.gd.composite(
265
    method=geedim.CompositeMethod.median,
266
    region=region,
267
    scale=30
268
)
269

270
# Create quality mosaic (best pixel based on cloud distance)
271
quality_composite = collection.gd.composite(
272
    method=geedim.CompositeMethod.q_mosaic,
273
    region=region,
274
    scale=30
275
)
276

277
# Create medoid composite
278
medoid_composite = collection.gd.composite(
279
    method=geedim.CompositeMethod.medoid,
280
    region=region,
281
    scale=30
282
)
283
```
284

285
### Batch Export
286

287
```python
288
# Export entire collection split by images
289
tasks = collection.gd.export(
290
    description='landsat_collection',
291
    folder='batch_export',
292
    region=region,
293
    scale=30,
294
    split='images',
295
    export_type=geedim.ExportType.drive
296
)
297

298
# Start all export tasks
299
for task in tasks:
300
    task.start()
301

302
# Export split by bands
303
band_tasks = collection.gd.export(
304
    description='landsat_bands',
305
    folder='band_export',  
306
    region=region,
307
    scale=30,
308
    split='bands',
309
    export_type=geedim.ExportType.cloud
310
)
311
```
312

313
### Collection Analysis
314

315
```python
316
# Get collection properties
317
props = collection.gd.properties
318
date_range = props.get('date_range')
319
image_count = props.get('count')
320

321
# Get schema information
322
schema = collection.gd.schema
323
property_names = schema.get('properties', [])
324

325
# Analyze cloud coverage
326
cloud_stats = collection.gd.cloudCoverage(region=region)
327
```
328

329
### Advanced Filtering
330

331
```python
332
# Create collection from specific images
333
image_ids = [
334
    'LANDSAT/LC08/C02/T1_L2/LC08_173083_20200601',
335
    'LANDSAT/LC08/C02/T1_L2/LC08_173083_20200717',
336
    'LANDSAT/LC08/C02/T1_L2/LC08_173083_20200802'
337
]
338

339
images = [ee.Image(img_id) for img_id in image_ids]
340
custom_collection = ee.ImageCollection.gd.fromImages(images)
341

342
# Add mask bands and mask clouds for entire collection
343
masked_collection = custom_collection.gd.addMaskBands(
344
    mask_cirrus=True,
345
    mask_shadows=True
346
).maskClouds()
347
```