Skip to content

Prep 1.4.1 #300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
May 2, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 20 additions & 107 deletions documentation/basics/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,14 +108,17 @@ History of supported solver versions
{:.table.table-striped}
| ilastik version | GUROBI version | CPLEX version |
|:----------------|:---------------|:--------------|
| 1.4.1 (in beta) | 9.5.1 | not supported |
| 1.4.1 | 12.0.0 | not supported |
| 1.4.0 | 9.5.1 | not supported |
| 1.3.3 | 8.1.1 | 1290 |
| 1.3.2 | 8.0.1 | 1280 |
| 1.3.0 | 7.5.2 | 1260 |

We'll go through the installation in the following sections.

For instructions on installing CPLEX in one of the old ilastik versions, please see [our legacy installation instructions][legacy installation].

[legacy installation]: {{site.baseurl}}/documentation/basics/installation_legacy_cplex#solver-setup
[tracking with learning]: {{site.baseurl}}/documentation/tracking/tracking#sec_structured_learning

### GUROBI Installation and Setup
Expand All @@ -137,7 +140,7 @@ The following sections contain platform-specific instructions for GUROBI install

#### Installation on Windows {#gurobi-setup-windows}

Double click the `Gurobi-9.0.3-win64.msi` installer to go through the installation process.
Double click the `Gurobi-12.0.0-win64.msi` installer to go through the installation process.
Restart your computer to complete the installation.
Once the installation is complete, you need to activate the license.
You can review all your current licenses [here][gurobi-licenses].
Expand All @@ -161,19 +164,19 @@ With that you should be able to use the "Calculate Tracking Weights" functionali
In case of problems, please take a look at the [GUROBI installation documentation][gurobi-install-win].

Note: Due to a bug in ilastik `1.3.3` the solver library is not recognized.
If you absolutely have to use this version then a solution is to manually copy `C:\gurobi811\win64\bin\gurobi811.dll` to your ilastik installation folder, e.g. `C:\Program Files\ilastik-1.3.3post3\Library\bin`.
If you absolutely have to use this version then a solution is to manually copy `C:\gurobi811\win64\bin\gurobi811.dll` to your ilastik installation folder, e.g. `C:\Program Files\ilastik-1.3.3\Library\bin`.

#### Installation on MacOSX and Linux {#gurobi-setup-linux-mac}

On MacOSX you can start the installation process by clicking on the downloaded file `gurobi9.5.1_macos_universal2.pkg`.
On MacOSX you can start the installation process by clicking on the downloaded file `gurobi12.0.0_macos_universal2.pkg`.
Note: on MacOSX, starting from ilastik 1.4.1, gurobi will only be found if it is installed into the `/Libary/gurobi1200/` directory (default).


On linux you have to unpack the downloaded archive:

```bash
tar -xvf gurobi9.5.1_linux64.tar.gz -C /your/target/directory
tar -xvf gurobi12.0.0_linux64.tar.gz -C /your/target/directory
```


Activate your installation by invoking `grbgetkey` with your license.
You can review all your current licenses [here][gurobi-licenses].
Licenses without an entry in the `Host Name` column have not been assigned a computer yet.
Expand All @@ -189,10 +192,10 @@ For the activation you'll have to open a terminal and follow this sequence of co

```bash
# Linux
cd /your/target/directory/gurobi951/linux64/bin
cd /your/target/directory/gurobi1200/linux64/bin
# OSX
# on OSX gurobi is installed to /Library/ per default.
cd /Libary/gurobi951/macos_universal2/bin
cd /Libary/gurobi1200/macos_universal2/bin

# use the obtained license key here
./grbgetkey aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
Expand All @@ -202,6 +205,12 @@ cd /Libary/gurobi951/macos_universal2/bin
In the next step you have to execute a script that will link your GUROBI libraries to your ilastik installation.
In a terminal, download the [script][gurobi-install-link-script] for linking gurobi to the ilastik installation:


##### Linking the gurobi libaries to the ilastik binary

This section only applies to Linux.
On MacOSX using ilastik 1.4.1 or newer, the gurobi solver will be found if it is installed into the default location.

```bash
# set-up environment, only necessary if gurobi.lic is not in the home folder
export GRB_LICENSE_FILE=/path/to/license/gurobi.lic
Expand All @@ -217,9 +226,9 @@ chmod +x install-gurobi-symlinks.sh

