Satellite Change Detection

 pip install satchange

A hands-on tutorial. Map deforestation, mining, urbanisation, floods, burns and surface-water change anywhere on Earth from free satellite data — then export georeferenced GeoTIFFs and print-ready maps. All in Python, powered by Google Earth Engine and Microsoft Planetary Computer.

Tutorial praktis. Petakan deforestasi, tambang, urbanisasi, banjir, kebakaran, dan perubahan air permukaan di mana saja dari data satelit gratis — lalu ekspor GeoTIFF tergeoreferensi dan peta siap cetak. Semua dengan Python, ditenagai Google Earth Engine dan Microsoft Planetary Computer.

1 · What you'll buildYang akan Anda buat

By the end you'll run a single command like this…

Di akhir tutorial, Anda menjalankan satu perintah seperti ini…

satchange -s deforestation --lat -3.333 --lon 122.25 --radius 6 --map

…and get three things for your chosen area:

…dan mendapat tiga berkas untuk area pilihan Anda:

• a quick-look PNG of the change,
• a full-resolution, georeferenced GeoTIFF you can open in QGIS/ArcGIS, and
• a value-added map (A4 PDF + PNG) with legend, scale bar, statistics and a location inset.

• PNG pratinjau perubahan,
• GeoTIFF resolusi penuh tergeoreferensi yang bisa dibuka di QGIS/ArcGIS, dan
• peta value-added (A4 PDF + PNG) dengan legenda, skala, statistik, dan inset lokasi.

You pick a scenario (what kind of change) and a location (a coordinate). The tool selects the right remote-sensing method automatically. No prior GIS coding required.

Anda memilih skenario (jenis perubahan) dan lokasi (koordinat). Alat memilih metode penginderaan jauh yang tepat secara otomatis. Tanpa perlu pengalaman pemrograman GIS.

2 · How it works (the science)Cara kerjanya (sainsnya)

“Change detection” compares the landscape at two (or more) points in time and highlights what changed. Different phenomena leave different spectral or radar fingerprints, so each scenario uses a purpose-built index or method:

“Deteksi perubahan” membandingkan bentang lahan pada dua (atau lebih) titik waktu dan menonjolkan apa yang berubah. Fenomena berbeda meninggalkan sidik jari spektral atau radar yang berbeda, sehingga tiap skenario memakai indeks atau metode khusus:

How clouds are handledCara menangani awan

Optical scenarios never rely on a single image. For each period the tool builds a cloud-masked median composite of many Sentinel-2 scenes: every scene is masked pixel-by-pixel using the Scene Classification (SCL) band, then the median is taken. The result is effectively cloud-free even in cloudy regions. The standalone Sentinel-2 downloader additionally prefers a single scene with ≤10% cloud, falling back to the composite when none exists.

Skenario optik tak pernah bergantung pada satu citra. Untuk tiap periode, alat menyusun median composite bebas awan dari banyak scene Sentinel-2: tiap scene di-mask per-piksel memakai band Scene Classification (SCL), lalu diambil mediannya. Hasilnya praktis bebas awan bahkan di wilayah berawan. Pengunduh Sentinel-2 mandiri juga mengutamakan satu scene dengan awan ≤10%, dan beralih ke composite bila tak ada.

3 · SetupPersiapan

You need Python 3.11+. The Earth Engine backend needs a free Google Earth Engine account (sign up); the Planetary Computer backend needs no account at all.

Anda memerlukan Python 3.11+. Backend Earth Engine butuh akun Google Earth Engine gratis (daftar); backend Planetary Computer tanpa akun sama sekali.

1. Install the packagePasang paket

   pip install 'satchange[all]'          # everything
   # or leaner:  pip install 'satchange[gee]'  ·  pip install 'satchange[mpc,maps]'

   Gives you the satchange and satmap commands. To work from source instead: git clone https://github.com/firmanhadi21/rs-change-detection && cd rs-change-detection && pip install -e '.[all]' — then python3 detect.py … works identically. Memberi perintah satchange dan satmap. Untuk memakai dari sumber: git clone https://github.com/firmanhadi21/rs-change-detection && cd rs-change-detection && pip install -e '.[all]' — lalu python3 detect.py … berfungsi sama.
