Andre Rothkirch posted on 17. Mar. 2021 13:20h - last edited by Andre Rothkirch on 28. Jun. 2023 15:24h

MSI packages are available for the installation of the external filter plugins for Windows. It is strongly recommended to use these packages and do not attempt to install the packages from the sources.

Required packages

External filter plugins for HDF5 files are available as MSI packages for the installation under Windows (see next section). At least one such MSI package of the external filter plugins and its matching Microsoft C++ runtime environment executable is required for installation.

Packages of (different versions of the) MS C++ runtime environment are all named “vc_redist.x64.exe” for 64Bit installations of Windows and can be downloaded from the Microsoft Support Sites (just google for it!).

Important note: The “.zip” File containing the HDF5 plugins as MSI package comes with a “README.txt” file specifying the exact/appropriate C++ runtime environment needed (see next section).

Note: The filter plugin needed depends on the application you're going to use, i.e. the hdf5 version it ships with and the compiler version used to build the application (see also next section). Even though you can install multiple versions of the plugin, you can define the windows common hdf 5 plugin path variable (see below) only once. Thus, if you use different applications build against different compiler versions, your application(s) should be able to internally (re)definde the plugin path at best.

In the future, the C++ runtime environment will be most likely bundled with the plugin package, so that only one file is required. However, for the time being the C++ runtime package must be installed manually.

MSI-package download

MSI packages are provided by HDF group on a public ftp server contained in '.zip' files. It is strongly recommended to use these provided packages and to not attempt installing the packages from source. The Plugins can be downloaded from this site:

https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.14/hdf5-1.14.1/plugins/ (external link, updated as recommended by hdf group [as of 20.06.2023])

(former/old link was gamma.hdfgroup.org/ftp/pub/outgoing/psfiles/plugins/windows/)

Packages for Windows are currently (as of September 1st, 2019) provided for HDF5 version 1.8 to 1.10 and these are built against different versions of Microsoft Visual Studio.  Files for Microsoft Visual Studio Versions 2012 or 2013 or 2015, 2017 and 2019 exist.  Check the “README.txt” File in the “.zip” File to identify the correct C++ runtime environment needed!

Beside others, the filter plugins allow for blosc, bzip2 and lz4 decompression.  In particular in view of lz4 they support “bitshuffle” mode as e.g. potentially applicable by the EIGER (tm) detectors from DECTRIS.

Notes: The MSI package needed depends on your windows application.  Please ask your beamline contact, which version to use, e.g. for

  • MATLAB 2018b (tm) by The MathWorks, Inc. was found to worked with:
    HDF5PluginsCMake-1.10-win7_64-vs15.zip  (likely works with 2016a and newer as well)
  • For IDL (tm) by Harris Geospatial Solutions, Inc.:
    - IDL 8.7.2 and before are build against version of Visual Studio not newer than VS 2010. There exists a plugin (test-)build for HDF5 1.8 against VS 2010 which is not recognized by IDL 8.7.2,  thus the plugins are considered NOT supported on Windows for IDL before/equal v. 8.7.2.
    Note that hdf5 library support for version hdf5 1.8 .x will end in 2021 and plugin support is depricated for older versions of VS.
    - IDL 8.8 ships with hdf5 version in 1.10.5 and IDL build is made with VS 2015. A preliminary test has been made on hdf5 files using lz4 and bitshuffle and IDL 8.8. was found to work at least with HDF5PluginsCMake-1.10-win10_64-vs15.zip using procedure sketched below (i.e. system variable definition).   

Installation of the C++ runtime environment

The C/C++ runtime environment is shipped as a installable .exe. file named vc_redist.x64.exe. This needs to be installed first. To start the installation just double click on the file and follow the instructions.. It probably requires a restart after the installation!

Installation of the filter plugin

In the following, we illustrate the installation principle of the LZ4 filter plugin required to read data from the Eiger detector. The plugin suitable for e.g. Matlab 2018b comes in an MSI package named “h5pl-1.11.6-win64.msi”, which is contained in the zip archive “HDF5PluginsCMake-1.10-win7_64-vs15.zip”. 

1) With a double click on the “.msi” file the installation wizard launches.

2) Continue by pressing Next and accept the licence agreement

3) In the next step the installation content and path must be confirmed / can be provided

Usually the defaults are fine. Note that this step is important because we need the installation path information for the configuration of a Windows environment variable in the next step of the installation.

Here we used the default path c:\Program Files\HDF_Group\HDF5\1.8.22 (please match this according to your downloaded version).  To continue the installation, press “Next” to come to the last dialog box where you press “Install” to start the installation.

WINDOWS Environment configuration

Before your WINDOWS applications can make use of the filter plugin, one has to make them aware of where to look for the plugin filters.  This is done by defining / adding / modifying a windows environment variable named “HDF5_PLUGIN_PATH”.  On Windows, environment variables can be created and modified via a GUI dialog.  Most probably the easiest way to come to this dialog is by searching for the keyword “environment” in the start menu of your Windows desktop and choose “edit the system environment variables” (alternatively one can reach the GUI dialog window by “Start → Windows System → Control panel → System → Advanced system settings”).  The System Properties dialog showing up to allow for environment variable definition should look similar to this:

Click on button Environment Variables to see current settings/definition settings or for the definition of new ones. The Evironment Variables dialog may look as follows:

If HDF5_PLUGIN_PATH does not already exist (as in the example above), add it as a new system variable by pressing the “New...” button close to the bottom of the dialog. If the variable already exists, than just use the “Edit …” button. This leads you to a new dialog window “Edit System Variable” which allows you to enter the name and the value of an environment variable (more precisely a system wide variable; one may also define the variable as user variable if needed by using the upper “New …” button).

Set as “Variable Name” “HDF5_PLUGIN_PATH” and point the “Variable Value” to the appropriate directory.  The path where to find the plugin library is the installation path (see above) plus an addition of  \lib\plugin . You can also browse to this directory.  The result should be then

Once this variable is set, you may have to restart all applications which should use the plugin. This is necessary as they have to read the new environment variable, which is typically done at application startup.

Applications which we know will work

We have tested the following applications with the filter plugin

  • Matlab 2018B by The MathWorks, Inc. with HDF5PluginsCMake-1.10-win7_64-vs15.zip  (likely works with 2016a and newer as well)
  • Matlab 2017A (tm) by The MathWorks, Inc. was tested with HDF5PluginsCMake-1.8-win7_64-vs12.zip
  • Preliminary finding: IDL 8.8 (tm) by Harris Geospatial Solutions Inc. was tested with HDF5PluginsCMake-1.10-win10_64-vs15.zip
    acccess possible to data being compressed by lz4/bitshuffle (i.e. a single functionalitly of the external filter plugin, NO 1.10 features tested)
  • No labels