Section 2 Installation

This section provides some guidelines to install the SegOptim package as well as the external / 3rd party software required to run the image segmentation algorithms.

2.1 Installing the package

It’s really simple to install the latest version of the package! You can do it directly from the GitHub repository (don’t forget to install the remotes package in case you haven’t done that yet):


# Check if devtools package is installed and install it if not

if(!requireNamespace("remotes")){
  install.packages("remotes")
}

# [!] Due to the removal from CRAN of package unbalanced
# this has to be compiled from source and installed

remotes::install_github("dalpozz/unbalanced")


# Now let's install SegOptim (with the latest updates)

remotes::install_github("joaofgoncalves/SegOptim")

2.2 Installing third party software for image segmentation

As previously mentioned, SegOptim relies on external (or 3rd party) software to implement image segmentation. So, in order to run the package, you have to install at least one of the available programs for this purpose (check compatible versions here).

By default, the package will not try to locate the software that you installed in your system. This is intended to give the user some degree of flexibility and to let him/her decide which programs it wants to install and run. To run the image segmentation we will then have to provide the specific paths to the software.

There are several different strategies to install the different open-source packages for image segmentation. For example, Windows-users can install (almost) all packages through the OSGeo4W network installer (available on the following link). However, our approach here will focus on installing each software separately.

2.2.1 ArcGIS Desktop

ArcGIS Desktop allows to collect and manage data, create professional maps, perform traditional and advanced spatial analysis, and solve real problems.

About installation not much to say… ESRI ArcGIS Desktop is only available for Windows (although there are ways to run it under Linux or Mac OS but that is outside of the scope of this tutorial). Just follow the software installer.
ArcGIS is packaged with a Python API that is used to control image segmentation; typically this is installed in C:/Python27/ArcGIS10.x directory or similar. The ArcGIS Python installation directory should be used as input to run the segmentation (in parameter pythonPath for function segmentation_ArcGIS_MShift()).

2.2.2 GRASS GIS

GRASS GIS, commonly referred to as GRASS (Geographic Resources Analysis Support System), is a free and open source Geographic Information System (GIS) software suite used for geospatial data management and analysis, image processing, graphics and maps production, spatial modeling, and visualization. GRASS GIS is currently used in academic and commercial settings around the world, as well as by many governmental agencies and environmental consulting companies. Its community is a founding member of the Open Source Geospatial Foundation (OSGeo).

For Windows the download and install instructions for the stand-alone can be found here:
https://grass.osgeo.org/download/software/ms-windows/
After installation, locate the grass72.bat file (or other number corresponding to your version) in the installation directory (e.g., C:/GRASS/grass72.bat) and use this path as the GRASS.path parameter in GRASS segmentation function segmentation_GRASS_RG().

For Linux download and install instructions can be found here:
https://grass.osgeo.org/download/software/linux/

For Mac OS X download and install instructions can be found here:
https://grass.osgeo.org/download/software/mac-osx/

After installation, locate the grass executable file in the install dir (e.g., /usr/bin/grass72) and use this path as the GRASS.path parameter in GRASS segmentation function segmentation_GRASS_RG().

To use GRASS you will also need to have the input raster data (containing features to be used in image segmentation) in a compatible GRASS database. To do this use r.import or r.in.gdal to import the data.

2.2.3 Orfeo Toolbox (OTB)

Orfeo ToolBox is an open-source project for state-of-the-art remote sensing, including a fast image viewer, apps are callable from Bash, Python or QGIS, and a powerful C++ API.

For downloading the Orfeo ToolBox stand-alone binary package for Linux, Mac OS or Windows follow this link: https://www.orfeo-toolbox.org/download/. Select OTB-contrib for your system;

For Windows just unpack the .zip file and you are ready to go.

For Linux or Mac OS X run the following command to unpack:

sh OTB-contrib-5.10.1-Linux64.run --target /home/username/otb

After installing, locate the bin folder (e.g., C:/OTB/bin (in Windows), ~/OTB/bin (Linux)); this will be used in parameter otbBinPath for the OTB segmentation function segmentation_OTB_LSMS().

2.2.4 RSGISLib

RSGISLib is the Remote Sensing and GIS software library (RSGISLib) is a collection of tools for processing remote sensing and GIS datasets. The project is jointly led by Pete Bunting (Earth Observation and Ecosystem Dynamics Group , Aberystwyth University) and Dan Clewley (Plymouth Marine Laboratory).

