0
# Compositing
1

2
Create temporal composites from image collections using various algorithms including median, medoid, q-mosaic, and statistical methods. Geedim provides sophisticated compositing capabilities that leverage cloud masking for optimal pixel selection.
3

4
## Capabilities
5

6
### Composite Methods
7

8
Enumeration of available compositing algorithms.
9

10
```python { .api }
11
class CompositeMethod(Enum):
12
    """Enumeration for compositing methods."""
13
    
14
    q_mosaic = 'q-mosaic'
15
    """
16
    Use the unmasked pixel with the highest cloud distance (distance to nearest
17
    cloud). When more than one pixel has the same cloud distance, the first one 
18
    is used.
19
    """
20
    
21
    mosaic = 'mosaic'
22
    """Use the first unmasked pixel."""
23
    
24
    medoid = 'medoid'
25
    """
26
    Medoid of the unmasked pixels - the pixel from the image with the minimum
27
    sum of spectral distances to the rest of the images. Where more than one 
28
    pixel has the same summed distance, the first one is used.
29
    """
30
    
31
    median = 'median'
32
    """Median of the unmasked pixels."""
33
    
34
    mode = 'mode'
35
    """Mode of the unmasked pixels."""
36
    
37
    mean = 'mean'
38
    """Mean of the unmasked pixels."""
39
```
40

41
### Spectral Distance Metrics
42

43
Metrics used for medoid compositing calculations.
44

45
```python { .api }
46
class SpectralDistanceMetric(Enum):
47
    """Enumeration for spectral distance metrics."""
48
    
49
    sam = 'sam'
50
    """Spectral angle mapper."""
51
    
52
    sid = 'sid'
53
    """Spectral information divergence."""
54
    
55
    sed = 'sed'
56
    """Squared euclidean distance."""
57
    
58
    emd = 'emd'
59
    """Earth movers distance."""
60
```
61

62
### Create Composite
63

64
Create temporal composites from image collections with advanced parameter control.
65

66
```python { .api }
67
def composite(
68
    self,
69
    method: CompositeMethod = CompositeMethod.median,
70
    region: dict | ee.Geometry = None,
71
    scale: float = None,
72
    bands: list[str] = None,
73
    date_range: tuple[str, str] = None,
74
    cloud_filter: float = None,
75
    **kwargs
76
) -> ee.Image:
77
    """
78
    Create a temporal composite from the image collection.
79
    
80
    Parameters:
81
    - method (CompositeMethod): Compositing algorithm to use
82
    - region (dict | ee.Geometry, optional): Composite region bounds
83
    - scale (float, optional): Composite scale in meters
84
    - bands (list[str], optional): Bands to include in composite
85
    - date_range (tuple, optional): Date range as (start_date, end_date)
86
    - cloud_filter (float, optional): Maximum cloud percentage (0-100)
87
    - **kwargs: Additional compositing parameters
88
    
89
    Returns:
90
    ee.Image: Composite image with metadata properties
91
    """
92
```
93

94
### Medoid Compositing
95

96
Specialized medoid compositing with configurable distance metrics.
97

98
```python { .api }
99
def medoid_composite(
100
    collection: ee.ImageCollection,
101
    bands: list[str] = None,
102
    metric: SpectralDistanceMetric = SpectralDistanceMetric.sed,
103
    region: dict | ee.Geometry = None,
104
    scale: float = None
105
) -> ee.Image:
106
    """
107
    Create medoid composite using spectral distance calculations.
108
    
109
    Parameters:
110
    - collection (ee.ImageCollection): Input image collection
111
    - bands (list[str], optional): Bands to use for distance calculations
112
    - metric (SpectralDistanceMetric): Distance metric algorithm
113
    - region (dict | ee.Geometry, optional): Analysis region
114
    - scale (float, optional): Analysis scale in meters
115
    
116
    Returns:
117
    ee.Image: Medoid composite image
118
    """
119
```
120

121
### Quality Mosaic
122

123
Create quality-based mosaics using cloud distance information.
124

