Package: rivuletpy
RivuletpyExample Neuron TracingsExample Lung Airway TracingRivuletpy == Rivulet2Rivuletpy is a Python3 toolkit for automatically reconstructing single neuron models from 3D microscopic image stacks & other tree structures from 3D medical images.It is actively maintained and being used in industry scale image analysis applications.The project was initiated in theBigNeuron projectThertracecommand is powered by the Rivulet2 algorithm published in IEEE Trans. TMI:[1] S. Liu, D. Zhang, Y. Song, H. Peng and W. Cai, "Automated 3D Neuron Tracing with Precise Branch Erasing and Confidence Controlled Back-Tracking," in IEEE Transactions on Medical Imaging. URL:http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=8354803&isnumber=4359023PDF [https://www.biorxiv.org/content/biorxiv/early/2017/11/27/109892.full.pdf]The predecessor Rivulet1 was published on Neuroinformatics:[2] Siqi Liu, Donghao Zhang, Sidong Liu, Dagan Feng, Hanchuan Peng, Weidong Cai,
"Rivulet: 3D Neuron Morphology Tracing with Iterative Back-Tracking",
Neuroinformatics, Vol.14, Issue 4, pp387-401, 2016.A C++ implementation of the Rivulet2 algorithm is also available in the lastestVaa3Dsources under theRivulet Plugin(Not yet available in the released build). However you can build Vaa3D easily on Mac/Linux following theVaa3D wikicarefully.Issues / questions / pull requestsIssues should be reported to theRivuletpy github repository issue tracker.
The ability and speed with which issues can be resolved depends on how complete and
succinct the report is. For this reason, it is recommended that reports be accompanied
with a minimal but self-contained code sample that reproduces the issue, the observed and
expected output, and if possible, the commit ID of the version used. If reporting a
regression, the commit ID of the change that introduced the problem is also extremely valuable
information.Questions are also welcomed in theRivuletpy github repository issue tracker.
If you put on aquestionlabel. We consider every question as an issue since it means we should have made things clearer/easier for the users.Pull requests are definitely welcomed! Before you make a pull requests, please kindly create an issue first to discuss the optimal solution.InstallationSetting up virtual environmentIt is recommended to install rivulet in a virtual enviornment.# create env and activate itcondacreate-nriv
condaactivateriv# install pip and gitcondainstallpipgitInstall from PyPITo installrivuletpyfromPyPIsimply activate your virtual environment and run:pipinstallrivuletpyInstall from GitHubOptionally, you can usepipto install the latest version directly from GitHub:pipinstallgit+https://github.com/RivuletStudio/rivuletpyTest InstallationIn ./rivuletpy/sh quicktest.shThis will download a simple neuron image and perform a neuron tracing with rivulet2 algorithm. If you encountered any issues while installing Rivuletpy, you are welcome to raise an issue for the developers in theissue trackerUsageReconstruct single neuron file.The script rtrace command will be installed$rtrace--help
usage:rtrace[-h]-fFILE[-oOUT][-tTHRESHOLD][-zZOOM_FACTOR][--save-soma][--no-save-soma][--speed][--quality][--no-quality][--clean][--no-clean][--silent][--no-silent][-v][--no-view][--tracing_resolutionTRACING_RESOLUTION][--vtk]ArgumentstoperformtheRivulet2tracingalgorithm.

optionalarguments:-h,--helpshowthishelpmessageandexit-fFILE,--fileFILETheinputfile.Aimagefile(*.tif,*.nii,*.mat).-oOUT,--outOUTThenameoftheoutputfile-tTHRESHOLD,--thresholdTHRESHOLDthresholdtodistinguishtheforegroundandbackground.Default0.Ifthreshold<0,otsuwillbeused.-zZOOM_FACTOR,--zoom_factorZOOM_FACTORThefactortozoomtheimagetospeedupthewholething.Default1.--save-somaSavetheautomaticallyreconstructedsomavolumealongwiththeSWC.--no-save-somaDon'tsavetheautomaticallyreconstructedsomavolumealongwiththeSWC(default)--speedUsetheinputdirectlyasspeedimage--qualityReconstructtheneuronwithhigherqualityandslightlymorecomputingtime--no-qualityReconstructtheneuronwithlowerqualityandslightlymorecomputingtime--cleanRemovetheunconnectedsegments(default).ItisrelativelysafetodowiththeRivulet2algorithm--no-cleanKeeptheunconnectedsegments--silentOmittheterminaloutputs--no-silentShowtheterminaloutputs&thenicelogo(default)-v,--viewViewthereconstructedneuronwhenrtracefinishes--no-view--tracing_resolutionTRACING_RESOLUTIONOnlyvalidformhdinputfiles.Willresamplethemhdarrayintoisotropicresolutionbeforetracing.Default1mm--vtkStoretheworldcoordinatevtkformatalongwiththeswcExample Usecases with single neurons in a TIFF imagertrace-fexample.tif-t10# Simple like this. Reconstruct a neuron in example.tif with a background threshold of 10rtrace-fexample.tif-t10--quality# Better results with longer running timertrace-fexample.tif-t10--quality-v# Open a 3D swc viewer after reconstructionExample Usecases with general tree structures in a mhd imagertrace-fexample.mhd-t10--tracing_resolution1.5--vtk# Perform the tracing under an isotropic resolution of 1.5mmx1.5mmx1.5mm and output a vtk output file under the world coordinates along side the swc.rtrace-fexample.mhd-t10--tracing_resolution1.5--vtk--speed# Use the input image directly as the source of making speed image. Recommended if the input mhd is a probablity map of centerlines.Please note that Rivulet2 is powerful of handling the noises, a relatively low intensity threshold is preferred to include all the candidate voxels.Compare a swc reconstruction against the manual ground truth$compareswc--help
usage:compareswc[-h]--targetTARGET--groundtruthGROUNDTRUTH[--sigmaSIGMA]Argumentsforcomparingtwoswcfiles.

optionalarguments:-h,--helpshowthishelpmessageandexit--targetTARGETTheinputtargetswcfile.--groundtruthGROUNDTRUTHTheinputgroundtruthswcfile.--sigmaSIGMAThesigmavaluetousefortheGaussianfunctioninNetMets.

$compareswc--targetr2_tracing.swc--groundtruthhand_tracing.swc0.99700.89460.986513Thecompareswccommand outputs five numbers which are in order:precision, recall, f1-score, No. connection error type A, No. connection error type BFAQWhat if I see on Mac OSImportError: Failed to find TIFF library. Make sure that libtiff is installed and its location is listed in PATH|LD_LIBRARY_PATH|..TrybrewinstalllibtiffWhat if I see...version `GLIBCXX_3.4.21' not found...when I runrtraceunder Anaconda?Try(riv)$condainstalllibgcc# Upgrades the gcc in your conda environment to the newestWhat if I seeIntel MKL FATAL ERROR: Cannot load libmkl_avx2.so or libmkl_def.so.?Try to get rid of the mkl in your conda, it has been reported to cause many issues(riv)$condainstallnomklnumpyscipyscikit-learnnumexpr(riv)$condaremovemklmkl-serviceDependenciesThe build-time and runtime dependencies of Rivuletpy are:numpyscipyCythonscikit-fmmscikit-imagematplotlibtqdmnibabel