Installation

Manual installation with pip

From OTB binaries

S1Tiling is a Linux Python software which is based on Python packages but also on C++ softwares OTB and GDAL.

We recommend to use a dedicated Python virtual environment and a dedicated OTB 9.0.0 binary installation to install S1Tiling. If you want use the OTB 7.4.2 version please use an earlier version of S1TIling. Starting from v1.2, compatibility to OTB < 9 is no longer activelly pursued.

Note

OTB 9+ binaries aren’t compatible with older distributions of Linux like for instance Ubuntu 18.04.

Please find below a step by step installation:

# First create a virtual environment and use it
# | We won't document other approaches like conda (that enables selecting
# | any version of Python), nor poetry, uv...
python3 -m venv venv-s1tiling
source venv-s1tiling/bin/activate

# Upgrade pip and setuptools in your virtual environment
pip install --upgrade pip
pip install --upgrade setuptools

# Make sure numpy is properly installed before updating GDAL python bindings
pip install numpy

# Install and configure OTB (included embedded GDAL) for S1Tiling
# | Actually, since OTB 9, only the following packages are required:
# | - OTB-9.0.0-Linux-FeaturesExtraction.tar.gz
# | - OTB-9.0.0-Linux-Sar.tar.gz
# | - OTB-9.0.0-Linux-Dependencies.tar.gz
# | - OTB-9.0.0-Linux-Core.tar.gz
# | But, OTB-9.0.0-Linux.tar.gz provides all OTB applications
curl https://www.orfeo-toolbox.org/packages/archives/OTB/OTB-9.0.0-Linux.tar.gz -o ./OTB-9.0.0-Linux.tar.gz
tar xf OTB-9.0.0-Linux.tar.gz --one-top-level=./venv-s1tiling/otb-9.0.0

# Patch gdal-config with a generic and relocatable version
curl https://gitlab.orfeo-toolbox.org/s1-tiling/s1tiling/-/raw/1.2.0alpha1/s1tiling/resources/gdal-config?ref_type=tags&inline=false -o venv-s1tiling/otb-9.0.0/bin/gdal-config
echo -e '\nLD_LIBRARY_PATH="${CMAKE_PREFIX_PATH}${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"' >> venv-s1tiling/otb-9.0.0/otbenv.profile
source venv-s1tiling/otb-9.0.0/otbenv.profile

# Note that extra OTB applications for NORMLIM calibration support aren't
# installed with this simplified procedure.
# At the moment, you'll need to compile them manually from sources, or to
# use S1Tiling docker distributions.

# Install S1Tiling
pip install S1Tiling==1.2.0alpha1

Note

We haven’t tested yet with packages distributed for Linux OSes. It’s likely you’ll need to inject in your $PATH a version of gdal-config tuned to return GDAL configuration information.

On HPC clusters

The procedure previously described stays valid. Yet you may already have pre-installed modules for Python, GDAL, OTB…

As an inspiration, we provide the installation script used on CNES HPC clusters. It may be a good starting point. See CNES installation script below.

Note

On CNES cluster where OTB has been compiled from sources, you can simply load the associated module:

# Example, on TREX:
module load otb/9.0.0-python3.8

Installation scripts

A couple of installation scripts used internally are provided.

CNES clusters installation script

install-CNES.sh takes care of installating S1Tiling on CNES HPC clusters.

Requirements

It…

  • OTB installed from sources as a Lmod module.

  • Installs S1Tiling in a dedicated space on the clusters,

  • Defines a Python virtual environment where S1Tiling will reside,

  • Automatically generates a S1Tiling module file.

Linux machines installation script

install-rcbin.sh takes care of installating S1Tiling on Linux machines

Requirements

It…

  • An un-extracted OTB binary release,

  • Python 3.8+,

  • A directory where S1Tiling has been cloned,

  • Conda.

  • Creates a conda environment for the selected python version (3.12 by default with OTB 9.x),

  • Extracts the OTB binary release in the directory where the OTB-M.m.p-Linux64.run file is,

  • Patches UseOTB.cmake if need be (in case of C++ ABI mismatch in 7.4.2 OTB release),

  • Patches otbenv.profile,

  • Regenerates Python bindings for OTB,

  • Installs GDAL python bindings from sources (to match GDAL version shipped by OTB binaries),

  • Install S1Tiling from its source directory,

  • And automatically generates a S1Tiling module file named: s1tiling/otb{Mmp}-py{Mm} (Major/minor/patch).

    Note

    You can source otbenv.profile and activate the conda environement manually if you don’t use Lmod.

Note

You will still need to install LIA extra applications in order to produce LIA maps, or to apply σ° NORMLIM calibration.

Extra packages

You may want to install extra packages like bokeh to monitor the execution of the multiple processing by Dask.

Using S1Tiling with a docker

As the installation of S1Tiling could be tedious, versions ready to be used are provided as Ubuntu dockers.

You can browse the full list of available dockers in S1Tiling registry. Their naming scheme is registry.orfeo-toolbox.org/s1-tiling/s1tiling:{version}-ubuntu-otb{otbversion}, with the version being either develop, latest or the version number of a recent release.

The docker, containing the version of S1Tiling of which you’re reading the documentation (i.e. version 1.2.0alpha1), could be fetched with:

docker pull registry.orfeo-toolbox.org/s1-tiling/s1tiling:1.2.0alpha1-ubuntu-otb9.0.0

or even directly used with

docker run                            \
    -v /localpath/to/MNT:/MNT         \
    -v "$(pwd)":/data                 \
    -v $HOME/.config/eodag:/eo_config \
    --rm -it registry.orfeo-toolbox.org/s1-tiling/s1tiling:1.2.0alpha1-ubuntu-otb9.0.0 \
    /data/MyS1ToS2.cfg

Note

This example considers:

  • DEM’s are available on local host through /localpath/to/MNT/ and they will be mounted into the docker as /MNT/.

  • Logs and output files will be produced in current working directory (i.e. $(pwd)) which will be mounted as data/.

  • EODAG configuration file to be in $HOME/.config/eodag which will be mounted as /eo_config/.

  • A configuration file named MyS1ToS2.cfg is present in current working directory, which is seen from docker perspective as in data/ directory.

  • And it relates to the volumes mounted in the docker in the following way:

    [Paths]
output : /data/data_out
dem_dir : /MNT/SRTM_30_hgt
...
[DataSource]
eodag_config : /eo_config/eodag.yml
...

Using S1LIAMap with a docker

It’s also possible to run S1LIAMap in the docker – see LIA Map production scenario. In order to do that, pass --lia as the first parameter to the docker entry point.

In other word, run the docker with something like the following

docker run                            \
    -v /localpath/to/MNT:/MNT         \
    -v "$(pwd)":/data                 \
    -v $HOME/.config/eodag:/eo_config \
    --rm -it registry.orfeo-toolbox.org/s1-tiling/s1tiling:1.2.0alpha1-ubuntu-otb9.0.0 \
    --lia                             \
    /data/MyS1ToS2.cfg

The only difference with the normal case example: there is a --lia parameter in the penultimate line.