Installation: Difference between revisions

From MiToBo
Jump to navigationJump to search
 
(38 intermediate revisions by 3 users not shown)
Line 3: Line 3:
There are two common ways to work with MiToBo:
There are two common ways to work with MiToBo:
<ul>
<ul>
<li> just using the operators included in MiToBo for improving your work and easing image processing tasks
<li> just using the operators included in MiToBo for improving your work and easing image processing tasks, e.g., via ImageJ or Fiji
<li> using the MiToBo API to write operators, plugins and other image analysis applications on your own
<li> using the MiToBo API to write operators, plugins and other image analysis applications on your own
</ul>
</ul>
Irrespective of which way you intend to go the first thing to is always to download the binary zip file containing the current release of MiToBo.<br> The actual installation instructions differ in some parts depending on which way you choose.<br> Below we will first provide some notes regarding the binary zipfile, and then outline more details about the installation steps required
The functionality of MiToBo is best used from within ImageJ or Fiji. In case that you aim to use MiToBo for your own development, you need to download the binaries explicitly. The actual installation instructions differ in some parts depending on which way of using MiToBo you have in mind.<br> Below we will first outline more details about the installation steps required for simply using MiToBo's operators in ImageJ and Fiji, and then provide some notes regarding the binary zip file. Finally we will present some details for using MiToBo's API with your own code.
for simply using MiToBo's operators. Finally we will present some details for using MiToBo's API.


== The [[downloads|MiToBo Binary]] Zip File ==
<blockquote style="background-color: lightgrey; border: solid thin grey;">
'''[[The recommended way to install and run MiToBo and its operators/plugins is via Fiji!]]'''<br>
MiToBo has its own Fiji update site named "MiToBo".


