Copyright 2021 Saif Aati ([email protected] || [email protected])
geoCosiCorr3D is an innovative, free and open-source software tailored for satellite image processing.
geoCosiCorr3D is adept at handling various types of satellite imagery, including push-broom, frame, and push-frame sensors.
At its core, geoCoiCorr3D excels in rigorous sensor model (RSM) refinement,
rational function model (RFM) refinement, and offers advanced processing features: including
orthorectification, sub-pixel image correlation, and 3D surface displacement extraction.
Designed for researchers in remote sensing.
geoCosiCorr3D serves as a critical bridge linking complex data processing requirements
with real-world applicability.
It is particularly beneficial for projects focused on change detection, time series analysis,
and applications in diverse scientific fields such as geology, geomorphology,
glaciology, planetology, as well as in the assessment and mitigation of natural disasters.
See the NEWS for the most recent additions and upgrades.
We welcome your questions, comments, and reports of any issues you encounter! Here's how you can reach out to us or contribute to the project. For direct inquiries or specific questions, feel free to reach out to Saif Aati: ( [email protected] (Preferred) || [email protected])
If you encounter any problems or bugs, please report them by submitting an issue on our GitHub project page. This helps us track and address issues efficiently. Your feedback and contributions are invaluable to us, and we look forward to hearing from you!
There are two methods available to install geoCosiCorr3D: using Conda or Docker. Follow the instructions below based
on your preferred installation method.
- To install using Conda, execute the following script in your terminal:
If Conda (or Miniconda) is not already installed on your machine, the script will attempt to install Miniconda automatically.
./install_cosicorr.sh --conda
- Once the installation is complete, you can activate the
geoCosiCorr3Denvironment with:Alternatively, you can run Python scripts within the environment without activating it by using:conda activate geoCosiCorr3D
Replaceconda run -n geoCosiCorr3D your_script.py
your_script.pywith the name of the Python script you wish to run.
For Docker installation, execute the following command:
./install_cosicorr.sh --dockerThis command will attempt to install Docker if it's not already installed on your system, start the Docker service, and
then pull the base geoCosiCorr3D Docker image. Ensure you have the necessary permissions to install software on your
system when using this option.
Note: Please follow these steps for a smooth installation process. If you encounter any issues or need further assistance, refer to the documentation (the documentation is still under construction 🚧) or submit an issue on the project's GitHub page.
LD_LIBRARY_PATH environment variable, you can use the following command in your terminal:
export LD_LIBRARY_PATH=<absolute_path_of_installation_directory>/Geospatial-COSICorr3D/lib/:$LD_LIBRARY_PATHAdd this line to your .bashrc or .bash_profile (depending on your shell and OS) to make the change permanent:
echo 'export LD_LIBRARY_PATH=<absolute_path_of_installation_directory>/Geospatial-COSICorr3D/lib/:$LD_LIBRARY_PATH' >> ~/.bashrcThe primary entry point for the geoCosiCorr3D command line interface (CLI) is accessible through the Python script
located at scripts/cosicorr.py.
To explore the available commands and their options, you can use the -h or --help flag.
Below is a brief overview of how to use the GeoCosiCorr3D CLI:
python3 scripts/cosicorr.py -h
usage: cosicorr3d [-h] <module> ...
GeoCosiCorr3D CLI
optional arguments:
-h, --help show this help message and exit
modules:
<module>
ortho Orthorectification
transform Transformation
correlate CorrelationFor detailed usage of the correlate module, execute the following command:
python3 scripts/cosicorr.py correlate -hCorrelate Module Usage
usage: cosicorr3d correlate [-h] [--base_band BASE_BAND] [--target_band TARGET_BAND] [--output_path OUTPUT_PATH] [--method {frequency,spatial}] [--window_size WINDOW_SIZE WINDOW_SIZE WINDOW_SIZE WINDOW_SIZE]
[--step STEP STEP] [--grid] [--show] [--pixel_based] [--vmin VMIN] [--vmax VMAX] [--mask_th MASK_TH] [--nb_iters NB_ITERS] [--search_range SEARCH_RANGE SEARCH_RANGE]
base_image target_image
positional arguments:
base_image Path to the base image.
target_image Path to the target image.
optional arguments:
-h, --help show this help message and exit
--base_band BASE_BAND
Base image band.
--target_band TARGET_BAND
Target image band.
--output_path OUTPUT_PATH
Output correlation path.
--method {frequency,spatial}
Correlation method to use.
--window_size WINDOW_SIZE WINDOW_SIZE WINDOW_SIZE WINDOW_SIZE
Window size. (Default [64])
--step STEP STEP Step size. (Default [8,8])
--grid Use grid.
--show Show correlation. (Default False)
--pixel_based Enable pixel-based correlation.
--vmin VMIN Minimum value for correlation plot. (Default -1)
--vmax VMAX Maximum value for correlation plot. (Default 1)
Frequency method arguments:
--mask_th MASK_TH Mask threshold (only for frequency method).
--nb_iters NB_ITERS Number of iterations (only for frequency method).
Spatial method arguments:
--search_range SEARCH_RANGE SEARCH_RANGE
Search range (only for spatial method).Example:
python3 scripts/cosicorr.py correlate tests/test_dataset/BASE_IMG.TIF tests/test_dataset/TARGET_IMG.TIF --show --vmin -3 --vmax 3
The batch correlation feature allows performing correlation on multiple images in batch mode. It supports specifying lists of base and target images, with the script handling the correlation accordingly.
Comma-separated lists of base and target images can be passed, or wildcard patterns may be used to include all matching files in a directory.
- Batch Correlation
- Multiband Correlation
Batch Correlate Module Usage
1- Serial Correlation:
python3 scripts/batch_correlation.py batch_correlate BASE_IMG_1.TIF,BASE_IMG_2.TIF TARGET_IMG_1.TIF,TARGET_IMG_2.TIF --output_path output/ --show --serialpython3 scripts/batch_correlation.py batch_correlate BASE_IMG_1.TIF,BASE_IMG_2.TIF "Target/*.TIF" --output_path output/ --show --all
2- All Combinations Correlation:
python3 scripts/batch_correlation.py batch_correlate BASE_IMG_1.TIF,BASE_IMG_2.TIF "Target/*.TIF" --output_path output/ --show --allIn these examples, the --serial option correlates images with the same index, while the --all option correlates all possible combinations of base and target images. If neither --serial nor --all is specified, the script defaults to --all.
Note: You can pass a comma-separated list of image paths or use a wildcard pattern like "folder/*.tif" to include all matching files in a directory.
Multiband Correlate Module Usage
The multiband correlation feature allows performing correlation between all possible bands in a given raster. If the --band_combination option is specified, the correlation will be done between the specified bands.
python3 scripts/cosicorr.py multi_band_correlation input_img.TIF --band_combination "1,2;3,4" --output_path output/ --showFor detailed usage of the transfrom module, execute the following command:
python3 scripts/cosicorr.py transform -hTransform Module Usage
This section demonstrates how to use the transform command within the geoCosiCorr3D CLI to perform coordinate transformations.
The examples show how to convert pixel coordinates to geographic coordinates (longitude, latitude, and altitude) and vice versa.
usage: cosicorr3d transform [-h] [--inv] [--dem_fn DEM_FN] x y <model_name> ...
positional arguments:
x list: x=cols and if with invert flag: lon
y list: y=lines and if with invert flag: lat
optional arguments:
-h, --help show this help message and exit
--inv Transform form ground to image space.
--dem_fn DEM_FN DEM file name (None)
model:
<model_name>
RFM RFM model specific arguments
RSM RSM model specific arguments
To convert pixel coordinates to geographic coordinates using a Rational Function Model (RFM), use the following command:
python3 scripts/cosicorr.py transform 0,1000 0,500 RFM tests/test_dataset/test_ortho_dataset/SP2_RPC.txtOutput:
lons: [30.52895296 30.65688292]lat: [41.24090926 41.16826844]alt: [1102.49239388 1102.49239388]
For the inverse operation: converting geographic coordinates back to pixel coordinates, use the --inv flag:
python3 scripts/cosicorr.py transform 30.52895296,30.65688292 41.24090926,41.16826844 --inv RFM tests/test_dataset/test_ortho_dataset/SP2_RPC.txtOutput:
cols: [9.70195697e-06 999.999998e+02]lines: [5.07104141e-06 500.000045e+02]
For detailed usage of the ortho module, execute the following command:
python3 scripts/cosicorr.py ortho -hOrtho Module Usage
usage: cosicorr3d ortho [-h] [--o_ortho O_ORTHO] [--corr_model CORR_MODEL] [--dem DEM] [--gsd GSD] [--resampling_method {sinc,bilinear}] [--debug] [--show] [--refine]
[--ref_img REF_IMG] [--gcps GCPS]
input_img <model_name> ...
positional arguments:
input_img Input file for ortho
optional arguments:
-h, --help show this help message and exit
--o_ortho O_ORTHO Output path for ortho. Defaults to the current working directory.
--corr_model CORR_MODEL
Correction model path (None)
--dem DEM DEM path (None)
--gsd GSD Output file for ortho (None)
--resampling_method {sinc,bilinear}
Resampling method (SINC)
--debug
--show
--refine Refine model, this require GCPs or reference imagery to collect GCPs
--ref_img REF_IMG Reference Ortho image (None)
--gcps GCPS GCPs file (None)
model:
<model_name>
RFM RFM model specific arguments
RSM RSM model specific argumentsusage: cosicorr3d ortho input_img RSM [-h] {Spot1,Spot2,Spot3,Spot4,Spot5,Spot15,Spot6,Spot7,Spot67,WV1,WV2,WV3,WV4,GE,QB,DG} rsm_fn
positional arguments:
{Spot1,Spot2,Spot3,Spot4,Spot5,Spot15,Spot6,Spot7,Spot67,WV1,WV2,WV3,WV4,GE,QB,DG}
Sat-name
rsm_fn Specifies the path to the .xml DMP file. Additional formats are supported in GeoCosiCorr3D.pro.usage: cosicorr3d ortho input_img RFM [-h] rfm_fn
positional arguments:
rfm_fn RFM file name (.tiff or .TXT)geoCosiCorr3D: GUI
If you are using this software for academic research or publications we ask that you please cite this software as:
[1] Aati, S., Milliner, C., Avouac, J.-P., 2022. A new approach for 2-D and 3-D precise measurements of ground deformation from optimized registration and correlation of optical images and ICA-based filtering of image geometry artifacts. Remote Sensing of Environment 277, 113038. https://doi.org/10.1016/j.rse.2022.113038
[2] S. Leprince, S. Barbot, F. Ayoub and J. Avouac, "Automatic and Precise Orthorectification, Coregistration, and Subpixel Correlation of Satellite Images, Application to Ground Deformation Measurements," in IEEE Transactions on Geoscience and Remote Sensing, vol. 45, no. 6, pp. 1529-1558, June 2007, doi: 10.1109/TGRS.2006.888937.
[3] Aati, S.; Avouac, J.-P. Optimization of Optical Image Geometric Modeling, Application to Topography Extraction and Topographic Change Measurements Using PlanetScope and SkySat Imagery. Remote Sens. 2020, 12,