125
```python { .api }
126
def quality_mosaic(
127
    collection: ee.ImageCollection,
128
    region: dict | ee.Geometry = None,
129
    scale: float = None,
130
    max_cloud_dist: float = 5000
131
) -> ee.Image:
132
    """
133
    Create quality mosaic based on cloud distance.
134
    
135
    Parameters:
136
    - collection (ee.ImageCollection): Input image collection
137
    - region (dict | ee.Geometry, optional): Mosaic region
138
    - scale (float, optional): Mosaic scale in meters
139
    - max_cloud_dist (float): Maximum cloud distance in meters
140
    
141
    Returns:
142
    ee.Image: Quality mosaic image
143
    """
144
```
145

146
## Usage Examples
147

148
### Basic Compositing
149

150
```python
151
import ee
152
import geedim
153

154
geedim.Initialize()
155

156
# Load image collection
157
collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2') \
158
    .filterDate('2020-06-01', '2020-09-30') \
159
    .filterBounds(ee.Geometry.Point(-122.4194, 37.7749).buffer(50000))
160

161
# Add cloud masking to collection
162
masked_collection = collection.gd.addMaskBands(
163
    mask_cirrus=True,
164
    mask_shadows=True
165
).maskClouds()
166

167
# Define region of interest  
168
region = ee.Geometry.Rectangle([-122.5, 37.7, -122.3, 37.8])
169

170
# Create median composite
171
median_composite = masked_collection.gd.composite(
172
    method=geedim.CompositeMethod.median,
173
    region=region,
174
    scale=30
175
)
176

177
print("Median composite created")
178
```
179

180
### Advanced Compositing Methods
181

182
```python
183
# Quality mosaic - selects best pixels based on cloud distance
184
quality_composite = masked_collection.gd.composite(
185
    method=geedim.CompositeMethod.q_mosaic,
186
    region=region,
187
    scale=30,
188
    bands=['B2', 'B3', 'B4', 'B5', 'B6', 'B7']  # Specific bands
189
)
190

191
# Medoid composite - spectrally representative pixels
192
medoid_composite = masked_collection.gd.composite(
193
    method=geedim.CompositeMethod.medoid,
194
    region=region,
195
    scale=30,
196
    bands=['B4', 'B5'],  # Use NIR and Red for medoid calculation
197
    metric=geedim.SpectralDistanceMetric.sam  # Spectral angle mapper
198
)
199

200
# Statistical composites
201
mean_composite = masked_collection.gd.composite(
202
    method=geedim.CompositeMethod.mean,
203
    region=region,
204
    scale=30
205
)
206

207
mode_composite = masked_collection.gd.composite(
208
    method=geedim.CompositeMethod.mode,
209
    region=region,
210
    scale=30
211
)
212
```
213

214
### Seasonal Compositing
215

216
```python
217
# Create seasonal composites
218
seasons = {
219
    'spring': ('2020-03-01', '2020-05-31'),
220
    'summer': ('2020-06-01', '2020-08-31'),
221
    'fall': ('2020-09-01', '2020-11-30'),
222
    'winter': ('2020-12-01', '2021-02-28')
223
}
224

225
seasonal_composites = {}
226

227
for season, (start_date, end_date) in seasons.items():
228
    # Filter collection by season
229
    seasonal_collection = collection \
230
        .filterDate(start_date, end_date) \
231
        .gd.addMaskBands().maskClouds()
232
    
233
    # Create composite for season
234
    composite = seasonal_collection.gd.composite(
235
        method=geedim.CompositeMethod.median,
236
        region=region,
237
        scale=30,
238
        cloud_filter=50  # Max 50% cloud cover
239
    )
240
    
241
    seasonal_composites[season] = composite
242
    print(f"{season.capitalize()} composite created")
243

244
# Export seasonal composites
245
for season, composite in seasonal_composites.items():
246
    task = composite.gd.export(
247
        description=f'landsat_{season}_composite',
248
        folder='seasonal_composites',
249
        region=region,
250
        scale=30
251
    )
252
    task.start()
253
```
254

255
### Multi-Sensor Compositing
256

257
```python
258
# Combine Landsat 8 and 9 collections
259
l8_collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2') \
260
    .filterDate('2020-01-01', '2020-12-31') \
261
    .filterBounds(region)
262

263
l9_collection = ee.ImageCollection('LANDSAT/LC09/C02/T1_L2') \
264
    .filterDate('2020-01-01', '2020-12-31') \
265
    .filterBounds(region)
266

267
# Merge collections (spectrally compatible)
268
combined_collection = l8_collection.merge(l9_collection)
269

270
# Add cloud masking
271
masked_combined = combined_collection.gd.addMaskBands(
272
    mask_cirrus=True,
273
    mask_shadows=True
274
).maskClouds()
275

276
# Create multi-sensor composite
277
multi_sensor_composite = masked_combined.gd.composite(
278
    method=geedim.CompositeMethod.q_mosaic,
279
    region=region,
280
    scale=30
281
)
282
```
283

