imagefusion

It is written in C++, but there are interfaces for R (planned via CRAN) and for Python (currently not online yet, planned via conda-forge).

A more detailed description about the library can be found in the API documentation. There is also a tutorial about the basic usage. Please have a look. See below for how to make the documentation.

Build

Note: This repository uses submodules, so clone with:

git clone --recurse-submodules URL

# or in two separate steps:
git clone URL
cd imagefusion
git submodule update --init --recursive

This project uses CMake as build system and should work on Windows, Linux and Mac. In order to compile the library you need a compatible compiler like gcc or clang (Boost did not support clang on Windows some time ago), which supports C++17. Then you need some dependencies:

• OpenCV
• GDAL
• Boost (Exception, ICL, Iterator, Tokenizer)
• Armadillo (and OpenBLAS, if SPSTFM should run in parallel)
• OpenMP (optional, only for parallelization, compiler should support OpenMP)
• Boost Unit Test Framework (optional, only for test configuration)

For the documentation you need:

• doxygen
• graphwiz (for dot diagrams)
• dia (for dia diagrams)
• LaTeX (currently used for formulas)
• ghostscript (only on windows)

Conda

Independent of the platform, you can build and install imagefusion using conda-build. The dependencies are all available as conda packages on conda-forge and will be installed automatically.

conda update conda

Install the build tool in your base environment:

conda install conda-build conda-verify

Then go to the directory containing the conda recipe

cd python/conda.recipe

Build the package using conda-forge dependencies. Either add the conda-forge channel permanently, as recommended here:

conda config --add channels conda-forge
conda config --set channel_priority strict
conda build .

However, this might lead to issues later on with other packages. So you can also choose conda-forge channel only for building:

conda build -c conda-forge .

This takes a while. When it is finished, you can install it into a new environment (--use-local and -c local do not work, currently, see: conda/conda/7758 conda/conda/7024):

conda create --name imfu -c conda-forge -c ${CONDA_PREFIX}/conda-bld/ imagefusion  # [linux or osx]
conda create --name imfu -c conda-forge -c %CONDA_PREFIX%/conda-bld/  imagefusion  # [win]
conda activate imfu

Or install it into the currently active environment:

conda install -c conda-forge -c ${CONDA_PREFIX}/conda-bld/ imagefusion  # [linux or osx]
conda install -c conda-forge -c %CONDA_PREFIX%/conda-bld/  imagefusion  # [win]

Or to reinstall:

conda install -c ${CONDA_PREFIX}/conda-bld/ --force-reinstall imagefusion-python imagefusion-utils libimagefusion  # [linux or osx]
conda install -c %CONDA_PREFIX%/conda-bld/  --force-reinstall imagefusion-python imagefusion-utils libimagefusion  # [win]

Now everything is there; utilities like starfm, the library, a CMake file to import the library in a C++ project and, most importantly, the python interface. Try it! Let's import the python interface:

(imfu) $ cd ../examples            # go to python/examples
(imfu) $ python starfm-example.py  # or execute another example

Or execute a binary utility:

(imfu) $ starfm --help

Linux

Ubuntu (20.04) and Debian (Buster) are supported, others should work with similar packages. Building in Linux is very easy. Assuming Ubuntu, install the build dependencies with

sudo apt install cmake g++ make libopencv-dev libgdal-dev libboost-all-dev libarmadillo-dev libopenblas-base libgomp1
# if you want to build with clang++ install these (optional, you would also have to set it as default compiler afterwards):
sudo apt install clang libomp-dev

and, optionally, the documentation dependencies with

sudo apt install doxygen graphviz dia texlive-full

Now go to the folder where this readme is located. Then do the following

mkdir build
cd build
cmake ..
make all -j 4    # -j 4 means 4 compiler jobs in parallel

which will build the library in lib/ and the utilities in bin/. For installation you can either install it directly or make a debian package. For direct installation use

sudo make install
# or when you are logged in as root with `su -` or `sudo -i` just:
make install

The default install path is /usr/local, which is the correct one for self compiled software. The all target includes the python interface, which gets installed to /usr/local/lib/python3/dist-packages/imagefusion/ by default when using the python from the linux distribution. To change the install path e. g. to ~/.local for a user installation use

cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME/.local ..
make install

or whatever you prefer as user install path. This does usually just work (it will install libimagefusion.so to ~/.local/lib and let the binaries find that library; you do not need to change LD_LIBRARY_PATH for the imagefusion binaries). You might want to add the local path ~/.local/bin in your profile file ~/.profile and source it with source ~/.profile.

You can also make a debian package. To make and install use

make package
sudo apt install ./imagefusion*.deb

To build and execute the tests, use

make testimagefusion
./testimagefusion

To build the documentation (open with doc/doc.html in the source directory, not the build directory), use one of the following:

make doc
# or for devs:
make docinternal

Python interface

The sudo make install should already install the python interface in /usr/local/lib/python3/dist-packages/imagefusion/. With conda the requirements are easier to handle, because they are available as conda packages. For installing imagefusion with conda, see conda build. You can also try pip:

