Setup CamiTK Development Environment on Windows

This page will guide you to install the development environment required to build CamiTK on Windows 10 and 11. After the procedure described in this page, your CamiTK environment will be ready.

Install dependencies and toolchain

Foreword: a warning on PATH

You have to be especially careful about the PATH environment variable. Some software will add path to their own installation directory where incompatible version of dependencies (for instance incompatible version Qt, which is a very popular library) will avoid you to setup the CamiTK development environment properly.

Another problem may arise when the PATH environment variable is already quite full. There is a limit to the length of this variable (or more exactly in the tool that modifies the variable value). If this limit is reached, setup the CamiTK development environment might not be done properly.

On Windows 10 and 11, it is therefore recommended:

• if possible, to start from a fresh Windows 10 and 11 install (or a machine that does not already zillions of software installed)
• check the value of the PATH environment variable to make sure:
  • there is no older/other dependency DLL accessible through the path (e.g. older/other version of Qt)
  • its length is not too close to the limit of 1023 characters (setx limit)

Overview

Setting up a development environment requires that all the tool chain and dependencies from scratch should be installed on your machine. This page will guide you during a step-to-step. Each step just need a copy-paste (and wait). The dependencies will be compiled from the source most of the time, as they are not available as pre-compiled/installable packages. This will take a little bit of time, but it is worth the trouble!

As stated in the support policy document, the following dependencies are required and will be installed step-by-step as stated in this page:

• CMake
• A modern C++ compiler (we recommend MSVC 2019)
• Qt (>= 5.11, for Windows 10 and 11 we recommend Qt 5.15 LTS)
• VTK (>= 7.1.1, for Windows 10 and 11 we recommend VTK 8.2.0)
• xerces-c (== 3.2, for Windows 10 and 11 we recommend xerces 3.2.5)
• XSD Code Synthesis (== 4.0.0)

If you would like to use the imaging open-source extensions (for image processing), the additional dependencies will also be installed:

• ITK (>= 4.12.12, for Windows 10 and 11 we recommend ITK 4.13.2)
• GDCM (>= 3.0.5, , for Windows 10 and 11 we recommend GDCM 3.0.6)

We also recommend that you install:

• visual studio or visual studio code (so you get an IDE). You can also choose any IDE you like, especially if it can interact with CMake.
• git and its bash shell subsystem.

Installation step by step

Open a command shell with elevated privilege

Most of the instructions given in this page are to be typed from a command shell with the admin privilege.

First to launch a cmd shell with admin privilege:

• Click Start (also shown as the circular Windows logo in the Start menu).
• Type Command Prompt and right-click Command Prompt when it appears in the Start menu. From the resulting context menu, click Run as administrator.

The following instructions refer to this command prompt with administrative privilege as the “shell”, “cmd prompt”, “cmd shell”, or “command shell”.

Decide where to install

We recommend to install the CamiTK development environment on the C: drive, in the C:\camitk-dev directory (as a short name is convenient to overcome the PATH length limit mentioned above). If for some reason, you prefer to install it somewhere else, keep the path short (otherwise some file path might go over the path length limit) and make sure there are no space and no special characters in the path.

The first step of this installation guide is to set the two install path variables:

• CAMITK_INSTALL_DRIVE is the name of the Windows drive (the default value set below is C:)
• CAMITK_INSTALL_ROOT is the full path to the root of the CamiTK development environment (the default value set below is C:\camitk-dev)

You may change the default value, but beware of the recommendations given above.

These two variables are used during the installation process to specify where source, build, and installation will take place.

