High-speed library for off-axis digital holography and Hermite-Gaussian decomposition
If this library was useful to you, please cite the User Guide [arXiv:2204.02348]
Full function documentation, benchmarks and background information available in the User Guide.
digHolo library introduction (YouTube)
off-axis digital holography tutorial (YouTube)
CPU : x86-64 with AVX2 and FMA3 support (processors after ~2015)
https://www.fftw.org/ (Used for all FFTs and DCTs).
Specifically, the functions cgesvd, sgels, cgemv, cgemm. Linking against openBLAS https://www.openblas.net/ has also been tested. Comment out "#define MKL_ENABLE" in digHolo.cpp
Trigonometric functions will be implemented using SVML if available (e.g. intel compiler and Microsoft compiler > VS2019). Otherwise, will default to hand-coded vectorised fast-math implementations.
The library can be compiled either as a dll/shared object, or as an executable. The executable can be called as 'digHolo.exe {settingsFile}', where {SettingsFile} is the filename of a tab-delimited text file containing configuration information. The examples given link against FFTW and Intel MKL. digHolo is written in C++11 and requires support for AVX2 and FMA3 instruction sets.
Linux (gcc or icc)
Shared Object
g++ -std=c++11 -O3 -mavx2 -mfma -fPIC -shared digHolo.cpp -o libdigholo.so
Executable
g++ -std=c++11 -O3 -mavx2 -mfma digHolo.cpp -o digHolo.exe -lfftw3f -lfftw3f_threads -lmkl_intel_lp64 -lmkl_sequential -lmkl_core -lpthread -lm -ldl
Windows
Example Visual Studio solution files are provided.
FFTW
Warning : always link FFTW3 first. Intel MKL also supports an FFTW interface, but does not support DCTs.
When linking statically with FFTW3, you'll have to comment out the line "#define FFTW_DLL" If you're dynamically linking, you'll have to include "#define FFTW_DLL"
Because Intel MKL also includes an FFTW compatible interface. Make sure you include the FFTW library before MKL.
e.g.
libfftw3f-3.lib;mkl_rt.lib
NOT
mkl_rt.lib;libfftw3f-3.lib;
Otherwise, when you link, you'll actually link with the MKL FFTs, not the FFTW FFTs. Which would be fine, except for the fact that real-to-real transforms
are not implemented in MKL. Real-to-real transforms are used during the 'AutoAlign' routine.
Intel MKL
Consult 'MKL Link link advisor' for assistance selecting the correct .libs
https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/onemkl/link-line-advisor.html
Windows examples
e.g. static linked...
mkl_intel_lp64.lib;mkl_intel_thread.lib;mkl_core.lib;libiomp5md.lib
or if you're having issues with libiomp5md.lib (openMP threads), link with the sequential version
mkl_intel_lp64.lib;mkl_sequential.lib;mkl_core.lib
e.g. dynamic linked...
mkl_rt.lib
Most of your dlls will likely be in this folder, or something similar
C:\Program Files (x86)\Intel\oneAPI\mkl\latest\redist\intel64..., if dynamically linked, you'll need to copy those into the same folder as your executable.
If linking against openMP threads library (libiomp5md.dll), don't forget the relevant dll will be in a different folder to most of the MKL dlls
C:\Program Files (x86)\Intel\oneAPI\compiler\latest\windows\redist\intel64_win\compiler\libiomp5md.dll
Although it is expected that this library would typically be compiled as a shared object/DLL, it is also possible to compile as an executable and process frames from the command-line. In this mode of operation, the executable is called with one or more arguments specifying the location of a tab-delimited text file which specifies the relevant configuration settings.
For example,
digHolo.exe digholoSettings.txt
An example digHoloSettings.txt file is provided for reference. Camera frame data is fed in as a binary file, from a filename specified within the tab-delimited text file.
For the most part, the text file specifies which 'Set' routines to run and what values to use.
For example, to set the 'fftWindowSizeX' property to 128 pixels, the following tab-delimited line would be included.
fftWindowSizeX 128
Which would in turn would mean the following function call is invoked before the digHolo processing pipeline is run...
digHoloConfigSetfftWindowSizeX(handleIdx, 128);
Similarly, to specify a BeamCentreX for two different polarisation components of 100e-6 and 200e-6 respectively
BeamCentreX 100e-6 200e-6
Output files can also be specified, which will either be plain text or binary files depending on the type of output
For example,
OutputFileSummary summary.txt
OutputFilenameFields fields.bin
See the 'main' and 'digHoloRunBatchFromConfigFile' routines for the code itself which processes the command-line usage.
An example digHoloSettings.txt file is provided for reference.