Image Composite

Create multi-temporal image composites from local GeoTIFF files. Supports cloud masking and multiple compositing methods. Works with Landsat and Sentinel-2 data.

Features

• Median, mean, maxNDVI, and minRed compositing
• Cloud masking via QA band or threshold
• Landsat and Sentinel-2 band naming support
• Handles multiple input files with progress reporting

Requirements

pip install rasterio numpy tqdm

Usage

# Median composite of multiple scenes
python scripts\image-composite.py composite --inputs scene1.tif scene2.tif scene3.tif --output composite.tif

# Mean composite
python scripts\image-composite.py composite --inputs *.tif --method mean --output mean_composite.tif

# maxNDVI composite (best vegetation)
python scripts\image-composite.py composite --inputs *.tif --method maxNDVI --output ndvi_composite.tif

# Cloud masking
python scripts\image-composite.py cloud-mask --input scene.tif --threshold 0.3 --output masked.tif

Installation

pip install rasterio numpy tqdm
# Or: pip install -r scripts/requirements.txt

Parameters

composite

Argument	Required	Default	Description
--inputs	Yes	—	Input GeoTIFF files (2+)
--output	Yes	—	Output composite path
--method	No	median	Compositing method: median, mean, maxNDVI, minRed
--cloud-mask	No	—	Optional cloud mask file

cloud-mask

Argument	Required	Default	Description
--input	Yes	—	Input GeoTIFF file
--qa-band	No	—	QA band name or index
--threshold	No	0.3	Cloud threshold (0-1)
--output	Yes	—	Output masked file

Data Source

• Input: Local GeoTIFF files (no download)
• Processing: 100% local

maxNDVI Pixel Selection

The maxNDVI method selects, for each pixel position, the scene that has the highest NDVI value at that location. This produces a composite with the greenest, healthiest vegetation — ideal for creating cloud-free, maximum vegetation composites. NDVI is calculated as (NIR - Red) / (NIR + Red).

Band Requirements by Method

Method	Required Bands	Description
median	Any	Median of all valid pixels
mean	Any	Mean of all valid pixels
maxNDVI	Red + NIR	Selects pixel with highest NDVI
minRed	Red	Selects pixel with lowest red reflectance

Handling Mismatched Extents/Resolutions

• Same extent, same resolution: Direct compositing (default)
• Different resolution: Auto-reproject to finest resolution using nearest-neighbor
• Different extent: Intersection of all extents (output covers overlapping area only)
• Different CRS: Auto-reproject to first input's CRS
• Use --target-crs and --target-resolution to override

QA Band Format (Landsat QA_PIXEL)

The QA_PIXEL band uses bit flags for cloud/shadow detection:

Bit	Name	Value	Description
0	Fill	0/1	Fill data
1	Dilated Cloud	0/1	Dilated cloud
2	Cirrus	0/1	Cirrus (Landsat 8/9)
3	Cloud	0/1	Cloud
4	Cloud Shadow	0/1	Cloud shadow
5	Snow	0/1	Snow
6	Clear	0/1	Clear
7	Water	0/1	Water

• Cloud-free pixels: bits 3-4 are 0
• Use --qa-bit 3 to mask clouds, --qa-bit 3,4 for cloud + shadow

Memory Management

• For large scenes (>2GB each), process in sequential mode with --sequential
• Use --max-memory 4096 to limit RAM usage (MB)
• Close other applications when compositing many high-res scenes
• Output is written incrementally to reduce peak memory

Output Data Type

• Default: preserves source data type (e.g., uint16 stays uint16)
• Specify with --dtype: uint8, uint16, float32
• Use --dtype float32 for methods requiring decimal precision (mean, median)

Landsat / Sentinel-2 Band Mapping

