Merge pull request #227 from KMarshallX/pre-release-2.0

Update docs

Author: KMarshallX

.github/workflows/test_boost.yml

@@ -9,6 +9,7 @@ on:
       - config/boost_config.py
       - environment.yml
       - documentation/boost_readme.md
+      - documentation/UPDATE.md
       - library/aug_utils.py
       - library/data_loaders.py
       - library/eval_utils.py
@@ -27,12 +28,14 @@ on:
       - config/boost_config.py
       - environment.yml
       - documentation/boost_readme.md
+      - documentation/UPDATE.md
       - library/aug_utils.py
       - library/data_loaders.py
       - library/eval_utils.py
       - library/loss_func.py
       - library/module_utils.py
       - library/train_utils.py
+      - tests/test_boost_module.sh
       - miniconda-setup.sh
       - .github/workflows/test_boost.yml
 

.github/workflows/test_prediction.yml

@@ -8,6 +8,7 @@ on:
       - prediction.py
       - config/pred_config.py
       - environment.yml
+      - documentation/UPDATE.md
       - documentation/predict_readme.md
       - library/aug_utils.py
       - library/data_loaders.py
@@ -26,6 +27,7 @@ on:
       - prediction.py
       - config/pred_config.py
       - environment.yml
+      - documentation/UPDATE.md
       - documentation/predict_readme.md
       - library/aug_utils.py
       - library/data_loaders.py

.github/workflows/test_train.yml

@@ -8,6 +8,7 @@ on:
       - train.py
       - config/train_config.py
       - environment.yml
+      - documentation/UPDATE.md
       - documentation/train_readme.md
       - library/aug_utils.py
       - library/data_loaders.py
@@ -26,6 +27,7 @@ on:
       - train.py
       - config/train_config.py
       - environment.yml
+      - documentation/UPDATE.md
       - documentation/train_readme.md
       - library/aug_utils.py
       - library/data_loaders.py

.github/workflows/test_tta.yml

@@ -8,6 +8,7 @@ on:
       - test_time_adaptation.py
       - config/adapt_config.py
       - environment.yml
+      - documentation/UPDATE.md
       - documentation/tta_readme.md
       - library/aug_utils.py
       - library/data_loaders.py
@@ -26,6 +27,7 @@ on:
       - test_time_adaptation.py
       - config/adapt_config.py
       - environment.yml
+      - documentation/UPDATE.md
       - documentation/tta_readme.md
       - library/aug_utils.py
       - library/data_loaders.py

README.md

@@ -1,7 +1,8 @@
 # **VesselBoost**
-*VesselBoost* is a Python-based software package utilizing deep learning techniques to segment high-resolution time-of-flight MRI angiography data, with high sensitivity towards small vessels. The software suite encompasses three essential functional modules: (1) *predict*, (2) *test-time adaptation* (TTA), and (3) *boost*. By leveraging these modules, users can efficiently segment high-resolution time-of-flight data or conveniently leverage our command line interface to boost segmentations for other vascular MRI image contrasts.
+*VesselBoost* is a Python-based software package utilizing deep learning techniques to segment high-resolution time-of-flight MRI angiography data, with high sensitivity towards small vessels (An experimental pretrained model is available for T2*-weighted imaging). The software suite encompasses three essential functional modules: (1) *predict*, (2) *test-time adaptation* (TTA), and (3) *boost*. By leveraging these modules, users can efficiently segment high-resolution time-of-flight data or conveniently leverage our command line interface to boost segmentations for other vascular MRI image contrasts.
 
 ## **Table of Contents**
