adds support for reading patterns from the Oxford HDF5 format (.h5oina)

Note that this requires an update of the EMsoft_SDK to include building the HDF5 plugins!!!

Author: marcdegraef

Source/EMsoftHDFLib/patternmod.f90

@@ -111,7 +111,7 @@ recursive function get_input_type(inputtype) result(itype)
 if (trim(inputtype).eq."TSLup2") itype = 3
 if (trim(inputtype).eq."TSLHDF") itype = 4
 if (trim(inputtype).eq."OxfordBinary") itype = 5
-if (trim(inputtype).eq."OxfordHDF") itype = 6    ! to be implemented
+if (trim(inputtype).eq."OxfordHDF") itype = 6
 if (trim(inputtype).eq."EMEBSD") itype = 7
 if (trim(inputtype).eq."BrukerHDF") itype = 8
 if (trim(inputtype).eq."NORDIF") itype = 9       
@@ -220,6 +220,7 @@ end subroutine invert_ordering_arrays
 !> @date 05/01/19 MA  1.7 add support for Oxford Instruments binary pattern files
 !> @date 10/09/19 HWÅ 1.8 support for NORDIF binary pattern files
 !> @date 04/06/20 MDG 1.9 adds support for 32-bit integer and float HDF files generated by EMEBSD 
+!> @date 11/10/22 MDG 2.0 adds support for Oxford HDF file format 
 !--------------------------------------------------------------------------
 recursive function openExpPatternFile(filename, npat, L, inputtype, recsize, funit, HDFstrings, verbose) result(istat)
 !DEC$ ATTRIBUTES DLLEXPORT :: openExpPatternFile