2. Authenticate Earth Engine (GEE backend only)Autentikasi Earth Engine (backend GEE saja)

   earthengine authenticate

   Opens a browser to link your Google account. To use a service-account key from any directory, point satchange at it with --ee-key /path/to/ee-geodetic.json, or export SATCHANGE_EE_KEY=/path/to/ee-geodetic.json, or copy it to ~/.config/earthengine/ee-geodetic.json. (A key at ./scripts/config/ee-geodetic.json only works when you run from the repo root.) Skip this entirely with --backend mpc. Membuka browser untuk menautkan akun Google. Untuk memakai kunci service account dari direktori mana pun, arahkan satchange dengan --ee-key /path/ke/ee-geodetic.json, atau export SATCHANGE_EE_KEY=/path/ke/ee-geodetic.json, atau salin ke ~/.config/earthengine/ee-geodetic.json. (Kunci di ./scripts/config/ee-geodetic.json hanya berlaku saat dijalankan dari root repo.) Lewati dengan --backend mpc.
3. Check it's workingCek berjalan

   satchange --list

   Should print the six available scenarios. Harusnya menampilkan enam skenario.

4 · Your first detectionDeteksi pertama Anda

Let's map vegetation loss around a coordinate. Pick any lat/lon (decimal degrees; south and west are negative).

Mari petakan kehilangan vegetasi di sekitar koordinat. Pilih lat/lon apa saja (derajat desimal; selatan dan barat negatif).

satchange -s deforestation --lat -3.333 --lon 122.25 --radius 6

The tool builds a square area of interest (half-side = radius km), makes a cloud-free Sentinel-2 NDVI composite for a baseline year and a recent year, subtracts them, and downloads the result. You'll see something like:

Alat membangun area minat persegi (setengah-sisi = radius km), membuat composite NDVI Sentinel-2 bebas awan untuk tahun dasar dan tahun terkini, menguranginya, lalu mengunduh hasilnya. Anda akan melihat kira-kira:

=== Change detection: deforestation ===
Location: -3.333, 122.25  radius 6.0 km  [m3p333_122p25]
Downloading dndvi PNG...    Saved: images/deforestation_dndvi_m3p333_122p25.png
Downloading dndvi GeoTIFF... Saved: data/deforestation_dndvi_m3p333_122p25.tif
=== Results ===
  "pct_affected": 6.3, "pct_severe": 2.7, "scenes_pre": 30, "scenes_post": 25 …

5 · Reading the outputsMembaca keluaran

For optical scenarios the change layer uses a diverging palette: red = loss, pale = little change, green = gain. The stats.json quantifies it — e.g. pct_affected is the share of the area whose change passed the threshold.

Untuk skenario optik, layer perubahan memakai palet divergen: merah = kehilangan, pucat = sedikit berubah, hijau = pertambahan. stats.json mengukurnya — mis. pct_affected adalah proporsi area yang perubahannya melewati ambang.

6 · Every scenarioSetiap skenario

List them any time with satchange --list. Commands:

Lihat daftarnya kapan saja dengan satchange --list. Perintah:

# Deforestation / vegetation loss (default baseline vs recent year)
satchange -s deforestation --lat -3.333 --lon 122.25

# Mining — radar temporal (SIRAD) + NDVI loss, two products
satchange -s mining --lat -3.333 --lon 122.25
#   set the 3 SIRAD periods (R/G/B) yourself with --epochs:
satchange -s mining --lat -3.333 --lon 122.25 \
    --epochs 2024-01-01:2024-06-30,2024-07-01:2024-12-31,2025-01-01:2025-06-30

# Urbanisation — built-up (NDBI) gain
satchange -s urbanization --lat -6.2 --lon 106.8 --radius 12