cd imagefusion   # make sure you are in the repository directory
pip install .    # or: pip3 if you use the pip version from the linux distribution

After installation you might want to test the python installation (note, conda build automatically does this during building):

# in the repository directory:
python -m unittest discover -s tests/ -p "*_test.py"

Troubleshooting

• For the error ../../lib/libimagefusion.so: undefined reference to ... are many reasons possible:

  • Check whether the *-dev and normal version of the libraries are installed (see above)
  • If there is a multi-user installation of Anaconda or Miniconda (e. g. in /opt), the GDAL CMake file might find the library shipped with the python package instead of the one installed with the package mangager (e. g. apt). To sort this out remove the gdal package (or maybe the opencv package, if that causes problems) as root user from the base environment:

  conda activate
  conda remove gdal
  conda deactivate

  Then as normal user create a new environment where you install the required packages:

  conda create  -n imagefusion  gdal rios python-fmask rasterio matplotlib pandas
  conda activate imagefusion

  Alternatively, as a quickfix, prepend the cmake command with the GDAL search path, e. g.:

  GDAL_DIR=/usr  cmake ..

• ModuleNotFoundError: No module named 'apt_pkg' during cmake run

  Try sudo apt install --reinstall python3-apt if you use the version from the package manager

• CMake Error at CMakeLists.txt:XXX (add_subdirectory): The source directory XXX does not contain a CMakeLists.txt file during cmake run

  You probably cloned the repository with git clone URL, which does not fetch the submodules. After cloning you can fetch them with:

  git submodule update --init --recursive

MacOS

This should work similar to Linux. However, MacOS is lacking a package manager, so if you do not have it yet, install Homebrew now:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install the dependencies:

brew install cmake opencv armadillo gdal boost libomp

Now go to the folder where this readme is located. Then do the following

mkdir build
cd build
cmake ..
make starfm estarfm staarch -j 4  # select the targets you want, imfupython might not work yet

which will build the library as lib/libimagefusion.dylib and the utilities as bin/starfm, bin/estarfm and bin/staarch.

The build on macOS is barely tested.

Windows

Multiple ways are possible. We suggest to use MSYS2, which basically allows to use a Linux way of installing. Assuming a 64 bit system, download MSYS2 64 bit from https://msys2.github.io/ and install it to the default folder (C:\msys64). First we will update pacman and install a compiler (MinGW). Start MSYS2 MSYS and execute:

pacman -Syu

Close MSYS2 and start it again. Execute:

pacman -Su
pacman -S mingw-w64-x86_64-gcc

Close MSYS2.

Next, we install all the dependencies. Start MSYS2 MSYS again and execute:

pacman -S mingw64/mingw-w64-x86_64-cmake \
          mingw64/mingw-w64-x86_64-extra-cmake-modules \
          mingw64/mingw-w64-x86_64-make \
          msys/make \
          mingw64/mingw-w64-x86_64-boost \
          mingw64/mingw-w64-x86_64-opencv \
          mingw64/mingw-w64-x86_64-gdal \
          mingw64/mingw-w64-x86_64-netcdf \
          mingw64/mingw-w64-x86_64-postgresql \
          mingw64/mingw-w64-x86_64-armadillo \
          mingw64/mingw-w64-x86_64-arpack \
          mingw64/mingw-w64-x86_64-curl \
          mingw64/mingw-w64-x86_64-proj

The above command will install cmake and all the other external dependent libraries. After the installation of the dependent libraries the imagefusion framework can be compiled and built. Before we start compiling and building the imagefusion framework, the following paths must be added to the user variables as well as the environment variable PATH.

User variables:

System Variables: Place these locations at the start of the values.

1. C:\msys64\mingw64\bin
2. C:\msys64\mingw64\lib
3. C:\msys64\usr\bin
4. C:\msys64\mingw64\share\OpenCV\bin

Once the above paths are added properly, the imagefusion framework is now ready to becompiled.

To compile the imagefusion framework open Windows command prompt and navigate to the imagefusion directory and execute the following commands,

mkdir build
cd build
cmake -G “MSYS Makefiles” ..
make all

The execution of the above commands will compile and build the imagefusion framework. This will result in a bin directory which contains the libimagefusion.dll file along with other utilities as .exe files which are built using the imagefusion library. This includes different data fusion utilities, cloud masking and interpolation utility, image crop and image compare utilities. The utilities and the libimagefusion.dll will be available in the bin folder. The utilities can be executed directly from command prompt using the appropriate options (HELPavailable with every utility).

The imagefusion framework not only provides the library of functions and utilties. It also provides an extensive documentation. This documentation helps the user to better understand the full potential of the imagefusion framework. It also supports the users to further develop the imagefusion framework and provides proper guidelines to use the API's available in the imagefusion library to develop new utilities. To compile the documentation following applications / tools / software are required.