Band	Landsat 8/9	Sentinel-2
Blue	SR_B2	B2
Green	SR_B3	B3
Red	SR_B4	B4
NIR	SR_B5	B8
SWIR1	SR_B6	B11
SWIR2	SR_B7	B12
QA_PIXEL	QA_PIXEL	SCL (Scene Classification)

Nodata Handling

• Source nodata values are excluded from compositing
• Output nodata: same as first input's nodata value
• Use --nodata VALUE to set custom nodata
• Pixels with nodata in ALL scenes remain nodata in output

Visualization

• Quick preview: rasterio.plot.show(composite, cmap='terrain')
• RGB composite: stack Red/Green/Blue bands with matplotlib
• NDVI visualization: plt.imshow(ndvi, cmap='RdYlGn', vmin=-1, vmax=1)
• Side-by-side comparison: use matplotlib subplots for before/after
• Export to PNG: rasterio.plot.show(out_file='preview.png')

Troubleshooting

Error	Cause	Solution
ConnectionError	Network issue	Check internet, retry
HTTP 429	Rate limit	Wait 60s, retry
ValueError	Invalid input	Check parameter format
Empty output	No data	Try different parameters
ModuleNotFoundError	Missing dep	Run pip install
MemoryError	Too many scenes	Use --sequential or --max-memory
CRSError	CRS mismatch	Use --target-crs to unify
Band not found	Wrong naming	Check band mapping table above

Citation

If you use this tool in your research, please cite the input data sources (e.g., USGS Landsat, ESA Sentinel-2) and acknowledge the compositing methodology:

@software{image_composite_2024,
  author = {ruiduobao},
  title = {Image Composite Tool},
  year = {2024},
  note = {Multi-temporal image compositing for Landsat/Sentinel-2}
}

For Landsat data: "Landsat data are provided by the U.S. Geological Survey and/or the National Aeronautics and Space Administration." For Sentinel-2 data: "Copernicus Sentinel data [2024] processed by ESA."

---

Advanced Usage

Weekly Composite Pipeline

# Composite all scenes from a week
python scripts\image-composite.py composite   --images S2A_20230101.tif S2A_20230105.tif S2A_20230110.tif   --method maxNDVI --sensor sentinel2   --output composite_week1.tif

CI/CD Integration (GitHub Actions)

# .github/workflows/weekly-composite.yml
name: Weekly Image Composite
on:
  schedule:
    - cron: '0 12 * * 1'  # Every Monday at 12:00