+- [Update History](#update-history)
 - [Purpose](#purpose)
 - [Current Version](#current-version)
 - [Requirements](#requirements)
@@ -10,6 +11,10 @@
 - [Citation](#citation)
 - [Contact](#contact)
 
+## **Update History**
+- **1.0.0**: Initial release, for details see [Citation](#citation)
+- **2.0.0 - pre-release**: for details see [Update Log - 16/Sept/2025](documentation/UPDATE.md)
+
 ## **Purpose**
 *VesselBoost* is a Python-based software package leveraging a UNet3D-based segmentation pipeline that utilizes data augmentation and test-time adaptation (TTA) to enhance segmentation quality and is generally applicable to high-resolution magnetic resonance angiograms (MRAs).\
 This repository contains 3 major modules: 
@@ -24,7 +29,7 @@ This repository contains 3 major modules:
 
 
 ## **Current Version**
-VesselBoost 1.0.0
+VesselBoost 2.0.0
 
 ## **Requirements**
 - Docker / Singularity container
@@ -38,16 +43,16 @@ VesselBoost, pre-trained models, and required software are packaged in software
 The Dockerhub container is available at Dockerhub. To download the container, run the following command:
 
 ```
-docker pull vnmd/vesselboost_1.0.0
+docker pull vnmd/vesselboost_2.0.0
 ```
 
 ### Neurodesk 
 To predict vessel segmentation using your data and the latest version of VesselBoost on Neurodesk, you can run the following code snippet:
 
 ```bash
 ml vesselboost
-path_to_model=/cvmfs/neurodesk.ardc.edu.au/containers/vesselboost_1.0.0_20240815/vesselboost_1.0.0_20240815.simg/opt/VesselBoost/saved_models/
-prediction.py --ds_path /path/ --out_path /path/ --pretrained "$path_to_model"/manual_0429 --prep_mode 4
+path_to_model=/cvmfs/neurodesk.ardc.edu.au/containers/vesselboost_2.0.0_20250916/vesselboost_2.0.0_20250916.simg/opt/VesselBoost/saved_models/
+prediction.py --image_path /path/ --output_path /path/ --pretrained "$path_to_model"/BM_VB2_aug_all_ep2k_bat_10_0903 --prep_mode 4
 ```
 
 For more information, please check our [notebooks](https://github.com/KMarshallX/VesselBoost/tree/master/notebooks).
@@ -56,9 +61,16 @@ For more information, please check our [notebooks](https://github.com/KMarshallX
 This is a Python-based software package. To successfully run this project on your local machine, please follow the following steps to set up the necessary software environment.
 
 1. Clone this repository to your local machine
+    For latest version:
     ```
     git clone https://github.com/KMarshallX/VesselBoost.git
+
+    ```
+    To clone the previous version (VesselBoost 1.0.0):
     ```
+    git clone -b stable_ver_1_0_0_hpc --single-branch https://github.com/KMarshallX/VesselBoost.git
+    ```
+
 2. Install miniconda:
     ```
     cd VesselBoost

documentation/UPDATE.md

@@ -0,0 +1,8 @@
+### Update Log - 16/Sept/2025
+- Pre-release of VesselBoost 2.0.0
+- New data augmentation strategies during training (train, TTA and boost)
+- Changed image preprocessing step from standardization to normalization
+- Improved code structure and readability
+- Bugs fixes and performance improvements
+- Added support for T2*-weighted imaging (experimental)
+- TODO: add notebook & github action test for previous version (1.0.0) 

documentation/train_readme.md

@@ -1,4 +1,4 @@
-# **Initial Training Module**
+# **Training Module**
 You can use this module to train your own base model.
 ## **Create a base model from scratch**
 ### Prepare the training data

documentation/tta_readme.md

@@ -11,7 +11,7 @@ mkdir ./pretrained_models/
 Download the pre-trained model from osf:
 
 ```bash
-osf -p abk4p fetch /osfstorage/pretrained_models/manual_0429 ./pretrained_models/manual_0429
+osf -p abk4p fetch /osfstorage/pretrained_models/BM_VB2_aug_all_ep2k_bat_10_0903 ./pretrained_models/BM_VB2_aug_all_ep2k_bat_10_0903
 ```
 
 

requirements.txt

@@ -41,9 +41,12 @@ mkdir ./pretrained_models/
 pip install osfclient
 osf -p nr6gc fetch /osfstorage/twoEchoTOF/raw/GRE_3D_400um_TR20_FA18_TE7p5_14_sli52_FCY_GMP_BW200_32.nii ./data/images/sub-001.nii
 #pretrained model download
-osf -p abk4p fetch /osfstorage/pretrained_models/manual_0429 ./pretrained_models/manual_0429
-osf -p abk4p fetch /osfstorage/pretrained_models/omelette1_0429 ./pretrained_models/omelette1_0429
-osf -p abk4p fetch /osfstorage/pretrained_models/omelette2_0429 ./pretrained_models/omelette2_0429
+osf -p abk4p fetch /osfstorage/pretrained_models/BM_VB2_aug_all_ep2k_bat_10_0903 ./pretrained_models/BM_VB2_aug_all_ep2k_bat_10_0903
+osf -p abk4p fetch /osfstorage/pretrained_models/VB2_aug_off_ep2k_bat10_0903 ./pretrained_models/VB2_aug_off_ep2k_bat10_0903
+osf -p abk4p fetch /osfstorage/pretrained_models/VB2_aug_random_ep2k_bat10_0903 ./pretrained_models/VB2_aug_random_ep2k_bat10_0903
+osf -p abk4p fetch /osfstorage/pretrained_models/VB2_aug_intensity_ep2k_bat10_0903 ./pretrained_models/VB2_aug_intensity_ep2k_bat10_0903
+osf -p abk4p fetch /osfstorage/pretrained_models/VB2_aug_spatial_ep2k_bat10_0903 ./pretrained_models/VB2_aug_spatial_ep2k_bat10_0903
+
 
 
 path_to_images="./data/images/"
@@ -55,7 +58,7 @@ echo "Path to output: "$path_to_output""
 path_to_preprocessed_images="./data/preprocessed_imgs/"
 echo "Path to preprocessed images: "$path_to_preprocessed_images""
 
-path_to_pretrained_model="./pretrained_models/manual_0429"
+path_to_pretrained_model="./pretrained_models/BM_VB2_aug_all_ep2k_bat_10_0903"
 echo "Path to pretrained model: "$path_to_pretrained_model""
 
 echo "[DEBUG]: testing prediction module without preprocessing:"