Installation: Difference between revisions

From MiToBo
Jump to navigationJump to search
No edit summary
 
(14 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 with your own code.
 
== The [[downloads|MiToBo Binary]] Zip File ==
 
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 and files:
* 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
* plugins - includes MiToBo jar and other jars used by MiToBo
* testimages - some sample images
* ''MiToBo-Guide-1.0.pdf'' - the user and programmer guide for MiToBo
* ''oprunner.sh'' - shell script to run MiToBo operators from commandline (Linux only)
* ''run.sh'' - shell script to run ImageJ with MiToBo (Linux only)
* ''README'' - with basic information
 
== Using MiToBo with ImageJ ==
 
'''Important Note:''' These instructions refer to ImageJ 1 only, instructions for ImageJ 2.0 will follow soon.


<br>
<br>
== 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. <br> The MiToBo update site is<br>


=== Linux ===
[http://sites.imagej.net/MiToBo http://sites.imagej.net/MiToBo]


==== Use MiToBo as shipped ====
To enable the site in your Fiji installation refer to the [http://fiji.sc/How_to_follow_a_3rd_party_update_site Fiji documentation].
Extract the zip file to a directory of your choice.<br>
You can use MiToBo right away using the ''run.sh'' and ''oprunner.sh'' scripts.<br>
Make sure that they have the 'x'-bit set before executing the scripts, i.e. do 'chmod u+x run.sh' and 'chmod u+x oprunner.sh' first.<br>
If an '''UnsatisfiedLinkError''' occurs, please read the '''Native libraries''' section below.


==== Use MiToBo with an existing ImageJ installation ====
'''Important notices:'''<br>
<ul>
<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


To use MiToBo with an existing ImageJ installation perform the following steps:
* jars/bio-formats/formats-common-5.1.x.jar


# copy the ''Mi_To_Bo.jar'' to be found in the 'plugins/' folder of the MiToBo zip-file to your 'ImageJ/plugins/' directory
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.
# 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 any jars already existing in your 'ImageJ/plugins/jars/' directory<br/>('''Notice:''' MiToBo requires explicit versions of some jars, other versions may not work properly, see [[downloads|requirements]].)
<li> For some of our operators special issues exist and require special treatment:
# copy the ''MiToBo_Runner.txt'' from the 'macros/toolsets/' directory in the MiToBo zip-file to your 'ImageJ/macros/toolsets/' directory;<br> then you can select the MiToBo toolset from the list of available sets by clicking on the arrows button on the right side of the ImageJ standard toolbar
<ul>
# Make the native libraries in lib/ of the MiToBo zip-file available to Java (see the '''Native libraries''' section below)
<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
</ul>
</ul>


You can still use the ''run.sh'' and ''oprunner.sh'' scripts if you copy them to your 'ImageJ/' directory.
<br>


==== Native libraries ====
== Using MiToBo with ImageJ ==


Some operators of MiToBo use native code via the Java Native Interface (JNI).<br>
'''Important Note:''' These instructions refer to ImageJ 1 only, instructions for ImageJ 2.0 will follow soon.
The 'lib/' directory in the zip-file provides precompiled JNI-libraries for 32- (lib/lib32) and 64-Bit (lib/lib64) Linux systems.<br>
For using the native code add the libraries appropriate for your system to the library path. <br>
The path to the native libraries must be available to any java application which uses MiToBo operators that depend on these libraries.<br>


* The ''run.sh'' and ''oprunner.sh'' scripts both add the 'lib/lib32' or 'lib/lib64' directory (depending on your architecture)<br> to the LD_LIBRARY_PATH, thus, you do not have to configure the LD_LIBRARY_PATH manually.
<br>
* 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 call to Java 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:
  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.


* '''Building of MiToBo's native libraries:'''
=== Linux ===
: MiToBo ships with precompiled native libraries for 32- and 64-Bit Linux. If you encounter problems with the Linux libraries you might try to compile MiToBo's native libraries by yourself:
: 1. Download the zip file containing the sources of MiToBo and unpack the file to a directory of your choice.
: 2. Go to the 'native/export' directory in MiToBo's directory structure.
: 3. Edit ''Makefile.rules'' if necessary (defaults are predefined):
::* Set the variable MITOBO_HOME which should point to your MiToBo installation directory.
::* Set the path to your java installation which includes the JNI-header files.
::* Set the path to the CGAL libraries.
::* Set the path to the CGAL headers.
: 4. Run ''make install'', which will build MiToBo's native libraries for your architecture and move them into the lib/lib32 or lib/lib64 directory. Note that this will overwrite the libraries in 'lib/lib32' and 'lib/lib64', respectively.


:Note that when using these libraries also the CGAL libraries have to be available on the LD_LIBRARY_PATH upon execution of MiToBo operators.
Using MiToBo with a [[Installation/Linux|Linux operating system]].


<br>
<br>
Line 80: Line 45:
=== Windows ===
=== Windows ===


<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/>
Using MiToBo with a [[Installation/Windows|Windows operating system]].
 
==== Use MiToBo with an existing ImageJ installation ====
 
For installing MiToBo into an existing ImageJ installation perform the following steps:


# go to the '''MiToBo-bin\plugins\''' directory
#* 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\macros\toolsets\''' directory
#* copy the ''MiToBo_Runner.txt'' to your ''..\ImageJ\macros\toolsets\'' directory<br/><br/>
==== Native libraries ====
Some operators of MiToBo use native code via the Java Native Interface (JNI).<br>
The 'lib/' directory in the zip-file provides precompiled JNI-libraries for 32-Bit (lib/libwin32) Windows systems.<br>
At the moment, JNI-librarie for Windows are only available for 32-Bit architectures, but can also be used with an 64-Bit architecture (see below).<br>
For using the native code add the libraries to the library path. <br>
The path to the native libraries must be available to any java application which uses MiToBo operators that depend on these libraries.<br>
===== <span style="text-decoration: underline;">32-Bit architecture</span> =====
# go to the '''MiToBo-bin\lib\''' directory
#* copy the ''libwin32'' directory to your ''..\ImageJ\'' directory<br/><br/>
# configurate your ImageJ startup
#* 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" -Xmx1024m -cp "C:\Program Files\ImageJ\ij.jar" ij.ImageJ
<br>
<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" -Xmx1024m -cp "C:\Program Files\ImageJ\ij.jar" ij.ImageJ


===== <span style="text-decoration: underline;">64-Bit architecture</span> =====
== The [[downloads|MiToBo Binary]] Zip File ==


Using a 64-Bit architecture <span style="text-decoration: underline;">requires a 32-Bit Java</span> installed on the system to use the 32-Bit JNI-libraries.<br>
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 and files:
Perform the following steps to run MiToBo on a 64-Bit architecture:
* lib - includes nesessary libaries for Linux and Windows
 
* licences - includes MiToBo license and licences for other software used by MiToBo
# go to the '''MiToBo-bin\lib\''' directory
* macros - includes the MiToBo macro toolset
#* copy the ''libwin32'' directory to your ''..\ImageJ\'' directory<br/><br/>
* plugins - includes MiToBo jar and other jars used by MiToBo
# configurate your ImageJ startup
* testimages - some sample images
#* edit ImageJ configuration file ''..\ImageJ\ImageJ.cfg'' and add the library path<br/><br/>'''-Djava.library.path="C:\Program Files (x86)\ImageJ\libwin32"'''<br/><br/>Example of an ImageJ.cfg file:
* ''MiToBo-Guide-1.0.pdf'' - the user and programmer guide for MiToBo
    C:\Program Files (x86)\ImageJ\
* ''oprunner.sh'' - shell script to run MiToBo operators from commandline (Linux only)
    C:\Program Files (x86)\Java\jre6\bin\javaw.exe
* ''run.sh'' - shell script to run ImageJ with MiToBo (Linux only)
    -Djava.library.path="C:\Program Files (x86)\ImageJ\libwin32" -Xmx1024m -cp "C:\Program Files (x86)\ImageJ\ij.jar" ij.ImageJ
* ''README'' - with basic information
<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:
  C:\Program Files (x86)\Java\jre6\bin\javaw.exe -Djava.library.path="C:\Program Files (x86)\ImageJ\libwin32" -Xmx1024m -cp "C:\Program Files (x86)\ImageJ\ij.jar" ij.ImageJ
 
<br/>'''Notice:''' The ''-Xmx1024m'' variable sets the maximum memory heap size of Java to 1024 MB. This value can be increased, depending on your installed system memory.<br\><br/>


== Using MiToBo's APIs ==
== Using MiToBo's APIs ==
To use the API of MiToBo and benefit from MiToBo's functionality in your own code you just need to make the jar archive to be found in the zip file available on your classpath. In addition, make sure that all jar archives MiToBo depends on and which are listed on the [[downloads|Download page]] are also in your classpath.<br> Note that the jars are also included in the MiToBo's binary zip file, thus, you don't need to download them manually.
To use the API of MiToBo and benefit from MiToBo's functionality in your own code you just need to make the jar archive to be found in the zip file available on your classpath. In addition, make sure that all jar archives MiToBo depends on and which are listed on the [[downloads|Download page]] are also in your classpath.<br> Note that the jars are also included in the MiToBo's binary zip file, thus, you don't need to download them manually.

Latest revision as of 12:35, 22 January 2019

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.


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: These instructions refer to ImageJ 1 only, instructions for ImageJ 2.0 will follow soon.


Linux

Using MiToBo with a Linux operating system.


Windows

Using MiToBo with a Windows operating system.


The MiToBo Binary Zip File

To get the current release of MiToBo download and extract the MiToBo Binary zip file.
You will find the following structure of directories and files:

  • 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
  • plugins - includes MiToBo jar and other jars used by MiToBo
  • testimages - some sample images
  • MiToBo-Guide-1.0.pdf - the user and programmer guide for MiToBo
  • oprunner.sh - shell script to run MiToBo operators from commandline (Linux only)
  • run.sh - shell script to run ImageJ with MiToBo (Linux only)
  • README - with basic information

Using MiToBo's APIs

To use the API of MiToBo and benefit from MiToBo's functionality in your own code you just need to make the jar archive to be found in the zip file available on your classpath. In addition, make sure that all jar archives MiToBo depends on and which are listed on the Download page are also in your classpath.
Note that the jars are also included in the MiToBo's binary zip file, thus, you don't need to download them manually.