1. Dia: Tool to generate diagrams in the API documentation. Available in http://dia-installer.de/
2. Graphviz: Tool to generate graphs in the API documentation. Available in https://www.graphviz.org/Download_windows.php
3. Ghostscript: Tool to generate pdf in the API documentation. Available in https://www.ghostscript.com/download/gsdnld.html
4. Doxygen: Tool to generate the API documentation. Available in https://www.doxygen.nl/download.html#srcbin
5. MikTeX: Tool to compile latex files. Available in https://miktex.org/download

After installing all the above mentioned applications / tools / software, their respective paths should be added to the environment variable PATH.

Now the documentation can be compiled by simply executing the following command in the windows command prompt with the current directory as build.

make doc

Executing this command will create a doc directory in the main imagefusion directory along with a doc.html file. Opening this file will take you to the main index page of the documentation.

Packaging

The cmake file of imagefusion framework also has commands to generate windows installer package for easy distribution of the imagefusion framework along with the implemented data fusion algorithms, remote sensing utilities, header files and documentation. This will enable the users to use the imagefusion framework without the need to install many tools and prepare an environment suitable for building and compiling the imagefusion framework. In order to perform the packaging and generate a “.msi” Microsoft installer file, the following tool is required.

1. WIXTOOLSET Tool to generate Microsoft installer file. Available in (https://wixtoolset.org/releases/)

After installation add the following system variable.

System variable:

Now we are ready to make the imagefusion framework package. The package can be generated by executing the following command from the windows command prompt as build as the current directory.

dir make package

Executing the above command will result in the creation of Imagefusion Framework-0.0.1-win64.msi. Now you have a Windows installer, which you can execute to install the library and the utilities. This also works on other computers, since it includes all runtime dependencies.

Other Make configurations:

The cmake file of the imagefusion framework is also provided with test configuration. This configuration will prepare and build all the test methods associated with the imagefusion framework to test all the functionalities. The test functions can be build by simply executing the following command.

make testimagefusion

This will build all the test functions into an exe file called testimagefusion.exe.

testimagefusion

Simply execute the testimagefusion.exe file to run all the test functions.

Note that at the time of writing the MSYS2 version of GDAL, which is used to read images, does not support images in the format HDF 4, but in HDF 5. This is bad, since MODIS images are in HDF 4 and it is incompatible to HDF 5. There is a utility to convert HDF 4 images to HDF 5 images (doc / download), which might help.

Troubleshooting

(Only applicable if the imagefusion framework library and other utilities are build from source)

After compilation if the imagefusion framework does not compile or run properly. This might be due to some issues with the dependent libraries. In this case it needs some trouble shooting. This is because imagefusion framework provides extensive functions to support various remote sensing operations as well as mathematical calculations. For this purpose the imagefusion framework depends on so many external libraries. It is always not possible to create a list of external dependent libraries. Installation of some external libraries should install the other dependent libraries by default. But the MSYS2 has some issues and the installation of the dependent external libraries does not happen automatically. In this case they have to be installed manually using the MSYS2 package manager (pacman).

An example situation is shown below: The imagefusion framework requires arpack for performing some mathematical computations. The availability of this external library is not checked during the CMAKE process and also during the MAKE process. So the CMAKE and MAKE process will work without any issues. Since this is included as a dynamic library, the availability of this library is only checked and required during the run time i.e. during the execution of the utilities. If it is not available then the execution of the utility will throw an error stating that the library is not found and needs to be installed. In this case the missing library (.dll) file can be searched in MSYS2 pacman and the missing package can be installed.

The below command shows how to search for a particular package and to install the package.

pacman -Ss arpack

Executing the above command in MSYS2 MSYS will search for arpack package and show the results. The result will look like:

mingw32/mingw-w64-i686-arpack 3.5.0-1
        Fortran77 subroutines designed to solve large scale eigenvalue problems
        (mingw-w64)
mingw64/mingw-w64-x86_64-arpack 3.5.0-1
        Fortran77 subroutines designed to solve large scale eigenvalue problems
        (mingw-w64)

Two versions of arpack packages are available. Based on the user preference, the user can install either of the versions by simply executing the following command.

# For 64 bit version
pacman -S mingw64/mingw-w64-x86_64-arpack

# For 32 bit version
pacman -S mingw32/mingw-w64-i686-arpack

The above instruction holds valid for any issues arising due to missing packages.

Recommended IDEs

If you like to contribute to the project, we recommend you the following IDEs

• QT Creator: Just open the CMakeLists.txt as project file. QT Creator can be installed on Windows with MSYS2 on linux from the repositories.

• Eclipse: Download from eclipse.org the package "Eclipse IDE for C/C++ Developers" and install or run. Then generate eclipse project files:

  cd ..
  mkdir imagefusion-eclipse
  cd imagefusion-eclipse
  cmake ../imagefusion -G"Eclipse CDT4 - Unix Makefiles"

  These steps work similarly with the CMake-GUI in Windows. Now you have .cproject and .project files, which you can import with eclipse.

License

See the license file for license rights and limitations (BSD-3).