@@ -319,9 +320,38 @@ recursive function openExpPatternFile(filename, npat, L, inputtype, recsize, fun
         end if
 
     case(6)  ! "OxfordHDF"
-        call FatalError("openExpPatternFile","OxfordHDF input format not yet implemented")
-! at this point in time (Feb. 2018) it does not appear that the Oxford HDF5 format has the 
-! patterns stored in it... Hence this option is currently non-existent.
+! Fall 2022, Oxford has an HDF5 file with extension .h5oina; some of the patterns in the 
+! "Processed Patterns" dataset may have been compressed using the lzf compression scheme.
+! Reading them does not require anything special when the most recent version of the 
+! EMsoft_SDK is used.  It does require that the HDF5_PLUGIN_PATH environment variable is 
+! set to the location of the plugin dynamical libraries; in a development environment, this
+! would be done with the following shell command (csh): 
+!    setenv HDF5_PLUGIN_PATH /full/path/to/EMsoft_SDK/hdf5-1.12.2-Release/lib/plugin
+! We remind the user here that this parameter needs to be set in order for the uncompression
+! dynamically loaded library to be found...  The actual reading of the data set is identical
+! to that of the TSLHDF format, but some or all patterns may be in compressed form.
+! [MDG, 11/09/22]
+       call Message(" ================================================================ ")
+       call Message("The Oxford HDF5 format uses the lzf compression algorithm to      ")
+       call Message("compress patterns; to properly read those patterns and uncompress ")
+       call Message("them, the HDF5_PLUGIN_PATH environmental parameter must be set.   ")
+       call Message("Please make sure that this parameter points to the correct folder;")
+       call Message("for instance, EMsoftOO_SDK/hdf5-1.12.2-Release/lib/plugin or      ")
+       call Message("similar; the folder should contain a liblzf.so or similar library.")
+       call Message(" ================================================================ ")
+
+       nullify(pmHDF_head%next)
+        ! open the file
+        hdferr =  HDF_openFile(ename, pmHDF_head, readonly=.TRUE.)
+        if (hdferr.ne.0) call HDF_handleError(hdferr,'HDF_openFile ')
+        ! open all the groups to the correct level of the data set
+        do i=1,hdfnumg
+            groupname = trim(HDFstrings(i))
+            hdferr = HDF_openGroup(groupname, pmHDF_head)
+            if (hdferr.ne.0) call HDF_handleError(hdferr,'HDF_openGroup: group name issue, check for typos ...')
+        end do
+        ! and here we leave this file open so that we can read data blocks using the hyperslab mechanism;
+        ! we can do this because the pmHDF_head pointer is private and has SAVE status for this entire module
 
     case(4, 7, 10, 11, 12)  ! "TSLHDF", "EMEBSD" , "EMEBSD32i" , "EMEBSD32f" , "EMEBSDdefect" 
         nullify(pmHDF_head%next)
@@ -419,6 +449,7 @@ end function openExpPatternFile
 !> @date 09/26/19 MDG 1.6 add option for vertical flip of patterns
 !> @date 10/09/19 HWÅ 1.7 support for NORDIF binary pattern files
 !> @date 02/02/21 CZ  1.8 support for reading EMEBSDdefect generated file
+!> @date 11/10/22 MDG 2.0 adds support for Oxford HDF file format 
 !--------------------------------------------------------------------------
 recursive subroutine getExpPatternRow(iii, wd, patsz, L, dims3, offset3, funit, inputtype, HDFstrings, &
                                       exppatarray, ROI, flipy) 
@@ -598,8 +629,21 @@ recursive subroutine getExpPatternRow(iii, wd, patsz, L, dims3, offset3, funit,
       where(exppatarray.lt.0.0) exppatarray = exppatarray + 256.0
 
     case(6)  ! "OxfordHDF"
-! at this point in time (Feb. 2018) it does not appear that the Oxford HDF5 format has the 
-! patterns stored in it... Hence this option is currently non-existent.
+! read a hyperslab section from the HDF5 input file; note that these patterns may be 
+! in lzf compressed form; the HDF read routine will transparently take care of the 
+! uncompressing, but only if the proper library can be found; make sure the HDF5_PLUGIN_PATH
+! environmental parameter has been set correctly.  [MDG, 11/09/22]
+       EBSDpatint = HDF_readHyperslabIntegerArray3D(dataset, offset3, dims3, pmHDF_head) 
+        exppatarray = 0.0
+        do kk=kkstart,kkend
+            do jj=1,dims3(2)
+                do ii=1,dims3(1)
+                   z = float(EBSDpatint(ii,jj,kk))
+                   if (z.lt.0.0) z = z+2.0**16
+                   exppatarray((kk-kkstart)*patsz+(jj-1)*dims3(1)+ii) = z
+                end do 
+            end do 
+        end do 
 
     case(4)  ! "TSLHDF" passed tests on 2/14/18 by MDG
 ! read a hyperslab section from the HDF5 input file
@@ -893,12 +937,19 @@ recursive subroutine getSingleExpPattern(iii, wd, patsz, L, dims3, offset3, funi
       where(exppat.lt.0.0) exppat = exppat + 256.0
 
     case(6)  ! "OxfordHDF"
-! at this point in time (Feb. 2018) it does not appear that the Oxford HDF5 format has the 
-! patterns stored in it... Hence this option is currently non-existent.
-
-! Update 07/13/19: after talking with Phillipe Pinard (Oxford) at the EMAS 2019 conference
-! in Trondheim, it is clear that Oxford is working on including the patterns into their
-! current HDF5 file version.  This might become available sometime by the end of 2019.
+! read a hyperslab section from the HDF5 input file; note that these patterns may be 
+! in lzf compressed form; the HDF read routine will transparently take care of the 
+! uncompressing, but only if the proper library can be found; make sure the HDF5_PLUGIN_PATH
+! environmental parameter has been set correctly.  [MDG, 11/09/22]
+       EBSDpatint = HDF_readHyperslabIntegerArray3D(dataset, offset3, dims3, pmHDF_head) 
+        exppat = 0.0
+        do jj=1,dims3(2)
+            do ii=1,dims3(1)
+                  z = float(EBSDpatint(ii,jj,1))
+                  if (z.lt.0.0) z = z+2.0**16
+                  exppat((jj-1)*dims3(1)+ii) = z
+            end do 
+        end do 
 
     case(4)  ! "TSLHDF" passed tests on 2/20/18 by MDG
 ! read a hyperslab single pattern section from the HDF5 input file
@@ -1968,16 +2019,13 @@ recursive subroutine closeExpPatternFile(inputtype, funit)
     case(2,3)  ! "TSLup2"
         close(unit=funit,status='keep')
 
-    case(4, 7, 10, 11, 12)  ! "TSLHDF" "EMEBSD" "EMEBSD32i" "EMEBSD32f" "EMEBSDdefect"
+    case(4, 6, 7, 10, 11, 12)  ! "TSLHDF" "EMEBSD" "EMEBSD32i" "EMEBSD32f" "EMEBSDdefect"
         call HDF_pop(pmHDF_head,.TRUE.)
         nullify(pmHDF_head%next)
 
     case(5)  ! "OxfordBinary"
         close(unit=funit,status='keep')
 
-    case(6)  ! "OxfordHDF"
-        call FatalError("closeExpPatternFile","input format not yet implemented")
-
     case(8)  !  "BrukerHDF"
         call HDF_pop(pmHDF_head,.TRUE.)
         nullify(pmHDF_head%next)