Package: epipolar-consistency
Epipolar consistency for transmission imaging (Python bindings)This repository provides python bindings for the computation of epipolar consistency conditions (ECC) as a metric in transmission imaging.
The ECC functionality itself is not implemented in this repository.
The source files are located inEpipolarConsistencyand are written in C++ by André Aichert.
This repository only provides bindings to the existing source code such that it can be used in Python.
The bindings are based onpybind11and this repository closely follows their providedcmake example.FunctionalityOnly the core functionality of the original repositoryEpipolarConsistencyis included in the Python module.
This includesthe initialization of images and projection matrices from numpy arrays,the computation of Radon intermediates,the evaluation of the ECC metric for all image pairs included in a given set of projection images and their corresponding projection matrices.More advanced functionality of the original repository, that isnotincluded in the bindings, includeseverything related to optimization,graphical user interfaces,everything related to 3D reconstruction.We think that these aspects can similarly be handled by native Python libraries.Example codeimporteccimportnumpyasnp# overview over all wrapped functions/ classesprint(help(ecc))# set parameters for computation of Radon intermediatessize_alpha=200size_t=100# load example projection imagesprojection_images=np.load('example_data/sinogram_cone.npy').astype(np.float32)# convert to listprojection_images=[projection_images[i,:,:]foriinrange(projection_images.shape[0])]# compute radon intermediates with 100 detector elements and 200 angular stepsradon_intermediates=[]forimageinprojection_images:image=ecc.ImageFloat2D(image.astype(np.float32))radon_intermediate=ecc.RadonIntermediate(image,size_alpha,size_t,ecc.RadonIntermediate.Filter.Derivative,ecc.RadonIntermediate.PostProcess.Identity)radon_intermediates.append(radon_intermediate)# load example projection matricesprojection_matrices=np.load('example_data/projection_matrices.npy')# convert to listprojection_matrices=[projection_matrices[i,:,:]foriinrange(projection_matrices.shape[0])]# create object to evaluate ECC metric on GPUecc_metric_gpu=ecc.MetricGPU(projection_matrices,radon_intermediates)# set the angle between epipolar planes (otherwise default value is taken)metric_gpu=ecc_metric_gpu.setdKappa(0.001)# evaluate the metricout_gpu=metric_gpu.evaluate()print(f'Result:{out_gpu}')Installation via pipPrebuilt wheels are available via pip for Linux operating system and Python versions 3.8, 3.9, and 3.10.
We strongly encourage to install the Python module directly from PyPI:pipinstallepipolar-consistencyInstallation from sourceIf you need to compile the code on Windows or want to build it yourself for another reason, you need to
(1) build the necessary dependencies for the core ECC functionality (seeEpipolarConsistency)
(2) build and install the module in this repository.
On Linux, you need a compiler with C++11 support and CMake >= 3.5.
On Windows, Visual Studio 2015 or newer is required (Pybind11 requires a C++11 compliant compiler) as well as CMake >= 3.8 (3.8 was the first version to support VS 2015).It is crucial to have all dependencies of the core ECC functionality written in C++ installed properly. Please also refer to the
Readme inEpipolarConsistency. On Ubuntu 20.04, a working set of dependencies
and their corresponding versions is:Eigen 3.3.9 (Even though Eigen is header only, in order to make sure that all files are located at the default locations, run
cmake and make install as described below. I know that André Aichert suggests to use Eigen 3.3.0, but that did not work for me.)NLopt 2.6.2LibGetSet from André Aichert's forkQt 5.12.11 (Any version with major version number 5 should work. It is helpful to set the CMAKE_PREFIX_PATH to Qt as describedhere.)Cuda 11.2The standard way to install most of these packages (like NLopt, GetSet) on Ubuntu ismkdirbuildcdbuild
cmake..
make
sudomakeinstallFor Windows, you need Visual Studio to build the solutions provided by cmake.To test whether all dependencies are installed and found correctly, it might make sense to first build the submoduleEpipolarConsistencyseparately and then try to pip install it as a python package.After having installed the necessary dependencies for the core ECC functionality, you can finally install the Python module.
Clone this repository (with--recurse-submodulesoption) and runcdecc_python
pipinstall.With thesetup.pyfile included in this example, thepip installcommand will invoke CMake and build the pybind11 module as specified inCMakeLists.txt.
This will both build the module and install it to your current Python environment.Test callTo check if the Python module has been installed properly, you can runimportecchelp(ecc)Building a wheelTo build a wheel of the ecc package on Linux, you need to have ninja installed (sudo apt-get install ninja-build) and then runpythonsetup.pybdist_wheel--plat-namemanylinux2014_x86_64Create html documentation of ecc moduleTo create an overview of all functions and classes provided by the ecc module, runpydoc-weccfrom an environment with ecc installed. It creates a file ecc.html within the same folder.Technical detailsThe functionality from EpipolarConsistency is compiled as a static library and linked into the shared python module.
For more details on this seehttps://github.com/pybind/cmake_example/issues/11#issuecomment-405092832.To take full advantage of this code, an NVIDIA GPU is needed for a parallelized computation of Radon intermediates and the ECC metric itself.LicensePybind11 is provided under a BSD-style license that can be found in the LICENSE
file. By using, distributing, or contributing to this project, you agree to the
terms and conditions of this license.CitationIf you use this code for your research, please cite the original work on ECC in transmission imaging by André Aichert:@ARTICLE{7094279,
  author={Aichert, André and Berger, Martin and Wang, Jian and Maass, Nicole and Doerfler, Arnd and Hornegger, Joachim and Maier, Andreas K.},
  journal={IEEE Transactions on Medical Imaging}, 
  title={Epipolar Consistency in Transmission Imaging}, 
  year={2015},
  volume={34},
  number={11},
  pages={2205-2219},
  doi={10.1109/TMI.2015.2426417}}