# Surface-water change (NDWI)
satchange -s water --lat -0.5 --lon 117.1

# Flood — needs an explicit baseline and event window
satchange -s flood --lat 27.2 --lon 68.3 \
    --pre 2022-07-01:2022-07-25 --post 2022-08-20:2022-09-10

# Disturbance — flood/landslide impact in terrain, when flood shows nothing
satchange -s disturbance --lat 1.9983 --lon 99.4235 --radius 15 \
    --pre 2025-11-01:2025-11-11 --post 2025-11-26:2025-11-29 --map

# Burn severity — needs pre-fire and post-fire windows
satchange -s burn --lat -7.5 --lon 110.4 \
    --pre 2025-08-01:2025-08-20 --post 2025-09-10:2025-09-30

# Urban growth timing across 3 epochs (Landsat; default 2010/2015/2020)
satchange -s urban-trend --lat -6.30 --lon 107.15 --radius 10 --map

# Urban history: built-up by decade since 1980 (GHSL + Landsat), whole metro
satchange -s urban-history --lat -6.2 --lon 106.85 --radius 45 -n jabodetabek

# Hybrid: auto-locate the most-changed hotspot + a PlanetScope ~3 m close-up
satchange -s urban-history --lat -6.2 --lon 106.85 --radius 45 --planet   # dry-run (free)

# Coastline: shoreline change (SAR) — erosion & accretion between two dates
satchange -s coastline --lat -6.95 --lon 110.45 --radius 8 \
    --pre 2016-01-01:2016-12-31 --post 2025-01-01:2025-12-31

# Coastline time-series + retreat-rate transects (Landsat, back to the 1990s)
satchange -s coastline --coast-method landsat --lat -6.95 --lon 110.45 --radius 10 \
    --epochs 1994-01-01:1996-12-31,2014-01-01:2016-12-31,2023-01-01:2025-12-31

# Custom cross-shore transects drawn in QGIS (clean m/yr in complex bays)
satchange -s coastline --coast-method landsat --city "Pekalongan" --radius 12 \
    --epochs 1994-01-01:1996-12-31,2014-01-01:2016-12-31,2023-01-01:2025-12-31 \
    --transects-file my_transects.geojson

# Public-transport access (SDG 11.2.1): % population within a walk of a stop
satchange -s transit-access --city "Semarang" --radius 8 --walk-dist 500,1000
# ...or supply your own stops/routes (e.g. a BRT corridor exported from QGIS)
satchange -s transit-access --city "Semarang" --radius 10 \
    --transit-file transjateng_stops.geojson

7 · Make a map productMembuat produk peta

Add --map to any run to render an A4-landscape map sheet (PDF + PNG) per product: OpenStreetMap basemap, the change layer, title, legend, a statistics panel, a location inset, coordinate grid, scale bar and north arrow.

Tambahkan --map pada run apa pun untuk membuat lembar peta A4 landscape (PDF + PNG) per produk: basemap OpenStreetMap, layer perubahan, judul, legenda, panel statistik, inset lokasi, grid koordinat, skala, dan panah utara.

satchange -s mining --lat -3.333 --lon 122.25 --map

Already have results and just want to re-render (no Earth Engine needed)? Every run drops a .meta.json sidecar, so:

Sudah punya hasil dan ingin render ulang (tanpa Earth Engine)? Tiap run menulis sidecar .meta.json, jadi:

satmap output/20260708-2226_deforestation_x_fac24e   # a run folder
satmap output/<run>/mining_sirad_x.tif --basemap gray  # or one .tif

Maps land in maps/. Tweak the layout in mapmaker.py and re-run instantly.

Peta tersimpan di maps/. Ubah tata letak di mapmaker.py lalu jalankan ulang seketika.

8 · Adapt it to your own areaMenyesuaikan untuk area Anda

Pick a locationPilih lokasi

Find coordinates by right-clicking a spot in Google Maps (it copies lat, lon), or from OpenStreetMap. Choose a --radius to match the feature: a few km for a single mine or town, 10–20 km for a flood plain or a fire.

