Skip to main content

Methods for spatial alignment of satellite imagery

Project description

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

PyPI License Black isort


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 fastcubo
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

# Download image collection
table = fastcubo.query_getPixels_imagecollection(
    point=(-75.71260, -14.18835),
    collection="COPERNICUS/S2_HARMONIZED",
    bands=["B2", "B3", "B4", "B8"],
    data_range=["2023-12-01", "2023-12-31"],
    edge_size=256,
    resolution=10,
)
fastcubo.getPixels(table, nworkers=4, output_path="output")

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.eec.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=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, create a data cube, and align the images using one of the three methods provided by the SatAlign package.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

satalign-0.1.9.tar.gz (39.8 kB view details)

Uploaded Source

Built Distribution

satalign-0.1.9-py3-none-any.whl (43.5 kB view details)

Uploaded Python 3

File details

Details for the file satalign-0.1.9.tar.gz.

File metadata

  • Download URL: satalign-0.1.9.tar.gz
  • Upload date:
  • Size: 39.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for satalign-0.1.9.tar.gz
Algorithm Hash digest
SHA256 2d2a82fcd896e8134723ec5710c5dd1a8e2e678cad6e77eb427448d4c9188e7e
MD5 c594c8f74f8f1ac434afdce9f3569a14
BLAKE2b-256 ee05a524ef0dceca1b332df3a278af9798e9a4b73520c16dc5287e95af8d5917

See more details on using hashes here.

File details

Details for the file satalign-0.1.9-py3-none-any.whl.

File metadata

  • Download URL: satalign-0.1.9-py3-none-any.whl
  • Upload date:
  • Size: 43.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for satalign-0.1.9-py3-none-any.whl
Algorithm Hash digest
SHA256 5a6bf3b04cedc60cea2b4596418f2da887742600eb28464f5b78d9096d87783b
MD5 8eabc87774b47cf84d7c66b1e28a7337
BLAKE2b-256 fea3d8086b3283fb8643b3d02a6e5d76060af1746cb4c6beb72eccfb2014978f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page