Cancer Imaging Phenomics Toolkit (CaPTk)  1.8.1

CaPTk is developed and maintained by the Center for Biomedical Image Computing and Analytics (CBICA) at the University of Pennsylvania, and draws upon research from several groups within the Center.

New applications, written in any programming language, can be integrated into CaPTk at different levels. These applications can then run within CaPTk, while having direct access to the full breadth of CaPTk’s interactive capabilities.

• Source level integration: At this level, the new application source code (C++) is compiled alongside CaPTk, ensuring the most optimized integration. Source-level integration is straight-forward (only requiring additions to relevant CMake files and minor additions to the interactive base) if the new application relies on a subset of CaPTk’s dependencies (i.e., ITK, VTK, OpenCV, Qt).
• Executable level integration: This level provides a graphical interface to an existing command-line application (not necessarily developed in C++), allowing users to leverage CaPTk’s functionality (e.g., interaction, feature extraction). Executable-level integration requires only minor additions to CaPTk to create a menu option for the new application.

Almost every application of CaPTk has an accompanying command-line executable (with more on the way). Those programs can be called directly, making the CaPTk applications available as components within a larger pipeline or for efficient batch processing of large numbers of images.

We will provide the technical details of the Cancer Imaging Phenomics Toolkit (CaPTk) using which new applications can be integrated into the global framework and also optimize/improve the code. For any questions/details, please feel free to email software@cbica.upenn.edu.

Different layers of application integration in CaPTk

