ENH: Master tracking — Eigen3 third-party design for ITK 6.x

[hjmjohnson]

ENH: Master tracking — Eigen3 third-party design for ITK 6.x

Why this issue

Thanks to @blowekamp and @dzenanz for suggesting that the Eigen design conversation needs a single venue rather than continued incremental patches.

Eigen-related work has accumulated multiple half-finished refactors (PR #5952, PR #6225), recurring user-confusion threads, and explicit "let's have a design discussion before more incremental patches" requests from @blowekamp (#6225) and @dzenanz (#5952). Several maintainer positions have been stated in scattered places (Discourse 2018-2023, individual PR threads) but never consolidated.

This issue is a single venue to converge on what we want Eigen to look like in ITK 6 and 7, what is grandfathered from earlier decisions, and what concrete sub-PRs the consolidated direction implies. ITKv6 is permitted to break or revise historical promises where the cost-benefit warrants it; the goal here is to make those revisions intentional, not accidental.

The historical baseline (load-bearing context)

These decisions were made deliberately and have shaped the current code:

1. Internal Eigen3 was added as a ThirdParty module in 2018 (Discourse #1429, authored by @phcerdan). Stated rationale: allow remote modules that already use Eigen (e.g. ITKTotalVariation bridging to proxTV) to share ITK's Eigen via find_package(Eigen3) pointed at ITK's tree. The long-term plan articulated by @matt.mccormick and @dzenanz: gradually migrate ITK internals from VNL to Eigen.

2. Symbols are NOT mangled — by design. @phcerdan, Discourse #5562 (2022): "It doesn't [mangle]. Eigen is a header-only library and it wasn't mangled to facilitate bridging with external libraries using native Eigen." Re-raising mangling in 2026 is fine, but must engage with this prior decision.

3. Three documented user-facing usage modes (@phcerdan, Discourse #5627 (2023)):

   • A. Use ITK's internal Eigen via <itkeigen/Eigen/Core>
   • B. -DITK_USE_SYSTEM_EIGEN:BOOL=ON + -DEigen3_DIR:PATH=... then <Eigen/Core>
   • C. Reuse ITK's internal Eigen as your project's Eigen (because no mangling)

4. VNL → Eigen migration never materialized beyond the 2018 plan. The aspiration is documented; the work is not staged. ITKv6 is the moment to either revive or formally retire that goal.

Where the current friction lives

Active / open PRs

PR	Author	State	Intent	Key blockers
#6225	@hjmjohnson	open, draft	Migrate include sites to canonical <Eigen/X> via Eigen3::Eigen (supersedes #5952)	@blowekamp wants design discussion first; @seanm reports external-build regression; Greptile P1 on missing warning suppression under ITK_USE_SYSTEM_EIGEN=ON
#5952	@blowekamp	stale (Mar 2026)	itk_Eigenvalues.h per-module wrappers (alternative direction)	@dzenanz: only 1/2 callers migrated, contradictory CMake change; @hjmjohnson asked for closure
#6224	—	open issue	ITK_EIGEN(Header) macro can't carry in-source SYSTEM include paths	Blocks the cleanest fix
#5484	—	open issue	Eigen -Wshadow warnings	Fix landed upstream in Eigen MR !1936; awaits next vendored-Eigen update

Recently merged (last 12 months)

• ENH: Update vendored Eigen3 to 5.0.1+master; verify USE_SYSTEM 3.3/3.4/5.x #6176 (@hjmjohnson, merged 2026-05-06) — Vendored Eigen 5.0.1+master. Acceptance matrix vs system 3.3.9 / 3.4.0 / 5.0.1.
• COMP: Expose itkeigen subdir in ITKEigen3_INCLUDE_DIRS for external consumers #6223 (@hjmjohnson, merged 2026-05-06) — Exposed itkeigen subdir for external consumers (this is what @seanm's ENH: Migrate Eigen3 includes to canonical <Eigen/x> via Eigen3::Eigen (supersedes #5952) #6225 regression report hangs off of).
• Refactor third-party Eigen3 CMake code #5831 (@blowekamp, merged 2026-03) — Large CMake refactor. @phcerdan in-thread: endorses retreating from "modules use raw Eigen", urges symbol mangling (not done).
• ENH: Support building with system Eigen3 >= 5 #5590 (@cho-m, merged 2025-11) — System Eigen ≥ 5 support.

Recurring user-pain issues

#4407, #4840, #4006, #1888 — ITKInternalEigen3 install brittleness across CMake versions; mostly fixed in 5.4. Worth checking that ITK 6 doesn't regress these.

The questions that need answers before more patches land

Each is binary or short-list; the goal is to get a maintainer-quorum answer to each, then translate them into work.

Q1. Header-path policy (the active flashpoint)

Three coexisting styles in-tree today:

ITK_EIGEN(Eigenvalues)        // legacy macro → <itkeigen/Eigen/Eigenvalues>
#include <Eigen/Eigenvalues>  // canonical, what PR #6225 wants
#include "itk_Eigenvalues.h"  // per-module wrapper, what PR #5952 wanted

Decision needed: Pick one canonical style for ITK 6 internals. The other two can remain as transitional aliases or be deprecated. Which?

Q2. Symbol mangling — revisit or honor the 2022 decision?

@phcerdan's 2022 reason for not mangling (bridge use case C above) is real but narrow. @phcerdan also endorsed mangling on PR #5831 in 2026. Two options:

• Honor 2022: keep unmangled, document that downstream modules can share ITK's Eigen, accept the ABI/ODR risk when an external library also vendors Eigen.
• Mangle in ITK 6: explicitly drop usage mode C, gain ODR safety à la VTK. Costs: bridging modules need updates; vendored-Eigen update mechanics get more involved.

Q3. Eigen3::Eigen CMake target — exposed to consumers?

Already partially the case (#6223). Decision needed: is Eigen3::Eigen (or ITK::Eigen3 aliased) a stable, supported CMake target that downstream find_package(ITK) consumers can link against, or an internal detail that may be removed?

Q4. Warning suppression scope

When ITK_USE_SYSTEM_EIGEN=ON, current code does not pass the same -Wno-* flags that the internal Eigen build uses. Greptile's P1 on #6225 surfaces this. Two options:

• Treat system Eigen as "user's responsibility, we don't suppress."
• Apply the same suppressions for both — uniform but means leaking flags into consumer builds.

Q5. VNL → Eigen migration — revive or formally retire?

The 2018 aspiration is unimplemented. Either:

• Revive: stage it for ITK 7+, accept it requires a multi-release deprecation cycle (GetVnlVector → GetInternalVector etc., per @phcerdan 2018).
• Retire: explicitly document VNL as the canonical numerics layer; relegate Eigen to its current niches (registration metrics, certain filters, third-party bridges) and remove "VNL replacement" from the roadmap.

Q6. Where does the design discussion happen?

GitHub issue (this one), Discourse thread, or a community-call agenda item? @blowekamp asked for "a discussion" on #6225 — naming the venue avoids the discussion happening in 5 places at once.

Q7. ITKv6 license to break

ITKv6 may revise historical promises where they no longer pay rent. Each Q above should be answered for ITK 6, not "what would have been compatible with the 2018 design." If the 2018 bridge-use case has zero real users in 2026, the design moves; if it has real users, accommodation matters.

Maintainer positions summarized (best understanding)

Maintainer	Position
@phcerdan	Original architect; bus-factor on vendored-update dance; OK to abandon "raw-Eigen-in-modules"; urged mangling on PR #5831
@blowekamp	Wants top-level design discussion before more patches; flagged "Eigen usage is rough around the edges"
@dzenanz	Permissive reviewer; "Eigen is extra complicated"; original VNL-replacement champion
@thewtex	2018: explicit Eigen-as-VNL-successor goal
@N-Dekker	Prefers tag-pinned over master-tip vendoring (raised on #4265, never addressed)
@seanm	Pushes fixes upstream; weak on subtree mechanics
@hjmjohnson	Filed this issue; current proposer of #6225 canonical-headers approach

Concrete asks of the maintainer group

1. Each maintainer (especially the seven listed above) leaves a comment with their position on Q1–Q5. Even one-line "I prefer option B because X" is enough.
2. Once Q1 has a quorum answer, ENH: Migrate Eigen3 includes to canonical <Eigen/x> via Eigen3::Eigen (supersedes #5952) #6225 either lands as the canonical-headers patch OR is closed in favor of ENH: Use standard header approach for eigen e.g. itk_Eigenvalues #5952's per-module-wrapper direction. No more half-merged refactors.
3. If Q5 says "revive," a separate ENH umbrella issue is opened to stage the VNL → Eigen migration for ITKv7.

[dzenanz]

1. #include <Eigen/Eigenvalues> is best, if we can have it without hassle somewhere else.
2. Updating eigen is already hard. If we throw in paying attention to mangling, it will be even harder.
3. Exposing Eigen3::Eigen sounds the best. If some project end up with duplicate eigens, they can either disable the other eigen, or point ITK to it via USE_SYSTEM_EIGEN.
4. I don't have a well developed opinion on this.
5. While I would like to replace VNL by eigen, it is a whole lot of work. If there is someone willing to do it, I would like to have it.
6. This issue is fine. I just added a forum post pointing here.
7. I don't know how many projects use ITK's eigen. If I remember correctly it was not overly convenient. Therefore number of projects is likely low. If someone has such a project, they should pitch in with their opinions.

[blowekamp]

Context: ITK's CMake Architecture for Third-Party Libraries

xref #6224

Before addressing the individual questions, it helps to clarify how ITK's CMake infrastructure is designed to work for third-party libraries, since several of the recent patches have been working against this design rather than with it.

ITK stores library information in two parallel systems:

1. Legacy per-module CMake variables (${itk-module}_INCLUDE_DIRS, ${itk-module}_SYSTEM_INCLUDE_DIRS, ${itk-module}_LIBRARIES): These are loaded from generated ${itk-module}.cmake files and merged together by UseITK.cmake into flat ITK_INCLUDE_DIRS / ITK_LIBRARIES variables. UseITK.cmake itself is deprecated.

2. Modern CMake interface targets (${itk-module}Module, e.g. ITKEigen3Module): These carry include directories, link dependencies, and compile definitions as target properties via target_include_directories(), target_link_libraries(), etc. CMake composes these properties intelligently and transitively when consumers link against the target.

The ${itk-module}_SYSTEM_INCLUDE_DIRS variable is part of the legacy system. Every current in-tree usage (ZLIB, TIFF, TBB, JPEG, Expat, MINC, HDF5, GDCM, DCMTK, VNL, PNG — 12 total) sets it to paths obtained from find_package() for system-installed libraries. The comment in ITKModuleMacros.cmake at line 274 states the design intent explicitly:

"System include directories are assumed to be external dependencies that are not installed, and thus do not have separate install interface paths."

This variable was never intended for in-source vendored paths. Using it for in-source paths fails CMake's export validation because the paths lack $<BUILD_INTERFACE:> / $<INSTALL_INTERFACE:> generator expression guards.

The ideal path forward for third-party libraries is for the ITK interface module to simply link to the actual third-party library target (e.g. eigen_internal) and automatically inherit include directories, SYSTEM treatment, and other properties from that target. This works for both vendored libraries and system-found packages. The eigen_internal target already does this correctly — it declares its include directory with SYSTEM INTERFACE and proper generator expressions in Modules/ThirdParty/Eigen3/src/itkeigen/CMakeLists.txt:

target_include_directories(eigen_internal SYSTEM INTERFACE
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/..>
  $<INSTALL_INTERFACE:${INCLUDE_INSTALL_DIR}>
)

The logic in PR #6223 — adding ${ITKEigen3_SOURCE_DIR}/src/itkeigen to ITKEigen3_INCLUDE_DIRS — was heading down a different route than this designed path. It duplicated include information through the legacy variable system as a non-SYSTEM include, bypassing the SYSTEM treatment that eigen_internal already provides correctly.

---

Q1: Header-path policy

Most ITK third-party libraries use an itk_X.h wrapper header (e.g. itk_zlib.h, itk_png.h, itk_jpeg.h, itk_tiff.h). This pattern exists for two reasons:

1. Correct library selection: It ensures the ITK-vendored version is used rather than a header that happens to be on the system include path. The wrapper uses a #cmakedefine ITK_USE_SYSTEM_X guard to switch between #include <itkvendored/X.h> and #include <X.h>.

2. Header isolation: It encapsulates ITK's vendored library so that an application can independently use a system or separate copy of the same library without header conflicts.

Eigen's itk_eigen.h already implements this pattern via the ITK_EIGEN(X) macro, which expands to <itkeigen/Eigen/X> (vendored) or <Eigen/X> (system) depending on ITK_USE_SYSTEM_EIGEN.

However, there are legitimate use cases where external code needs <Eigen/X> directly — for example, proxTV (used by ITKTotalVariation) has its own source files that #include <Eigen/Dense> and cannot be modified to use ITK_EIGEN(). Supporting <Eigen/X> resolution for these external consumers is necessary.

I think both B (<Eigen/X> for external consumers) and the existing ITK_EIGEN() macro (A, for ITK internal code) need to be supported. The <Eigen/X> path should come through proper target properties on eigen_internal rather than through the legacy _INCLUDE_DIRS variables. The per-module wrapper approach (C, PR #5952) adds unnecessary complexity.

Q2: Symbol mangling

If we are able to compile with visibility set to hidden (which ITK already does — see CXX_VISIBILITY_PRESET hidden and VISIBILITY_INLINES_HIDDEN in ITKModuleMacros.cmake) so that compilation units don't expose Eigen symbols in ITK's shared libraries, then symbol mangling should not be a hard requirement. The ODR risk is real but narrow, and the cost of maintaining a mangling layer on top of Eigen's header-only template library is significant — especially given that Eigen updates are already complex.

Q3: Eigen3::Eigen CMake target — exposed to consumers?

To avoid target name conflicts, Eigen3::Eigen should not be exposed when using ITK's vendored Eigen. If a consumer's project also uses Eigen independently, having ITK inject a Eigen3::Eigen target with different properties would cause conflicts.

For usage of ITK's Eigen — whether vendored or transitively from the system — consumers should link against ITK::ITKEigen3Module. This is the standard ITK pattern: consumers link to the module interface target and get the correct includes, link libraries, and compile definitions transitively.

The existing ITKInternalEigen3::Eigen alias for eigen_internal serves an internal purpose (the ITKInternalEigen3Config.cmake export) and does not need to be promoted to a public consumer-facing target. This enables find_package to find ITK's installation. This is a questionable feature or requirement that could be removed, IMHO.

Q4: Warning suppression scope

Include directories and their SYSTEM treatment should be set as properties on the eigen_internal target directly, not through the legacy ${itk-module}_SYSTEM_INCLUDE_DIRS module variables. The eigen_internal target already does this correctly for its <itkeigen/Eigen/X> path. If an additional path is needed for <Eigen/X> resolution, it should be added to eigen_internal the same way — with target_include_directories(eigen_internal SYSTEM INTERFACE ...) and proper $<BUILD_INTERFACE:> / $<INSTALL_INTERFACE:> guards.

This approach makes warning suppression automatic and consistent for both vendored and system Eigen, since the SYSTEM property propagates transitively through ITKEigen3Module → eigen_internal. It avoids the asymmetry issue described in #6224 where _SYSTEM_INCLUDE_DIRS cannot handle in-source paths.

[phcerdan]

Good discussion, my two cents from my history on this.

I wouldn't allow the native <Eigen/Eigenvalues> header in ITK core. If Eigen is installed in a system PATH, it will try to pick that one rather than ITK's, even when external Eigen isn't enabled by the user. Using the current ITK_EIGEN() macro to select between internal or external is a good enough solution, and we have full control of it in ITK core, so it's fine. So, no #6225.

Allowing external modules to use native eigen was the whole motivation of my work on this. The responsibility of reusing the internal itkeigen was exclusively on the external module (ITKTotalVariation). Without this, modules that depend on third-parties (proxTV for example) would need to add the ITK_EIGEN() macro in all the native Eigen headers, which will imply having to fork every library out there using eigen.
The reality of this is that only one module is doing this right now (ITKTotalVariation that uses the external proxTV). And even here, we had to fork proxTV for proper CMake support.

VTK mangles Eigen symbols with a single #define Eigen vtkeigen in upstream Eigen/Core. This changes the namespace into a new one, but it would still have problems with headers guards (remember the header only nature of Eigen). Mangling a la VTK is a really simple change, with no hard maintenance, but it doesn't guarantee zero-collisions when internal and external eigen are in the same TU. You can find an example of this in VTK approach (see https://gitlab.kitware.com/third-party/eigen/-/commit/c8b4f2cc523fce5b0dd6494ab8b88cfa994b5cee), and I implemented it in https://gitlab.kitware.com/phcerdan/eigen/-/commit/9cd4aec6122b29a37e8de3fbfff47de3af0fc371, but never got into ITK proper given that we weren't facing mangling issues. The recommended approach for zero surprises in code mixing Eigen and ITK is using Eigen as external in ITK.

I honestly don't think replacing vnl with Eigen is that hard. The only thing that VNL has that is a bit more hassle to add is the fourier transform implementation, but I am sure we can find FT libraries that are more permissive than FFTW (https://github.com/mreineck/pocketfft maybe -- used in scipy, numpy--, or its c++17 evolution: https://github.com/mreineck/ducc with other numerical goodies).

[thewtex]

Q1. Header-path policy

ITK_EIGEN(Eigenvalues)

+1 for controlled definition

Q2. Symbol mangling

+1 for symbol mangling for compatibility

Q3. Eigen3::Eigen CMake target — exposed to consumers?

No, ITK::Eigen for controlled direction

Q4. Warning suppression scope

If warnings from system eigen are known to be noise, we should suppress them specifically so they do not obfuscate real warnings.

Q6. Where does the design discussion happen?

+1 for GitHub

Q7. ITKv6 license to break

+1 for replacing VNL :-)

[phcerdan]

Rereading this, one last thing about mangling.

VTK is not templated, so they can put Eigen code (files with eigen headers) in .cpp files, compile that, link privately, and no Eigen code will surface to consumers of VTK. Given the template nature of ITK and Eigen, we cannot follow that approach, so Eigen surfaces more easily to C++ consumers of ITK.
That's also one of the reason why we didn't follow the namespace mangling, because it wasn't solving it completely. And mixture of eigens versions might occur in headers.
There is no shortcut on this, we would need to modify our vendored version and modify all header guards #ifnotdef EIGEN_X -> #ifnotdef ITKEIGEN_X. This mangling will of course break the original motivation of allowing external modules to use third-party libraries that use eigen.

PS: If we are doing the correct vendoring version, I would also change the namespace explicitly, rather than with the #define that VTK uses, for the same reason, that #define eigen itkeigen can interfere with other eigens.
So, in a nutshell, we need one commit that performs the mangling properly. Changes all header guards, and changes all the namespace ocurrences.
Or... state clearly that eigen is not mangled, maintain the flexibility for third-party modules to use external eigens, and enforce consumers to use their own eigen if they are using eigen code outside itk. I personally prefer the NOT MANGLING approach, if somebody is using eigen and ITK, they will use an external eigen, pass it to ITK, and everybody is happy.
We haven't received mangling concerns in a lot of time, so I am 100% sure consumers are doing that with no problems.

I cast same votes than @thewtex in everything except in:
Q2. Symbol Mangling.
+1 for no symbol mangling (current state).

[hjmjohnson]

For Q5: I would like to stage this replacement. Recent work to remove vnl_random with std:: randomvariants was a move to reduce the dependence of vnl.

I recommend moving from vnl_svd to eigen::svd as a first step. It should be faster and a cleaner interface. numerical drift due to algorithmic shifts may require tests to be fortified for value shift (acceptable numerical tolerance instead of bit-identical answers).

[hjmjohnson]

Empirical dual-Eigen test results — feeds #6230 Q2 with measurement, not priors

Set up two Eigens of different major versions in the same C++ program:

• ITK vendored Eigen 5.0.1 (post-PR BUG: Restore eigen_internal export to ITK's main targets set (#6239) #6247 install at ~/src/ITK-build-test-tree-eigen/install-fix)
• System Eigen 3.4.0 (downloaded headers at /tmp/dual-eigen-test/eigen-3.4.0)

Compiler: clang++ -std=c++17 -O0 (Apple Clang on macOS arm64).
Reproducer: /tmp/dual-eigen-test/scenarios/{1,2,3}/.

Scenario 1 — both Eigens included in the same TU

#include <itkeigen/Eigen/Core>   // 5.0.1
#include <Eigen/Core>            // 3.4.0

Result: COMPILE FAIL (~6 errors). Header guards (#ifndef EIGEN_CORE_H) protect the top-level files but partial-include sub-headers collide:

error: redefinition of 'gebp_traits<float, float>'
error: redefinition of 'gebp_traits<double, double>'
error: function-like macro 'EIGEN_GNUC_AT_LEAST' is not defined

Macros from one version leak into the other's internals. No surprise; nobody would do this on purpose.

Scenario 2 — different TUs, extern "C" boundary (no Eigen types crossing)

TU A includes only <itkeigen/Eigen/Core>, TU B includes only <Eigen/Core>. They expose extern "C" functions taking double const*. main calls both.

ITK Eigen 5.0.1 trace=3
Sys Eigen 3.4.0 trace=3

Result: PASS — link clean, runtime correct. No link-time symbol collision because each Eigen 's templates instantiate into different mangled symbols (different inline-namespace, different sizes, different template signatures). Both versions coexist happily in the same executable as long as Eigen types do not cross TU boundaries.

Scenario 3 — Eigen::Matrix3d crosses the TU boundary

TU A (compiled with ITK Eigen 5.0.1) declares Eigen::Matrix3d make_identity_itk(). main.cxx is compiled with system Eigen 3.4.0 BUT also includes the header that declares the function (which transitively pulls in ITK's <itkeigen/Eigen/Core>). Both Eigens end up in main's TU.

error: redefinition of 'random_default_impl'
error: redefinition of 'random_impl'
error: use of undeclared identifier 'plain_enum_min'
error: no type named 'get_integer_by_size' in namespace 'Eigen::numext'
   ... (20 errors total, 2 warnings)
warning: 'EIGEN_MAJOR_VERSION' macro redefined  (5 vs 4)

Result: COMPILE FAIL — 20 errors. Same catastrophic collision as Scenario 1, just triggered indirectly through a header that exposes Eigen types in its public API.

Interpretation

Scenario	Verdict	What it tells us
1: same-TU dual include	fail (compile)	Trivially diagnosable. Not a real-world hazard — nobody writes this.
2: different-TU, no Eigen at boundary	PASS	Two Eigens can coexist in one process today, without symbol mangling, as long as Eigen types stay TU-local.
3: Eigen types cross TU boundary	fail (compile)	The danger zone. Caught at compile time, not runtime — there is no silent ODR window.

Conclusion for #6230 Q2

The ODR risk that motivates symbol mangling (silent runtime corruption from two Eigen versions linked into one program) is not observed empirically with current ITK / Eigen 5.0.1. The compiler catches the collision at the #include site (Scenario 3). Mangling would prevent Scenario 3's compile error, but Scenario 3 is exactly the case that should fail loudly: putting two incompatible Eigen versions into the same TU is a design error.

What mangling does fix is allowing a header that exposes Eigen::Matrix3d to coexist with a consumer using a different Eigen version — i.e., expanding ITK's API surface to include Eigen types as part of the public contract. That is a policy decision, not a robustness fix.

Concrete data points for #6230 Q2:

• @phcerdan / @blowekamp / @dzenanz position ("no mangling, current state is fine"): supported by Scenario 2 — TU-local Eigen really does coexist cleanly.
• @thewtex position ("+1 for symbol mangling for compatibility"): supported by Scenario 3 as a policy choice — if and only if ITK wants to expose Eigen types in public headers as supported API. Today it does not (every public ITK header that touches Eigen wraps it in ITK_EIGEN(...) indirection or keeps it internal).

The empirical finding aligns with the architectural guidance from the proxTV investigation: ITK should keep Eigen TU-local (do not expose Eigen::* types in public headers). Under that constraint, no mangling is needed. Under the alternative constraint (expose Eigen types in public API), mangling becomes mandatory.

Reproducer preserved at /tmp/dual-eigen-test/scenarios/.

[hjmjohnson]

Architectural commitment for #6230 (Hans, 2026-05-09)

ITK's public API must not expose Eigen types — neither directly nor transitively. Public ITK headers must not force consumers to have Eigen on their include path or know about Eigen as a vendored dependency.

This collapses several of the open Q1-Q4 questions:

#	Question	Answer under this principle
Q1	Header-path policy	ITK_EIGEN(X) / <itkeigen/Eigen/X> allowed in non-public code (.cxx); never in public .h/.hxx. Bare <Eigen/X> is never exposed; #6223's ITKEigen3_INCLUDE_DIRS second entry should be revisited (was added under the assumption external modules need it; the proxTV use case driving it is implementation-only and easily patchable).
Q2	Symbol mangling	Not needed. Empirical dual-Eigen test (above comment) shows Eigen 5.0.1 + Eigen 3.4.0 coexist cleanly in one process when types stay TU-local. Mangling is only required if Eigen types cross the public API boundary — which under this principle, they never will.
Q3	Eigen3::Eigen consumer-facing target	No. Public API doesn't reference Eigen, so consumers don't need a target for it. Vendored eigen_internal stays an implementation-detail target used only by ITK modules internally.
Q4	SYSTEM include treatment	Still worth fixing per @blowekamp's 2026-05-07 architectural note (target-property propagation through eigen_internal rather than legacy _SYSTEM_INCLUDE_DIRS), but lower urgency since external consumers will not transitively pull Eigen at all.

Current public-header leakage (2026-05-09 audit, post-PR #6247)

$ grep -rEln '#include\s*[<"](itk_eigen|itkeigen/Eigen|Eigen/)' Modules/*/*/include/
Modules/Core/Common/include/itkSymmetricEigenAnalysis.h
Modules/Registration/Montage/include/itkTileMontage.hxx

Two files. Both isolatable:

• itkSymmetricEigenAnalysis.h — class-scope alias using EigenLibPermutationMatrix = Eigen::PermutationMatrix<...> (line 103) is the only true public-API leak; the method-scope aliases (548/557/617/620/675) can move to a .cxx via explicit instantiation. The class-scope alias can be hidden behind a forward-declaring trait or replaced with a typedef-to-itk::* type.
• itkTileMontage.hxx — one method-local Eigen::LeastSquaresConjugateGradient<...> (line 465). Since .hxx files are installed and consumed transitively through template instantiation, this counts. Mechanically isolatable to a .cxx via PIMPL or explicit instantiation.

Proposed regression test (Phase A1, anchoring this commitment)

A CTest test that fails if any header under Modules/*/*/include/ contains #include "itk_eigen.h", ITK_EIGEN(, or matches Eigen::. Implementation: a CMake script that greps the source tree and asserts the file count is <= 2 (the current grandfathered set) or whatever lower number we ratchet down to as the two existing files are migrated. Long-term goal: 0.

This test, run on every PR, prevents future Eigen-API leakage at the same moment a new contributor would otherwise add it. It is mechanically simple, fast, and has no Eigen-version dependency — so it works regardless of whether the vendored Eigen is 3.x, 5.x, or future.

I'll work this up as a draft PR (separate from #6247) once the principle is acknowledged here.

[seanm]

I saw myself tagged here, but this is all TLDR. (It looks like AI blather honestly.)

I don't have any strong opinions on eigen in ITK. All I know is recent eigen changes keep breaking my builds.

Replacing VNL would be nice, since it seems barely maintained, and mostly by Hans, but alas I don't have cycles to help with that.

[hjmjohnson]

Build-matrix continuation: silent Eigen-version skew on ITK_USE_SYSTEM_EIGEN=ON

Continuing the empirical test matrix on top of PR #6247. Built ITK three ways (default modules + ITKIOTransformMINC + ITKReview, on macOS arm64 / Apple Clang):

Build	Mode	Eigen at ITK build time
install-fix	vendored	5.0.1 (ITK's bundled, post-PR #6247)
install-sys-eigen-501	system	5.0.1 (homebrew /opt/homebrew/Cellar/eigen/5.0.1)
install-sys-eigen-340	system	3.4.0 (downloaded + installed at /tmp/dual-eigen-test/eigen-3.4.0-install)

Smoke consumer (uses ITK's official ITK_EIGEN(Core) shim, the portable form):

#include "itk_eigen.h"
#include ITK_EIGEN(Core)
int main() {
  Eigen::Matrix3d m = Eigen::Matrix3d::Identity();
  std::cout << "trace=" << m.trace()
            << " EIGEN=" << EIGEN_WORLD_VERSION << "."
            << EIGEN_MAJOR_VERSION << "." << EIGEN_MINOR_VERSION;
}

Per-install consumer build, find_package(ITK) only (no Eigen3_DIR pin):

ITK install	Consumer Eigen reported	Match ITK's?
install-fix (vendored 5.0.1)	EIGEN=3.5.0	✅ (vendored path resolves through <itkeigen/Eigen/Core>)
install-sys-eigen-501	EIGEN=3.5.0	✅ (consumer found brew 5.0.1)
install-sys-eigen-340	EIGEN=3.5.0	❌ — ITK was built against 3.4.0; consumer silently got brew 5.0.1

Note: EIGEN_WORLD_VERSION is hard-coded 3 in Eigen; the second number is the major. So 3.5.0 = Eigen 5.0.x, 3.4.0 = Eigen 3.4.x.

Force the consumer to use the matching Eigen 3.4.0:

cmake -G Ninja -S . -B build \
  -DITK_DIR=.../install-sys-eigen-340/lib/cmake/ITK-6.0 \
  -DEigen3_DIR=/tmp/dual-eigen-test/eigen-3.4.0-install/share/eigen3/cmake \
  -DCMAKE_PREFIX_PATH=/tmp/dual-eigen-test/eigen-3.4.0-install
$ ./itk_eigen_smoke
trace=3 EIGEN=3.4.0

Root cause

The installed Modules/ITKEigen3.cmake ships this snippet (verbatim from Modules/ThirdParty/Eigen3/CMakeLists.txt:38-44):

find_package("Eigen3" REQUIRED CONFIG)
if(Eigen3_VERSION VERSION_LESS 3.3)
  message(FATAL_ERROR "Eigen3 version 3.3 or later is required.")
endif()

There is no path pin and no exact-version assertion. The consumer's find_package(Eigen3 REQUIRED CONFIG) follows the standard CMake search order, which on this machine finds brew's 5.0.1 long before the /tmp/... 3.4.0 install. ITK passes the ≥ 3.3 floor check and configure proceeds — with a different Eigen than ITK was compiled against.

Implications

• Silent ABI/version skew at the consumer boundary when ITK is installed with ITK_USE_SYSTEM_EIGEN=ON and the build-time Eigen is not the system-default one. This is a separate failure class from BUG: Eigen3 update (64ddc666) breaks downstream FetchContent+find_package use of ITK — eigen_internal removed from main export set #6239 (which was about vendored-mode export-set fragmentation) and from ITKModuleMacros: _SYSTEM_INCLUDE_DIRS does not support in-source paths (blocks SYSTEM treatment of vendored Eigen) #6224 (SYSTEM-include macro asymmetry).
• Compounds the public-API exposure concern: as long as ITK headers transitively #include Eigen, a consumer compiling against ITK's headers is implicitly compiling against whatever Eigen version find_package(Eigen3) resolves at consumer-time, not what ITK was built with. Today that means: hash, alignment, packet-traits, and template-instantiation choices made at ITK build time may not match what the consumer's Eigen headers express. The dual-Eigen scenario tests (above comment) show this fails loudly when types cross a TU boundary, but inline template methods in ITK headers (e.g. itkSymmetricEigenAnalysis.h lines 548+) instantiate against whichever Eigen the consumer picked up — silently divergent from ITK's.

Suggested remediation (sketch — not in scope of this comment)

Three options, increasing in scope:

1. Snapshot exact version in install — record EIGEN3_VERSION discovered at ITK configure-time and emit it into ITKConfig.cmake.in. Consumer re-find_package(Eigen3) then asserts Eigen3_VERSION VERSION_EQUAL <snapshot> (or VERSION_GREATER_EQUAL with a tighter compatibility window than just ≥ 3.3).
2. Pin path in install — record Eigen3_DIR in ITKConfig.cmake.in and pre-set it before consumer's find_package. Brittle (paths move) but unambiguous.
3. Eliminate the consumer's find_package(Eigen3) need entirely — couple with the "no public-API exposure" architectural commitment from earlier in this thread: if consumers don't transitively pull Eigen, the system-Eigen vs build-time-Eigen mismatch becomes irrelevant. This is the long-term path.

Option 1 is the minimum-surface fix; option 3 is the preferred end-state.

Reproducer preserved at /tmp/itk-eigen-smoke/ and the three install trees at ~/src/ITK-build-test-tree-eigen/install-{fix,sys-eigen-501,sys-eigen-340}/.