Tractome

Tractome (http://tractome.org) is an interactive clustering-based 3D tool for exploration and segmentation of tractography data.

Tractome is an interactive tool for visualisation, exploration and segmentation of tractography data. It supports neuroanatomists and medical doctors in their study of white matter anatomical structures from diffusion magnetic resonance imaging (dMRI) data. Unlike previous systems for tractography segmentation, Tractome is a computer-assisted tool in which the user interacts with a summary of the tractography instead of the whole set of streamlines. The summary is generated by clustering the tractography into a desired number of clusters, usually in the order of tens or one hundred. The summary shows only one representative streamline for each cluster, so that it is easier to interact with them in the 3D scene. The user can then iteratively select the representative streamlines of interest and re-cluster the associated sets or streamlines into smaller ones in order to incrementally reveal details of the anatomical structure of interest. The interaction is powered by novel efficient algorithms for fast clustering. Tractome is written in Python language and it supports the TrackVis format and the DiPy format for tractography files.

Dev Installation

To install the tractome from the source, we need to install the dependencies. Execute the following command in the project root directory.

pip install -r requirements.txt

Once, we gather the dependencies we can install the tractome locally. (Required: If you want to use the CLI).

pip install -e .

To run the tractome

tractome 

The three-dot More menus in IMAGE, MESH, PARCELS, ROI, and Track View show their supplied action icons even when the platform normally hides menu icons. Icons and labels have a consistent left gutter inside the selection highlight; iconless actions remain aligned with the other labels. The ROI constraint-status line omits the icon-column indentation.

Parcel point clouds

Use tractome --parcel <file.csv-or-ply> or the PARCELS upload button. PLY parcels show individual colored vertex spheres; faces are ignored. CSV accepts comma-separated rows and existing whitespace-separated numeric rows, with an optional x,y,z header (case-insensitive). Column layouts:

• x,y,z: white points.
• x,y,z,scalar: white points with probabilities in [0,1].
• x,y,z,r,g,b,scalar: RGB colors and probabilities.
• x,y,z,HEX,scalar: HEX colors and probabilities.
• x,y,z,r,g,b: RGB colors in [0,255].
• x,y,z,HEX: HEX colors.

Seven columns always mean RGB plus probability, never RGBA, regardless of header labels. HEX colors in comma-separated CSV contain exactly six hex digits, optionally prefixed by #; quoted fields and surrounding whitespace are accepted. Full-line and trailing # comments are supported without discarding HEX prefixes.

In four-column files, a fourth header label of HEX selects color; any other label (such as value, probability, scalar, or float) selects probability. Without a header, a numeric fourth field selects probability: 000001 means probability 1. Use #000001 or a HEX header for RGB [0,0,1]. Five-column files unambiguously contain HEX plus probability.

PLY vertex properties red, green, and blue provide RGB colors. probability (or, if absent, value) supplies probabilities independently of those colors. No other scalar property is interpreted as a probability. Nonfinite coordinates/colors/probabilities, RGB outside [0,255], and probabilities outside [0,1] are rejected. A CSV directory loads immediate .csv children in sorted order; nonempty files must have matching optional attributes. RGB and HEX files can be combined when probability presence matches.

The Minimum probability slider appears only for probability-bearing parcels. It keeps points whose probability is at least the selected fraction, including equality, without rebuilding the point cloud or moving the camera. The threshold is remembered across selections; RGB-only parcels ignore it. The existing Opacity control adjusts point size, and the eye controls visibility. Size and uniform Colour changes preserve the probability filter; recoloring also retains point positions, size, and hidden/shown state.

To visualize cluster representation

You are required to pre-compute the embeddings of the streamlines, use the following command to save a new .trx file with embedding. Later you can provide this newly saved file to open the tractogram in the above command.

tractome_compute_dis_matrix <file_path>

For getting a complete list and details of the options available.

tractome_compute_dis_matrix --help

Binary Packaging

Tractome uses Briefcase to create platform-native application bundles and installers. Briefcase bundles a Python runtime and the runtime dependencies declared in pyproject.toml under [tool.briefcase.app.tractome].

Use Python 3.12 for packaging:

python -m pip install briefcase
briefcase dev
briefcase create
briefcase build
briefcase package

Run the packaging commands on each target operating system. Briefcase uses the current platform to create the matching installer format.

Contribution

Contributions are welcome. To contribute, please:

1. Create a feature branch from master.
2. Install development dependencies with:

   pip install -r requirements/dev.txt
   

3. Run formatting and checks before opening a pull request.
4. Open a pull request with a clear description of the change.