Skip to content

Commit

Permalink
initial commit
Browse files Browse the repository at this point in the history
  • Loading branch information
@tengfeixue-victor
tengfeixue-victor committed Jul 20, 2023
1 parent a6fe776 commit 9898ce4
Show file tree
Hide file tree
Showing 3 changed files with 393 additions and 0 deletions.
104 changes: 104 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# Custom
*.idea
*.pdf
*.tar.gz
/ModelWeights
/results
/SegModels
/TestData
/TrainData_800clu800ol
/TrainedModel
/registered_tractography_parcellation_results
/parcellation_results

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
env/
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
*.egg-info/
.installed.cfg
*.egg

# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*,cover
.hypothesis/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
target/

# IPython Notebook
.ipynb_checkpoints

# pyenv
.python-version

# celery beat schedule file
celerybeat-schedule

# dotenv
.env

# virtualenv
venv/
ENV/

# Spyder project settings
.spyderproject

# Rope project settings
.ropeproject

*.pickle
198 changes: 198 additions & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
For more information, please see:

http://www.slicer.org

The 3D Slicer license below is a BSD style license, with extensions
to cover contributions and other issues specific to 3D Slicer.


3D Slicer Contribution and Software License Agreement ("Agreement")
Version 1.0 (December 20, 2005)

This Agreement covers contributions to and downloads from the 3D
Slicer project ("Slicer") maintained by The Brigham and Women's
Hospital, Inc. ("Brigham"). Part A of this Agreement applies to
contributions of software and/or data to Slicer (including making
revisions of or additions to code and/or data already in Slicer). Part
B of this Agreement applies to downloads of software and/or data from
Slicer. Part C of this Agreement applies to all transactions with
Slicer. If you distribute Software (as defined below) downloaded from
Slicer, all of the paragraphs of Part B of this Agreement must be
included with and apply to such Software.

Your contribution of software and/or data to Slicer (including prior
to the date of the first publication of this Agreement, each a
"Contribution") and/or downloading, copying, modifying, displaying,
distributing or use of any software and/or data from Slicer
(collectively, the "Software") constitutes acceptance of all of the
terms and conditions of this Agreement. If you do not agree to such
terms and conditions, you have no right to contribute your
Contribution, or to download, copy, modify, display, distribute or use
the Software.

PART A. CONTRIBUTION AGREEMENT - License to Brigham with Right to
Sublicense ("Contribution Agreement").

1. As used in this Contribution Agreement, "you" means the individual
contributing the Contribution to Slicer and the institution or
entity which employs or is otherwise affiliated with such
individual in connection with such Contribution.

2. This Contribution Agreement applies to all Contributions made to
Slicer, including without limitation Contributions made prior to
the date of first publication of this Agreement. If at any time you
make a Contribution to Slicer, you represent that (i) you are
legally authorized and entitled to make such Contribution and to
grant all licenses granted in this Contribution Agreement with
respect to such Contribution; (ii) if your Contribution includes
any patient data, all such data is de-identified in accordance with
U.S. confidentiality and security laws and requirements, including
but not limited to the Health Insurance Portability and
Accountability Act (HIPAA) and its regulations, and your disclosure
of such data for the purposes contemplated by this Agreement is
properly authorized and in compliance with all applicable laws and
regulations; and (iii) you have preserved in the Contribution all
applicable attributions, copyright notices and licenses for any
third party software or data included in the Contribution.

3. Except for the licenses granted in this Agreement, you reserve all
right, title and interest in your Contribution.

4. You hereby grant to Brigham, with the right to sublicense, a
perpetual, worldwide, non-exclusive, no charge, royalty-free,
irrevocable license to use, reproduce, make derivative works of,
display and distribute the Contribution. If your Contribution is
protected by patent, you hereby grant to Brigham, with the right to
sublicense, a perpetual, worldwide, non-exclusive, no-charge,
royalty-free, irrevocable license under your interest in patent
rights covering the Contribution, to make, have made, use, sell and
otherwise transfer your Contribution, alone or in combination with
any other code.

5. You acknowledge and agree that Brigham may incorporate your
Contribution into Slicer and may make Slicer available to members
of the public on an open source basis under terms substantially in
accordance with the Software License set forth in Part B of this
Agreement. You further acknowledge and agree that Brigham shall
have no liability arising in connection with claims resulting from
your breach of any of the terms of this Agreement.

6. YOU WARRANT THAT TO THE BEST OF YOUR KNOWLEDGE YOUR CONTRIBUTION
DOES NOT CONTAIN ANY CODE THAT REQURES OR PRESCRIBES AN "OPEN
SOURCE LICENSE" FOR DERIVATIVE WORKS (by way of non-limiting
example, the GNU General Public License or other so-called
"reciprocal" license that requires any derived work to be licensed
under the GNU General Public License or other "open source
license").

PART B. DOWNLOADING AGREEMENT - License from Brigham with Right to
Sublicense ("Software License").

