diff --git a/ImageJ_Updater_AdvancedMode.png b/ImageJ_Updater_AdvancedMode.png new file mode 100644 index 0000000..cc7be91 Binary files /dev/null and b/ImageJ_Updater_AdvancedMode.png differ diff --git a/ImageJ_Updater_search_java8.png b/ImageJ_Updater_search_java8.png new file mode 100644 index 0000000..4d0e762 Binary files /dev/null and b/ImageJ_Updater_search_java8.png differ diff --git a/Readme.md b/Readme.md index 6f061a2..40e4fe5 100644 --- a/Readme.md +++ b/Readme.md @@ -3,25 +3,18 @@ ImageJ plugin for reading and writing HDF5 files. Upon opening an HDF5 file, an import dialog lists the available image data sets -and allows the selection of one or multiple data sets to be opened: +contained in the file and allows the selection of one or multiple data sets to +be opened: ![Import dialog to select datasets to be opened](hdf5plugin_select_datasets.png) -For 3D datasets, the whole data set is read into an image stack by default. -However, only individual slices can also be selected for visualization. -Furthermore, especially for very big datasets, only every n-th slice can be -selected for visualization. This can be done by either specifying a number, -e.g. `10` (for the slice 10) or a number with a preceding %, e.g. `%10` (for -every 10th image). Indexing starts at 0. Another useful feature when working -with lage data sets is the option to load the data into a virtual image stack. - Note that the Fiji distribution of ImageJ comes with an hdf5 plugin already installed out of the box. This packaged hdf5 plugin (HDF5_Vibez) has some great features, and may be all you need. However, it does not allow one to load large -image arrays as virtual stacks, and thus often results in "out of memory" -errors when working with large data sets. In those cases, the PSI plugin for -reading and writing HDF5 files described here might be your preferred choice. - +image arrays as virtual stacks or to select only sliced subsets of the data, +and thus often results in "out of memory" errors when working with large data +sets. In those cases, the PSI plugin for reading and writing HDF5 files +described here might be your preferred choice to work with HDF5 files. # Usage @@ -39,7 +32,8 @@ File > SaveAs > HDF5 ## Scripting -To use this plugin from the ImageJs' (python) scripting interface these lines can be used to open a dataset: +To use this plugin from the ImageJs' (python) scripting interface these lines +can be used to open a dataset: ```python from ch.psi.imagej.hdf5 import HDF5Reader @@ -50,7 +44,7 @@ stack = reader.open("",False, "/Users/ebner/Desktop/A8_d_400N030_.h5", "/exchang # Installation ## Prerequisites -To be able to install this plugin, ImageJ need to be run with a Java 7 or +To be able to install this plugin, ImageJ needs to be run with a Java 7 or greater JVM. At the time of writing, the latest Fiji distribution of ImageJ comes bundled @@ -72,15 +66,17 @@ Java 6. You can check whether Java-8 is included with Fiji as follows: -* Open the update dialog from the menu via Fiji > Help > Update... -* Wait for the application to finish checking for new updates +* Open the update dialog from the menu via `Fiji > Help > Update...`. +* Wait for the application to finish checking for new updates. * In the ImageJ Updater Window, click on "Advanced Mode" -* Type java-8 into the "Search" field. -* If you see an entry lib/Java-8 in the results box below, then Java 8 is ready - to be used on your system (see screenshots below). +* Type `java-8` into the "Search" field. +* If you see an entry `lib/Java-8` in the results box below, then Java 8 is + ready to be used on your system (see screenshots below). + +![ImageJ Updater Advanced Mode](ImageJ_Updater_AdvancedMode.png) +![ImageJ Updater Search Java 8](ImageJ_Updater_search_java8.png) - -## Download the source +## Downloading the source Download latest HDF5 ImageJ plugin from [releases](https://github.com/paulscherrerinstitute/ch.psi.imagej.hdf5/releases). @@ -88,25 +84,75 @@ Download latest HDF5 ImageJ plugin from ## Installation for Fiji with Java 8 +### Deactivate the distributed hdf5 plugin +As mentioned previously, unfortunately the standard hdf5 plugin (HDF5_Vibez) of +Fiji interferes with the PSI plugin. You will be able to tell which plugin is +currently active when trying to import an hdf5 file +(`Fiji > File > Import > HDF5...`). Once you have selected an hdf5 file, the +standard plugin opens an import dialog that looks as follows: +![Import dialog of packaged HDF5_Vibez plugin](hdf5_Vibez_select_datasets.png) + +To disable the standard hdf5 plugin, follow these steps. + +* Open the update dialog from the menu via `Fiji > Help > Update...`. +* Wait for the application to finish checking for new updates. +* In the ImageJ Updater Window, click on "Advanced Mode". +* Type hdf5 into the "Search" field. +* The results box below should now list the `plugins/HDF5_Vibez` entry. +* Select that `plugins/HDF5_Vibez` entry and click "Uninstall" below, then hit + "Apply Changes". +* The "Status/Action" column of the `plugins/HDF5_Vibez` entry should now say + `Not installed`. +* Restart Fiji. + +### Install the PSI hdf5 plugin + +The installation of the plugin essentially only requires one to add the +contents of the downloaded source archive into the `plugins` and `lib` +directories inside the Fiji installation directory. Follow these steps: + +* Locate the installation directory of the Fiji application (`FIJI_DIR`). +* Unpack the contents of the downloaded source file into `FIJI_DIR`: + * Windows: Right-click the zip file with the source and select "Extract + to...", then navigate to `FIJI_DIR`. + * Linux: `unzip ` + * macOS: `unzip ` +* Close any running instances of the Fiji applications, then reopen Fiji. +* Try to import an hdf5 file: `Fiji > File > Import > HDF5...`. + * If the installation of the pluging was sucessful, the file import dialog + should look like in the screenshot below once you have selected an hdf5 + file. + * If there is no `HDF5...` loader available in the + `Fiji > File > Import` menu, the installation did not succeed. Check that + all the files downloaded for the new plugin are actually present in the + correct locations, i.e. in `/plugins` and `/lib`. +* The new hdf5 plugin is now ready to be used! + +![Import dialog to select datasets to be opened](hdf5plugin_select_datasets.png) ## Installation for older versions of ImageJ/Fiji with Java 6 +The following steps assume that no other hdf5 plugin is already installed with +ImageJ/Fiji (see above). -* Download latest HDF5 ImageJ plugin from [releases](https://github.com/paulscherrerinstitute/ch.psi.imagej.hdf5/releases). - -* Go into the ImageJ installation folder and extract the downloaded zip. +Go into the ImageJ installation folder and extract the downloaded zip. ``` cd -unzip +unzip ``` -## Configuration (Optional) +The plugin is now available in ImageJ/Fiji, but you may want to configure it +further for easier use (see below). -If you want to configure the HDF5 Reader as a standard file reader you need to register the reader within the `HandleExtraFileTypes.java` file. -This can be done as follows (details on this can be found on: http://albert.rierol.net/imagej_programming_tutorials.html): +### Configuration (Optional) + +If you want to configure the HDF5 Reader as a standard file reader you need to +register the reader within the `HandleExtraFileTypes.java` file. This can be +done as follows (details on this can be found on: +http://albert.rierol.net/imagej_programming_tutorials.html): * Add `HandleExtraFileTypes.java` @@ -121,8 +167,26 @@ if (name.endsWith(".h5") || name.endsWith(".hdf5")) { javac -classpath ij.jar ./plugins/Input-Output/HandleExtraFileTypes.java ``` +### Older Fiji versions +For older versions of Fiji, we have to instruct Fiji to use an alternative Java +(which has to be installed on the systems separately, of course). This can be +done as follows: + +``` +cd + --java-home /usr/lib/jvm/jre-1.7.0-openjdk.x86_64 -Djava.library.path=lib/linux64 +``` + +Starting with Java 8 just the LD_LIBRARY_PATH variable need to be set. For +MacOSX it is `export DYLD_LIBRARY_PATH=lib/mac64/:$DYLD_LIBRARY_PATH`. + + # Usage +For normal usage, you should just be able to open Fiji/ImageJ as usual and +start using the hdf5 plugin. Below are some hints for advanved usage, +specifying the amount of memory to be used, etc. + ## Mac OS X ``` @@ -135,33 +199,30 @@ java -Djava.library.path=./lib/mac64 -Xmx3048m -jar ImageJ64.app/Contents/Resour java -Djava.library.path=./lib/linux64 -Xmx3048m -jar ij.jar ``` -The `Xmx` setting is quite random it depends on how big hdf5 files you are planning to open. +The `Xmx` setting is quite random it depends on how big hdf5 files you are +planning to open. -# Fiji -Fiji currently comes with Java 6 bundled. As the HDF5 Plugin requires Java 7 or higher we have to instruct Fiji to use an alternative Java. -This can be done as follows: - -``` -cd - --java-home /usr/lib/jvm/jre-1.7.0-openjdk.x86_64 -Djava.library.path=lib/linux64 -``` - -Starting with Java 8 just the LD_LIBRARY_PATH variable need to be set. For MacOSX it is export `DYLD_LIBRARY_PATH=lib/mac64/:$DYLD_LIBRARY_PATH`. - # Development -To be able to run the tests and plugin from within the following arguments need to be passed: +To be able to run the tests and plugin from within the following arguments need +to be passed: ![RunSettings](RunSettings.png) -To create an all in one zip file for installation in a ImageJ installation use: +To create an all in one zip file for installation in a ImageJ installation use: `mvn clean compile assembly:assembly` -The zip file contains an all in one jar as well as the required native libraries for Windows, Linux and Mac OS X. +The zip file contains an all in one jar as well as the required native +libraries for Windows, Linux and Mac OS X. -Note: to be able to build the package you need to have access to the PSI artifact server. Therefore this only works within the PSI networks and if you have a certain maven configuration. An example Maven settings.xml that you can copy to `~/.m2/settings.xml` is located [here](settings.xml). +Note: to be able to build the package you need to have access to the PSI +artifact server. Therefore this only works within the PSI networks and if you +have a certain maven configuration. An example Maven settings.xml that you can +copy to `~/.m2/settings.xml` is located [here](settings.xml). # Acknowledgements -This project was inspired by the ImageJ HDF Plugin of Matthias Schlachter Chair of Pattern Recognition and Image Processing, University of Freiburg, Germany ( https://code.google.com/p/imagej-hdf ) . -It is a complete rewrite of the code with the focus on efficiency and maintainability +This project was inspired by the ImageJ HDF Plugin of Matthias Schlachter Chair +of Pattern Recognition and Image Processing, University of Freiburg, Germany ( +https://code.google.com/p/imagej-hdf ) . It is a complete rewrite of the code +with the focus on efficiency and maintainability diff --git a/hdf5_Vibez_select_datasets.png b/hdf5_Vibez_select_datasets.png new file mode 100644 index 0000000..ef21118 Binary files /dev/null and b/hdf5_Vibez_select_datasets.png differ