FARSIGHT Tutorials/Building Software/Bio-Formats/WinTutorial
WARNING: This tutorial is still under development. Currently, FARSIGHT has not been confirmed to work amicably with Bio-Formats. In theory, however, these are the steps one would take to make them work.
This step-by-step guide is intended to be used by developers of the FARSIGHT and Bio-Formats projects. The goal of this tutorial is to download and build all the required source code and components for these two projects. At the end of this tutorial, you should be able to easily make modifications to the source code and rebuild your solutions.
This tutorial is specifically designed for Windows operating systems and was created on 32-bit Windows XP and 64-bit Windows 7. There are analogous tutorials for Linux and Mac.
If you only need to use FARSIGHT for image analysis and don't need to make modifications to source code see the user-only tutorial section.
If you have any problems during this process, please contact the bio-formats team.
Contents |
Cmake GUI Mini-Guide
This tutorial will be using cmake to generate platform-specific makefiles for the FARSIGHT components, and may be used in troubleshooting Bio-Formats components. This will be done via the cmake GUI. The cmake GUI is opened from
Start Menu -> All Programs -> Cmake <version> -> CMake (cmake-gui)
When you open the Cmake GUI you will see lines "Where is the source code:" and "Where to build the binaries:" - these need to be filled in appropriate to the source/build locations of your current target. Once they are filled in, you can press "Configure" to do an initial configuration for your project.
Your GUI should look approximately like this:
When you press configure, you will be prompted to select a generator. You should have Microsoft Visual Studio 9 2008 installed on your system, and select it here. Then click the radio button for "Specify native compilers" and click Next.
On the next step you should enter the path to your MSVC9 C compiler for both the C and C++ compilers. If you used the default install for visual studio, this will be C:/Program Files(x86)/Microsoft Visual Studio 9.0/VC/bin/cl.exe. Click Finish to start the initial configure.
After configuring, you will see lists of keys mapping attribute names to values. At this point you should ensure the "Avanced" button above the list of keys is checked, as many of the attributes you'll be changing are in the "Advanced" list - advanced mode simply expands the list of keys that is displayed.
There are several different types of key values, including boolean (checkboxes) paths and filepaths. After making any changes, as needed for the current project, press Configure. If there are any new, dependent keys that pop up based on the changes you've made they will be red. Just keep Configuring until there are no red entries any more. The Generate option will now be available - click it to create a MSVC 9 solution. You can then open this solution in MSVC 9 and start the compilation process with F7.
Adding to your Path
Windows will require you to add several paths to your "Path" environment variable. To edit this variable in Windows 7:
- Click Start
- Right-click on "Computer"
- Click Advanced System Settings
- Click Environment Variables
In the "System Variables" section you will find the "Path" variable and can edit it. Multiple paths can be added to this single variable, each being separated with a semi-colon (;).
32-bit vs. 64-bit Windows
This guide was written using 64-bit Windows 7 for the example paths. As the builds for FARSIGHT and Bio-Formats were 32-bit targets, the supporting software was for a 32-bit architecture, and thus most path references are C:\Program Files (x86)\<path>. The x86 addition is the "32-bit" Program Files directory on 64-bit Windows, so if you're using a 32-bit OS you likely just have a "Program Files" directory and will have to adjust your paths from this tutorial as such.
Prerequisites
You will need a C/C++ compiler to compile the code for these projects. This tutorial was only tested with Microsoft Visual Studio 9 Express. Make sure you have the most recent Windows updates before installing MSVS. MSVS10 has known issues with FARSIGHT that require manual recompilation of Qt (at the least).
You will also need Subversion to check out code. We recommend (and will provide instructions for) Tortoise SVN. Just pick the appropriate 32 or 64 bit installer.
Farsight
Step 1: Organize your Directories
There is a significant amount of code for both of these projects, with a number of dependencies. It will be extremely helpful to organize your code in a meaningful way. Additionally, the instructions in this tutorial will assume a specific hierarchy of directories when indicating where to download or install certain components.
In particular, it is assumed that there is a specific <path to directory>/ where you will create a farsight/ and loci/ folder. This could simply be your top-level, C:\ directory.
For convenience, we will assume an environment variable ROOT_DIR pointing to this top-level path has been defined. Throughout this tutorial, paths will be referenced as $ROOT_DIR\<path>.
You should now build folders representing the following structure in your $ROOT_DIR:
- farsight
- farsight
- build
- itk
- vtk
- vxl
- ftk
- build
- farsight
- loci
- bioformats
- jace
Step 2: Download the Source Code
In this step we will download the source code for FARSIGHT and Bio-Formats, and the components upon which these projects depend (ITK, VTK, VXL and Jace).
Download and extract the following projects' source code into your $ROOT_DIR/farsight directory:
- VXL - Use version previous to current build. Last tested v 1.13.0
- ITK - Last tested v 3.20.0
- VTK - Last tested v 5.6.0
Next we'll check out code for FARSIGHT, Bio-Formats and Jace. In each case, navigate to the destination directory in your Windows Explorer. Right-click anywhere in the directory and select "SVN Checkout..." to check out code with TortoiseSVN.
The TortoiseSVN GUI should look like this:
For each project, use the following information:
- FARSIGHT - destination directory: $ROOT_DIR\farsight\farsight. URL of repository: svn://www.openworld.rpi.edu/repos/farsight/trunk.
- Bio-Formats - destination directory: $ROOT_DIR\loci\bioformats. URL of repository: http://dev.loci.wisc.edu/svn/software/trunk
- Jace - destionation directory: $ROOT_DIR\loci\jace. URL of repository: https://jace.svn.sourceforge.net/svnroot/jace/trunk. Click the "Revision" radio button at the bottom of the Checkout GUI, and enter "39" in the empty bar to the right. Note: more recent versions of Jace will likely break your build.
Step 3: Install Supporting Software
We will be manually compiling code, using Cmake to manage project configurations. Thus you will need the cmake gui. FARSIGHT requires QT and Boost; certain modules also require glut. You will also need a JDK, Ant and the Boost thread library for Bio-Formats.
- Java - Go here and click one of the "Download JDK" links. This should take you to a platform selection page - choose Windows, NOT Windows x64, regardless of what version of Windows you are using. Agree to the license and click "continue" to proceed to the .exe download page. Simply run the executable after downloading and follow the setup wizard to install Java. After installation, add "C:\Program Files (x86)\Java\jdk1.6.0_22" to your Path, and define a new environment JAVA_HOME set to "C:\Program Files (x86)\Java\jdk1.6.0_22".
- Ant - Download the latest zipped binaries from this location. Extract the archive's contents to a location of your choice, e.g. C:\ProgramFiles(x86)\. Then add C:\Program Files (x86)\aparche-ant-<version>\bin to your Path.
- Qt - Go to this location and download the Qt open source (LPGL) source code for Windows - last tested version 4.7.1. Follow the instructions on this page.
- Boost - Go to this location and download the latest BoostPro Installer (last tested with 1.44.0). Run the downloaded installer. On the Select default variants screen, select the version of MSVS you are using (9.0 if you are following this tutorial). Select all the variants on the right-hand side. On the Choose Components screen, select all components. Components with a gray checkbox are not selected - only those with green checkboxes are actually selected. Keep following the install wizard to download and install Boost.
- Glut - First download the zipped binaries from here. Extract the archive contents to a location of your choice. In the extracted folder, move glut32.dll to your C:\Windows\System32 folder. Move glut.h to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\include\gl (you probably will have to create the "gl" subdirectory"). Move glut32.lib to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\lib\. You can follow this tutorial if necessary.
- Glext.h - Create a new document called "glext.h" in your C:\Program Files (x86)\Microsoft SDKs\Windodws\v7.0A\Include\gl directory (where GL.h is). Open glext.h, then copy and paste its code from this location.
Step 4: Install VXL
Open the Cmake GUI. Set the source path to: $ROOT_DIR\farsight\vxl-<version>. Set the build path to $ROOT_DIR\farsight\farsight\build\vxl. Press "Configure" and specify the generator and native compiler. Click "Finish" to start the configure process.
After the initial configuration, switch to advanced mode and turn the following options OFF:
- BUILD_BRL
- BUILD_CONVERSIONS
- BUILD_EXAMPLES
- BUILD_GEL
- BUILD_OUL
- BUILD_OXL
- BUILD_PRIP
- BUILD_TBL
- BUILD_TESTING
Press "Confifgure" after making your changes, and then "Generate" to create your solution file.
In Visual Studio, open $ROOT_DIR\farsight\farsight\build\vxl\vxl.sln. Change "Debug" to "Release" for the Solution Configuration. Then, start your build with F7.
Step 5: Install ITK
Open the Cmake GUI. Set the source path to: $ROOT_DIR\farsight\InsightToolkit-<version>. Set the build path to: $ROOT_DIR\farsight\farsight\build\itk. Press "Configure" and specify the generator and native compiler. Click "Finish" to start the configure process.
After the initial configuration, switch to advanced mode and turn the following options OFF:
- BUILD_TESTING
- BUILD_EXAMPLES
- BUILD_DOXYGEN
Set the following options ON:
- BUILD_SHARED_LIBS
- IKT_USE_SYSTEM_VXL
After making your changes, press "Configure" until you are able to generate, then press "Generate" to create your solution file.
In Visual Studio, open $ROOT_DIR\farsight\farsight\build\itk\ITK.sln. Change "Debug" to "Release" for the Solution Configuration. Then, start your build with F7.
After the build is complete, add $ROOT_DIR\farsight\farsight\build\itk\bin\Release (the path to ITKCommon.dll) to your Path variable.
Step 6: Install VTK
Open the Cmake GUI. Set the sourth path to: $ROOT_DIR\farsight\vtk-<version>. Set the build path to: $ROOT_DIR\farsight\farsight\build\vtk. Press "Configure" and specify the generator and native compiler. Click "Finish" to start the configure process.
After the initial configuration, switch to advanced mode and turn the following options OFF:
- VTK_USE_SYSTEM_JPEG
- VTK_USE_SYSTEM_TIFF
- VTK_USE_SYSTEM_ZLIB
- BUILD_DOCUMENTATION
- BUILD_EXAMPLES
- BUILD_SHARED_LIBS
- BUILD_TESTING
Turn the following options ON:
- VTK_USE_BOOST
- VTK_USE_GUISUPPORT
- VTK_USE_QT
Then use the "Add Entry" button to define the following variables with these corresponding values values:
These variables are of the "Path" type:
- JPEG_INCLUDE_DIR = $ROOT_DIR\farsight\vxl-<version\v3p\jpeg
- TIFF_INCLUDE_DIR = $ROOT_DIR\farsight\vxl-<version\v3p\tiff
- ZLIB_INCLUDE_DIR = $ROOT_DIR\farsight\vxl-<version\v3p\zlib
These variables are of the "Filepath" type:
- JPEG_LIBRARY = $ROOT_DIR\farsight\farsight\build\vtk\lib\Release\jpeg.lib
- TIFF_LIBRARY = $ROOT_DIR\farsight\farsight\build\vtk\lib\Release\tiff.lib
- ZLIB_LIBRARY = $ROOT_DIR\farsight\farsight\build\vtk\lib\Release\z.lib
Press "Configure" after making your changes, and then "Generate" to create your solution file.
In Visual Studio, open $ROOT_DIR\farsight\farsight\build\vtk\VTK.sln. Change "Debug" to "Release" for the Solution Configuration. Then, start your build with F7.
Step 7: Install FARSIGIHT
Open the Cmake GUI. Set the sourth path to: $ROOT_DIR\farsight\farsight. Set the build path to: $ROOT_DIR\farsight\farsight\build\ftk. Press "Configure" and specify the generator and native compiler. Click "Finish" to start the configure process.
After the initial configuration, set the following variables OFF:
- BUILD_EXAMPLES
- BUILD_TESTING
You can also turn any modules on or off, as desired. This tutorial assumes you will build the Nucleus Editor (BUILD_NUCLEI) at a minimum.
If you would like to build a module that requires GLUT, you will have to set the following variables as well:
- GLUT_INCLUDE_DIR = C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\include\gl
- GLUT_glut_LIBRARY = C:\Program Files (x86)\Micrsoft Visual Studio 9.0\VC\lib\glut32.lib
Press "Configure" after making your changes, and then "Generate" to create your solution file.
In Visual Studio, open $ROOT_DIR\farsight\farsight\build\ftk\Farsight.sln. Change "Debug" to "Release" for the Solution Configuration. Then, start your build with F7.
When this build completes, you will have a working version of FARSIGHT installed on your computer. You can try out $ROOT_DIR\farsight\farsigiht\build\ftk\exe\Release\Nucleus Editor.exe.
Here's a sample image opened in the FARSIGHT Nucleus Editor:
Note: multidimensional images are not fully supported (the time-slice slider probably will not work) and if you try to open a file type not natively supported, you will see the message "NO IMAGEIO WAS FOUND" in your terminal. This is because FARSIGHT is built on ITK, which uses a plug-in system. When opening an image, the ITK_AUTOLOAD_PATH environment variable is checked for supporting plug-ins to see if there is an available plug-in that can open the current image type.
Lacking a plug-in, a limited number of formats are supported natively. In the next section of this tutorial, we will build the Bio-Formats plug-in, which will allow processing additional file types.
Bio-Formats
Step 8: Install BF-CPP
FARSIGHT modules are written in C++ while Bio-Formats is written in Java - this requires an intermediary to translate between the languages. We use Jace to create C++ proxies for Java methods, then the actual BF-ITK plug-in uses these bindings in its image processing. In this step we will create the C++ bindings.
In your command prompt, navigate to $ROOT_DIR\loci\bioformats and run:
ant tools
When that script finishes, navigate to $ROOT_DIR\loci\bioformats\components\native\bf-cpp and run the command:
ant -Djace.home=$ROOT_DIR\loci\jace
After this script completes, a Visual Studio instance should open up with your BF-CPP project solution loaded. Change "Debug" to "Release" for the Solution Configuration. Then, start your build with F7.
Step 9: Install BF_ITK
In your terminal, navigate to $ROOT_DIR\loci\bioformats\components\native\bf-itk and run the command:
ant -Djace.home=$ROOT_DIR\loci\jace -Ditk.home=$ROOT_DIR\farsight\farsight\build\itk
After this script completes, a Visual Studio instance should open up with your BF-ITK project solution loaded. Change "Debug" to "Release" for the Solution Configuration. Then, start your build with F7.
After this build completes, in your same terminal, run the command:
ant -Djace.home=$ROOT_DIR\loci\jace -Ditk.home=$ROOT_DIR\farsight\farsight\build\itk dist
to put all the necessary plug-in files in a common folder. Your $ROOT_DIR\loci\bioformats\components\native\bf-itk\build\dist\bf-itk should now look like this:
To enable ITK-based applications (i.e., FARSIGHT) to use this plug-in, you need to create a new environment variable ITK_AUTOLOAD_PATH with the value: $ROOT_DIR\loc\bioformats\components\native\bf-itk\build\dist\bf-itk
Now, when you open a new instance of a module like the Nucleus Editor, you should be able to work with images of all the types supported by Bio-Formats. If you ever disable the ITK_AUTOLOAD_PATH to turn the BFITK plugin off, your FARSIGHT modules will respond with a "NO IMAGEIO FOUND" error message whenever you try to open an unsupported image type.
