Durin
=====

XDS plugin for reading HDF5 files following the NeXuS format or those written by Dectris Eiger detectors.

See:
* https://www.nexusformat.org
* https://www.dectris.com/features/features-eiger-x/hdf5-and-nexus
* https://strucbio.biologie.uni-konstanz.de/xdswiki

## Paul Scherrer Institute fork
This fork is maintained by Paul Scherrer Institute.
The plugin is based on the code developed by the Diamond Light Source and modified by Global Phasing.
Modifications from PSI side:
* Using CMake for building the plugin
* HDF5 is built as part of the CMake process
* Bitshuffle/LZ4 is updated to the latest version
* HDF5 filter is automatically registered for virtual dataset HDF5 files
* Docker image to build the plugin on x86/RH7 is provided.
* Generated versioned shared library, so the used version can be tracked.

## Get Durin
Linux x86 version is automatically built on RHEL 7 and available from the Gitea release page.

## Usage
In your XDS.INP add:
```
LIB=[path to libdurin-plugin.so]
NAME_TEMPLATE_OF_DATA_FRAMES=[data_path]/data_images_??????.h5
```
XDS will instruct the plugin to load `[data_path]/data_images_master.h5` and this must be the
Eiger master file or the NeXus file for the data collection.

It is generally assumed that the files `[data_path]/data_images_data_xxxxxx.h5` contain the actual
datasets and the master file contains HDF5 external links to these, but that is not required, so long as
the master file contains an `NXdata` or `NXdetector` group with either a dataset named `data` or a
series of datasets named `data_000001`, `data_000002`, etc.


## Building
Requires CMake version 3.19 or later + GCC compiler. There is no need to build HDF5 separately.
To build:
```
mkdir build
cd build
cmake ..
make -j
```

The plugin is located at `build/libdurin-plugin.so` and should be added to the
XDS.INP file as `LIB=<CURRENT_DIRECTORY>/build/libdurin-plugin.so`.
Alternatively, versioned copy is also provided, e.g. `libdurin-plugin.so.1.0.0`, allowing to track 
the current version of the plugin.

## Example XDS.INP
```
DETECTOR=PILATUS MINIMUM_VALID_PIXEL_VALUE=0 OVERLOAD=4096
LIB=/opt/durin/build/libdurin-plugin.so
SENSOR_THICKNESS= 0.450
!SENSOR_MATERIAL / THICKNESS Si 0.450
!SILICON= 3.953379
DIRECTION_OF_DETECTOR_X-AXIS= 1.00000 0.00000 0.00000
DIRECTION_OF_DETECTOR_Y-AXIS= 0.00000 1.00000 0.00000
DETECTOR_DISTANCE= 194.633000
ORGX= 1041.30 ORGY= 1160.90
ROTATION_AXIS= 0.00000 -1.00000 -0.00000
STARTING_ANGLE= -30.000
OSCILLATION_RANGE= 0.100
X-RAY_WAVELENGTH= 0.97891
INCIDENT_BEAM_DIRECTION= -0.000 -0.000 1.022
FRACTION_OF_POLARIZATION= 0.999
POLARIZATION_PLANE_NORMAL= 0.000 1.000 0.000
NAME_TEMPLATE_OF_DATA_FRAMES= ../image_9264_??????.h5
TRUSTED_REGION= 0.0 1.41
DATA_RANGE= 1 600
JOB=XYCORR INIT COLSPOT IDXREF DEFPIX INTEGRATE CORRECT
```