Update README.md

This makes "make" build only the most useful software by default.

Building the test_plugin target requires fortran and openmp, which are
otherwise not required for the durin plugin itself, and is not of
interest to most building the software.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2018, Diamond Light Source
+Copyright (c) 2018-2019, Diamond Light Source
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -8,15 +8,15 @@ modification, are permitted provided that the following conditions are met:
     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
-    * Neither the name of the <organization> nor the
+    * Neither the name of the copyright holder nor the
       names of its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR
-DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

Makefile

@@ -10,12 +10,12 @@ BSLZ4_INC_DIR = $(BSLZ4_SRC_DIR)
 CC=h5cc
 CFLAGS=-Wall -g -O2 -fpic -I$(INC_DIR) -I$(BSLZ4_INC_DIR) -std=c89
 
-.PHONY: all
-all: plugin example test_plugin
-
 .PHONY: plugin
 plugin: $(BUILD_DIR)/durin-plugin.so
 
+.PHONY: all
+all: plugin example test_plugin
+
 .PHONY: example
 example: $(BUILD_DIR)/example
 

README.md

@@ -29,8 +29,69 @@ series of datasets named `data_000001`, `data_000002`, etc.
 
 
 ## Building
+
+### Building HDF5 library
+The HDF5 library used when building durin must have been compiled with specific switches enabled
+to allow the durin plugin to be built and used.
+
+Download the HDF5 source code (https://www.hdfgroup.org/downloads/hdf5/source-code) and extract
+to any directory (referred to as `/hdf5_dir`), and run the following commands.
 ```
-cd durin
+cd /hdf5_dir
+mkdir build
+cd build
+export CFLAGS=-fPIC
+../configure --enable-threadsafe --enable-deprecated-symbols --enable-hl --enable-unsupported
+make
+make check
+make install
+```
+The hdf5 tools and libraries should now be located in `/hdf5_dir/build/hdf5`
+
+For reference, the plugin requires the thread-safe switch and the optimised chunk read function.
+The chunk read function may be defined in the high level library instead of the regular library,
+depending on the exact HDF5 version downloaded (hence the --enable-deprecated-symbols _and_ --enable-hl).
+The unsupported flag enables building with both threadsafe and high-level enabled.
+
+
+### Building durin plugin
+The plugin makefile will use the "h5cc" compiler wrapper, provided by the HDF5 library, which
+must be on your PATH.
+Download or clone the plugin source code (https://github.com/DiamondLightSource/durin)
+into any directory (referred to as `/durin_dir`) and run the following commands.
+```
+cd /durin_dir
+PATH=/hdf5_dir/build/hdf5/bin:$PATH
 make
 ```
-Plugin file is `build/durin-plugin.so`
+The plugin is located at `/durin_dir/build/durin-plugin.so` and should be added to the
+XDS.INP file as `LIB=/durin_dir/build/durin-plugin.so`
+
+
+
+## Example XDS.INP
+```
+DETECTOR=PILATUS MINIMUM_VALID_PIXEL_VALUE=0 OVERLOAD=4096
+LIB=/opt/durin/build/durin-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
+```
+
+N.B. the master file is needed, not the .nxs one which follows the
+standard.

src/file.c

@@ -567,7 +567,13 @@ close_dataset:
 	H5Dclose(ds_id);
 done:
 	return retval;
+}
 
+
+int get_null_pixel_mask(const struct ds_desc_t *desc, int *buffer) {
+	hsize_t buffer_length = desc->dims[1] * desc->dims[2];
+	memset(buffer, 0, sizeof(*buffer) * buffer_length);
+	return 0;
 }
 
 
@@ -808,7 +814,8 @@ int create_dataset_descriptor(struct ds_desc_t **desc, struct det_visit_objects_
 			H5Lexists(g_id, "detectorSpecific/pixel_mask", H5P_DEFAULT) > 0) {
 		pxl_mask_func = &get_dectris_eiger_pixel_mask;
 	} else {
-		ERROR_JUMP(-1, done, "Could not locate pixel_mask");
+		pxl_mask_func = &get_null_pixel_mask;
+		fprintf(stderr, "WARNING: Could not find pixel mask - no masking will be applied\n");
 	}
 
 	/* determine where the data is stored and what strategy to use */