.. _scil_fodf_bundleparc:

scil_fodf_bundleparc
====================

::

	usage: __main__.py [-h] [--out_prefix OUT_PREFIX] [--out_dir OUT_DIR]
	                   [--half_precision] [--bundles {} [{} ...]]
	                   [--checkpoint CHECKPOINT] [--volume_size VOLUME_SIZE]
	                   [--nb_pts NB_PTS | --mm MM | --continuous]
	                   [--min_blob_size MIN_BLOB_SIZE | --keep_biggest_blob] [-f]
	                   [-v [{DEBUG,INFO,WARNING,ERROR}]]
	                   in_fodf
	
	BundleParc: automatic tract labelling without tractography.
	
	This method takes as input fODF maps and outputs 71 bundle label maps. These maps can then be used to perform tractometry/tract profiling/radiomics. The bundle definitions follow TractSeg's minus the whole CC.
	
	**IMPORTANT**: fODF inputs are presumed to come from Tractoflow, must have stride of -1,2,3,4 and must be BET and cropped. fODFs must be in SH format, basis descoteaux07_legacy and can be of order < 8 but accuracy may be reduced.
	
	Model weights will be downloaded the first time the script is run, which will require an internet connection at runtime. Otherwise they can be manually downloaded from zenodo [1] and by specifying --checkpoint.
	
	Example usage:
	    $ scil_fodf_bundleparc fodf.nii.gz --out_prefix sub-001__
	
	Example output:
	    sub-001__AF_left.nii.gz, sub-001__AF_right.nii.gz, ..., sub-001__UF_right.nii.gz
	
	The output can be further processed with scil_bundle_mean_std to compute statistics for each bundle.
	
	The default value of 50 for --min_blob_size was found empirically on adult brains at a resolution of 1mm^3. The best value for your dataset may differ.
	
	This script requires a GPU with ~6GB of available memory. If you use half-precision (float16) inference, you may be able to run it with ~3GB of GPU memory available. Otherwise, install the CPU version of PyTorch. Execution on MacOS is not supported for now.
	
	Parts of the implementation are based on or lifted from:
	    SAM-Med3D: https://github.com/uni-medical/SAM-Med3D
	    Multidimensional Positional Encoding: https://github.com/tatp22/multidim-positional-encoding
	
	To cite: Antoine Théberge, Zineb El Yamani, François Rheault, Maxime Descoteaux, Pierre-Marc Jodoin (2025). LabelSeg. ISMRM Workshop on 40 Years of Diffusion: Past, Present & Future Perspectives, Kyoto, Japan.
	
	[1]: Descoteaux, M., Deriche, R., Knösche, T. R., & Anwander, A. (2007). Deterministic and probabilistic tractography based on complex fibre orientation distributions. IEEE Transactions on Medical Imaging, 26(11), 1464-1477.
	[2]: https://zenodo.org/records/15579498
	
	positional arguments:
	  in_fodf               Input fODF volume in nifti format. 
	
	options:
	  -h, --help            show this help message and exit
	  --out_prefix OUT_PREFIX
	                        Output file prefix. Default is nothing. 
	  --out_dir OUT_DIR     Output destination. Default is [bundleparc].
	  --half_precision      Use half precision (float16) for inference. This reduces memory usage but may lead to reduced accuracy.
	  --bundles {} [{} ...]
	                        Bundles to predict. Default is every bundle.
	  --checkpoint CHECKPOINT
	                        Checkpoint (.ckpt) containing hyperparameters and weights of model. Default is [/home/docs/.scilpy/checkpoints/bundleparc.ckpt]. If the file does not exist, it will be downloaded.
	  --volume_size VOLUME_SIZE
	                        Size of volume to resample to for inference. Only modify if you know what you are doing.
	  --nb_pts NB_PTS       Number of divisions per bundle. Default is [10].
	  --mm MM               If set, bundles will be split in sections roughly X mm wide.
	  --continuous          If set, the output label maps will be continuous ∈ [0, 1].
	  --min_blob_size MIN_BLOB_SIZE
	                        Minimum blob size (in voxels) to keep. Smaller blobs will be removed. Default is [50].
	  --keep_biggest_blob   Only keep the biggest blob predicted.
	  -f                    Force overwriting of the output files.
	  -v [{DEBUG,INFO,WARNING,ERROR}]
	                        Produces verbose output depending on the provided level. 
	                        Default level is warning, default when using -v is info.