RSGISLib is installed through Conda (Anaconda or Miniconda). We recommend to use the Anaconda system which is defined “a freemium open source distribution of the Python and R programming languages for large-scale data processing, predictive analytics, and scientific computing, that aims to simplify package management and deployment.” (see wiki Anaconda can be download from this link

Select the Python 3.x version of Anaconda for your system and download. For Windows simply run the installer. For Linux or Mac OS X run the following command:

bash Anaconda3-4.3.1-Linux-x86_64.sh

Once Anaconda is installed you proceed to download and install the RSGISLib package and related dependencies. As of the writing of this tutorial (May-2017), for RSGISLib you need to create an environment inside the Anacondadistribution. Full instructions can be found here and copied below:

For Linux:

conda env create au-eoed/au-osgeo-lnx
source activate au-osgeo-lnx

And for Mac OS X:

conda env create au-eoed/au-osgeo-osx
source activate au-osgeo-osx

If you just want RSGISLib without the extras in the pre-packaged environments above then you can also install using the following commands. You also need to install an environment with Python version 3.5 for which RSGISLib is available (at the time of writing this tutorial May-2017). This should work for Windows users:

conda create -n py35 python=3.5 anaconda
source activate py35

conda install -c conda-forge -c rios "rsgislib<3.5"

Note that RSGISLib version >3.4 are not yet compatible with SegOptim package.

It is recommended that you also install the following packages:

conda install -c conda-forge -c rios scikit-learn rios tuiview h5py

After installation, locate the Python directory under /Anaconda/envs, for example: C:/Anaconda3/envs/py35 (Windows) or /home/user_name/anaconda3/envs/au-osgeo/bin (Linux). This path should be used in parameter pythonPath for running RSGISLib segmentation function with Shepherd k-means algorithm segmentation_RSGISLib_Shep.

2.2.5 SAGA GIS

SAGA (or System for Automated Geoscientific Analyses) can be download in the following link for Mac OS and Windows users: https://sourceforge.net/projects/saga-gis/.

For Linux Ubuntu users, SAGA can be installed through the following:

sudo add-apt-repository ppa:johanvdw/saga-gis
sudo apt-get update
sudo apt-get install saga

After installing the software, locate the folder with the saga_cmd executable file (inside the installation folder) for example: C:/Program Files/SAGA/ (Windows) or /usr/bin (Linux). This path should be used as the input for parameter SAGApath for SAGA’s Seeded Region Growing segmentation algorithm, function segmentation_SAGA_SRG().

2.2.6 TerraLib 5

TerraLib 5 is a C++ software library base to develop Geographical Information Systems (GIS). It is developed by the National Institute for Space Research (INPE), Brazil. TerraLib is free and open source software. You can redistribute it and/or modify it under the terms of the GNU Lesser General Public License (version 3 or later). More info about this software can be found in this (link)[http://www.dpi.inpe.br/terralib5/wiki/doku.php].

TerraLib 5 provides access to a large number of algorithms including two image segmentation methods:
- Mean Region Growing;
- Baatz-Schape multiresolution image segmentation.

Due to some particularities of this software, we provide a minimalistic build (named TISA - Terralib Image Segmentation Algorithms) giving command line access to these segmentation routines. You can find these packages and installation instructions below.

Windows

  • Download the package from the following link: https://goo.gl/NwtaEl
  • Unzip the package in a location of your choice e.g., C:/terralib-5.2.1-TISA

Now, locate the folder in C:/terralib-5.2.1-TISA/lib (or other, depending on the base location used). This path will be used as input for argument TerraLib.path for running image segmentation with functions: segmentation_Terralib_Baatz() or segmentation_Terralib_MRGrow().
The executables named terralib_cli_baatz or terralib_cli_rg inside the binary folder above are responsible for running each of the functions.

Linux

  • Download the package from the following link: https://goo.gl/6rdv3y
  • Place the .tar.gz file under your user root folder at: /home/username
  • Unzip and untar using:

gnuzip terralib-5.2.1-TISA-linux_x64.tar.gz   
tar -xf terralib-5.2.1-TISA-linux_x64.tar

You now have a folder called terralib in your user root directory. Do not try to change folder names or locations otherwise package dependencies will not work correctly!
Locate the folder in /home/username/terralib/build-5.2.1-dev/bin. This path will be used as input for argument TerraLib.path for running image segmentation with functions: segmentation_Terralib_Baatz() or segmentation_Terralib_MRGrow().
The executables named terralib_cli_baatz or terralib_cli_rg inside the binary folder above are responsible for running each of the functions.

Mac OS

Sorry… not currently available (but we are making an effort to do it ;-)


INFO
Instead of using the full paths to 3rd party segmentation softwares, alternatively you can add them to your PATH variable. Although possible, we advise providing them explicitly to avoid problems.