gemo-tractography 0.1.0__tar.gz

gemo_tractography-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amin Barati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gemo_tractography-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: gemo-tractography
+Version: 0.1.0
+Summary: Geometric & morphological deep learning classifier for tractography streamlines
+Author: Amin Barati
+License: MIT
+Project-URL: Homepage, https://github.com/amin-barati/GEMO
+Project-URL: Repository, https://github.com/amin-barati/GEMO
+Keywords: tractography,diffusion-mri,deep-learning,neuroimaging,streamlines
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy
+Requires-Dist: nibabel
+Requires-Dist: h5py
+Requires-Dist: tqdm
+Requires-Dist: scipy
+Requires-Dist: scikit-image
+Dynamic: license-file
+
+# **GEMO: A deep learning method for brain fiber classification and tract segmentation using geometrical and morphological features**
+
+PyTorch implementation of GEMO, a deep learning framework for white matter streamline classification and tract segmentation using convolutional neural networks together with handcrafted geometric and morphological features.
+
+**Overview**
+
+Diffusion-weighted magnetic resonance imaging (dMRI) is often used to study brain structure. One of the important applications made possible by dMRI is streamline tractography that is utilized for structural connectivity evaluation and neurosurgical planning. GEMO is a supervised deep learning framework for white matter streamline classification that combines convolutional neural network (CNN) features with handcrafted geometric and morphological descriptors to improve classification performance. This approach benefits from GEometrical and MOrphological features in addition to the features extracted from a convolutional neural network for improving the final classification performance. Streamlines are transformed from three-dimensional coordinate space into two-dimensional color-encoded images using the “xyz2RGB” mapping method and are subsequently fed into a convolutional neural network for learning and classification. This method performs the streamline classification from a whole brain tractogram, only focusing on each streamline’s features, which include those provided from CNN in addition to geometric and morphologic features.
+
+![alt text](Figures/Graphical_abstract.png)
+
+**Complete list of output classes in GEMO**
+
+- AF_L — Left Arcuate Fasciculus
+- AF_R — Right Arcuate Fasciculus
+- CC_Fr_1 — Corpus Callosum, Frontal Region 1
+- CC_Fr_2 — Corpus Callosum, Frontal Region 2
+- CC_Oc — Corpus Callosum, Occipital Region
+- CC_Pa — Corpus Callosum, Parietal Region
+- CC_Pr_Po — Corpus Callosum, Precentral/Postcentral Region
+- CG_L — Left Cingulum
+- CG_R — Right Cingulum
+- FAT_L — Left Frontal Aslant Tract
+- FAT_R — Right Frontal Aslant Tract
+- FPT_L — Left Frontopontine Tract
+- FPT_R — Right Frontopontine Tract
+- IFOF_L — Left Inferior Fronto-Occipital Fasciculus
+- IFOF_R — Right Inferior Fronto-Occipital Fasciculus
+- ILF_L — Left Inferior Longitudinal Fasciculus
+- ILF_R — Right Inferior Longitudinal Fasciculus
+- MCP — Middle Cerebellar Peduncle
+- MdLF_L — Left Middle Longitudinal Fasciculus
+- MdLF_R — Right Middle Longitudinal Fasciculus
+- POPT_L — Left Parieto-Occipital Pontine Tract
+- POPT_R — Right Parieto-Occipital Pontine Tract
+- PYT_L — Left Pyramidal (Corticospinal) Tract
+- PYT_R — Right Pyramidal (Corticospinal) Tract
+- SLF_L — Left Superior Longitudinal Fasciculus
+- SLF_R — Right Superior Longitudinal Fasciculus
+- UF_L — Left Uncinate Fasciculus
+- UF_R — Right Uncinate Fasciculus
+- OR_ML_L — Left Optic Radiation (Meyer's Loop)
+- OR_ML_R — Right Optic Radiation (Meyer's Loop)
+
+    
+ 
+# Installation
+
+Install directly from GitHub:
+
+```bash
+pip install git+https://github.com/amin-barati/GEMO.git
+```
+
+This requires `git` to be available on your machine.
+
+# Usage: classify a tractogram
+
+```bash
+gemo-infer --trk-path wholebrain.trk --output-dir classified_output
+```
+
+By default this uses the checkpoint and label map bundled with the package
+(`gemo/checkpoints/best.pt`, `gemo/checkpoints/label_map.json`). To use a
+different, custom-trained model instead:
+
+```bash
+gemo-infer --trk-path wholebrain.trk \
+    --checkpoint /path/to/best.pt \
+    --label-map /path/to/label_map.json \
+    --output-dir classified_output \
+    --threshold 0.70
+```
+
+This writes one `.trk` file per predicted tract class, plus one
+`_Unknown.trk` file for streamlines whose top softmax probability falls
+below `--threshold`.
+
+
+# xyz2RGB
+
+The `xyz2RGB` module converts each streamline of a tractogram into a RGB image by mapping the normalized x, y, and z coordinates to the red, green, and blue color channels, respectively. These images provide a compact representation of streamline geometry and serve as the input to the convolutional neural network (CNN) used in GEMO. The following example converts all streamlines contained in a single `.trk` file into RGB images.
+
+![image_xyz2RGB](Figures/xyz2RGB.png)
+
+
+**Generate RGB images from a single tractogram**
+
+An example of how `xyz2RGB` maps each streamline to an RGB image is provided in the following code.
+
+```python
+from xyz2RGB_test import trk_to_images
+
+images = trk_to_images("Sample_Tract.trk", output_dir="output_images")
+```
+
+**TCK to TRK Conversion**
+
+If your tractogram files are in `.tck` format, convert them to `.trk` format before starting training or inference. The `tck_to_trk.py` utility supports both individual files and entire directories.
+
+Convert a single `.tck` file:
+```bash
+python tck_to_trk.py --input AF_left.tck --output AF_left.trk
+```
+
+Convert all .tck files in a directory:
+
+```bash
+python tck_to_trk.py --input "TCK_directory" --output "TRK_directory"
+```
+
+# Training on your own data
+
+ After generating the RGB images and extracting the handcrafted features, the model can be trained using the provided training script. During training, the RGB images are processed by a CNN, the handcrafted features are encoded using a multilayer perceptron (MLP), and the learned representations are fused to classify each streamline into its corresponding white matter tract. The command below starts the complete training pipeline.
+
+
+# Requirements
+    python==3.12
+    numpy==2.2.6
+    scipy==1.16.0
+    torch==2.8.0
+    torchvision==0.23.0
+    nibabel==5.3.2
+    h5py==3.14.0
+    tqdm==4.67.1
+    scikit-learn==1.7.1
+    matplotlib==3.10.5
+
+```bash
+pip install -r requirements.txt
+```
+
+    GEMO/
+    ├── train.py
+    ├── streamline_model.py
+    ├── dataset.py
+    ├── streamline_features.py
+    ├── xyz2RGB.py
+    ├── utils.py
+    ├── config.py    
+    ├── inference.py    
+    ├── requirements.txt
+    ├── TRK_directory/
+    │   ├── Tract_01.trk
+    │   ├── ...
+    │   └── Tract_999.trk
+    ├── bounds.h5
+    └── features.h5
+
+## 1. Precompute subject bounds
+
+ ```python
+ from streamline_features import compute_and_save_bounds_metadata
+ compute_and_save_bounds_metadata("TRK_directory", "bounds.h5")
+ ```
+
+
+
+## 2. Extract handcrafted features
+
+**Extract geometric and morphological features**
+
+GEMO utilizes several handcrafted geometric and morphological descriptors for each streamline, including length, curvature, tortuosity, spectral entropy, fractal dimension, and lacunarity. These features are computed once and stored in an HDF5 (`.h5`) file, allowing efficient loading during training without repeated feature computation.
+
+ ```python
+from streamline_features import extract_features_from_directory
+extract_features_from_directory("TRK_directory", "features.h5", bounds_h5_path="bounds.h5")
+ ```
+## 3. Train model
+
+ ```bash
+ python train.py --trk-dir TRK_directory --features-h5 features.h5 --bounds-h5 bounds.h5
+ ```
+## 4. Inference
+
+```bash
+python inference.py --trk-path wholebrain.trk --checkpoint checkpoints/best.pt --label-map checkpoints/label_map.json --output-dir classified_output --threshold 0.70
+```
+
+# Citation
+GEMO is the code for the following paper; if you use this repository in your research, please cite:
+
+    GEMO: A deep learning method for brain fiber classification and tract segmentation using geometrical and morphological features
+    
+    Journal: Academic Radiology
+    
+    DOI:https://doi.org/10.1016/j.acra.2026.07.024

gemo_tractography-0.1.0/README.md

@@ -0,0 +1,186 @@
+# **GEMO: A deep learning method for brain fiber classification and tract segmentation using geometrical and morphological features**
+
+PyTorch implementation of GEMO, a deep learning framework for white matter streamline classification and tract segmentation using convolutional neural networks together with handcrafted geometric and morphological features.
+
+**Overview**
+
+Diffusion-weighted magnetic resonance imaging (dMRI) is often used to study brain structure. One of the important applications made possible by dMRI is streamline tractography that is utilized for structural connectivity evaluation and neurosurgical planning. GEMO is a supervised deep learning framework for white matter streamline classification that combines convolutional neural network (CNN) features with handcrafted geometric and morphological descriptors to improve classification performance. This approach benefits from GEometrical and MOrphological features in addition to the features extracted from a convolutional neural network for improving the final classification performance. Streamlines are transformed from three-dimensional coordinate space into two-dimensional color-encoded images using the “xyz2RGB” mapping method and are subsequently fed into a convolutional neural network for learning and classification. This method performs the streamline classification from a whole brain tractogram, only focusing on each streamline’s features, which include those provided from CNN in addition to geometric and morphologic features.
+
+![alt text](Figures/Graphical_abstract.png)
+
+**Complete list of output classes in GEMO**
+
+- AF_L — Left Arcuate Fasciculus
+- AF_R — Right Arcuate Fasciculus
+- CC_Fr_1 — Corpus Callosum, Frontal Region 1
+- CC_Fr_2 — Corpus Callosum, Frontal Region 2
+- CC_Oc — Corpus Callosum, Occipital Region
+- CC_Pa — Corpus Callosum, Parietal Region
+- CC_Pr_Po — Corpus Callosum, Precentral/Postcentral Region
+- CG_L — Left Cingulum
+- CG_R — Right Cingulum
+- FAT_L — Left Frontal Aslant Tract
+- FAT_R — Right Frontal Aslant Tract
+- FPT_L — Left Frontopontine Tract
+- FPT_R — Right Frontopontine Tract
+- IFOF_L — Left Inferior Fronto-Occipital Fasciculus
+- IFOF_R — Right Inferior Fronto-Occipital Fasciculus
+- ILF_L — Left Inferior Longitudinal Fasciculus
+- ILF_R — Right Inferior Longitudinal Fasciculus
+- MCP — Middle Cerebellar Peduncle
+- MdLF_L — Left Middle Longitudinal Fasciculus
+- MdLF_R — Right Middle Longitudinal Fasciculus
+- POPT_L — Left Parieto-Occipital Pontine Tract
+- POPT_R — Right Parieto-Occipital Pontine Tract
+- PYT_L — Left Pyramidal (Corticospinal) Tract
+- PYT_R — Right Pyramidal (Corticospinal) Tract
+- SLF_L — Left Superior Longitudinal Fasciculus
+- SLF_R — Right Superior Longitudinal Fasciculus
+- UF_L — Left Uncinate Fasciculus
+- UF_R — Right Uncinate Fasciculus
+- OR_ML_L — Left Optic Radiation (Meyer's Loop)
+- OR_ML_R — Right Optic Radiation (Meyer's Loop)
+
+    
+ 
+# Installation
+
+Install directly from GitHub:
+
+```bash
+pip install git+https://github.com/amin-barati/GEMO.git
+```
+
+This requires `git` to be available on your machine.
+
+# Usage: classify a tractogram
+
+```bash
+gemo-infer --trk-path wholebrain.trk --output-dir classified_output
+```
+
+By default this uses the checkpoint and label map bundled with the package
+(`gemo/checkpoints/best.pt`, `gemo/checkpoints/label_map.json`). To use a
+different, custom-trained model instead:
+
+```bash
+gemo-infer --trk-path wholebrain.trk \
+    --checkpoint /path/to/best.pt \
+    --label-map /path/to/label_map.json \
+    --output-dir classified_output \
+    --threshold 0.70
+```
+
+This writes one `.trk` file per predicted tract class, plus one
+`_Unknown.trk` file for streamlines whose top softmax probability falls
+below `--threshold`.
+
+
+# xyz2RGB
+
+The `xyz2RGB` module converts each streamline of a tractogram into a RGB image by mapping the normalized x, y, and z coordinates to the red, green, and blue color channels, respectively. These images provide a compact representation of streamline geometry and serve as the input to the convolutional neural network (CNN) used in GEMO. The following example converts all streamlines contained in a single `.trk` file into RGB images.
+
+![image_xyz2RGB](Figures/xyz2RGB.png)
+
+
+**Generate RGB images from a single tractogram**
+
+An example of how `xyz2RGB` maps each streamline to an RGB image is provided in the following code.
+
+```python
+from xyz2RGB_test import trk_to_images
+
+images = trk_to_images("Sample_Tract.trk", output_dir="output_images")
+```
+
+**TCK to TRK Conversion**
+
+If your tractogram files are in `.tck` format, convert them to `.trk` format before starting training or inference. The `tck_to_trk.py` utility supports both individual files and entire directories.
+
+Convert a single `.tck` file:
+```bash
+python tck_to_trk.py --input AF_left.tck --output AF_left.trk
+```
+
+Convert all .tck files in a directory:
+
+```bash
+python tck_to_trk.py --input "TCK_directory" --output "TRK_directory"
+```
+
+# Training on your own data
+
+ After generating the RGB images and extracting the handcrafted features, the model can be trained using the provided training script. During training, the RGB images are processed by a CNN, the handcrafted features are encoded using a multilayer perceptron (MLP), and the learned representations are fused to classify each streamline into its corresponding white matter tract. The command below starts the complete training pipeline.
+
+
+# Requirements
+    python==3.12
+    numpy==2.2.6
+    scipy==1.16.0
+    torch==2.8.0
+    torchvision==0.23.0
+    nibabel==5.3.2
+    h5py==3.14.0
+    tqdm==4.67.1
+    scikit-learn==1.7.1
+    matplotlib==3.10.5
+
+```bash
+pip install -r requirements.txt
+```
+
+    GEMO/
+    ├── train.py
+    ├── streamline_model.py
+    ├── dataset.py
+    ├── streamline_features.py
+    ├── xyz2RGB.py
+    ├── utils.py
+    ├── config.py    
+    ├── inference.py    
+    ├── requirements.txt
+    ├── TRK_directory/
+    │   ├── Tract_01.trk
+    │   ├── ...
+    │   └── Tract_999.trk
+    ├── bounds.h5
+    └── features.h5
+
+## 1. Precompute subject bounds
+
+ ```python
+ from streamline_features import compute_and_save_bounds_metadata
+ compute_and_save_bounds_metadata("TRK_directory", "bounds.h5")
+ ```
+
+
+
+## 2. Extract handcrafted features
+
+**Extract geometric and morphological features**
+
+GEMO utilizes several handcrafted geometric and morphological descriptors for each streamline, including length, curvature, tortuosity, spectral entropy, fractal dimension, and lacunarity. These features are computed once and stored in an HDF5 (`.h5`) file, allowing efficient loading during training without repeated feature computation.
+
+ ```python
+from streamline_features import extract_features_from_directory
+extract_features_from_directory("TRK_directory", "features.h5", bounds_h5_path="bounds.h5")
+ ```
+## 3. Train model
+
+ ```bash
+ python train.py --trk-dir TRK_directory --features-h5 features.h5 --bounds-h5 bounds.h5
+ ```
+## 4. Inference
+
+```bash
+python inference.py --trk-path wholebrain.trk --checkpoint checkpoints/best.pt --label-map checkpoints/label_map.json --output-dir classified_output --threshold 0.70
+```
+
+# Citation
+GEMO is the code for the following paper; if you use this repository in your research, please cite:
+
+    GEMO: A deep learning method for brain fiber classification and tract segmentation using geometrical and morphological features
+    
+    Journal: Academic Radiology
+    
+    DOI:https://doi.org/10.1016/j.acra.2026.07.024

gemo_tractography-0.1.0/gemo/__init__.py

@@ -0,0 +1,69 @@
+"""
+==============================================================================
+GEMO: A Deep Learning Method for Brain Fiber Classification and Tract
+Segmentation Using Geometrical and Morphological Features
+
+DOI:        https://doi.org/10.1016/j.acra.2026.07.024
+
+Email       : Amin_br@yahoo.com
+GitHub      : https://github.com/amin-barati/GEMO
+
+==============================================================================
+
+
+Command-line tools
+------------------------------------------------------
+    gemo-train   Train a StreamlineClassifier on a directory of .trk files.
+    gemo-infer   Classify a whole-brain .trk file with a trained checkpoint
+
+
+Python API
+----------
+>>> from gemo import StreamlineClassifier, classify_tractogram
+>>> model = StreamlineClassifier(num_handcrafted_features=6, num_classes=30)
+"""
+
+from .streamline_model import (
+    StreamlineClassifier,
+    CNNFeatureExtractor,
+    HandcraftedFeatureEncoder,
+    FeatureFusion,
+    ClassificationHead,
+    StreamlineDataset,
+    build_label_mapping,
+    classify_tractogram,
+    count_trainable_parameters,
+)
+from .xyz2RGB import (
+    streamline_to_rgb,
+    load_bounds_metadata_h5,
+    save_bounds_metadata_h5,
+    group_trk_files_by_subject,
+)
+from .streamline_features import (
+    extract_features_from_directory,
+    compute_and_save_bounds_metadata,
+)
+from .config import Config
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "StreamlineClassifier",
+    "CNNFeatureExtractor",
+    "HandcraftedFeatureEncoder",
+    "FeatureFusion",
+    "ClassificationHead",
+    "StreamlineDataset",
+    "build_label_mapping",
+    "classify_tractogram",
+    "count_trainable_parameters",
+    "streamline_to_rgb",
+    "load_bounds_metadata_h5",
+    "save_bounds_metadata_h5",
+    "group_trk_files_by_subject",
+    "extract_features_from_directory",
+    "compute_and_save_bounds_metadata",
+    "Config",
+    "__version__",
+]

gemo_tractography-0.1.0/gemo/checkpoints/label_map.json

@@ -0,0 +1,32 @@
+{
+  "AF_L": 0,
+  "AF_R": 1,
+  "CC_Fr_1": 2,
+  "CC_Fr_2": 3,
+  "CC_Oc": 4,
+  "CC_Pa": 5,
+  "CC_Pr_Po": 6,
+  "CG_L": 7,
+  "CG_R": 8,
+  "FAT_L": 9,
+  "FAT_R": 10,
+  "FPT_L": 11,
+  "FPT_R": 12,
+  "IFOF_L": 13,
+  "IFOF_R": 14,
+  "ILF_L": 15,
+  "ILF_R": 16,
+  "MCP": 17,
+  "MdLF_L": 18,
+  "MdLF_R": 19,
+  "OR_ML_L": 20,
+  "OR_ML_R": 21,
+  "POPT_L": 22,
+  "POPT_R": 23,
+  "PYT_L": 24,
+  "PYT_R": 25,
+  "SLF_L": 26,
+  "SLF_R": 27,
+  "UF_L": 28,
+  "UF_R": 29
+}

gemo_tractography-0.1.0/gemo/config.py

@@ -0,0 +1,87 @@
+"""
+config
+======
+
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, Tuple
+
+
+@dataclass
+class DataConfig:
+    trk_dir: str = "trk_dir"
+    features_h5_path: str = "features.h5"
+    bounds_h5_path: str = "bounds.h5"
+    separator: str = "__"
+    index_width: int = 7
+    grid_size: int = 64
+    scales: Tuple[int, ...] = (1, 2, 4, 8, 16)
+    feature_names: Tuple[str, ...] = (
+        "length",
+        "curvature",
+        "tortuosity",
+        "spectral_entropy",
+        "fractal_dimension",
+        "lacunarity",
+    )
+    truncate: bool = True
+
+    shuffle_buffer_size: int = 2000
+
+    max_streamlines_per_class_per_epoch: Optional[int] = 100_000
+    val_fraction: float = 0.2
+    split_seed: int = 42
+
+
+@dataclass
+class ModelConfig:
+    num_handcrafted_features: int = 6
+    num_classes: int = 30
+    cnn_base_channels: int = 32
+    cnn_embedding_dim: int = 128
+    feature_hidden_dims: Tuple[int, ...] = (32, 64)
+    feature_embedding_dim: int = 64
+    classifier_hidden_dims: Tuple[int, ...] = (256, 128)
+    dropout: float = 0.2
+    fusion_mode: str = "concat"
+
+
+@dataclass
+class TrainConfig:
+    batch_size: int = 256
+    num_workers: int = 4
+    num_epochs: int = 100
+    learning_rate: float = 1e-4
+    weight_decay: float = 5e-4
+    lr_step_size: int = 10
+    lr_gamma: float = 0.5
+    grad_clip_norm: float = 5.0
+    device: str = "auto"  
+    checkpoint_dir: str = "checkpoints"
+    log_every_n_steps: int = 50
+    val_every_n_epochs: int = 1
+
+    class_weight_scheme: str = "inverse_sqrt"
+    seed: int = 0
+
+
+@dataclass
+class InferenceConfig:
+    threshold: float = 0.7
+    batch_size: int = 256
+    device: str = "auto"
+    output_dir: str = "classified_output"
+
+
+@dataclass
+class Config:
+    data: DataConfig = field(default_factory=DataConfig)
+    model: ModelConfig = field(default_factory=ModelConfig)
+    train: TrainConfig = field(default_factory=TrainConfig)
+    inference: InferenceConfig = field(default_factory=InferenceConfig)
+
+
+__all__ = ["DataConfig", "ModelConfig", "TrainConfig", "InferenceConfig", "Config"]