284
### Composite Analysis and Metadata
285

286
```python
287
# Create composite with metadata analysis
288
composite = masked_collection.gd.composite(
289
    method=geedim.CompositeMethod.median,
290
    region=region,
291
    scale=30
292
)
293

294
# Get composite metadata
295
composite_info = composite.getInfo()
296
print(f"Composite bands: {[band['id'] for band in composite_info['bands']]}")
297

298
# Get image count used in composite
299
image_count = composite.get('COMPOSITE_COUNT').getInfo()
300
print(f"Images used in composite: {image_count}")
301

302
# Get date range of source images
303
date_range = composite.get('DATE_RANGE').getInfo()
304
print(f"Date range: {date_range}")
305

306
# Analyze composite quality
307
quality_bands = ['FILL_MASK', 'CLOUDLESS_MASK']
308
if any(band in [b['id'] for b in composite_info['bands']] for band in quality_bands):
309
    # Calculate quality statistics
310
    quality_stats = composite.select(quality_bands).gd.regionCoverage(
311
        region=region,
312
        scale=120  # Lower resolution for faster analysis
313
    )
314
    print(f"Composite quality: {quality_stats}")
315
```
316

317
### Custom Compositing Workflows
318

319
```python
320
def create_best_pixel_composite(collection, region, scale=30):
321
    """Create composite using best available pixels."""
322
    
323
    # Add mask bands to collection
324
    masked_collection = collection.gd.addMaskBands().maskClouds()
325
    
326
    # Filter for high-quality images
327
    high_quality = masked_collection.gd.search(
328
        cloudless_portion=80,
329
        fill_portion=95
330
    )
331
    
332
    # Create quality mosaic if enough high-quality images
333
    image_count = high_quality.size().getInfo()
334
    
335
    if image_count >= 5:
336
        # Use quality mosaic for best pixels
337
        composite = high_quality.gd.composite(
338
            method=geedim.CompositeMethod.q_mosaic,
339
            region=region,
340
            scale=scale
341
        )
342
    elif image_count >= 2:
343
        # Use median for fewer images
344
        composite = high_quality.gd.composite(
345
            method=geedim.CompositeMethod.median,
346
            region=region,
347
            scale=scale
348
        )
349
    else:
350
        # Use simple mosaic as fallback
351
        composite = masked_collection.gd.composite(
352
            method=geedim.CompositeMethod.mosaic,
353
            region=region,
354
            scale=scale
355
        )
356
    
357
    return composite.set('IMAGES_USED', image_count)
358

359
# Apply custom compositing
360
custom_composite = create_best_pixel_composite(collection, region)
361
images_used = custom_composite.get('IMAGES_USED').getInfo()
362
print(f"Custom composite used {images_used} images")
363
```
364

365
### Temporal Compositing
366

367
```python
368
# Create monthly composites for a year
369
import calendar
370

371
monthly_composites = {}
372

373
for month in range(1, 13):
374
    # Get month date range
375
    start_date = f'2020-{month:02d}-01'
376
    if month == 12:
377
        end_date = '2020-12-31'
378
    else:
379
        end_date = f'2020-{month+1:02d}-01'
380
    
381
    # Filter collection by month
382
    monthly_collection = collection \
383
        .filterDate(start_date, end_date) \
384
        .gd.addMaskBands().maskClouds()
385
    
386
    # Create monthly composite
387
    monthly_composite = monthly_collection.gd.composite(
388
        method=geedim.CompositeMethod.median,
389
        region=region,
390
        scale=30
391
    )
392
    
393
    month_name = calendar.month_name[month].lower()
394
    monthly_composites[month_name] = monthly_composite
395
    
396
    print(f"{month_name.capitalize()} composite created")
397

398
# Create annual composite from monthly composites
399
annual_collection = ee.ImageCollection.fromImages(
400
    list(monthly_composites.values())
401
)
402

403
annual_composite = annual_collection.gd.composite(
404
    method=geedim.CompositeMethod.median,
405
    region=region,
406
    scale=30
407
)
408
```