mirror of
https://github.com/paulscherrerinstitute/ch.psi.imagej.hdf5.git
synced 2025-06-06 02:20:42 +02:00
Completed update of installation instructions in Readme.md file
This commit is contained in:
parent
da539b17dd
commit
c7d6f1068c
BIN
ImageJ_Updater_AdvancedMode.png
Normal file
BIN
ImageJ_Updater_AdvancedMode.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
BIN
ImageJ_Updater_search_java8.png
Normal file
BIN
ImageJ_Updater_search_java8.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
155
Readme.md
155
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:
|
||||
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
|
||||
|
||||
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 <Source.zip> <FIJI_DIR>`
|
||||
* macOS: `unzip <Source.zip> <FIJI_DIR>`
|
||||
* 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 `<FIJI_DIR>/plugins` and `<FIJI_DIR>/lib`.
|
||||
* The new hdf5 plugin is now ready to be used!
|
||||
|
||||
|
||||
|
||||
## 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 <IMAGEJ_HOME>
|
||||
unzip <path of downloaded zip>
|
||||
unzip <path of downloaded source zip>
|
||||
```
|
||||
|
||||
## 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 <FIJI_HOME>
|
||||
<fiji> --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 <FIJI_HOME>
|
||||
<fiji> --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:
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
BIN
hdf5_Vibez_select_datasets.png
Normal file
BIN
hdf5_Vibez_select_datasets.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 119 KiB |
Loading…
x
Reference in New Issue
Block a user