Installation

We advise to create isolated environment using conda (or virtualenv). This allow to get rid of version requirement incompatibilities and access the latest versions of some of the libraries (packaged version often stay way behind for stability reasons).

In the following sections, we describe different types of install, make sure you understand their specificity before choosing one!

Important

You need to install miniconda first if you plan to use a conda environment. To do so, follow Installing Miniconda documentation. If you don’t know what is conda take a look at Introducing Conda.

Several mechanisms allows to create conda environments, choose how easy you want it among:

IF you still want to install the sources, look here: Installing TimageTK from sources.

Introducing Conda

Conda is a tool to install and manage different software libraries, possibly at different versions, into independent system configurations called environments. Each environment has a name and stores its own version of each library (distinct from the one of your general system) so that you can make installations that would be incompatible with the rest of your system without impacting its functioning and breaking everything!

Concretely, miniconda will create a new directory for each environment where it will download libraries, binaries and packages. The command source activate environment_name modifies your environment variables (e.g. PATH, PYTHONPATH) so that your system points onto this directory. To recover your general system installation, you simply need to run the command source deactivate.

Installing Miniconda

Warning

This use the latest Miniconda2 distribution, change it to Miniconda3 to use Python3.

Download the latest miniconda installer from the official website:

With Linux and MacOSX, make sure to answer YES when asked to add conda to your PATH environment variable.

Linux

Download manually or use wget to perform this download from a shell:

$ wget https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh

Install miniconda by running the installer in a shell prompt (where you downloaded the installer):

$ bash Miniconda2-latest-Linux-x86_64.sh

Once installed, you can remove the installer:

$ rm Miniconda2-latest-Linux-x86_64.sh

MacOSX

Download manually or use wget to perform this download from a shell:

$ wget https://repo.continuum.io/miniconda/Miniconda2-latest-MacOSX-x86_64.sh

Install miniconda by running the installer in a shell prompt (where you downloaded the installer):

$ bash Miniconda2-latest-MacOSX-x86_64.sh

Once installed, you can remove the installer:

$ rm Miniconda2-latest-MacOSX-x86_64.sh

Windows

Download manually, execute the installer and follow the instructions.

Note

If you have Windows 10, you should try the new Windows Subsystem for Linux, see: https://docs.microsoft.com/en-us/windows/wsl/install-win10

Installing TimageTK in a conda environment

Automatic conda environment creation and TimageTK installation

Once you have installed miniconda you can create the conda environment (here named timagetk) and install the python packages required by TimageTK in one line as follow:

$ conda create -n timagetk -c mosaic timagetk

Before using TimageTK, do not foget to activate your environment as follow:

$ source activate timagetk

Manual creation of a new environment

Choose between a manual or automatic environment creation and installation. We advise to use the automatic version, but for the sake of clarity, we hereafter detail the steps required to perform a manual installation.

Manual creation

To create a new conda environment, to install timagetk and its dependencies (named timagetk for instance):

$ conda create -n timagetk -y python=2.7

By default ipython is not installed in the newly created environment, to install it run:

$ conda install ipython

To activate the environment, run:

$ source activate timagetk
Installing Python packages

To install the python packages inside a conda environment, eg. named timagetk, open a shell prompt and type:

$ source activate timagetk
$ conda install numpy networkx scikit-image
Installing optional Python packages

To install the python packages inside a conda environment, eg. named timagetk, open a shell prompt and type:

$ source activate timagetk
$ conda install nose sphinx

You are now set to clone and install the source repository of timagetk as detailed in Installing TimageTK from sources.

Automatic creation

After installing miniconda, create a YAML configuration file, named timagetk.yml, listing requirements and dependencies:

name: timagetk
channels:
  - defaults
dependencies:
  - python=2.7
  - ipython
  - numpy
  - scikit-image
  - networkx
  - nose
  - sphinx

To automatically create the environment and install dependencies, in a new terminal run:

$ conda env create -f timagetk.yml

To activate the environment, run:

$ source activate timagetk

You are now set to clone and install the source repository of timagetk as detailed in Installing TimageTK from sources.

Adding TimageTK to an existing conda install

If you already have a conda environment (eg. named myenv) and you wish to add TimageTK to this environment follow these steps:

  1. Activate your environment:

    $ source activate myenv
    
  2. Install TimageTK in it:

    $ conda install -c mosaic timagetk
    
  3. Test the install in python by importing a functionality from TimageTK:

    $ python -c "from timagetk.algorithms import fusion"
    

If there is no ImportError returned you are good to go!

Installing TimageTK from sources

This type of install makes sense if you are a developer or want to test the latest developments located in a specific branch.

Warning

Python and python packages are installed within a conda environment (see: Manual creation of a new environment)!

Requirements

System requirements

To install TimageTK from source you will need the following system library:

  • zlib1g-dev (compression/decompression - development)

Python requirements

To install TimageTK from source you will need the following system library:

TimageTK is dependent of the following Python libraries:

Optional requirements

Optional system requirements

If you want to install from the sources and contribute to TimageTK development (see Contribution guidelines) you will need to install git.

  • git (version control system)
  • wget (retrieve files using HTTP, HTTPS, FTP and FTPS)

Optional Python requirements

If you want to run the tests provided with TimageTK, you will have to install nose. If you want to contribute to the documentation or compile it locally, you will have to install sphinx.

  • nose (testing, all platforms)
  • sphinx (python documentation generator)

Install system requirements

To install zlib:

  • Ubuntu and Debian:

    $ sudo apt-get install zlib1g-dev
    
  • Fedora and Redhat:

    $ sudo yum install zlib-devel
    
  • MacOS (using Macports):

    $ sudo port install zlib-devel
    

Clone sources and install

First install git as explained in Contribution guidelines. Then choose among one of the repository above (Github or GitLab) and:

  1. Clone the timagetk repository (default is GitLab):

    $ git clone https://gitlab.inria.fr/mosaic/timagetk
    
  2. Change directory to timagetk:

    $ cd timagetk/
    
  3. Install using python:

    $ python setup.py develop --user
    
  4. Check the LD_LIBRARY_PATH environment variable has been correctly added to your .bashrc file:

  1. Open your .bashrc file:

    $ nano ~/.bashrc
    
  2. Look for the following lines at the end (replacing </path/to/timagetk/folder> by your installation path), if not there, add them:

    timagetk_path=</path/to/timagetk/folder>
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${timagetk_path}/timagetk/build-scons/lib
    
  1. Open a new shell prompt, or source the bashrc file in the current prompt:

    $ source ~/.bashrc
    
  2. To execute the tests, use nose:

    $ cd timagetk/test/
    $ nosetests -v