# Add internal third party module Eigen3

**URL:** https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429
**Category:** Algorithms
**Tags:** eigen
**Created:** [November 20, 2018, 5:26am UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429 "2018-11-20T05:26:17Z")
**Posts on this page:** 8
**Page:** 1

<div class="post-metadata">

### Author: ![phcerdan](https://discourse.itk.org/user_avatar/discourse.itk.org/phcerdan/32/286_2.png) [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [November 20, 2018, 5:26am UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/1 "2018-11-20T05:26:18Z")

</div>

I am glad to announce that after a few force-pushes, the pull request to add [Eigen3](http://eigen.tuxfamily.org/index.php?title=Main_Page) as an internal third party module is ready for [review](https://github.com/InsightSoftwareConsortium/ITK/pull/183).  
Kudos to @matt.mccormick @jcfr and @bpaniagua for the support ⛏🎈!

- Introduce Eigen3 as an internal ThirdParty module. It allows remote modules to use `find_package(Eigen3)` where Eigen3\_DIR points to the internal ITK. This is convenient for modules bridging with third parties modules that are using Eigen, so they do not have to change the third party reference to the Eigen target `Eigen3::Eigen` . One instance of such a module is [ITKTotalVariation](https://github.com/phcerdan/ITKTotalVariation), that aims to bring total variation regularization (denoising) bridging the third-party library [proxTV](https://github.com/phcerdan/proxTV/tree/use_eigen)

- The first use of Eigen3 is in `itkSymmetricEigenAnalysis.h.`  
A flag `m_UseEigenLibrary` is added to allow using Eigen3 with a `Eigen::Matrix<TValue, Dynamic, Dynamic>` (where the size is unknown at compile time).

Also another class in the same header has been added: `SymmetricEigenAnalysisFixedDimension` , that allows usage of `Eigen::Matrix<TValue, Dimension, Dimension>` that performs optimized computations.

Current tests have been expanded to exercise the added features.

- Performance test:  
Using [this image](https://github.com/mkrcah/bone-segmentation/blob/master/sample-volumes/001-CT.nii), and [this example](https://github.com/InsightSoftwareConsortium/ITKBoneEnhancement/tree/eab6df404c5b5c25464ded41d1ab9002e21b6e0d/example) --modifying the SymmetricEigenAnalysis there accordingly–  
with the command

```bash
for i in {1..10}; do ./BoneEnhancementExamples ~/Data/BoneEnhancement/001-CT.nii ~/Data/BoneEnhancement/out_preprocessed.nrrd ~/Data/BoneEnhancement/out_measure.nrrd 0 0 3 2 2 2; done

```

Results:

```auto
Eigen FixedDimension: 40.19
Old -const netlib-: 48.12
Eigen Dynamic: 57.10

```

Which is around `16%` faster when using the fixed dimension.

- Classes that have been modified to use the faster SymmetricEigenAnalysisFixedDimension:

```auto
Modules/Core/Common/include/itkSymmetricSecondRankTensor.h
Modules/Filtering/ImageFeature/include/itkHessian3DToVesselnessMeasureImageFilter.h
Modules/Filtering/ImageFeature/include/itkHessianToObjectnessMeasureImageFilter.hxx
Modules/Registration/Common/include/itkLandmarkBasedTransformInitializer.hxx

```

Beyond the shown usage for computing eigenvalues, Eigen3 would allow ITK to reach and bridge with more existing algorithms.

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [November 20, 2018, 4:59pm UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/2 "2018-11-20T16:59:54Z")

</div>

@phcerdan congratulations on this monumental contribution! 🏗

This will enable us to gradually transition to Eigen from VNL.

---

<div class="post-metadata">

### Author: ![spinicist](https://discourse.itk.org/user_avatar/discourse.itk.org/spinicist/32/183_2.png) [@spinicist](https://discourse.itk.org/u/spinicist)
#### Post date: [December 6, 2018, 11:17am UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/3 "2018-12-06T11:17:06Z")

</div>

Fantastic news! I just spotted this when updating my master branch.

Is there any plan for transitioning to Eigen throughout ITK? I know this has been discussed on-and-off for a long time. For my own code, it will be a big help if the underlying type of `itk::VectorImage` is an `Eigen::ArrayXd` instead of a `vnl_vector`, but I am aware that’s a pretty fundamental change.

If I can find time to help with this transition, I will gladly do so.

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [December 6, 2018, 6:08pm UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/4 "2018-12-06T18:08:25Z")

</div>

There is a 2-step plan:

1. Encapsulate `vnl_vector` and friends behind ITK type aliases such as `NumericVector` or `InternalVector` or something similar. Make VNL an internal dependency not visible to users of ITK.
2. Swap out Eigen in place of VNL. Possibly gradually, as time and resources allow.

---

<div class="post-metadata">

### Author: ![phcerdan](https://discourse.itk.org/user_avatar/discourse.itk.org/phcerdan/32/286_2.png) [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [December 6, 2018, 7:40pm UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/5 "2018-12-06T19:40:26Z")

</div>

I think it won’t be that hard to change the internal data, however it will span the whole library. But with the awesome test coverage of ITK, it shoudn’t be a problem.  
Related with @dzenanz suggestion, the current name to access the vnl data is GetVnlVector, GetVnlMatrix, etc… which is unfortunate for this kind of internal refactoring.

Maybe 5.0 is a good opportunity to deprecate `GetVnlVector`, in favor of an equivalent new method: `GetInternalVector` or similar, so changes will be less painful for third parties in the future.

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [December 7, 2018, 7:03pm UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/6 "2018-12-07T19:03:37Z")

</div>

As we come across small, bite-size tasks to facilitate the migration from VNL to Eigen, I think it will be helpful to create issues in GitHub. After we have a sufficient number of issues, we could collect them in a GitHub Project. 🐙 This should help facilitate forward progress! 🦉

---

<div class="post-metadata">

### Author: ![spinicist](https://discourse.itk.org/user_avatar/discourse.itk.org/spinicist/32/183_2.png) [@spinicist](https://discourse.itk.org/u/spinicist)
#### Post date: [December 10, 2018, 2:12pm UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/7 "2018-12-10T14:12:52Z")

</div>

Great idea. I’ve started “Watching” the github repo - but I may stop that as on something the size of ITK there tend to be a _lot_ of notifications. Having this in a project I can keep an eye on would be fantastic.

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [December 10, 2018, 3:07pm UTC](https://discourse.itk.org/t/add-internal-third-party-module-eigen3/1429/8 "2018-12-10T15:07:17Z")

</div>

After we have enough issues collected, perhaps we should hold a hackathon to begin tackling them. 🏈
