<commit_before># External C++ tools

This is a collection of additional tools that might be helpful during a tractogram evaluation with the COMMIT framework. At the moment, the following tool(s) are availablae:

- [COMMIT_debugger](#commit_debugger)

# How to compile the code

## Install dependencies

You will still need to install the following libraries:

- [CMake](http://www.cmake.org/) to allow cross-platform compilation;
- [Niftilib](https://sourceforge.net/projects/niftilib/) for reading/writing NIFTI files;
- [Blitz++](http://sourceforge.net/projects/blitz/) for efficiently manipulating multi-dimensional arrays;
- [OpenGL](https://www.opengl.org/) and [GLUT](https://www.opengl.org/resources/libraries/glut/) for 3D visualization.

Please follow the corresponding documentation to install these libraries on your platform. Our code was successfully tested on Linux (Ubuntu 14.04) and OSX (10.9 up to 10.15) systems.

### OSX with homebrew

If your're using [homebrew](https://brew.sh), then the following should do:

```bash
brew tap brewsci/science
brew install cmake
brew install blitz
brew install niftilib
```

The `OpenGL` and `GLUT` libraries are already provided by the operating system.

##  Compile, build and install

Open the terminal and type:

```bash
cd extras
mkdir build
cd build
ccmake ..
```

Hit `c` (twice) and then `g`. This will create the required makefiles for the compilation.
Once back to the terminal, type:

```bash
make
make install
```

This will install the binaries into the `/usr/local/bin` folder. This installation path can be changed by rerunning `ccmake ..` and then modifying the `CMAKE_INSTALL_PREFIX` parameter to suits your custom needs.


#  List of tools

## COMMIT_debugger

This tool allows one to display, in a common 3D world, all ingredients considered in the COMMIT framework:

- DWI data (4D NIFTI file)
- its acquisition scheme (Camino format)
- voxelwise main diffusion orientations (4D NIFTI file)
- tractogram (TrackVis format).

**NB**: please note that this tool is very rudimental and is released only for debugging purposes.

![Application screenshot](https://github.com/daducci/COMMIT/
ob/master/doc/COMMIT_debugger.jpg)

### Synopsis

```bash
COMMIT_debugger \
    <dwi> \
    <scheme> \
    <peaks> \
    [-f <tracts>] \
    [-m <map>]
```

- `dwi`, `scheme`: DWI data and corresponding scheme file. Only the signal from the outer shell is plotted.
- `peaks`: directions to be interpreted as the major directions of the *hindered* water pools in each voxel.
- `tracts`: tractogram to generate the *restricted* contributions of the tracts in each voxel.
- `map`: background map; default is the average b0 computed from the data.

### Shortcuts

- `left`, `right`, `up`, `down`, `page-up`, `page-down`: move voxel position

- `1`, `2`, `3`: show/hide the x-, y-, z-plane, respectively. All plotting is performed on these planes.
- `o`, `O`: decrease/increase the opacity of the three planes
- `m`, `M`: decrease/increase the maximum intensity in the image
- `r`: reset the view to its inital settings

- `s`: show/hide the DWI signal
- `S`: change shell to display
- `X`, `Y`, `Z`: flip the signal glyphs along each axis
- `b`, `B`: change the portion of voxels where to plot the glyphs

- `p`: show/hide the peaks
- `a`: do/don't use the affine transformation
- `x`, `y`, `z`: flip the peaks along each axis
- `t`, `T`: decrease/increase the peaks threshold
- `n`: normalize the length of the peaks
- `w`, `W`: decrease/increase the line-width of the peaks/glyphs

- `k`, `K`: decrease/increase the threshold for coloring the peaks depending on their norm (range is hard-coded to 0-20). If k=0, then the peaks are colored depending on their directions as usual.
- `l`: change the colormap (lut) for the peaks

- `f`: show/hide the tracts
- `c`, `C`: decrease/increase the slab region in which plotting the fibers
- `space`: alternate between "crop fibers to slab around the planes" and "crop fibers in the current voxel (yellow)"
- `ALT` + `left`, `right`, `up`, `down`, `page-up`, `page-down`: apply a shift to streamlines coordinates
<commit_msg>Updated documentation<commit_after># External C++ tools

This is a collection of additional tools that might be helpful during a tractogram evaluation with the COMMIT framework. At the moment, the following tool(s) are availablae:

- [COMMIT_debugger](#commit_debugger)

# How to compile the code

## Install dependencies

You will still need to install the following libraries:

- [CMake](http://www.cmake.org/) to allow cross-platform compilation;
- [Niftilib](https://sourceforge.net/projects/niftilib/) for reading/writing NIFTI files;
- [Blitz++](http://sourceforge.net/projects/blitz/) for efficiently manipulating multi-dimensional arrays;
- [OpenGL](https://www.opengl.org/) and [GLUT](https://www.opengl.org/resources/libraries/glut/) for 3D visualization.

Please follow the corresponding documentation to install these libraries on your platform. Our code was successfully tested on Linux (Ubuntu 14.04) and OSX (10.9 up to 10.15) systems.

### OSX with homebrew

If your're using [homebrew](https://brew.sh), then the following should do:

```bash
brew tap brewsci/science
brew install cmake
brew install blitz
brew install niftilib
```

The `OpenGL` and `GLUT` libraries are already provided by the operating system.

##  Compile, build and install

Open the terminal and type:

```bash
cd extras
mkdir build
cd build
ccmake ..
```

Hit `c` (twice) and then `g`. This will create the required makefiles for the compilation.
Once back to the terminal, type:

```bash
make
make install
```

This will install the binaries into the `/usr/local/bin` folder. This installation path can be changed by rerunning `ccmake ..` and then modifying the `CMAKE_INSTALL_PREFIX` parameter to suits your custom needs.


#  List of tools

## COMMIT_debugger

This tool allows one to display, in a common 3D world, all ingredients considered in the COMMIT framework:

- DWI data (4D NIFTI file)
- its acquisition scheme (Camino format)
- voxelwise main diffusion orientations (4D NIFTI file)
- tractogram (TrackVis format).

**NB**: please note that this tool is very rudimental and is released only for debugging purposes.

![Application screenshot](https://github.com/daducci/COMMIT/
ob/master/doc/COMMIT_debugger.jpg)

### Synopsis

```bash
COMMIT_debugger \
    <dwi> \
    <scheme> \
    <peaks> \
    [-f <tracts>] \
    [-m <map>]
```

- `dwi`, `scheme`: DWI data and corresponding scheme file. Only the signal from the outer shell is plotted.
- `peaks`: directions to be interpreted as the major directions of the *hindered* water pools in each voxel.
- `tracts`: tractogram to generate the *restricted* contributions of the tracts in each voxel.
- `map`: background map; default is the average b0 computed from the data.

A **dropdown menu** will appear with right-click of the mouse.
{'fraction_non_alphanumeric': 0.10665701881331403, 'fraction_numerical': 0.005643994211287988, 'mean_word_length': 4.243550834597875, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 10, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6559676', 'n_tokens_mistral': 2164, 'n_tokens_neox': 1979, 'n_words': 892}