1. As used in this Software License, "you" means the individual
downloading and/or using, reproducing, modifying, displaying and/or
distributing the Software and the institution or entity which
employs or is otherwise affiliated with such individual in
connection therewith. The Brigham and Women's Hospital,
Inc. ("Brigham") hereby grants you, with right to sublicense, with
respect to Brigham's rights in the software, and data, if any,
which is the subject of this Software License (collectively, the
"Software"), a royalty-free, non-exclusive license to use,
reproduce, make derivative works of, display and distribute the
Software, provided that:

(a) you accept and adhere to all of the terms and conditions of this
Software License;

(b) in connection with any copy of or sublicense of all or any portion
of the Software, all of the terms and conditions in this Software
License shall appear in and shall apply to such copy and such
sublicense, including without limitation all source and executable
forms and on any user documentation, prefaced with the following
words: "All or portions of this licensed product (such portions are
the "Software") have been obtained under license from The Brigham and
Women's Hospital, Inc. and are subject to the following terms and
conditions:"

(c) you preserve and maintain all applicable attributions, copyright
notices and licenses included in or applicable to the Software;

(d) modified versions of the Software must be clearly identified and
marked as such, and must not be misrepresented as being the original
Software; and

(e) you consider making, but are under no obligation to make, the
source code of any of your modifications to the Software freely
available to others on an open source basis.

2. The license granted in this Software License includes without
limitation the right to (i) incorporate the Software into
proprietary programs (subject to any restrictions applicable to
such programs), (ii) add your own copyright statement to your
modifications of the Software, and (iii) provide additional or
different license terms and conditions in your sublicenses of
modifications of the Software; provided that in each case your use,
reproduction or distribution of such modifications otherwise
complies with the conditions stated in this Software License.

3. This Software License does not grant any rights with respect to
third party software, except those rights that Brigham has been
authorized by a third party to grant to you, and accordingly you
are solely responsible for (i) obtaining any permissions from third
parties that you need to use, reproduce, make derivative works of,
display and distribute the Software, and (ii) informing your
sublicensees, including without limitation your end-users, of their
obligations to secure any such required permissions.

4. The Software has been designed for research purposes only and has
not been reviewed or approved by the Food and Drug Administration
or by any other agency. YOU ACKNOWLEDGE AND AGREE THAT CLINICAL
APPLICATIONS ARE NEITHER RECOMMENDED NOR ADVISED. Any
commercialization of the Software is at the sole risk of the party
or parties engaged in such commercialization. You further agree to
use, reproduce, make derivative works of, display and distribute
the Software in compliance with all applicable governmental laws,
regulations and orders, including without limitation those relating
to export and import control.

5. The Software is provided "AS IS" and neither Brigham nor any
contributor to the software (each a "Contributor") shall have any
obligation to provide maintenance, support, updates, enhancements
or modifications thereto. BRIGHAM AND ALL CONTRIBUTORS SPECIFICALLY
DISCLAIM ALL EXPRESS AND IMPLIED WARRANTIES OF ANY KIND INCLUDING,
BUT NOT LIMITED TO, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR
A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
BRIGHAM OR ANY CONTRIBUTOR BE LIABLE TO ANY PARTY FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY ARISING IN ANY WAY
RELATED TO THE SOFTWARE, EVEN IF BRIGHAM OR ANY CONTRIBUTOR HAS
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM
EXTENT NOT PROHIBITED BY LAW OR REGULATION, YOU FURTHER ASSUME ALL
LIABILITY FOR YOUR USE, REPRODUCTION, MAKING OF DERIVATIVE WORKS,
DISPLAY, LICENSE OR DISTRIBUTION OF THE SOFTWARE AND AGREE TO
INDEMNIFY AND HOLD HARMLESS BRIGHAM AND ALL CONTRIBUTORS FROM AND
AGAINST ANY AND ALL CLAIMS, SUITS, ACTIONS, DEMANDS AND JUDGMENTS
ARISING THEREFROM.

6. None of the names, logos or trademarks of Brigham or any of
Brigham's affiliates or any of the Contributors, or any funding
agency, may be used to endorse or promote products produced in
whole or in part by operation of the Software or derived from or
based on the Software without specific prior written permission
from the applicable party.

7. Any use, reproduction or distribution of the Software which is not
in accordance with this Software License shall automatically revoke
all rights granted to you under this Software License and render
Paragraphs 1 and 2 of this Software License null and void.

8. This Software License does not grant any rights in or to any
intellectual property owned by Brigham or any Contributor except
those rights expressly granted hereunder.

PART C. MISCELLANEOUS

This Agreement shall be governed by and construed in accordance with
the laws of The Commonwealth of Massachusetts without regard to
principles of conflicts of law. This Agreement shall supercede and
replace any license terms that you may have agreed to previously with
respect to Slicer.
91 changes: 91 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
## TractCloud

This repository releases the source code, training data, trained model, and testing samples for the work, "TractCloud: Registration-free tractography parcellation with a novel local-global streamline point cloud representation", which is accepted by MICCAI 2023.

