Windows Build - 3dct/open_iA GitHub Wiki

Up to Build Environment.

The easiest way to set up a working build environment for open_iA in an automated fashion is through using our superbuild. In contrast, this document provides detailed instructions on how to manually set up a build environment for open_iA on Windows with Visual Studio.

Prerequisites

For these libraries, we usually try to support the latest versions. If those don't work for you, check our compatibility list!

Visual Studio

Which version should I pick?

We currently build open_iA using Visual Studio 2019 and 2022. Older versions are not actively used anymore and might therefore fail in compiling newer developments which start to use newer C++ features. The version of Visual Studio to choose is also important to consider in case you want to use any module requiring CUDA (AstraReconstruction, and potentially AI (though the use of DirectML is recommended there), currently):

  • First, make sure to choose a version of Visual Studio supported by the CUDA toolkit version you are using. This was more critical with previous CUDA versions; CUDA toolkit versions >= 11.7 seem to be compatible to Visual Studio 2019 and 2022, according to NVidia's documentation.

  • In case you are thinking about building the ASTRAReconstruction module, check its build instructions and consider that the official source code releases are tailored for specific versions of Visual Studio and CUDA, and will require adaptation for other versions.

  • In case you are building the AI module with CUDA backend, you will want to make sure that the CUDA and cuDNN library versions you are using are compatible with the one that the onnx runtime was built against, see its requirement table. It is however highly recommended to build the AI module against the DirectML backend (CUDA support is currently broken).

Note: The open_iA superbuild contains patches that adapt for example the Astra build to VS 2019/2022; so consider using it!

Installation

Make sure that the "Desktop Development with C++" workload is selected for installation.

Qt

