This code implements a stereo pipeline which produces elevation models from images taken by high resolution optical satellites such as Pléiades, WorldView, QuickBird, Spot or Ikonos. It generates 3D point clouds and digital surface models from stereo pairs (two images) or tri-stereo sets (three images) in a complete automatic fashion.

The main language is Python, although several operations are handled by binaries written in C.

The pipeline is implemented in the file s2p.py. The s2p module can be used to produce surface models and 3D point clouds from arbitrarily large regions of interest or from complete images. If needed, it cuts the region of interest in several small tiles and process them in parallel.

The easiest way to use s2p is to run the binary s2p.py from a shell, with a json configuration file as unique argument:

$ ./s2p.py test.json

All the parameters of the algorithm, paths to input and output data are stored in the json file. See the provided test.json file for an example, and the comments in the file python/config.py for some explanations about the roles of these parameters.

The processed Region of interest (ROI) is defined by the image coordinates (x, y) of its top-left corner, and its dimensions (w, h) in pixels. These four numbers must be given in the json configuration file (as in the example). They are ignored if the parameter 'full_img' is set to true. In that case the full image will be processed. If neither the ROI definition or the 'full_img' flag are present in the configuration file, then a preview of the reference image must be provided. The ROI will be selected interactively on that preview. The path of the preview file must be given by the key 'prv' of the 'images'[0] dictionary (as in the example).

Another way is to import the s2p module in a python session, and run the functions process_pair or process_triplet, depending on the kind of dataset you have (stereo pair or triplet), to generate an altitude map. A 3D point cloud can be generated from this altitude map using the function generate_cloud, and then a raster digital surface model map can be generated from the 3D point cloud.

python
>>> import s2p
>>> alt_map = s2p.process_triplet('test', 'pan1.tif', 'rpc1.xml', 'pan2.tif', 'rpc2.xml', 'pan3.tif', 'rpc3.xml', 25150, 24250, 300, 300, 3)
>>> s2p.generate_cloud('test', 'pan1.tif', 'rpc1.xml', 'xs1.tif', 25150, 24250, 300, 300, alt_map)
>>> s2p.generate_dsm('test/dsm.tif', ['test/cloud.ply'], 4)

See the docstrings of the functions process_pair, process_triplet, generate_cloud and generate_dsm for a complete description of their arguments.

All the python modules are located in the python folder. Some python functions of these modules rely on external binaries. Most of these binaries were written on purpose for the needs of the pipeline, and their source code is provided here in the c folder. For the other binaries, the source code is provided in the 3rdparty folder.

All the sources (ours and 3rdparties) are compiled from the same makefile. Just run make from the s2p folder to compile them. This will create a bin directory containing all the needed binaries.

Required dependencies: cmake, libtiff, libpng, libjpeg, libfftw3, libgeotiff, gdal. These can be installed on Debian 7 (wheezy) with

apt-get install cmake libfftw3-dev libtiff5-dev libgeotiff-dev gdal-bin

gdal version must be 1.10 or newer. Comments about dependencies that were required in previous versions of s2p are still here just in case.

cd 3rdparty
wget http://download.osgeo.org/gdal/1.10.1/gdal-1.10.1.tar.gz
tar xzf gdal-1.10.1.tar.gz
cd gdal-1.10.1
./configure --prefix=$HOME/local
make install

If you want to use MicMac for the stereo matching step, you must install it first and create a symlink to the micmac directory (the one containing a 'bin' folder with a bunch of executables in it, among with 'MICMAC' and 'mm3d') in the 'bin' folder:

ln -s PATH_TO_YOUR_MICMAC_DIR bin/micmac

Here are the instuctions to install them in a local folder, without root privileges. First create a local folder:

mkdir ~/local

If you want to use a different path, do the appropriate changes in the following instructions.

cd 3rdparty/GeographicLib-1.32
mkdir build
cd build
cmake -D CMAKE_INSTALL_PREFIX=~/local -D GEOGRAPHICLIB_DATA=~/local/share/GeographicLib ..
make
make install

Since we use GeographicLib to evaluate geoid heights we must also install the geoids data files by running the following script, which has been configured by cmake:

~/local/sbin/geographiclib-get-geoids

It is a wrapper around the OpenCV implementation of semi-global block-matching, which is a variant of Hirschmuller famous semi-global matching (SGM). You must first compile and install a few OpenCV modules:

git clone https://github.com/Itseez/opencv.git
cd opencv
git checkout 2.4
mkdir build
cd build
cmake -D CMAKE_INSTALL_PREFIX=~/local -D CMAKE_BUILD_TYPE=RELEASE -D BUILD_opencv_ml=OFF -D BUILD_opencv_objdetect=OFF -D BUILD_opencv_video=OFF -D BUILD_opencv_photo=OFF -D BUILD_opencv_nonfree=OFF -D BUILD_opencv_java=OFF -D BUILD_opencv_ts=OFF ..
make
make install

Please note the importance of compiling the code of the 2.4 branch, and not the master branch, since the OpenCV API may change and break the compatibility with our wrapper.

Now you can compile the SGBM wrapper:

cd 3rdparty/stereo_hirschmuller_2008
mkdir build
cd build
cmake -D CMAKE_PREFIX_PATH=~/local ..
make

cd 3rdparty
wget http://sourceforge.net/projects/numpy/files/NumPy/1.6.1/numpy-1.6.1.tar.gz
tar xzf numpy-1.6.1.tar.gz
cd numpy-1.6.1
python setup.py build --fcompiler=gnu95 <!---check the README.txt of numpy for the compiler options-->
python setup.py install --prefix=~/local/

cd 3rdparty
git clone https://github.com/carlodef/iio.git
cd piio_packaged
python setup.py install --prefix=~/local
export PYTHONPATH=$PYTHONPATH:$HOME/local/lib/python2.6/site-packages

on python 2.7, linux x86_64 (Fedora)

export PYTHONPATH=$PYTHONPATH:$HOME/local/lib64/python2.7/site-packages

To make the 3rd party binaries available to the s2p system run the following script

cd bin
. copy_from_3rdparty.sh

If GDAL or Geographic LIB was installed locally then also run:

cp ~/local/bin/{CartConvert,GeoidEval,gdal_translate} .

Each image must be accompanied by an xml file containing rpc coefficients.

Due to storage limitations, no images are available on this repository. If you want to run the s2p code, you have to get a copy of Pleiades, WorldView of QuickBird datasets by other means. The typical size of a Pléiades image is around 40000 x 40000 pixels, covering an area of 20km x 20km. The files weigh approximately 2GB each.

Run the script data/pleiades/create_links.sh to generate symbolic links to the images files and copy the xml files. The links will be located in the data/pleiades/* subfolders and are easier to use than the actual real paths to the image files.