/
2_GettingStarted.txt
536 lines (388 loc) · 35.3 KB
/
2_GettingStarted.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
/**
\page Getting_Started Getting Started
For Download/Installation Instructions, please see the following:
- [Download Instructions](Download.html)
- [Installation Instructions](Installation.html)
For Frequently Asked Questions, please see the dedicated [FAQ](FAQ.html) section.
CaPTk has been designed as a modular platform, currently incorporating components for:
-# User interaction (e.g., coordinate definition, region annotation, and spherical approximation of abnormalities)
- \ref gs_imageLoading
- \ref gs_imageVisualization
- \ref gs_tabDocking
- \ref gs_seedpoints
- \ref gs_utilities
- \ref gs_drawing
- \ref gs_keyboard
-# \ref gs_preprocessing (e.g., smoothing, bias correction, co-registration, normalization)
-# \ref gs_segmentation
-# \ref gs_features
-# \ref gs_specializedApps
The components of interaction and pre-processing are available for all integrated applications giving a researcher (whether clinical or computational) a single point of entry and exit for all their tasks.
Several CaPTk algorithms and tools can be used from the web on the [CBICA Image Processing Portal](https://ipp.cbica.upenn.edu/).
The following sections give a high-level overview of CaPTk, with the intention of familiarizing a new user with the platform functionalities and interface.
\tableofcontents
--------
\section gs_FAQ Frequently Asked Questions
Please see the dedicated [FAQ](FAQ.html) section.
--------
\section gs_supportedImages Supported Images
Currently, CaPTk supports visualization of <b>MR, CT, PET, X-Ray and Full-field Digital Mammography (FFDM) </b> images in NIfTI (i.e., <b>.nii</b>, <b>.nii.gz</b>) format. DICOM (i.e., <b>.dcm</b>) support is limited to a few protocols for MR, CT and MG modalities. In NIfTI format, for MRI, the following modalities are currently supported (the image modality box equivalent is shown in parenthesis):
| Acronym | Image Type |
|:-----------:|:---------------------------------------------------------------------:|
| T1 | Native T1-weighted MR Image |
| T1Gd | Post-contrast T1-weighted MR Image (also known as T1c, T1-CE) |
| T2 | Native T2-weighted MR Image |
| FLAIR | T2-weighted Fluid Attenuated Inversion Recovery MR Image |
| DSC-ap-rCBV | automatically-extracted proxy to relative Cerebral Blood Volume |
| PERFUSION | Dynamic Susceptibility Contrast-enhanced MR Image (also known as DSC) |
| DTI | Diffusion Tensor Image |
| DWI | Diffusion Weighted Image |
| REC | Recurrence Maps |
<b>*</b> These modalities are currently visualized only within the "Confetti" application.
In addition, CaPTk offers the ability to extract and visualize commonly used measurements from DTI [1] and DSC-MRI, while accounting for leakage correction [2]. The exact measurements supported are:
| Acronym | Image Type |
|:-----------:|:---------------------------------------------------------------:|
| DTI-FA | Fractional Anisotropy |
| DTI-AX | Axial Diffusivity |
| DTI-RAD | Radial Diffusivity |
| DTI-TR | Trace |
| DSC-ap-rCBV | automatically-extracted proxy to relative Cerebral Blood Volume |
| DSC-PH | Peak Height |
| DSC-PSR | Percentage Signal Recovery |
--------------------------------------------------------------------
References:
-# J.M.Soares, P.Marques, V.Alves, N.Sousa. "A hitchhiker's guide to diffusion tensor imaging", Front Neurosci. 7:31, 2013, DOI: 10.33
fnins.2013.00031
-# E.S.Paulson, K.M.Schmainda, "Comparison of dynamic susceptibility-weighted contrast-enhanced MR methods: recommendations for measuring relative cerebral blood volume in brain tumors", Radiology. 249(2):601-613, 2008, DOI: 10.1148/radiol.2492071659
--------
\section gs_imageLoading Image & Mask Loading
The <b>File -> Load -> Images</b> menu is used to load all image types. Images can also be loaded by dragging and dropping onto the application. In case of DICOM images, loading/dragging a single image loads the entire dicom series.
<br>
Mask must be loaded via <b>File -> Load -> ROI</b> menu and also by dragging and dropping onto the application.
\image html imageLoading_resize.png "Loading images & mask for visualization/processing"
\image latex imageLoading_resize.png "Loading images & mask for visualization/processing"
--------
For every loaded NIfTI image, the modality is automatically assigned using information from the filename. To <b> assign modalities </b> for DICOM images, or in case of a discrepancy in the modality of a NIfTI image, the user can use the drop-down modality switcher (see below) to revise the modality accordingly. This is typically needed in the <a href="ht_SpecialApps.html">Specialized Applications</a>.
\image html modalities_resize.png "Modality switching for individual images"
\image latex modalities_resize.png "Modality switching for individual images"
--------
\section gs_imageVisualization Image Visualization
Sliders on each visualization panel (highlighted in green in the figure below) control the movement across respective axes. Note that in DSC-MRI, the single horizontal slider (highlighted in yellow) moves across the time of the acquired dynamic scan.
<br>
Various adjustments are available to the user, including:
-# Window/Level: right mouse button press + horizontal/vertical mouse move on any visualization panel, respectively.
-# Manual Window/Level and setting of different visualization presets: bottom-right panel.
-# Image zoom: Ctrl + mouse wheel.
-# Image pan: Ctrl + left mouse button press + mouse move.
The bottom-left panel of CaPTk (highlighted in red) shows basic information about the image and the position of the cross-hair. In the visualization panes, the "Z" axis is the center; and "Y" and "X" are to its left and right, respectively. "Z" represents the Axial view for RAI-to-LPS images.
\image html sliders_resize.png "Visualization Sliders and Image Information"
\image latex sliders_resize.png "Visualization Sliders and Image Information"
The "Overlay" functionality enables the visualization between two loaded images:
-# Double-click one of the two images you want to visualize and then click on its corresponding "overlay" radio button, on its right-most column.
-# Click on the "overlay" radio button of the second image that you want to visualize.
-# Both "Overlay" and "Underlay" images are now visualized with 50% opacity.
-# Check the tick box "Change Opacity".
-# Moving the slider changes the opacity between the "Overlay" and the "Underlay" images.
The "Comparison Mode" puts the loaded images (3 maximum) side-by-side for easy visualization along the same axis.
\image html comparisonMode.png "Comparison Mode visualization"
\image latex comparisonMode.png "Comparison Mode visualization"
--------
\section gs_tabDocking Tab Docking
Double clicking on the tab bar will dock/undock the entire section, resulting in larger visualization panels in your monitor. This behavior is replicated by single click of the dock/undock button at the end of the section as well.
\image html dock_comparison_resize.png "Left is while dock is active and right is undocked behavior"
\image latex dock_comparison_resize.png "Left is while dock is active and right is undocked behavior"
--------
\section gs_seedpoints Coordinate definition (Seed-point initialization)
The <b>Seed Points</b> tab includes two general types of initialization (i.e., tumor and tissue points), controlled by the respective radio buttons.
\image html seeds_resize.png "Seed point initialization"
\image latex seeds_resize.png "Seed point initialization"
Loading and saving is done via text files in a format consistent with respective applications. Seedpoint files are needed for the following applications (and all derivatives): GLISTR (https://www.cbica.upenn.edu/sbia/software/glistr/) [1-3], GLISTRboost (BraTS 2015 top-ranked algorithm - https://www.med.upenn.edu/sbia/glistrboost.html) [4-6], and PORTR (https://www.cbica.upenn.edu/sbia/software/portr/) [7].
The controls to add/remove points are the shown below.
--------
\subsection gs_seedpoints_tumor Tumor Points
These are seed-points used to approximate a tumor by a parametric spherical model, using a seed-point for its center and another for defining its radius. These are helpful for applications like tumor growth model estimation as currently incorporated in GLISTR and GLISTRboost. The controls are as follows:
| Key Stroke | Function/Action |
|:---------------:|:--------------------------------------------------------------------------:|
| Shift + Space | [SEED POINT] Set initial tumor center |
| Control + Space | [SEED POINT] Update tumor radius; on macOS, this is "Fn + Command + Space" |
| Space | [SEED POINT] Update tumor center |
--------
\subsection gs_seedpoints_tissue Tissue Points
These are seed-points with coordinate information. They can be used for a multitude of applications where manual initialization(s) are required for a semi-automated algorithm, e.g, segmentation. At the moment these points are being assigned various brain tissue labels, as follows:
| Tissue Acronym | Full Form |
|:--------------:|:-------------------------------:|
| CSF | Cerebrospinal Fluid |
| VT | Ventricular Cerebrospinal Fluid |
| GM | Gray Matter |
| WM | White Matter |
| VS | Vessels |
| ED | Edema |
| NCR | Necrosis |
| ET | Enhancing Tumor |
| NE | Non-Enhancing Tumor |
| CB | Cerebellum |
| CAE | Enhancing Cavity |
| CAN | Non-Enhancing Cavity |
| RTN | Tumor Recurrence |
| RTE | Enhanced Tumor Recurrence |
--------
Application-specific tissue types are automatically enabled when the corresponding application is selected. For example, when trying to initialize tissue points for GLISTR/GLISTRboost, only CSF, GM, WM, VS, ED, NCR, TU, NE and CB buttons will be enabled and the rest will be disabled. If there are some required tissue types missing for an application, CaPTk will display a warning and not let the user save an incomplete set of tissue points.
<br>
--------------------------------------------------------------------
References:
-# A.Gooya, K.M.Pohl, M.Billelo, G.Biros, C. Davatzikos, "Joint segmentation and deformable registration of brain scans guided by a tumog rowth model", Med Image Comput Comput Assist Interv. 14(Pt 2):532-40, 2011, DOI:10.1007/978-3-642-23629-7_65
-# A.Gooya, K.M.Pohl, M.Bilello, L.Cirillo, G.Biros, E.R.Melhem, C.Davatzikos, "GLISTR: glioma image segmentation and registration", IEET rans Med Imaging. 31(10):1941-54, 2012, DOI:10.1109/TMI.2012.2210558
-# D.Kwon, R.T.Shinohara, H.Akbari, C.Davatzikos, "Combining Generative Models for Multifocal Glioma Segmentation and Registration", MeI mage Comput Comput Assist Interv. 17(Pt 1):763-70, 2014, DOI:10.1007/978-3-319-10404-1_95
-# S.Bakas, K.Zeng, A.Sotiras, S.Rathore, H.Akbari, B.Gaonkar, M.Rozycki, S.Pati, C.Davatzikos, "Segmentation of gliomas in multimodam agnetic resonance imaging volumes based on a hybrid generative-discriminative framework", In Proc. Multimodal Brain Tumor Segmentation (BraTS) Challenge. 4:5-12, 2015.
-# S.Bakas, K.Zeng, A.Sotiras, S.Rathore, H.Akbari, B.Gaonkar, M.Rozycki, S.Pati, C.Davatzikos, "GLISTRboost: combining multimodal MRs egmentation, registration, and biophysical tumor growth modeling with gradient boosting machines for glioma segmentation", Brainlesion (2015). 9556:144-155, 2016, DOI:10.1007/978-3-319-30858-6_1
-# S.Bakas, H.Akbari, A.Sotiras, M.Bilello, M.Rozycki, J.Kirby, J.Freymann, K.Farahani, C.Davatzikos, "Advancing The Cancer Genome Atlag lioma MRI collections with expert segmentation labels and radiomic features", Nature Scientific Data 4:170117, 2017, DOI:10.103s data.2017.117
-# D.Kwon, M.Niethammer, H.Akbari, M.Bilello, C.Davatzikos, K.M.Pohl, "PORTR: Pre-Operative and Post-Recurrence Brain Tumor Registration", IEEE Trans Med Imaging. 33(3):651-667, 2014, DOI:10.1109/TMI.2013.2293478
--------
\section gs_drawing Label Annotation/Drawing Panel
This panel provides the ability to annotate Regions of Interest (ROIs) and save them as masks.
\image html drawing_resize.png "Drawing functions"
\image latex drawing_resize.png "Drawing functions"
While drawing, you can switch across the image volumes loaded in CaPTk, by pressing the numbers 1-9 on your keyboard.
Toggle between non-zero (taken from the opacity box) and zero opacity of the entire annotated mask by using the keyboard key "m".
Visualize a single label using "Control + <label number>" and add labels to the visualization using "Alt + <label number>". To reset, press "Control/Alt + 0".
There are the following controls underneath the <b>Drawing</b> tab:
| Button/Box | Description |
|:--------------------:|:----------------------------------------------------------------------------------------------------------------------------------------:|
| View Mode | Switch from drawing mode (which is enabled when either Near or Far ROI drawing is selected) to normal viewing mode |
| Line | Draw a line of selected label color and size |
| Rectangle | Draw a rectangle of selected label color and size |
| Circle | Draw a circle of selected label color and size |
| Sphere | Draw a sphere of selected label color and pre-determined size from the size combo-box |
| Free-Hand | Draw selected label using brush of specified size using mouse left button drag |
| Fill | Fill a closed boundary with selected label - uses ITK's connected component filter |
| Eraser | Erases all labels using brush of specified size |
| Label Selector | Label selector between 1-9 |
| Marker Size | A square marker of specific voxel size |
| Marker Opacity | Sets the opacity of the marker between 0.0 (transparent) and 1.0 (opaque) |
| Clear Selected Label | Remove selected label completely from the mask |
| Clear All Labels | Remove all labels completely from the mask |
| Undo | By providing the same number of old and new values in the format AxBxC, the values of the annotated region can be quickly changed |
| Change Values | By providing the same number of old and new values in the format <b>AxBxC</b>, the values of the annotated region can be quickly changed |
--------
\section gs_keyboard Keyboard Shortcuts
These are the keyboard shortcuts available on CaPTk:
| Key Stroke | Function/Action |
|:---------------:|:--------------------------------------------------------------------------:|
| 1-9 | [IMAGES] Show selected image from table |
| "m" | [DRAWING] Show/Hide all regions; picks up last used opacity |
| Control + 1-9 | [DRAWING] Only show selected label |
| Alt + 1-9 | [DRAWING] Add selected label to visualization |
| Control/Alt + 0 | [DRAWING] Reset label visualization; i.e., show all |
| Shift + Space | [SEED POINT] Set initial tumor center |
| Control + Space | [SEED POINT] Update tumor radius; on macOS, this is "Fn + Command + Space" |
| Space | [SEED POINT] Update tumor center |
--------
\section gs_utilities Utilities (Command-line only)
To make pipeline construction using CaPTk easier, a bunch of utilities have been provided:
-# Resizing
-# Resampling
-# Image information
-# Unique values in image
-# Get smallest bounding box in mask (optional isotropic bounding box)
-# Test 2 images
-# Create mask from threshold
-# DICOM to NIfTI conversion
-# NIfTI to DICOM & DICOM-Seg conversion
-# Re-orient image
-# Cast image to another pixel type
-# Thresholding:
- Below
- Above
- Above & Below
- Otsu
- Binary
-# Convert file formats
-# Extract Image Series from Joined stack and vice-versa (4D <-> 3D)
-# Transform coordinates from world to image and vice-versa
-# Label similarity Metrics between 2 label images: pure mathematical formulations are given as output
-# BraTS similarity Metrics between 2 label images: special considerations for metrics are done in this mode because output needs to be BraTS-compliant.
-# Collect information from all images in a directory and put it in CSV
For a full list of this functionality and more details, please see the corresponding [How-To page](ht_utilities.html).
--------
\section gs_preprocessing Pre-processing
Image pre-processing is essential to quantitative image analysis. CaPTk pre-processing tools available under the "Preprocessing" menu are fully-parameterizable and comprise:
- <b>Denoising.</b> Intensity noise reduction in regions of uniform intensity profile is offered through a low-level image processing method, namely Smallest Univalue Segment Assimilating Nucleus (SUSAN) [1]. This is a custom implementation and does <b>NOT</b> call out to the original implementation distributed by FSL.
- <b>Co-registration.</b> Registration of various images to the same anatomical template, for examining anatomically aligned imaging signals in tandem and at the voxel level, is done using the Greedy Registration algorithm [5].
- <b>Bias correction.</b> Correction for magnetic field inhomogeneity is provided using a non-parametric non-uniform intensity normalization [2].
- <b>Intensity normalization.</b> Conversion of signals across modalities to comparable quantities using histogram matching [4].
- <b>Z-Scoring normalization.</b> Images are normalized using a z-scoring mechanism with option to do the normalization within the region of interest or across the entire image. In addition, there is an option to remove outliers & noise from the image by removing a certain percentage of the top and bottom intensity ranges [6].
- <b>Histogram Matching</b>
- <b>Skull Stripping (Deep Learning based)</b>
- <b>Mammogram Pre-processing</b>
- <b>BraTS Pre-processing Pipeline</b>
<B>NOTE:</B> An extended set of algorithms are available via the command line utility <b>Preprocessing</b>. For full details, run the command:
\verbatim
Preprocessing.exe -u
\endverbatim
\image html pre-processing_resize.png "Available pre-processing algorithms"
\image latex pre-processing_resize.png "Available pre-processing algorithms"
<br>
--------------------------------------------------------------------
References:
-# S.M.Smith, J.M.Brady, "SUSAN - a new approach to low level image processing", Int. J. Comput. Vis. 23(1):45-78, 1997, DOI:10.102A :1007963824710
-# N.J.Tustison, B.B.Avants, P.A.Cook, Y.Zheng, A.Egan, P.A.Yushkevich, J.C.Gee, "N4ITK: Improved N3 Bias Correction", IEEE Trans MeI maging. 29(6):1310-20, 2010, DOI: 10.1109/TMI.2010.2046908
-# S.P.Thakur, J.Doshi, S.Pati, S.M.Ha, C.Sako, S.Talbar, U.Kulkarni, C.Davatzikos, G.Erus, S.Bakas, "Brain Extraction on MRI Scans in Presence of Diffuse Glioma:
Multi-institutional Performance Evaluation of Deep Learning Methods and Robust Modality-Agnostic Training", NeuroImage 2020, DOI:10.1016/j.neuroimage.2020.117081
-# L.G.Nyul, J.K.Udupa, X.Zhang, "New Variants of a Method of MRI Scale Standardization", IEEE Trans Med Imaging. 19(2):143-50, 2000, DOI:10.1109/42.836373
-# P.A.Yushkevich, J.Pluta, H.Wang, L.E.Wisse, S.Das, D.Wolk, "Fast Automatic Segmentation of Hippocampal Subfields and Medical Temporal Lobe Subregions in 3 Tesla and 7 Tesla MRI", Alzheimer's & Dementia: The Journal of Alzheimer's Association, 12(7), P126-127, DOI:10.1016/j.jalz.2016.06.205
-# T.Rohlfing, N.M.Zahr, E.V.Sullivan, A.Pfefferbaum, "The SRI24 multichannel atlas of normal adult human brain structure", Human Brain Mapping, 31(5):798-819, 2010, DOI:10.1002/hbm.20906
--------
\section gs_segmentation Segmentation
Currently there are two ways to produce segmentation labels for various structures in the images that are loaded:
-# using the Geodesic Distance Transform
-# using ITK-SNAP
-# Skull Stripping (Deep Learning based)
-# Tumor Segmentation (Deep Learning based)
\image html applicationsSeg_resize.png "Segmentation applications"
\image latex applicationsSeg_resize.png "Segmentation applications"
More information on how to run those is provided in the <a href="ht_Segmentation.html">corresponding How-To section</a>.
--------
\section gs_features Feature Extraction
The feature extraction tab in CaPTk enables clinicians and other researchers to easily extract feature measurements, commonly used in image analysis, and conduct large-scale analyses in a repeatable manner.
\image html featurepanel_resize.png "Feature Panel screenshot"
\image latex featurepanel_resize.png "Feature Panel screenshot"
Although the feature panel in CaPTk is continuously expanding, it currently comprises i) intensity-based, ii) textural (GLCM, GLRLM, GLSZM, NGTDM, LBP), and iii) volumetric/morphologic features. You can find the exact list of features incorporated in CaPTk, together with their mathematical definition in the <a href="ht_FeatureExtraction.html">corresponding How-To section</a>.
Specialized applications in CaPTk, such as "EGFRvIII Surrogate Index", "Survival Prediction", "Recurrence Estimator", and "SBRT-Lung" use features of this panel. However, the general idea is to keep the features generic and adaptable for different types of images by just changing the input parameters. Currently we provide some pre-selected parameters for Neuro and Torso images (i.e., Brain, Breast, Lung). Users can alter these pre-selected values through the <b>Custom</b> menu option, or create their own set of parameters via the <b>Advanced</b> menu. The <b>output</b> of the feature extraction tab is a text (<b>.csv</b>) file, with feature names and values. Note that the reported features are extracted per modality, per annotated region and per offset (offset represents the radius around the center pixel; for radius 1, the offset will be +/- 1) value.
--------
\section gs_specializedApps Specialized Applications
Various <a href="ht_SpecialApps.html">Specialized Applications</a> are currently incorporated in CaPTk focusing on brain tumors, breast cancer, and lung nodules as shown in the figure below.
\image html applications_resize.png "Feature Panel screenshot"
\image latex applications_resize.png "Feature Panel screenshot"
For details, please see \ref ht_SpecialApps.
--------
\section gs_commandLineUsage Command Line Usage
Almost every application offered by CaPTk can be used from the command line and utilizing the CaPTk's powerful command line APIs is relatively straight-forward. The following parameters are present in every CLI:
| Laconic | Verbose | Function/Action |
|:-------:|:-------:|:--------------------------------------------------------------------------------------------:|
| u | usage | Usage message giving all the possible parameters of an application |
| h | help | Help message giving details of parameters (including defaults and ranges) with some examples |
| v | version | The version information of the application |
An example to show the verbose help for an application called <b>${Application}</b>:
| Platform (x64) | Command |
|:--------------:|:--------------------------------------------------------------------------------:|
| Windows | ${CaPTk_InstallDir}/bin/${ApplicationName}.exe -h |
| Linux | ${CaPTk_InstallDir}/bin/${ApplicationName} -h |
| macOS | ~/Applications/CaPTk_${version}.app/Contents/Resources/bin/${ApplicationName} -h |
Detailed explanation of using the command line is available in the \ref How_To_Guides.
--------
*/
/**
\page FAQ Frequently Asked Questions
\tableofcontents
\section gs_FAQ_1 Which platforms are supported by CaPTk installers?
| Platform (x64) | Tested | Unsupported |
|:--------------:|:------------------------------------------------------:|:----------------------:|
| Windows | 7, 8, 10 | XP, Vista |
| Linux | Ubuntu 16.04, 18.04; Debian 9, CentOS 7 (source build) | Ubuntu 14.04; CentOS 6 |
| macOS | 10.13, 10.14 | 10.12 |
| Docker | N.A. | N.A. |
\section gs_FAQ_2 What DICOM images are currently supported by CaPTk?
CaPTk has limited DICOM support. It only supports a limited protocols for MR, CT and MG modalities. DICOM loading has only been tested for images from UPenn. If you are not able to load your DICOM images, please [open a new issue](https://github.com/CBICA/CaPTk/issues/new?assignees=&labels=&template=bug-report.md&title=) and send some anonymized DICOM images for us to test.
\section gs_FAQ_3 How do I run CaPTk Applications from the Command Line?
- The full list of command line applications available is shown by running the following command (pretty much every application is available via the command line):
\verbatim
${CaPTk_InstallDir}/bin/CaPTk -h
\endverbatim
- An exemplary scenario to run Applications from the command line (the example shown is to get verbose help):
| Platform (x64) | Functionality | Successful Installation | Build From Source (after invoking "make install") | FUSE Issues (after invoking "--appimage-extract") |
|:--------------:|:-----------------:|:--------------------------------------------------------------------------------:|:-------------------------------------------------:|:-------------------------------------------------:|
| Windows | Generic | ${CaPTk_InstallDir}/bin/${ApplicationName}.exe -h | ${CaPTk_InstallDir}/bin/${ApplicationName}.exe -h | N.A. |
| Linux | Generic | ${CaPTk_InstallDir}/bin/captk ${CaPTk_InstallDir}/bin/${ApplicationName}.cwl -h | ${CaPTk_InstallDir}/bin/${ApplicationName} -h | ~/CaPTk/${version}/${ApplicationName} -h |
| macOS | Generic | ~/Applications/CaPTk_${version}.app/Contents/Resources/bin/${ApplicationName} -h | ${CaPTk_InstallDir}/bin/${ApplicationName} -h | N.A. |
| Windows | FeatureExtraction | ${CaPTk_InstallDir}/bin/FeatureExtraction.exe -h | ${CaPTk_InstallDir}/bin/FeatureExtraction.exe -h | N.A. |
| Linux | FeatureExtraction | ${CaPTk_InstallDir}/bin/captk FeatureExtraction.cwl -h | ${CaPTk_InstallDir}/bin/FeatureExtraction -h | ~/CaPTk/${version}/FeatureExtraction -h |
| macOS | FeatureExtraction | ~/Applications/CaPTk_${version}.app/Contents/Resources/bin/FeatureExtraction -h | ${CaPTk_InstallDir}/bin/FeatureExtraction -h | N.A. |
- There are detailed examples of individual command line usage in the [How To](How_To_Guides.html) section of the documentation.
\section gs_FAQ_4 What are the OpenGL requirements to run CaPTk?
- If CaPTk is unable to load images or you receive the error about minimum OpenGL version wasn't found, please update your display drivers in order to have **OpenGL version 3.2 or above**. Some useful resources:
- OpenGL update for Ubuntu [[ref](https://www.phoronix.com/scan.php?page=news_item&px=Ubuntu-16.04-OI-Intel-GL-4.2)]:
\verbatim
sudo apt-add-repository ppa:oibaf/graphics-drivers && sudo apt-get update && sudo apt-get dist-upgrade
\endverbatim
- https://community.khronos.org/t/how-to-update-opengl/75314
- https://ubuntuforums.org/showthread.php?t=2326268
- https://www.techwalla.com/articles/how-to-update-opengl-drivers
- [A reply to a related issue](https://github.com/CBICA/CaPTk/issues/654#issuecomment-543744366):
\verbatim
MESA_GL_VERSION_OVERRIDE=4.5 #put the opengl version you want to use here
\endverbatim
\section gs_FAQ_5 What if I am having issues with the Linux Installer?
This section highlights some of the common issues on Linux machines.
\subsection gs_FAQ_5_1 FUSE Issues
If the installer successfully finishes and you are not able to run CaPTk due to FUSE issues, please extract the installer using the following command to extract the contents of the AppImage onto the hard drive:
\verbatim
user@pc:~# ~/CaPTk/${version}/captk --appimage-extract
\endverbatim
- This will extract the package to the path `~/CaPTk/${version}/squashfs-root/usr/` with the binaries present in `~/CaPTk/${version}/squashfs-root/usr/bin`.
- To run **CaPTk** from the command line in this manner, the user would need to make the following additions:
- Add the path `~/CaPTk/${version}/squashfs-root/usr/lib` to their environment variable **PATH**: `export PATH=~/CaPTk/${version}/squashfs-root/usr/bin:$PATH`
- Add the path `~/CaPTk/${version}/squashfs-root/usr/lib` to their environment variable **LD_LIBRARY_PATH**: `export LD_LIBRARY_PATH=~/CaPTk/${version}/squashfs-root/usr/lib:$LD_LIBRARY_PATH`
- This will need to be present in the user's shell start up file `.bashrc`, `.cshrc`, `.profile`, `.kshrc`, etc.` for the settings to be persistent across login sessions.
- All the command line applications should now be available for use. For example:
\verbatim
FeatureExtraction \ # the executable should already be in the $PATH
-n AAC0_timestamp \ # this is the subject ID for this run
-i /usr/path/T1.nii.gz,/usr/path/T2.nii.gz -t T1,T2 \ # the co-registered input image(s) and their respective modalities
-m /user/path/mask.nii.gz \ # the mask file (co-registered with the input image(s)
-r 2,4,5 -l ED,EN,NE \ # the labels from the mask file from where features need to be extracted and their respective label identifier(s)
-p /usr/path/features.csv \ # the parameter file to use
-o /usr/path/output.csv # the path to write the output
\endverbatim
\subsection gs_FAQ_5_2 GLIBCXX or GLIBC Issues
- This is happening because the Linux binaries are compiled using the [GCC-4.8 package on Ubuntu 16.04](https://packages.ubuntu.com/xenial/gcc-4.8); therefore you will need to update GCC 4.8.5 or newer in order to get CaPTk to work. Some examples are shown:
- Ubuntu [[ref](https://askubuntu.com/a/581497)]:
\verbatim
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-4.9 g++-4.9
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 60 --slave /usr/bin/g++ g++ /usr/bin/g++-4.9
\endverbatim
- CentOS [[ref](https://www.softwarecollections.org/en/scls/user/rhscl/?search=devtoolset&policy=&repo=&order_by=-create_date&per_page=10)]:
\verbatim
sudo yum install centos-release-scl
sudo yum install devtoolset-6
\endverbatim
- You can still build CaPTk from source using the instructions in [Technical Reference](Technical_Reference.html). Note that you will need a [C++11 compliant compiler](https://en.cppreference.com/w/cpp/compiler_support#cpp11).
\subsection gs_FAQ_5_3 CXXABI issues
If you are running into mis-matched `CXXABI` behavior with a message similar to:
\verbatim
libstdc++.so.6: version `CXXABI_1.3.8' not found (required by /lib/x86_64-linux-gnu/libGLU.so.1).
\endverbatim
This means that you are running on a very new Linux distribution. Please see the discussion in https://github.com/CBICA/CaPTk/issues/1229 for details.
\section gs_FAQ_6 Is there a minimum recommended screen resolution for running CaPTk?
The minimum recommended resolution is 1200x1024. We have seen some visualization issues with high DPI (>2K) screens and bug reports related to it will be appreciated.
\section gs_FAQ_7 Where can I find the CaPTk Docker Image?
You can find all the builds in our Docker Hub repository: https://hub.docker.com/r/cbica/captk
\section gs_FAQ_8 How do I run the CaPTk Docker Image to show the interface?
\verbatim
docker run -it \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v $(pwd)/test:/app \
-e DISPLAY=$DISPLAY \
-u qtuser \
cbica/captk
\endverbatim
\section gs_FAQ_9 Is there something wrong with Feature Extraction?
Please see the [Feature Extraction FAQ](https://github.com/sarthakpati/CaPTk/tree/featureExtraction/src/applications/FeatureExtraction#frequently-asked-questions).
\section gs_FAQ_10 I am having issues running CaPTk on Ubuntu 20.04
This is a well-known problem, documented in the following GitHub issues:
- https://github.com/CBICA/CaPTk/issues/1336
- https://github.com/AppImage/AppImageKit/issues/1076#issuecomment-702059005
A possible solution is to revert the default GCC to version 5 using the following steps [[ref](https://github.com/CBICA/CaPTk/issues/1336#issuecomment-769290424)]
\verbatim
echo "deb http://archive.ubuntu.com/ubuntu xenial main" | sudo tee /etc/apt/sources.list.d/xenial.list
sudo apt-get update
sudo update-alternatives --remove-all gcc
sudo update-alternatives --remove-all g++
sudo apt-get install gcc-5 g++-5
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-5 10
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-5 10
\endverbatim
\section gs_FAQ_10 What if I am having an issue not listed here?
Please [open a new issue](https://github.com/CBICA/CaPTk/issues/new?assignees=&labels=&template=bug-report.md&title=) with us and we will do our best to resolve it.
*/