Typically you will want to use the pre-built binaries, see below. Only in very rare cases (e.g., when you're building with a Visual Studio version unsupported by Qt) you need to build Qt from source.

Pre-built binaries

Pre-built binaries are available for installation from within the Online Installer, available at the Qt Open Source Development site. The Online Installer offers multiple different binaries. Make sure sure to expand the sub-entries of the respective version you want to install, and check only the box for the fitting binaries for the required binaries (for a build with Visual Studio 2019 or 2022, this is the "MSVC 2019 64-bit" entry). If you also want to build the "Adaptive Thresholding" module of open_iA, also check the "Qt Charts" checkbox under "Additional libraries". If you need Qt just for open_iA, uncheck all other checkboxes. Otherwise you will end up with an unnecessarily huge Qt installation folder.

Qt VS Addin

To enable expansion of Qt types in Visual Studio debugger, you might want to install the respective Qt Visual Studio addin. Search for the "Qt Visual Studio Tools" in Visual Studio under Extensions -> Manage Extensions.

VTK

See Build Instructions VTK.

OpenCL

Optional - only required for the GPU-accelerated versions of some filters in ITK (which are used in open_iA if available), as well as for the DreamCaster module. See Build Instructions OpenCL.

ITK

See Build Instructions ITK.

Eigen

Optional - only a soft requirement for SegmentationRandomWalker module; it works without Eigen, using vtk's vnl math libraries, but will be a bit faster with it.

  • Download latest version from the Eigen page.
  • Extract the contents to a directory, e.g. C:\Tools\eigen-3.3.4
  • This is a header-only library; there is no need to build it.
  • During open_iA build, set EIGEN3_INCLUDE_DIR to this directory (eigen extracts its own subfolder, e.g. eigen-eigen-5a0156e40feb for version 3.3.4; you can of course rename this folder, just make sure the directory you use as EIGEN3_INCLUDE_DIR is the topmost one from the zip file that contains a README.md).

HDF5

Optional - required if you want to be able to read arbitrary HDF5 files.

  • In the following we only list the essential build steps. For more detailed information, please refer to the HDF5 group's support page on CMake build instructions

  • Prerequisites: NSIS (Nullsoft Scriptable Installer System) must be installed.

  • Go to the HDF5 group download page, click on the version you want to use (e.g. 1.12.2), there download respective CMake source bundle (e.g. CMake-hdf5-1.12.2.zip).

  • Unpack this zip file into a directory of your choice.

  • Find the build script for your operating system and build environment. On Windows, for Visual Studio 2019 64 bit, this is build-VS2019-64.bat

  • Uncomment two lines in HDF5options.cmake; change

    #set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF") to

    set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF")

    You can also disable testing by changing

    #set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_TESTING:BOOL=OFF") to

    set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_TESTING:BOOL=OFF")

    but not that this also requires adding --no-tests=ignore to the ctest options in build-VS2019-64.bat

  • Execute the build script, the library will be built

  • Find the generated installer. This is an executable file, e.g. HDF5-1.10.1-win64.exe

  • Run the installer

  • Note down the location where you install the library, you later have to add the 'cmake/hdf5' subdirectory of the install location as 'HDF5_DIR' during CMake-Configuration of open_iA

ASTRA Toolbox

Optional - only required if you want to build and use the ASTRA Toolbox and its reconstruction methods from within open_iA. Note: The open_iA superbuild can automatically adapt the Astra build for specific versions of Visual Studio and CUDA, so consider using it instead of manually building ASTRA yourself!

Building this library requires several other libraries:

Note: To properly run with larger datasets, currently the GPU timeout has to be increased. See e.g. https://stackoverflow.com/a/17187135/671366 for details. In short, add a DWORD key named TdrDelay in the registry under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GraphicsDrivers, and enter some numeric value, which is the new timeout in seconds (default is 2, try e.g. 30 or 60). You'll have to restart your Windows for this change to be effective.

OpenVR

Optional - one out of OpenVR or OpenXR (see below) is required if you want to build a module using VR (ImNDT, XVRA).

  • Download and install Steam from https://store.steampowered.com/
  • Start Steam, login or create account
  • In the "Library", there should be an entry "SteamVR" in the list on the left -> Install
  • You'll also require the OpenVR SDK for the VTK Build and the open_iA build (see below).

OpenXR

Optional - one out of OpenVR (see above) or OpenXR is required if you want to build a module using VR (ImNDT, XVRA).

  • As backend, you will probably require some compatible runtime, such as SteamVR; see OpenVR section above for guidance on how to install that.
  • Download the OpenXR SDK:
    • For the respective release, check under assets (at the very bottom)
    • Look for the openxr_loader_windows... file (you might have to press the "Show all ... assets" at the bottom)
    • Extract the file, and have it available for the VTK Build and the open_iA build (see below).

onnx runtime

Optional - only required if you want to build the AI module.

  • Download and extract an onnx runtime release (Note: Currently, we recommend choosing the version with DirectML backend (Microsoft.ML.OnnxRuntime.DirectML... packages).
  • Make sure that you have an appropriate DirectML.dll available; it is contained for example in the Microsoft.AI.DirectML nuget packages; the required version is noted in the onnx runtime release notes (e.g.., for onnx runtime version 1.14, DirectML version 1.10 is required; for onnx runtime versions 1.15/1.16, DirectML version 1.12 is required). the .nuget files can be extracted; the DirectML.dll for 64bit windows is contained in the bin/x64-win folder; specify the path to this file under the DIRECTML_LIBRARY setting in open_iA's CMake configuration.

open_iA

  • Clone from source (https://github.com/3dct/open_iA.git) into an arbitrary source directory open_iA-src-dir, e.g. C:\Tools\open_iA\src. Make sure that the full path you choose for vtk-src-dir (and vtk-bin-dir, below) is not too long, otherwise you might see errors regarding the command line for moc being to long (see also the troubleshooting section below).
  • Run CMake
  • Specify source directory open_iA-src-dir, and an arbitrary open_iA-bin-dir (e.g. C:\Tools\open_iA\bin)
  • Press "Configure".
  • When asked, specify "Visual Studio 16 2019 Win64" as generator, leave "Use default native compilers" checked. You will receive an error that CMake couldn't find ITK.
  • Set ITK_DIR to itk-bin-dir
  • Press "Configure" again.
  • You might receive an error message that Qt couldn't be found. In that case, set the Qt6_DIR variable to the version/buildtype/lib/cmake/Qt6 (or Qt5 for Qt < 6.0.0) sub-directory of the Qt installation folder (with Qt 6.3.2 and the Visual Studio 2019 64 bit build installed, this would be Qt-installation-dir/6.3.2/msvc2019_64/lib/cmake )
  • If you want to be able to load HDF5 files, set HDF5_DIR to the 'cmake' subdirectory of where you installed the HDF5 library (see the section on HDF5 above).
  • Press "Configure". It should run through without errors.
  • Enable any modules you want to build (the Module_xyz flags). These Modules contain the Filters and Tools that make up much of the functionality of open_iA. In case you want to build all modules, set the openiA_BUILD_ALL_MODULES flag (see the Build Options).
    • If you enable the Random Walker segmentation module (Module_SegmentationRandomWalker), and want to improve performance, set EIGEN3_INCLUDE_DIR to the place where you extracted the archive downloadable from the Eigen library homepage; see also the section on Eigen above.
    • If you enable the ASTRA Toolbox module (Module_AstraReconstruction flag), you have to set the ASTRA_TOOLBOX_DIR to the base directory of your ASTRA Toolbox build.
    • If you enable the ImNDT module, or if VTK was build with VTK_MODULE_ENABLE_VTK_RenderingOpenVR or VTK_MODULE_ENABLE_VTK_RenderingOpenXR:
      • If using OpenVR: Set OpenVR_INCLUDE_DIR and OpenVR_LIBRARY (See Build Instructions VTK for details).
      • If using OpenXR: Set OpenXR_INCLUDE_DIR and OpenXR_LIBRARY (See Build Instructions VTK for details); note that using ImNDT through OpenXR currently comes with the minor limitation that the AR mode is not available, as we haven't found a way yet to access the camera of e.g. an HTC Vive Pro Eye through the OpenXR SDK.
  • Press "Configure". it should run through without errors.
  • Press "Generate".
  • Open "open_iA.sln" in open_iA-bin-dir in Visual Studio 2019, and build the desired configuration(s) (for example Debug).

Additional open_iA build options

See Build Options open_iA.

Troubleshooting

  • For more potential problems, see the troubleshooting section of our superbuild

  • If you get an error that some vtk or itk lib is not found, check the project properties. If they contain the referenced lib without a path (in the project properties, under Linker->Input->Additional Dependencies), then the respective lib bin directory has become corrupted. You will have to remove it and start the build for that library and all depending libraries from scratch (i.e. if it happens for VTK, rebuild VTK and ITK).

  • In case CMake or the build report some problem with any path or file specified in the CMake interface - Make sure to use correct slashes in all file/folder paths you enter in CMake - CMake expects forwards slashes ("/") instead of backslashes in path names.

  • During the vtk/itk/open_iA build process, you get an error for moc.exe, which looks something like this: AutoMoc : error : moc process failed for

    • This is due to a too long path name in one or all of the vtk/itk/open_iA binary or source directories.
    • The only currently known workaround is to use shorter folder names for the source and binary directories.

  • During the vtk build, CMake might fail with some message about GlU32, gl32 or some other OpenGL related library (e.g.:):

    • Failed to find "glu32" in "".
    • Add a new variable "CMAKE_LIBRARY_PATH", and make it point to the Windows SDK 8.1 library dir, e.g.:
    • CMAKE_LIBRARY_PATH=C:\Program Files (x86)\Windows Kits\8.1\Lib\winv6.3\um\x64
    • Restart CMake, then the error should be gone

  • During a build in Visual Studio, uic.exe fails with error 0xc00000135:

  • When running open_iA, you get one of the following error messages: "Procedure entry point ... was not found in the DLL ... " or "This program can't start because some-dll-file is missing from your computer..."

    • In case this happens when you run open_iA.exe directly from the explorer / from the command line: open_iA must be deployed first before it can be run directly. You have two options:
      • Use cpack to easily create an installer package. See the section Creating an installer package for information on how to deploy open_iA.
      • You could copy the Qt/VTK/ITK dll files mentioned in the error message from their respective binary directories (make sure you choose the appropriate configurations) to the same folder as open_iA.exe.
    • In case this happens when starting open_iA from Visual Studio: The problem is that CMake should create a configuration file for Visual Studio that specifies the paths of all required libraries in the first successful configure run, but apparently this has failed here. Solution:
      • If the open_iA solution is opened in Visual Studio, close it.
      • Go to open_iA-bin-dir, remove the file ALL_BUILD.vcxproj.user
      • Go to the subdirectory "gui" of the open_iA-bin-dir folder, and remove the file open_iA.vcxproj.user
      • Go to the subdirectory "cmd" of the open_iA-bin-dir folder, and remove the file open_iA_cmd.vcxproj.user
      • Open CMake, enter your open_iA-bin-dir under "Where to build the binaries"
      • Press "Configure"
      • Make sure that the files you deleted in step 2 and 3 were recreated
      • Open "open_iA.sln" in open_iA-bin-dir in Visual Studio
      • You can check whether the paths were properly set:
        • Go to the ALL_BUILD or open_iA project
        • Right click on the project, select "Properties"
        • Select "Debugging" on the left
        • Make sure the appropriate configuration (i.e. the one you tried to start before) is selected in the dropdown on top (e.g. Debug)
        • Check the "Environment" entry. There you should see an assignment to PATH, containing a semicolon-separated list of library paths, containing at least your VTK, ITK and Qt library paths.
      • open_iA should now start fine when started from Visual Studio.

  • When running open_iA, you get an error message: "This application failed to start because it could not find or load the Qt platform plugin 'windows'. Reinstalling the application may fix this problem."

    • Qt related problem which might occour if open_iA was not built on the same machine (e.g. copied from another)
    • Solution: (note: see point above before trying this!)
      • Create new folder where open_iA.exe is located named 'platforms'
      • Copy qwindows.dll and qwindowsd.dll from Qt-installation-dir/qtbase/plugins/platforms into this folder

  • In case of a fatal error C1090: PDB API call failed, error code '3' error in ITK build, see our ITK page.