# link the installed gurobi libraries to the ilastik installation
# Linux
bash install-gurobi-symlinks.sh /your/target/directoy/gurobi951/linux64 /path/to/ilastik-1.*-Linux
bash install-gurobi-symlinks.sh /your/target/directoy/gurobi1200/linux64 /path/to/ilastik-1.*-Linux
# Mac
bash install-gurobi-symlinks.sh /your/target/directoy/gurobi951/macos_universal2/ /path/to/ilastik-1.*-OSX.app
bash install-gurobi-symlinks.sh /your/target/directoy/gurobi1200/macos_universal2/ /path/to/ilastik-1.*-OSX.app
```

After a successful installation, learning the weights in the *Tracking with Learning Workflow* will be enabled.
Expand All @@ -243,99 +252,3 @@ Should you run into any problems, please [contact us]({{site.baseurl}}/community
[gurobi-install-win]: https://www.gurobi.com/documentation/9.0/quickstart_windows/software_installation_guid.html
[gurobi-install-link-script]: https://raw.githubusercontent.com/ilastik/ilastik/main/scripts/install-gurobi-symlinks.sh
[ilastik-download]: {{site.baseurl}}/download.html

--------

### CPLEX Installation and Setup

#### Application for Academic License at IBM

IBM CPLEX is a commercial solver which is free for academic use.
Details on the application for an academic license, may be found on
[the IBM Academic Initiative website](https://developer.ibm.com/academic/).
Please note that it might take some days until the application gets approved by IBM.

#### Download IBM CPLEX

Once the license has been approved by IBM, instructions for download will be provided.

The current version of ilastik works with
**IBM ILOG CPLEX Optimization Studio V12.9**.
After choosing the appropriate platform, you have to agree with the IBM license.
Finally, CPLEX may be downloaded and is ready to install.

**Important note: It is not sufficient to download the Trial version of CPLEX since its solver can only handle
very small problem sizes. Please make sure, the correct version is downloaded as described here.**

The following sections contain platform-specific instructions for CPLEX installation on [Windows](#cplex-setup-windows) as well as on [Linux and Mac](#cplex-setup-linux-mac).

#### Setup on Windows {#cplex-setup-windows}

Run the installer by double clicking the executable that you've downloaded.

On Windows, there are typically no further modifications needed after installing CPLEX.
After a successful installation, learning the weights in the *Tracking with Learning Workflow* will be enabled.
If it isn't, something went wrong with the CPLEX installation.
To track down the problem, proceed like this:

* Make sure that the environment variable `CPLEX_STUDIO_DIR129` is set and points to the proper location.
You can check this by typing `echo %CPLEX_STUDIO_DIR129%` at the DOS command prompt.
The output should be something like `C:\Program Files\IBM\ILOG\CPLEX_Studio129`.
* Make sure that `cplex` is in the PATH.
Type `where cplex` at a DOS prompt.
It should produce something like `C:\Program Files\ibm\ILOG\CPLEX_Studio129\cplex\bin\x64_win64\cplex.exe` (the path prefix should match the contents of the `CPLEX_STUDIO_DIR129` variable).
* Make sure that the directory containing `cplex.exe` also contains `cplex129.dll`, `ILOG.CPLEX.dll`, and `ILOG.Concert.dll`.

Learning the weights in the *Tracking with Learning Workflow* should now be enabled.
If it isn't, you may copy the files `cplex129.dll`, `ILOG.CPLEX.dll`, and `ILOG.Concert.dll` (if you can locate them somewhere) to the *binary* folder of the ilastik installation, usually located at `C:\Program Files\ilastik\bin`.
If it still doesn't work, please [contact us]({{site.baseurl}}/community.html).


#### Setup on Linux and Mac {#cplex-setup-linux-mac}

On Linux and Mac, the CPLEX installer comes as a commandline executable (`cplex-someversion.sh` on Linux and `cplex-someversion.bin` on Mac).
To install it, open a terminal and run `bash /path/to/your/cplex-someversion.sh` (or `bash /path/to/your/cplex-someversion.bin` on Mac).

**Hint:** on Mac and most Linux distributions you can drag and drop the installer file into the terminal to get the full path appended to your command line.

CPLEX packages for Linux and Mac do not provide shared versions of all required libraries, but only static variants.
In order to enable CPLEX with ilastik, the static libraries have to be converted.
Before you can convert your static CPLEX libraries into shared library versions, you need to have a compiler installed on your machine.
You can check whether you already have a compiler installed by running the following command in a terminal (open the Terminal app!).

gcc --version

If no compiler is installed, choose what to do depending on your OS version:

- For Linux, use your OS package manager (e.g. `apt-get`) to install the `gcc` package.
- For all OSX < 10.9, so up to Mountain Lion, you need to install XCode from the AppStore.
Then you need to go to XCode's Preferences, to the Downloads tab, and install the command line tools.
- For OSX 10.9 Mavericks it suffices to install the command line tools using the following command without installing XCode.

xcode-select --install

Then you need to accept the XCode licence by running "sudo gcc" once.

Now you can run a script, that will convert your CPLEX static libraries into shared libraries, and install them into the appropriate directory of your ilastik directory.
Starting with ilastik-1.1.7, this script can be found in ilastik-1.\*.\*/ilastik-meta/ilastik/scripts.
Prior to that version the [script](https://github.com/ilastik/ilastik/blob/master/scripts/install-cplex-shared-libs.sh) needs to be downloaded manually in the terminal:

wget https://raw.githubusercontent.com/ilastik/ilastik/master/scripts/install-cplex-shared-libs.sh

Navigate to the directory containing the script and execute it:

# navigate to the script location, e.g. /path/to/ilastik-1.*-Linux/ilastik-meta/ilastik/scripts
cd /path/to/script
# Linux:
bash install-cplex-shared-libs.sh /path/to/your/cplex-root-dir /path/to/ilastik-1.*-Linux
# Mac:
bash install-cplex-shared-libs.sh /path/to/your/cplex-root-dir /path/to/ilastik-1.*-OSX.app

In the command above, `/path/to/your/cplex-root-dir` is the location of your cplex studio installation. It should contain directories named `concert` and `cplex`, among others.

**Note:** The above script installs CPLEX directly into your ilastik installation.
Once you've done that, you should not distribute your copy of ilastik to others, unless you have a license to distribute CPLEX.

After a successful installation, learning the weights in the *Tracking with Learning Workflow* will be enabled.

----------
105 changes: 105 additions & 0 deletions documentation/basics/installation_legacy_cplex.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
title: Installation
tagline:
category: "Documentation"
group: "basic-documentation-legacy"
weight: 0
---

# Legacy Installation Instructions

## Commercial Solver Installation {#solver-setup}

### CPLEX Installation and Setup

Applies to ilastik versions `1.3.0` (cplex 1260), `1.3.2` (cplex 1280), and `1.3.3` (cplex 1290),

#### Application for Academic License at IBM

IBM CPLEX is a commercial solver which is free for academic use.
Details on the application for an academic license, may be found on
[the IBM Academic Initiative website](https://developer.ibm.com/academic/).
Please note that it might take some days until the application gets approved by IBM.

#### Download IBM CPLEX

Once the license has been approved by IBM, instructions for download will be provided.

The current version of ilastik works with
**IBM ILOG CPLEX Optimization Studio V12.9**.
After choosing the appropriate platform, you have to agree with the IBM license.
Finally, CPLEX may be downloaded and is ready to install.

**Important note: It is not sufficient to download the Trial version of CPLEX since its solver can only handle
very small problem sizes. Please make sure, the correct version is downloaded as described here.**

The following sections contain platform-specific instructions for CPLEX installation on [Windows](#cplex-setup-windows) as well as on [Linux and Mac](#cplex-setup-linux-mac).

#### Setup on Windows {#cplex-setup-windows}

Run the installer by double clicking the executable that you've downloaded.

On Windows, there are typically no further modifications needed after installing CPLEX.
After a successful installation, learning the weights in the *Tracking with Learning Workflow* will be enabled.
If it isn't, something went wrong with the CPLEX installation.
To track down the problem, proceed like this:

* Make sure that the environment variable `CPLEX_STUDIO_DIR129` is set and points to the proper location.
You can check this by typing `echo %CPLEX_STUDIO_DIR129%` at the DOS command prompt.
The output should be something like `C:\Program Files\IBM\ILOG\CPLEX_Studio129`.
* Make sure that `cplex` is in the PATH.
Type `where cplex` at a DOS prompt.
It should produce something like `C:\Program Files\ibm\ILOG\CPLEX_Studio129\cplex\bin\x64_win64\cplex.exe` (the path prefix should match the contents of the `CPLEX_STUDIO_DIR129` variable).
* Make sure that the directory containing `cplex.exe` also contains `cplex129.dll`, `ILOG.CPLEX.dll`, and `ILOG.Concert.dll`.

Learning the weights in the *Tracking with Learning Workflow* should now be enabled.
If it isn't, you may copy the files `cplex129.dll`, `ILOG.CPLEX.dll`, and `ILOG.Concert.dll` (if you can locate them somewhere) to the *binary* folder of the ilastik installation, usually located at `C:\Program Files\ilastik\bin`.
If it still doesn't work, please [contact us]({{site.baseurl}}/community.html).


#### Setup on Linux and Mac {#cplex-setup-linux-mac}

On Linux and Mac, the CPLEX installer comes as a commandline executable (`cplex-someversion.sh` on Linux and `cplex-someversion.bin` on Mac).
To install it, open a terminal and run `bash /path/to/your/cplex-someversion.sh` (or `bash /path/to/your/cplex-someversion.bin` on Mac).

**Hint:** on Mac and most Linux distributions you can drag and drop the installer file into the terminal to get the full path appended to your command line.

CPLEX packages for Linux and Mac do not provide shared versions of all required libraries, but only static variants.
In order to enable CPLEX with ilastik, the static libraries have to be converted.
Before you can convert your static CPLEX libraries into shared library versions, you need to have a compiler installed on your machine.
You can check whether you already have a compiler installed by running the following command in a terminal (open the Terminal app!).

gcc --version

If no compiler is installed, choose what to do depending on your OS version:

- For Linux, use your OS package manager (e.g. `apt-get`) to install the `gcc` package.
- For all OSX < 10.9, so up to Mountain Lion, you need to install XCode from the AppStore.
Then you need to go to XCode's Preferences, to the Downloads tab, and install the command line tools.
- For OSX 10.9 Mavericks it suffices to install the command line tools using the following command without installing XCode.

xcode-select --install

Then you need to accept the XCode licence by running "sudo gcc" once.

Now you can run a script, that will convert your CPLEX static libraries into shared libraries, and install them into the appropriate directory of your ilastik directory.
Starting with ilastik-1.1.7, this script can be found in ilastik-1.\*.\*/ilastik-meta/ilastik/scripts.
Prior to that version the [script](https://github.com/ilastik/ilastik/blob/master/scripts/install-cplex-shared-libs.sh) needs to be downloaded manually in the terminal:

wget https://raw.githubusercontent.com/ilastik/ilastik/master/scripts/install-cplex-shared-libs.sh

Navigate to the directory containing the script and execute it:

# navigate to the script location, e.g. /path/to/ilastik-1.*-Linux/ilastik-meta/ilastik/scripts
cd /path/to/script
# Linux:
bash install-cplex-shared-libs.sh /path/to/your/cplex-root-dir /path/to/ilastik-1.*-Linux
# Mac:
bash install-cplex-shared-libs.sh /path/to/your/cplex-root-dir /path/to/ilastik-1.*-OSX.app

In the command above, `/path/to/your/cplex-root-dir` is the location of your cplex studio installation. It should contain directories named `concert` and `cplex`, among others.

**Note:** The above script installs CPLEX directly into your ilastik installation.
Once you've done that, you should not distribute your copy of ilastik to others, unless you have a license to distribute CPLEX.

After a successful installation, learning the weights in the *Tracking with Learning Workflow* will be enabled.
4 changes: 2 additions & 2 deletions documentation/tda/tda.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Trainable Domain Adaptation (beta)
tagline: Trainable Domain Adaptation (beta)
title: Trainable Domain Adaptation
tagline: Trainable Domain Adaptation
category: "Documentation"
group: "workflow-documentation"
weight: 0
Expand Down
Loading