jobs:
  composite:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install numpy rasterio
      - run: |
          python scripts\image-composite.py composite \
            --images data/scenes/*.tif \
            --method maxNDVI --sensor sentinel2 \
            --output data/composite_$(date +%Y%m%d).tif

Zonal Statistics with rasterio + GeoPandas

import rasterio
import geopandas as gpd
from rasterio.features import geometry_mask

with rasterio.open('composite.tif') as src:
    img = src.read(1)
    profile = src.profile

# Compute zonal stats for polygons
gdf = gpd.read_file('aoi.gdf')

Performance Tips

• Use --max-memory to limit RAM usage for large scenes
• --sequential mode reads one band at a time (slower but memory-safe)
• Mismatched extents are handled by intersection; use --reference to control output grid

---

中文说明

从本地 GeoTIFF 文件创建多时相影像合成。支持云掩膜和多种合成方法。兼容 Landsat 和 Sentinel-2 数据。

功能

• 中位数、平均值、最大 NDVI、最小红波段合成
• 通过 QA 波段或阈值进行云掩膜
• 支持 Landsat 和 Sentinel-2 波段命名
• 多文件输入带进度报告

依赖

pip install rasterio numpy tqdm

使用方法

# 中位数合成
python scripts\image-composite.py composite --inputs scene1.tif scene2.tif scene3.tif --output composite.tif

# 平均值合成
python scripts\image-composite.py composite --inputs *.tif --method mean --output mean_composite.tif

# 最大 NDVI 合成（最佳植被）
python scripts\image-composite.py composite --inputs *.tif --method maxNDVI --output ndvi_composite.tif

# 云掩膜
python scripts\image-composite.py cloud-mask --input scene.tif --threshold 0.3 --output masked.tif

数据来源

• 输入: 本地 GeoTIFF 文件（无下载）
• 处理: 完全本地

maxNDVI 像素选择说明

maxNDVI 方法在每个像素位置选择 NDVI 值最高 的场景。这样生成的合成影像具有最绿、最健康的植被——适合创建无云、最大植被覆盖的合成影像。NDVI 计算公式: (NIR - Red) / (NIR + Red)。

各合成方法的波段需求

方法	所需波段	描述
median	任意	所有有效像素的中位数
mean	任意	所有有效像素的平均值
maxNDVI	红 + 近红外	选择 NDVI 最高的像素
minRed	红波段	选择红反射率最低的像素

不匹配范围/分辨率的处理

• 相同范围、相同分辨率: 直接合成（默认）
• 不同分辨率: 使用最近邻法自动重投影到最高分辨率
• 不同范围: 所有范围的交集（输出仅覆盖重叠区域）
• 不同坐标系: 自动重投影到第一个输入的 CRS
• 使用 --target-crs 和 --target-resolution 覆盖默认行为

QA 波段格式 (Landsat QA_PIXEL)

QA_PIXEL 波段使用位标志进行云/阴影检测:

位	名称	值	描述
0	Fill	0/1	填充数据
1	Dilated Cloud	0/1	膨胀云
2	Cirrus	0/1	卷云（Landsat 8/9）
3	Cloud	0/1	云
4	Cloud Shadow	0/1	云阴影
5	Snow	0/1	雪
6	Clear	0/1	晴空
7	Water	0/1	水体

• 无云像素: 位 3-4 为 0
• 使用 --qa-bit 3 掩膜云，--qa-bit 3,4 掩膜云+阴影

内存管理

• 大场景（>2GB/个）使用 --sequential 顺序处理
• 使用 --max-memory 4096 限制内存使用（MB）
• 合成多个高分辨率场景时关闭其他应用程序
• 输出增量写入以降低峰值内存

输出数据类型

• 默认: 保留源数据类型（如 uint16 保持 uint16）
• 使用 --dtype 指定: uint8, uint16, float32
• 需要小数精度的方法（mean, median）使用 --dtype float32

Landsat / Sentinel-2 波段映射表

波段	Landsat 8/9	Sentinel-2
蓝	SR_B2	B2
绿	SR_B3	B3
红	SR_B4	B4
近红外	SR_B5	B8
短波红外1	SR_B6	B11
短波红外2	SR_B7	B12
QA_PIXEL	QA_PIXEL	SCL (场景分类)

无数据值处理

• 合成时排除源 nodata 值
• 输出 nodata: 与第一个输入的 nodata 值相同
• 使用 --nodata VALUE 设置自定义 nodata
• 所有场景中均为 nodata 的像素在输出中仍为 nodata

可视化

• 快速预览: rasterio.plot.show(composite, cmap='terrain')
• RGB 合成: 使用 matplotlib 堆叠 Red/Green/Blue 波段
• NDVI 可视化: plt.imshow(ndvi, cmap='RdYlGn', vmin=-1, vmax=1)
• 并排比较: 使用 matplotlib subplots 显示前后对比
• 导出 PNG: rasterio.plot.show(out_file='preview.png')

故障排除

错误	原因	解决方案
ConnectionError	网络问题	检查网络，重试
HTTP 429	速率限制	等待 60 秒后重试
ValueError	无效输入	检查参数格式
空输出	无数据	尝试不同参数
ModuleNotFoundError	缺少依赖	运行 pip install
MemoryError	场景过多	使用 --sequential 或 --max-memory
CRSError	坐标系不匹配	使用 --target-crs 统一
波段未找到	命名错误	查看上方波段映射表