source: branches/4.0.0/components/native/itk-plugin/readme.txt @ 4879

Revision 4879, 3.5 KB checked in by melissa, 11 years ago (diff)

Synced 4.0.0 branch to r4878 (including r4804).

Line 
1Bio-Formats ITK plugin
2----------------------
3
4This package provides an ImageIO plugin for ITK that uses Bio-Formats
5to read and write supported life sciences file formats.
6
7The initial plugin implementation is complete. However, there are a number of
8symbol lookup errors at runtime, so portions of the functionality are currently
9commented out to avoid them.
10
11
12LICENSE
13
14OME Bio-Formats package for reading and converting biological file formats.
15Copyright (C) 2005-@year@ UW-Madison LOCI and Glencoe Software, Inc.
16
17This program is free software; you can redistribute it and/or modify
18it under the terms of the GNU General Public License as published by
19the Free Software Foundation; either version 3 of the License, or
20(at your option) any later version.
21
22This program is distributed in the hope that it will be useful,
23but WITHOUT ANY WARRANTY; without even the implied warranty of
24MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
25GNU General Public License for more details.
26
27You should have received a copy of the GNU General Public License
28along with this program; if not, write to the Free Software
29Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
30
31Adapted from the Slicer3 project: http://www.slicer.org/
32http://viewvc.slicer.org/viewcvs.cgi/trunk/Libs/MGHImageIO/
33
34See slicer-license.txt for Slicer3's licensing information.
35
36For more information about the ITK Plugin IO mechanism, see:
37http://www.itk.org/Wiki/Plugin_IO_mechanisms
38
39
40BUILDING AND TESTING THE PLUGIN ON LINUX
41
421) Download and build the Insight Toolkit source code from:
43
44  http://www.itk.org/ITK/resources/software.html
45
462) Follow the directions in components/native/bf-cpp to build the Bio-Formats
47   C++ bindings.
48
493) Change to this directory (components/native/itk-plugin).
50
514) Run the (lame, temporary) build script:
52
53  ITK_DIR=/path/to/itk/build sh build.sh 2> /dev/null
54
555) After the build succeeds, the script will copy dependent libraries
56   (libjace.so, libbfjace.so, jace-runtime.jar and loci_tools.jar) into the ITK
57   binaries directory, then suggest some commands to proceed in testing. These
58   commands boil down to: a) set ITK_AUTOLOAD_PATH; b) run ImageHistogram1
59   example program on a TIFF file; c) optionally, clear ITK_AUTOLOAD_PATH and
60   rerun to compare against the results with ITK's built-in TIFF reader.
61
62If you get this far, you will have noticed that the histogram is always filled
63with 255s. This is because the plugin does not currently copy the planar data
64between data structures, due to one of the symbol lookup errors.
65
66
67SYMBOL LOOKUP ERRORS
68
69As a rule of thumb, anything labeled "NB:" or "TEMP" in the
70itkBioFormatsImageIO.cxx source file documents a known problem and/or
71associated workaround at the moment, the most show-stopping of which are the
72symbol lookup errors.
73
74For example, from lines 260-2 of itkBioFormatsImageIO.cxx:
75
76  // NB: Using brackets with a JArray causes a symbol lookup error on:
77  //     _ZN4jace6helper12newGlobalRefEP10_Jv_JNIEnvP9__jobject
78  //for (int i=0; i<bytesPerSubPlane; i++) data[p++] = buf[i];
79
80Uncommenting the for loop and rerunning the build script yields:
81
82  $ ./ImageHistogram1 image.tif
83  *snip output*
84  Reading image plane 1/1
85  ./ImageHistogram1: symbol lookup error: libBioFormatsIO.so: undefined symbol: _ZN4jace6helper12newGlobalRefEP10_Jv_JNIEnvP9__jobject
86
87Dumping the relevant symbols from libjace.so yields:
88
89  $ nm libjace.so | grep newGlobalRef
90  00025621 T _ZN4jace6helper12newGlobalRefEP7JNIEnv_P8_jobject
91
92So the symbol is essentially there, but slightly different...
Note: See TracBrowser for help on using the repository browser.