To set the installation path variables, from the command shell, just type (comment lines start with # and should, of course, not be typed):

setx CAMITK_INSTALL_DRIVE "C:"
setx CAMITK_INSTALL_ROOT "C:\camitk-dev"

Close the shell so that the modification of the path are taken into account, and reopen a command shell with admin privilege (you are going to do that a lot in this page as changing the environment variable does not modify the current command shell!).

Install chocolatey

All the installation steps below will be done on the command line using a classic/default Windows shell.

First launch a shell with administrative privilege.

In the following steps, all downloads, install and build will be done in %CAMITK_INSTALL_ROOT%. You can change this for any other location on your disk.

The first step is to install chocolatey, the package manager.

From the command shell, just type (comment lines start with # and should, of course, not be typed):

:: create the directory structure and update required environment variables
mkdir %CAMITK_INSTALL_ROOT% %CAMITK_INSTALL_ROOT%\downloads %CAMITK_INSTALL_ROOT%\src %CAMITK_INSTALL_ROOT%\build %CAMITK_INSTALL_ROOT%\install

:: add the future install binary in the path
setx /M path "%path%;%CAMITK_INSTALL_ROOT%\install\bin"

:: create tmp dir so that msbuild does not fail over filename being over 260 char
setx TMPDIR "%CAMITK_INSTALL_DRIVE%\tmp"
mkdir "%TMPDIR%"

:: install chocolatey
powershell -NoProfile -ExecutionPolicy Bypass -Command^
    $Env:chocolateyUseWindowsCompression = 'false' ;^
    "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))"

Now exit the cmd shell so that the modification of the path are taken into account.

Install utilities and tool chain

In thes steps we will install:

• git bash
• curl
• CMake 3.17
• 7zip
• pedeps (a tool to determine dll dependencies)
• MSVC2019 v14 (note that you may also install Visual Studio)
  • visualstudio2019buildtools
  • visualstudio2019-workload-vctools
  • visualstudio2019-remotetools
• python (required by “another qt installer”, see next step)
• jom (to empower your cores)

In this documentation, these utilities and tool chain will be installed and compiled from the command line. You may also use an IDE to build the dependencies (please use the same flags and options as specified in the remaining).

First download CamiTK 5.0 chocolatey configuration file and save it to %CAMITK_INSTALL_ROOT%\install.

Then, from a new cmd shell with administrator privilege, install everything listed above thanks to chocolatey and this config file:

:: Do not ask the user for interactive confirmation before each install
choco feature enable -n allowGlobalConfirmation

:: install all package defined in the configuration file
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%
choco install install\camitk-win10-5.config -y

:: get the actual msvc version installed (bash was installed along git, the command can be run using git bash if this fails)
bash -c "setx MSVC_INSTALL_VERSION $(ls /C/Program\ Files\ \(x86\)/Microsoft\ Visual\ Studio/2019/BuildTools/VC/Tools/MSVC)"

At this stage it is recommended to reboot.

After rebooting, open a new command shell with the administrator privilege, and type:

:: add the MSVC compiler in the path
setx /M path "%path%;C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\%MSVC_INSTALL_VERSION%\bin\Hostx64\x64"

Now exit the cmd shell so that the modification of the path are taken into account.

Install Qt

This step is using a great tool, called Another Qt installer (it requires Python, which was installed at the previous step) which install Qt without requiring user interaction.

Open a new cmd with administrative privilege and type:

:: install Another Qt installer
pip install aqtinstall

:: install Qt using Another Qt installer 
python -m aqt install --outputdir %CAMITK_INSTALL_ROOT%\install\Qt 5.15.1 windows desktop win64_msvc2019_64

:: add Qt binaries in the path and add required environment variables
setx /M path "%path%;%CAMITK_INSTALL_ROOT%\install\Qt\5.15.1\msvc2019_64\bin"
setx /M QT_PLUGIN_PATH "%CAMITK_INSTALL_ROOT%\install\Qt\5.15.1\msvc2019_64\plugins"

Now exit the cmd shell so that the modification of the path are taken into account.

Install VTK

Now you will need to open a specific developer cmd prompt. You can do either of the following:

• either from inside a developer command prompt. To open the developer command prompt, start typing x64 in the Windows Start menu and you should see a x64 Native Tools Command Prompt for VS 2019 in the list of suggestions. Select x64 Native Tools Command Prompt for VS 2019 and choose “Run as administrator”
• or a regular cmd command prompt with MSVC setup and administrator privilege. First, open a cmd shell with the administrator privilege and type "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" amd64 (don’t forget the double quotes " to ensure the path with space are taken into account) as the first command.

Once you opened one of the proper command prompt, type:

:: go to the top level directory of your install drive
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%\

:: download VTK
curl -L https://www.vtk.org/files/release/8.2/VTK-8.2.0.zip --output %CAMITK_INSTALL_ROOT%\downloads\VTK-8.2.0.zip
:: if you get a warning/error about SSL revocation, you may add the "--ssl-no-revoke" (at your own risk):
:: curl  --ssl-no-revoke -L https://www.vtk.org/files/release/8.2/VTK-8.2.0.zip --output %CAMITK_INSTALL_ROOT%\downloads\VTK-8.2.0.zip

:: extract the source
7z x %CAMITK_INSTALL_ROOT%\downloads\VTK-8.2.0.zip -o%CAMITK_INSTALL_ROOT%\src

As VTK 8.2.0 was published before Qt 5.15.0, there is a missing an include directive, see this issue]). You therefore need to patch VTK.

First download the patched source vtkQtLabelRenderStrategy.cxx and vtkQtStringToImage.cxx and overwrite the initial version that was just previously unzipped in %CAMITK_INSTALL_ROOT%\src\vtk-8.2.0\Rendering\Qt\. In order to build from the command line without any error, you also need to use our patched PluginInstall.cmake.in and overwrite the initial version in %CAMITK_INSTALL_ROOT%\src\VTK-8.2.0\GUISupport\Qt\.

Then, from the same command shell:

:: go to the top level directory of your install drive
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%\

:: configure
mkdir %CAMITK_INSTALL_ROOT%\build\vtk8
cd %CAMITK_INSTALL_ROOT%\build\vtk8

:: This is:
cmake ..\..\src\vtk-8.2.0^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -DCMAKE_DEBUG_POSTFIX="-debug"^
      -DBUILD_SHARED_LIBS=TRUE^
      -DVTK_Group_Qt=ON^
      -DVTK_QT_VERSION=5^
      -DVTK_Group_Imaging=ON^
      -DVTK_Group_Views=ON^
      -DVTK_Group_Qt=ON^
      -DModule_vtkRenderingExternal=ON^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Debug"

:: build and install the debug version
:: In the next line, 
:: (the parallel argument should match the number of core of your computer)
cmake --build . --target install

:: Do the same for the release version
cmake ..\..\src\vtk-8.2.0^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -DBUILD_SHARED_LIBS=TRUE^
      -DVTK_Group_Qt=ON^
      -DVTK_QT_VERSION=5^
      -DVTK_Group_Imaging=ON^
      -DVTK_Group_Views=ON^
      -DVTK_Group_Qt=ON^
      -DModule_vtkRenderingExternal=ON^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Release"

cmake --build . --target install

:: add required environment variables
setx /M VTK_DIR "%CAMITK_INSTALL_ROOT%\install\lib\cmake\vtk-8.2"

Install xerces-c

From the same command shell:

:: go to the top level directory of your install drive
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%\

:: download xerces-c
curl -L https://miroir.univ-lorraine.fr/apache//xerces/c/3/sources/xerces-c-3.2.5.zip --output %CAMITK_INSTALL_ROOT%\downloads\xerces-c-3.2.5.zip

:: extract the source
7z x %CAMITK_INSTALL_ROOT%\downloads\xerces-c-3.2.5.zip -o%CAMITK_INSTALL_ROOT%\src

:: configure
mkdir %CAMITK_INSTALL_ROOT%\build\xerces
cd %CAMITK_INSTALL_ROOT%\build\xerces
cmake ..\..\src\xerces-c-3.2.5^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Debug"

:: build and install the debug version
cmake --build . --target install

:: Do the same for the release version
cmake ..\..\src\xerces-c-3.2.5^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Release"

cmake --build . --target install

:: add required environment variables
setx XERCESC_DIR "%CAMITK_INSTALL_ROOT%\install"

Install Code Synthesis XSD

From the same command shell:

:: go to the top level directory of your install drive
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%\

:: download XSD binaries
curl -L https://www.codesynthesis.com/download/xsd/4.0/windows/i686/xsd-4.0.0-i686-windows.zip --output %CAMITK_INSTALL_ROOT%\downloads\xsd-4.0.0-i686-windows.zip

:: extract the binaries
7z x %CAMITK_INSTALL_ROOT%\downloads\xsd-4.0.0-i686-windows.zip -o%CAMITK_INSTALL_ROOT%\install

:: add required environment variables
setx XSD_DIR "%CAMITK_INSTALL_ROOT%\install\xsd-4.0.0-i686-windows"

Now we need to fix a mixup between Microsoft Xml Schemas/DataTypes support utility and Code Synthesis XSD (both called xsd.exe). We are just going to rename Code Synthesis XSD executable to xsdcxx.exe (this is taken care later on of by CamiTK anyway).

From the same command shell:

copy "%CAMITK_INSTALL_ROOT%\install\xsd-4.0.0-i686-windows\bin\xsd.exe" "%CAMITK_INSTALL_ROOT%\install\xsd-4.0.0-i686-windows\bin\xsdcxx.exe"

As Code Synthesis XSD binaries were compiled for a previous version of MSVC, we need to patch one header in order to flawlessly compile with MSVC 2019.

Just download the patched header serialization.txx and overwrite the initial version installed in %CAMITK_INSTALL_ROOT%/install/xsd-4.0.0-i686-windows/libxsd/xsd/cxx/tree/

Install GDCM

From the same command shell:

:: go to the top level directory of your install drive
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%\

:: download gdcm
curl -L https://github.com/malaterre/GDCM/archive/v3.0.6.zip --output %CAMITK_INSTALL_ROOT%\downloads\gdcm-3.0.6.zip

:: extract the source
7z x %CAMITK_INSTALL_ROOT%\downloads\gdcm-3.0.6.zip -o%CAMITK_INSTALL_ROOT%\src

:: configure
mkdir %CAMITK_INSTALL_ROOT%\build\gdcm
cd %CAMITK_INSTALL_ROOT%\build\gdcm
cmake ..\..\src\GDCM-3.0.6^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -DCMAKE_DEBUG_POSTFIX="-debug"^
      -DGDCM_BUILD_SHARED_LIBS=TRUE^
      -DGDCM_USE_VTK=TRUE^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Debug"

:: build and install the debug version
:: (the parallel argument should match the number of core of your computer)
cmake --build . --target install

:: Do the same for the release version
cmake ..\..\src\GDCM-3.0.6^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -DGDCM_BUILD_SHARED_LIBS=TRUE^
      -DGDCM_USE_VTK=TRUE^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Release"

cmake --build . --target install

Install ITK

From the same command shell:

:: go to the top level directory of your install drive
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%\

:: download ITK
curl -L https://github.com/InsightSoftwareConsortium/ITK/releases/download/v4.13.2/InsightToolkit-4.13.2.zip --output %CAMITK_INSTALL_ROOT%\downloads\InsightToolkit-4.13.2.zip

:: extract the source
7z x %CAMITK_INSTALL_ROOT%\downloads\InsightToolkit-4.13.2.zip -o%CAMITK_INSTALL_ROOT%\src

As ITK 4.13.2 was published before MSVC 2019, you need to patch VTK.

First download the patched source gdcmIPPSorter.cxx and overwrite the initial version that was just previously unzipped in %CAMITK_INSTALL_ROOT%\src\InsightToolkit-4.13.2\Modules\ThirdParty\GDCM\src\gdcm\Source\MediaStorageAndFileFormat\.

Depending on your compiler version, you may encounter a compilation error mentionning lrintf. In that case you must edit the file %CAMITK_INSTALL_ROOT%\src\InsightToolkit-4.13.2\Modules\ThirdParty\OpenJPEG\src\openjpeg\opj_includes.h and replace the two lines (95 and 106) from static INLINE long lrintf(float f){ to static INLINE long opj_lrintf(float f){.

Then, from the same command shell:

:: go to the top level directory of your install drive
%CAMITK_INSTALL_DRIVE%
cd %CAMITK_INSTALL_ROOT%\

:: configure
mkdir %CAMITK_INSTALL_ROOT%\build\itk
cd %CAMITK_INSTALL_ROOT%\build\itk
cmake ..\..\src\InsightToolkit-4.13.2^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -DCMAKE_DEBUG_POSTFIX="-debug"^
      -DBUILD_SHARED_LIBS=TRUE^
      -DBUILD_TESTING=FALSE^
      -DModule_ITKDeprecated:BOOL=ON^
      -DModule_ITKReview:BOOL=ON^
      -DModule_ITKVtkGlue:BOOL=OFF^
      -DITKV3_COMPATIBILITY:BOOL=ON^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Debug"

:: build and install the debug version
cmake --build . --target install

:: Fix ITK debug CMake misconfiguration
copy %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5_cpp_D-debug.lib %CAMITK_INSTALL_ROOT%\install\lib\itkhdf5_cpp-static-4.13-debug.lib
copy %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5_D-debug.lib %CAMITK_INSTALL_ROOT%\install\lib\itkhdf5-static-4.13-debug.lib


:: configure the release version
cmake ..\..\src\InsightToolkit-4.13.2^
      -DCMAKE_INSTALL_PREFIX=%CAMITK_INSTALL_ROOT%\install^
      -DBUILD_SHARED_LIBS=TRUE^
      -DBUILD_TESTING=FALSE^
      -DModule_ITKDeprecated:BOOL=ON^
      -DModule_ITKReview:BOOL=ON^
      -DModule_ITKVtkGlue:BOOL=OFF^
      -DITKV3_COMPATIBILITY:BOOL=ON^
      -G"NMake Makefiles JOM"^
      -DCMAKE_BUILD_TYPE="Release"

:: build and install the release version
cmake --build . --target install

:: Fix ITK release CMake misconfiguration
copy %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5_cpp.lib %CAMITK_INSTALL_ROOT%\install\lib\itkhdf5_cpp-static-4.13.lib
copy %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5.lib %CAMITK_INSTALL_ROOT%\install\lib\itkhdf5-static-4.13.lib
copy %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5_D-debug.lib %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5_D.lib
copy %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5_cpp_D-debug.lib %CAMITK_INSTALL_ROOT%\install\lib\libitkhdf5_cpp_D.lib

Congratulations! All the dependencies and tool chains are now install!

Cleanup some space (optional)

During this installation process the build objects were generated in the %CAMITK_INSTALL_ROOT%\build directory. If everything seems to work well, you may save a lot of space on your disk by simply deleting this directory.

Install an Interactive Development Environment

If you are going to spend some time coding on Windows, we recommend that you install Visual Studio 2019. Again, to simplify the installation we recommend to use chocolatey to install the IDE. From a cmd console with the administrator privilege:

choco install visualstudio2019community --package-parameters "--passive --locale en-US"

Note that other IDE are available as well:

• Visual Code with the C/C++ extension (use choco install vscode)
• KDevelop (use choco install kdevelop)
• Qt creator (use choco install qtcreator)

Where should I go next?

You can now proceed to build and install CamiTK