![overview_v3](https://github.com/tengfeixue-victor/TractCloud-OpenSource/assets/56477109/1d41ef2c-367e-41dc-bfe2-6df955fc89d3)

## License

The contents of this repository are released under an [Slicer](LICENSE) license.

## Dependencies

The environment test was performed on RTX4090 and A5000

`conda create --name TractCloud python=3.8`

`conda activate TractCloud`

`conda install pytorch==1.12.1 torchvision==0.13.1 torchaudio==0.12.1 cudatoolkit=11.3 -c pytorch`

`conda install -c fvcore -c iopath -c conda-forge fvcore iopath`

`conda install -c bottler nvidiacub`

`pip install pytorch3d`

`pip install git+https://github.com/SlicerDMRI/whitematteranalysis.git`

`pip install h5py`

`pip install seaborn`

`pip install scikit-learn`

`pip install openpyxl`

## Training on anatomically curated atlas (ORG atlas)

The ORG atlas used in training is available at http://dmri.slicer.org/atlases/. You can directly download our processed data at https://github.com/SlicerDMRI/TractCloud/releases (1 million streamlines, 800 clusters & 800 outliers).
1. Download `TrainData_800clu800ol.zip` to `./` and `tar -xzvf TrainData_800clu800ol.zip`
2. Run `sh TrainOnAtlas.sh`

## Training on your custom dataset
Your input streamline features should have size of (number_streamlines, number_points_per_streamline, 3), and size of labels is (number_streamlines, ). You may save/load features and labels using .pickle files.

## Train/Validation/Test results and tips
The script calculates the accuracy and f1 on 42 anatomically meaningful tracts and one "Other" category (43 classes).

For training using the setting reported in our paper (k=20, k_global=500), most of CPU memory consumption comes from k. If you get out of CPU memory issue, you can try to reduce the value of k. Most of GPU memory consumption comes from k_global. If you get out of GPU memory issue, you can try to reduce the value of k_global.

## Testing on real data (registration-free parcellation)
Use the our trained model to parcellate real tractography data without registration.
1. Download `TrainedModel.zip` (https://github.com/SlicerDMRI/TractCloud/releases) to `./`, and `tar -xzvf TrainedModel.zip`
2. Download `TestData.zip` (https://github.com/SlicerDMRI/TractCloud/releases) to `./`, and `tar -xzvf TestData.zip`
3. Run `sh TractCloud.sh`

## Visualizing test parcellation results

Install 3D Slicer (https://www.slicer.org) and SlicerDMRI (http://dmri.slicer.org).

vtp/vtk files of 42 anatomically meaningful tracts are in `./parcellation_results/[test_data]/[subject_id]/SS/predictions`. "SS" means subject space.

You can visualize them using 3D Slicer.

**TOADD Photos for 4 example subjects.**

## References

**Please cite the following papers for using the code and/or the training data:**

Tengfei Xue, Yuqian Chen, Chaoyi Zhang, Alexandra J. Golby, Nikos Makris, Yogesh Rathi, Weidong Cai, Fan Zhang, Lauren J. O'Donnell
TractCloud: Registration-free Tractography Parcellation with a Novel Local-global Streamline Point Cloud Representation.
International Conference on Medical Image Computing and Computer Assisted Intervention (MICCAI) 2023.

Zhang, F., Wu, Y., Norton, I., Rathi, Y., Makris, N., O'Donnell, LJ.
An anatomically curated fiber clustering white matter atlas for consistent white matter tract parcellation across the lifespan.
NeuroImage, 2018 (179): 429-447

**For projects using Slicer and SlicerDMRI please also include the following text (or similar) and citations:**

* How to cite the [Slicer platform](http://wiki.slicer.org/slicerWiki/index.php/CitingSlicer)
* An example of how to cite SlicerDMRI (modify the first part of the sentence according to your use case):

"We performed diffusion MRI tractography and/or analysis and/or visualization in 3D Slicer (www.slicer.org) via the SlicerDMRI project (dmri.slicer.org) (Norton et al. 2017)."

Fan Zhang, Thomas Noh, Parikshit Juvekar, Sarah F Frisken, Laura Rigolo, Isaiah Norton, Tina Kapur, Sonia Pujol, William Wells III, Alex Yarmarkovich, Gordon Kindlmann, Demian Wassermann, Raul San Jose Estepar, Yogesh Rathi, Ron Kikinis, Hans J Johnson, Carl-Fredrik Westin, Steve Pieper, Alexandra J Golby, Lauren J O’Donnell.
SlicerDMRI: Diffusion MRI and Tractography Research Software for Brain Cancer Surgery Planning and Visualization.
JCO Clinical Cancer Informatics 4, e299-309, 2020.

Isaiah Norton, Walid Ibn Essayed, Fan Zhang, Sonia Pujol, Alex Yarmarkovich, Alexandra J. Golby, Gordon Kindlmann, Demian Wassermann, Raul San Jose Estepar, Yogesh Rathi, Steve Pieper, Ron Kikinis, Hans J. Johnson, Carl-Fredrik Westin and Lauren J. O'Donnell.
SlicerDMRI: Open Source Diffusion MRI Software for Brain Cancer Research. Cancer Research 77(21), e101-e103, 2017.

0 comments on commit 9898ce4

Please sign in to comment.