To get the current release of MiToBo download and extract the [[downloads|MiToBo Binary zip file]].<br> You will find the following structure of directories:
[http://sites.imagej.net/MiToBo http://sites.imagej.net/MiToBo]<br>
* docs - includes the MiToBo manual
* lib - includes nesessary libaries for Linux and Windows
* licences - includes MiToBo license and licences for other software used by MiToBo
* macros - includes the MiToBo macro toolset
* native - sources and Makefiles to build MiToBo's native libraries
* plugins - includes MiToBo jar and other jars used by MiToBo
* ''oprunner.sh'' - shell script to run MiToBo operators from commandline (Linux only)
* ''run.sh'' - shell script to run ImageJ with MiToBo (Linux only)


== Linux ==
To enable this site in your Fiji installation refer to the [http://fiji.sc/How_to_follow_a_3rd_party_update_site Fiji documentation].


=== Use MiToBo as shipped ===
Note that for some plugins (e.g., PaCeQuant) also the "Biomedgroup" update site needs to be activated.
</blockquote>


You can use MiToBo right away using the ''run.sh'' and ''oprunner.sh'' scripts.
== Using MiToBo with Fiji ==
If an '''UnsatisfiedLinkError''' occurs, please read the '''Native libraries''' section below.
Since release 1.5 MiToBo features a Fiji update site and the easiest way to use MiToBo's operators and plugins is to enable the update site in your Fiji installation. <br> The MiToBo update site is<br>


=== Use MiToBo with an existing ImageJ installation ===
[http://sites.imagej.net/MiToBo http://sites.imagej.net/MiToBo]


To use MiToBo with an existing ImageJ installation perform the following steps:
To enable the site in your Fiji installation refer to the [http://fiji.sc/How_to_follow_a_3rd_party_update_site Fiji documentation].


# copy the ''Mi_To_Bo.jar'' in plugins/ of the MiToBo zip-file to your ImageJ/plugins/ directory
'''Important notices:'''<br>  
# copy all jars in plugins/jars/ of the MiToBo zip-file to your ImageJ/plugins/jars/ <span style="text-decoration: underline;">except</span> the ij.jar and jars already existing in your ImageJ/plugins/jars/ directory<br/>('''Notice:''' MiToBo requires explicite versions of some jars, other versions may not work probably, see [[downloads|requirements]].)
<ul>
# copy the ''MiToBo_Runner.txt'' from the macros/toolsets/ directory in the MiToBo zip-file to your ImageJ/macros/toolsets/ directory
<li> Occasionally MiToBo '''operators crash when run from within Fiji'''. The reason for this behaviour are most of the time '''conflicting jar archives''' delivered with the Fiji distribution.<br> We figured out that particularly the jar file
# Make the native libraries in lib/ of the MiToBo zip-file available to java (see the '''Native libraries''' section below)


You can still use the ''run.sh'' and ''oprunner.sh'' scripts if you copy the to your ImageJ/ directory.
* jars/bio-formats/formats-common-5.1.x.jar


Since release $0.9.6$ \mitobo supports the ImageJ toolbar, i.e.~offers a configuration file for fast
often causes such trouble. Thus, if you encounter problems running MiToBo operators, please try to locally delete or uninstall the abovementioned jar archive from your local Fiji installation and then re-run the MiToBo operator.
access of its plugins via a toolbar button. To add the \mitobo toolset to ImageJ, \mitobo is shipped
<li> For some of our operators special issues exist and require special treatment:
with a macro configuration file. It can be found in the zip archives and is called
<ul>
{\tt MiToBo\_Tools.txt}. Simply copy the file into the folder {\tt macros/toolsets} of your ImageJ
<li> [[Applications/CellBoundaryExtractor2D| CellBoundaryExtractor2D]]: there are version conflicts with regard to the '''JGraphT library''' used by this operator and also by default included in every Fiji distribution; please refer to installation instructions on the [[Applications/CellBoundaryExtractor2D|webpage of the operator]] for a workaround
installation and run ImageJ. Then you can select the \mitobo toolset from the list of available
</ul>
sets by clicking on the arrows button on the right side of the ImageJ standard toolbar.
</ul>
Selecting {\tt 'MiToBo\_Tools'} will add a button with the \mitobo logo to the toolbar allowing
 
for direct access to all \mitobo plugins (Fig.~\ref{fig:toolbar}).
<br>
 
== Using MiToBo with ImageJ ==
 
'''Important Note 1:''' Before you consider installing MiToBo manually within ImageJ, check if it could not be an option to use Fiji and activate MiToBo's update site - in most cases this will be significantly less painful...


=== Native libraries ===
'''Important Note 2:''' These instructions refer to ImageJ 1.


Some operators of MiToBo use native code via the Java Native Interface (JNI).
<br>
The lib/ directory in the zip-file provides JNI-libraries for 32- (lib/lib32) and 64-Bit (lib/lib64) systems,
General remarks:<br>
but for several reasons an '''UnsatisfiedLinkError''' might occur when you run MiToBo operators that depend on native code. UnsatisfiedLinkErrors are thrown if the native library required is not available or cannot be loaded for other reasons.
For using MiToBo with ImageJ it is the easiest to download the latest distribution zipfile (*-bin.zip) from<br>
In the following solutions to the different reasons are described.


==== Troubleshooting ====
[https://moon.informatik.uni-halle.de/repository/releases/de/unihalle/informatik/MiToBo/mitobo-plugins/ https://moon.informatik.uni-halle.de/repository/releases/de/unihalle/informatik/MiToBo/mitobo-plugins/]<br>
* '''Library paths not configured:'''
:The path to the native libraries must be available to any java application which uses MiToBo operators that depend on these libraries.
:The ''run.sh'' and ''oprunner.sh'' scripts both add the lib/lib32 or lib/lib64 directory depending on your architecture to the LD_LIBRARY_PATH, thus you do not have to configure the LD_LIBRARY_PATH manually.
:If you run ImageJ with MiToBo or the OpRunner in another way, the directories of native libraries can be passed to java in any of the following two ways:
:* The LD_LIBRARY_PATH environment variable must contain the path to the native libraries used
:* The java-call has to be augmented with an option to tell where native libraries reside:
  java -Djava.library.path=/path/to/libs1:/path/to/libs2[:...] ...
::  For example, you can run ImageJ with MiToBo on a 32-Bit system with the unzipped MiToBo structure, but not the ''run.sh'' script, with the following command (the /usr/lib is also provided here as it is assumed to contain the CGAL libraries - see next problem):
  java -Djava.library.path=lib/lib32:/usr/lib -cp plugins/jars/ij.jar ij.ImageJ
:Configuring the LD_LIBRARY_PATH and running java with the -Djava.library.path option are equivalent and thus only the LD_LIBRARY_PATH is referred in the following.


* '''CGAL libraries not installed:'''
which already includes '''''all''''' dependencies and ships with some scripts to run MiToBo's operators and plugins out of the box.
: Any MiToBo operator using Snake Active Contours is based on a Snake datatype that is backed by the CGAL (Computational Geometry Algorithms Library) libraries [http://www.cgal.org/]. The library ''libJNI_Cgal_Polygon2D.so'' shipped with MiToBo defines the interface to these libraries and thus requires that the CGAL libraries are installed on your system.
:Make sure that the path to the CGAL libraries is specified in your LD_LIBRARY_PATH.


* '''Building of MiToBo's native libraries:'''
=== Linux ===
: You might have installed a different version of libraries compiled with a different compiler than the libraries used to build the libraries shipped with MiToBo. Therefore MiToBo's native libraries might not work and an '''UnsatisfiedLinkError''' is thrown. Then you have to compile MiToBo's native libraries yourself:
:# Go to the native/ directory in MiToBo's directory structure
:# Edit ''Makefile.rules'' if necessary (defaults are predefined):
::* The path to your java installation which includes the JNI-header files
::* The path to the CGAL libraries
::* The path to the CGAL headers
:# Run ''make install'', which will build MiToBo's native libraries for your architecture and move them into the lib/lib32 or lib/lib64 directory. This will overwrite the libraries in lib/lib32 and lib/


== Windows ==
Using MiToBo with a [[Installation/Linux|Linux operating system]].


<br/>'''Notice:''' The ImageJ directory path depends on your ImageJ installation. Following, we assume that the ImageJ home directory is set up to ''C:\Program Files\ImageJ\''.<br\><br/>
<br>


For installing MiToBo into an existing ImageJ installation perform the following steps:
=== Windows ===


# go to the '''MiToBo-bin\plugins\''' directory
Using MiToBo with a [[Installation/Windows|Windows operating system]].
#* copy the ''Mi_To_Bo.jar'' to your ''..\ImageJ\plugins\'' directory
#* copy all jars to your ''..\ImageJ\plugins\jars\'' directory <span style="text-decoration: underline;">except</span> the ij.jar and jars already existing<br/>('''Notice:''' MiToBo requires explicite versions of some jars, other versions may not work probably, see [[downloads|requirements]].)<br/><br/>
# go to the '''MiToBo-bin\lib\''' directory
#* copy the ''libwin32'' directory to your ''..\ImageJ\'' directory<br/><br/>
# go to the '''MiToBo-bin\macros\toolsets\''' directory
#* copy the ''MiToBo_Runner.txt'' to your ''..\ImageJ\macros\toolsets\'' directory<br/><br/>
# configurate your ImageJ startup<br/><br/>
:* edit ImageJ configuration file ''..\ImageJ\ImageJ.cfg'' and add the library path<br/><br/>'''-Djava.library.path="C:\Program Files\ImageJ\libwin32"'''<br/><br/>Example of an ImageJ.cfg file:
    C:\Program Files\ImageJ\
    C:\Program Files\Java\jre6\bin\javaw.exe
    -Djava.library.path="C:\Program Files\ImageJ\libwin32" -cp "C:\Program Files\ImageJ\ij.jar" ij.ImageJ
<br/>
:* as an alternative you can start ImageJ from command line
::* open your Windows command line
::* move to the ''..\ImageJ\'' directoy
::* type the following command:
  java -Djava.library.path="C:\Program Files\ImageJ\libwin32" -cp "C:\Program Files\ImageJ\ij.jar" ij.ImageJ

Latest revision as of 11:59, 29 November 2023

General remarks

There are two common ways to work with MiToBo:

  • just using the operators included in MiToBo for improving your work and easing image processing tasks, e.g., via ImageJ or Fiji
  • using the MiToBo API to write operators, plugins and other image analysis applications on your own

The functionality of MiToBo is best used from within ImageJ or Fiji. In case that you aim to use MiToBo for your own development, you need to download the binaries explicitly. The actual installation instructions differ in some parts depending on which way of using MiToBo you have in mind.
Below we will first outline more details about the installation steps required for simply using MiToBo's operators in ImageJ and Fiji, and then provide some notes regarding the binary zip file. Finally we will present some details for using MiToBo's API with your own code.

The recommended way to install and run MiToBo and its operators/plugins is via Fiji!
MiToBo has its own Fiji update site named "MiToBo".

http://sites.imagej.net/MiToBo

To enable this site in your Fiji installation refer to the Fiji documentation.

Note that for some plugins (e.g., PaCeQuant) also the "Biomedgroup" update site needs to be activated.

Using MiToBo with Fiji

Since release 1.5 MiToBo features a Fiji update site and the easiest way to use MiToBo's operators and plugins is to enable the update site in your Fiji installation.
The MiToBo update site is

http://sites.imagej.net/MiToBo

To enable the site in your Fiji installation refer to the Fiji documentation.

Important notices:

  • Occasionally MiToBo operators crash when run from within Fiji. The reason for this behaviour are most of the time conflicting jar archives delivered with the Fiji distribution.
    We figured out that particularly the jar file
    • jars/bio-formats/formats-common-5.1.x.jar
    often causes such trouble. Thus, if you encounter problems running MiToBo operators, please try to locally delete or uninstall the abovementioned jar archive from your local Fiji installation and then re-run the MiToBo operator.
  • For some of our operators special issues exist and require special treatment:
    • CellBoundaryExtractor2D: there are version conflicts with regard to the JGraphT library used by this operator and also by default included in every Fiji distribution; please refer to installation instructions on the webpage of the operator for a workaround


Using MiToBo with ImageJ

Important Note 1: Before you consider installing MiToBo manually within ImageJ, check if it could not be an option to use Fiji and activate MiToBo's update site - in most cases this will be significantly less painful...

Important Note 2: These instructions refer to ImageJ 1.


General remarks:
For using MiToBo with ImageJ it is the easiest to download the latest distribution zipfile (*-bin.zip) from

https://moon.informatik.uni-halle.de/repository/releases/de/unihalle/informatik/MiToBo/mitobo-plugins/

which already includes all dependencies and ships with some scripts to run MiToBo's operators and plugins out of the box.

Linux

Using MiToBo with a Linux operating system.


Windows

Using MiToBo with a Windows operating system.