Cari koordinat dengan klik kanan di Google Maps (menyalin lat, lon), atau dari OpenStreetMap. Pilih --radius sesuai objek: beberapa km untuk satu tambang atau kota, 10–20 km untuk dataran banjir atau kebakaran.

Save a named presetSimpan preset bernama

Add reusable places to sites.py and call them with --site:

Tambahkan lokasi yang sering dipakai ke sites.py dan panggil dengan --site:

SITES = {
  "my_area": {
    "label": "My study area",
    "lat": 1.234, "lon": 103.456, "radius_km": 8.0,
    "sentinel2_date": "2026-06-15",
    "sirad_periods": [("2024-01-01","2024-12-31"),
                      ("2025-01-01","2025-12-31"),
                      ("2026-01-01","2026-06-30")],
    "ndvi_pre":  ("2023-01-01","2023-12-31"),
    "ndvi_post": ("2026-01-01","2026-06-30"),
  },
}

satchange -s deforestation --site my_area --map

Add a brand-new scenarioTambah skenario baru

Most scenarios are one dictionary entry in scenarios.py. To add, say, a moisture-change scenario using NDWI on a custom threshold you only add a registry entry — the generic optical-change engine does the rest:

Kebanyakan skenario hanya satu entri dictionary di scenarios.py. Untuk menambah, misalnya, skenario perubahan kelembapan memakai NDWI dengan ambang khusus, cukup tambahkan satu entri — mesin perubahan optik generik menangani sisanya:

"moisture": {
    "label": "Moisture change (NDWI)",
    "run": _optical("NDWI", "gain", 0.08, 0.20),  # index, direction, thresholds
    "radius": 10.0, "needs": "pre_post",
    "pre":  ("2023-01-01","2023-12-31"),
    "post": ("2025-01-01","2025-12-31"),
    "interpretation": "Greener = wetter.",
},

New spectral indices go in indices.py (a one-line normalised difference). Radar or bespoke methods get a small run_* function in scenarios.py.

Indeks spektral baru masuk ke indices.py (satu baris normalized difference). Metode radar atau khusus memakai fungsi run_* kecil di scenarios.py.

9 · Reproducibility & dataReproduksibilitas & data

• Data: Copernicus Sentinel-1 (radar) and Sentinel-2 (optical), free and open, courtesy ESA, processed in Google Earth Engine.
• AOI: a square centred on your coordinate (half-side = radius), axis-aligned in EPSG:4326.
• Orbit auto-selection: radar scenarios check both ascending and descending orbits and use whichever has imagery in every period.
• Outputs are regenerable, so results and maps are git-ignored; only code and this tutorial are versioned.

• Data: Copernicus Sentinel-1 (radar) dan Sentinel-2 (optik), gratis dan terbuka, dari ESA, diproses di Google Earth Engine.
• AOI: persegi berpusat di koordinat Anda (setengah-sisi = radius), sejajar sumbu di EPSG:4326.
• Pemilihan orbit otomatis: skenario radar memeriksa orbit ascending dan descending lalu memakai yang punya citra di tiap periode.
• Keluaran bisa dibuat ulang, jadi hasil dan peta di-git-ignore; hanya kode dan tutorial ini yang diversikan.

10 · TroubleshootingPemecahan masalah

11 · Further readingBacaan lanjut

• Zha, Gao & Ni (2003). Use of NDBI in automatically mapping urban areas from TM imagery. Int. J. Remote Sensing 24(3).
• Key & Benson (2006). Landscape Assessment: the Normalized Burn Ratio (NBR/dNBR). USDA Forest Service, FIREMON.
• UN-SPIDER. Recommended Practice: Flood Mapping with Sentinel-1 SAR in Google Earth Engine.
• UN-SPIDER. Normalized Burn Ratio — in detail.
• Earth Lab. Work with the Differenced Normalized Burn Index (dNBR).
• Google Earth Engine. Sentinel-1 SAR guide · Sentinel-2 SR Harmonized.