satalign

A Python package for efficient multi-temporal image co-registration 🚀

---

GitHub: https://github.com/IPL-UV/satalign 🌐

PyPI: https://pypi.org/project/satalign/ 🛠️

---

Overview 📊

Satalign is a Python package designed for efficient multi-temporal image co-registration. It enables aligning temporal data cubes with reference images using advanced techniques such as Phase Cross-Correlation (PCC), Enhanced Cross-Correlation (ECC), and Local Geometric Matching (LGM). This package facilitates the manipulation and processing of large volumes of Earth observation data efficiently.

Key features ✨

• Advanced alignment algorithms: Leverages ECC, PCC, and LGM to accurately align multi-temporal images. 🔍
• Efficient data cube management: Processes large data cubes with memory and processing optimizations. 🧩
• Support for local feature models: Utilizes models like SuperPoint, SIFT, and more for keypoint matching. 🖥️
• Parallelization: Executes alignment processes across multiple cores for faster processing. 🚀

Installation ⚙️

Install the latest version from PyPI:

pip install satalign

To use the PCC module, you need to install additional dependencies:

pip install satalign[pcc]

Alternatively, if you already have satalign installed:

pip install scikit-image

To use the LGM module, you need to install additional dependencies:

pip install satalign[deep]

How to use 🛠️

Align an ee.ImageCollection with satalign.pcc.PCC 🌍

Load libraries

import ee
import cubexpress
import satalign
import satalign.pcc
import matplotlib.pyplot as plt
from IPython.display import Image, display

Auth and Init GEE

# Initialize depending on the environment
ee.Authenticate()
ee.Initialize(opt_url="https://earthengine-highvolume.googleapis.com")  # project = "name"

Dataset

# Discover and download a Sentinel-2 collection with cubexpress
rt = cubexpress.point_to_rt(
    lon=-75.71260, lat=-14.18835,
    width=256, height=256, scale=10,
)
table = cubexpress.discover_images(
    "COPERNICUS/S2_HARMONIZED", rt,
    start="2023-12-01", end="2023-12-31",
).select_bands("B2", "B3", "B4", "B8")

cubexpress.express(table, outfolder="output", nworkers=4)

Align dataset

# Create a data cube and select images if desired
s2_datacube = satalign.utils.create_array("output", "datacube.pickle")

# Define reference image
reference_image = s2_datacube.sel(time=s2_datacube.time > "2022-08-03").mean("time")

# Initialize and run PCC model
pcc_model = satalign.pcc.PCC(
    datacube=s2_datacube,
    reference=reference_image,
    channel="mean",
    crop_center=128,
    num_threads=2,
)
# Run the alignment
aligned_cube, warp_matrices = pcc_model.run_multicore()

# Display the warped cube
warp_df = satalign.utils.warp2df(warp_matrices, s2_datacube.time.values)
satalign.utils.plot_s2_scatter(warp_df)
plt.show()

Graphics

# Display profiles
satalign.utils.plot_profile(
    warped_cube=aligned_cube.values,
    raw_cube=s2_datacube.values,
    x_axis=3,
    rgb_band=[3, 2, 1],
    intensity_factor=1/3000,
)
plt.show()

# Create PNGs and GIF
# Note: The following part requires a Linux environment
# !apt-get install imagemagick
gifspath = satalign.utils.plot_animation1(
    warped_cube=aligned_cube[0:50].values,
    raw_cube=s2_datacube[0:50].values,
    dates=s2_datacube.time[0:50].values,
    rgb_band=[3, 2, 1],
    intensity_factor=1/3000,
    png_output_folder="./output_png",
    gif_delay=20,
    gif_output_file="./animation1.gif",
)
display(Image(filename='animation1.gif'))

Here's an addition to clarify that datacube and reference_image have already been defined:

Align an Image Collection with satalign.ecc.ECC 📚

import satalign.ecc

# Initialize the ECC model
ecc_model = satalign.ecc.ECC(
    datacube=s2_datacube,
    reference=reference_image,
    gauss_kernel_size=5,
)
# Run the alignment
aligned_cube, warp_matrices = ecc_model.run()

Align using Local Features with satalign.lgm.LGM 🧮

Here's the updated version with a note about using floating-point values or scaling:

import satalign.lgm

# Initialize the LGM model
lgm_model = satalign.lgm.LGM(
    datacube=s2_datacube / 10_000,
    reference=reference_image / 10_000,
    feature_model="superpoint",
    matcher_model="lightglue",
)
# Run the alignment
aligned_cube, warp_matrices = lgm_model.run()

In this document, we presented three different examples of how to use satalign with PCC, ECC, and LGM for multi-temporal image co-registration. Each example shows how to download an image collection from Google Earth Engine with cubexpress, create a data cube, and align the images using one of the three methods provided by the satalign package.