Applications written in any language can be integrated with CaPTk via calls to stand-alone command line executables, but deeper integration (including data passing via objects in-memory and access to full breadth of interactive capabilities of the CaPTk Console) is only possible with applications written in C++ (https://isocpp.org/).

• LIBRA, in its current form (MATLAB executable) has the least possible integration with the CaPTk Console; the console can call the executable, which launches its own UI for the user.
• ITK-SNAP is an example of integration where CaPTk Console communicates with the application using the provided API; in this case CaPTk ensures that the loaded images, ROIs, masks, etc. are all passed to ITK-SNAP and the result from the segmentation step there gets passed to the console for visualization after ITK-SNAP is closed.
• SBRT Lung is an example of integration with a stand-alone CLI application. The Console calls the executable in accordance with CLI, passes the loaded images and ROIs, etc. and visualizes the result when the application is done.
• EGFRvIII Surrogate Index provides the tightest possible integration with the CaPTk Console. All data (loaded images, ROIs, etc.) is passed in-memory and the visualization of results happens instantaneously.
• All functions available in native C++ libraries (ITK (https://itk.org/), OpenCV (http://opencv.org/), VTK (http://www.vtk.org/)) are available for native applications to use.

You need to compile CaPTk from source to proceed. The following sections give that information.

# Building CaPTk from Sources

## Prerequisites

Source code for the CaPTk graphical interface and applications is distributed for sites that wish to examine the code, collaborate with CBICA in future development, and for compatibility.

For end-to-end build examples for Windows/Linux (Ubuntu Xenial)/macOS (10.13), please see our Azure Pipelines configuration file.

Before building CaPTk, the following software libraries are required to be installed. Please note that to build in Windows, CMake needs to be used an appropriate compiler (Win64 version of Visual Studio is recommended). The selected solution platform is needed to match with dependent libraries.

Package Version Description
Archiver or Git N.A. - Windows: Built-in unzip tool
- Linux: gzip
C++ compiler C++11 compliance needed - Windows: Visual Studio 2015/2017
- Linux: GCC/4.9.2-7.4.0
- macOS: CLang 10.0.0, LLVM 6.0.1
OpenGL 3.2+ (hardware-dependent) - Windows/macOS: Update graphics drivers
- Ubuntu: apt-get install libgl-dev
- CentOS: yum install mesa-libGL-devel
- Details in FAQ
CMake 3.10 - 3.12 To configure the CaPTk compilation along with its dependencies (via Superbuild).
X11 [Linux-only] N.A. - Ubuntu: apt-get install libxkbcommon-x11-0
- CentOS: yum install libXt-deve
dos2unix [Linux-only] N.A. - Ubuntu: apt-get install dos2unix
- CentOS: yum install dos2unix
Doxygen 1.8+ OPTIONAL: For documentation only.

Ensure all dependencies are met before proceeding.

## Build

Please follow commands below in a shell/terminal (e.g., Bash (http://www.gnu.org/software/bash/)). They will configure and build CaPTk using GNU Make (http://www.gnu.org/software/make/). The main CMake configuration file (CMakeLists.txt) is located in the root directory of the package. Windows users need to follow the equivalent graphical interface or from PowerShell.

An example of the list of commands to run to compile CaPTk and its dependencies:

git clone https://github.com/CBICA/CaPTk.git
cd CaPTk
git submodule update --init --recursive # this ensures all submodules are initialized and up-to-date
mkdir build # this is where we will build all the binaries
cd build
cmake .. # configure the superbuild first - builds ITK, VTK and OpenCV based on specific Qt version which is downloaded
make -j # multi-threaded compilation: use 'make -j${N}' to specify number of threads to use; on Windows, compile the ALL_BUILD project cmake -DCMAKE_INSTALL_PREFIX=${path_to_where_you_want_to_install} .. # configure CaPTk
make -j # multi-threaded compilation: use 'make -j${N}' to specify number of threads to use; on Windows, compile the ALL_BUILD project make install/strip # installs CaPTk and all its files to${path_to_where_you_want_to_install}; on Windows, compile the INSTALL project


# Integrating your C++ application into CaPTk

Let’s say the name of your application is yourSourceApp. The following steps highlight the steps required for you to integrate your application into CaPTk:

• Input and Output of files is handled by the graphical layer, which takes into account file handling, directory sorting, etc. so you can worry about the important stuff, i.e., your algorithm.
• We are currently developing actively on MSVC/12 - Visual Studio 2013 (https://www.microsoft.com/en-US/download/details.aspx?id=44914) and GCC/4.9.2. Plans are in motion to migrate to MSVC/14 - Visual Studio 2015 (https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx) and GCC/5.x very soon, upon which all C++11 features (https://en.wikipedia.org/wiki/C%2B%2B11) will be enabled by default.
• The graphical layer reads DICOM or NIfTI files and passes it on as an ITK-Image (http://www.itk.org/Doxygen/html/classitk_1_1Image.html). The data type defaults to the same type in which the original image was written. This is done using the ITK-ImageIOBase class (http://www.itk.org/Doxygen/html/classitk_1_1ImageIOBase.html).
• Your application should read either a single ITK-Image or a vector (http://www.cplusplus.com/reference/vector/vector/) of ITK-Images and give output in a similar format (either a single ITK-Image or a vector of ITK-Images).
• yourSourceApp should be structured as a single class, i.e., a collection of yourSourceApp.h and yourSourceApp.cpp (ensure that the extensions match up otherwise CMake won’t pick them up as valid applications). Put the class implementation in the following folder - $PROJECT_SOURCE_DIR/src/applications and let CMake pick your application up in the next compilation step. • If your algorithm does any kind of compilation or builds dependencies (libraries, executables, etc.), ensure that all the new files (non-source code files) are generated out-of-source. This is done to ensure that packaging the final application can happen in a concurrent manner. • CaPTk is able to handle application-specific dependencies well. For example, if you prefer the SVM implementation of LibSVM (https://github.com/cjlin1/libsvm) rather than that of OpenCV (http://docs.opencv.org/2.4/modules/ml/doc/support_vector_machines.html), you can simply create a new folder called /yourSourceApp_includes under$PROJECT_SOURCE_DIR/src/applications and let CMake take care of the configuration. yourSourceApp will see the includes as if it was present in the same folder (i.e., no need to specify folder when including these dependencies).

# Integrating your Python application into CaPTk

Let’s say the name of your application is yourPythonApp. The following steps give a brief high-level overview regarding the steps required for integrating it with CaPTk:

• Input and Output of files is handled by the graphical layer, which takes into account file handling, directory sorting, etc. so you can worry about the important stuff, i.e., your algorithm.
• For interpreted languages such as Python, the graphical layer writes a NIfTI file (yes, there is disk I/O, yes it is inefficient, yes it is stupid but there is no other way around it so just deal with it).
• Your application should be structured as a single yourPythonApp.py script (can be a class or pipeline). This should be present in the $PROJECT_SOURCE_DIR/src/applications/py directory. Your application should also have a file analogous to the setup.py (https://pythonhosted.org/an_example_pypi_project/setuptools.html) file used in Python projects by the name yourPythonApp_setup.py. • The Python configuration creates a virtual environment in the$PROJECT_BINARY_DIR/py directory, where all the dependencies are constructed.
• Your application should support command line interfaces properly (verbose parameters throughout at the very least).
• Add a new application under the APP_LIST_PY_GUI in CaPTk_source_code/src/applications/CMakeLists.txt and then make the corresponding addition in the fMainWindow and ui_fMainWindow class (take LIBRA as a starting point).
• Once you have a menu item and the corresponding function call for your application, you can recompile CaPTk and then it will be able to pick up your application