Merge pull request #53 from ofgulban/devel

v1.3.0

.appveyor.yml

@@ -0,0 +1,20 @@
+build: false
+
+environment:
+  matrix:
+    - PYTHON_VERSION: 2.7
+      MINICONDA: C:\Miniconda
+
+init:
+  - "ECHO %PYTHON_VERSION% %MINICONDA%"
+
+install:
+  - "set PATH=%MINICONDA%;%MINICONDA%\\Scripts;%PATH%"
+  - conda config --set always_yes yes --set changeps1 no
+  - conda update -q conda
+  - "conda env create --force -f environment.yml python=2.7"
+  - activate segmentator
+  - python setup.py develop
+
+test_script:
+  - py.test

.coveragerc

@@ -0,0 +1,9 @@
+[run]
+source = segmentator
+
+omit =
+    *__init__*
+    *__main__*
+    *config*
+    *tests/*
+    segmentator/future/*

.gitignore

@@ -61,3 +61,5 @@ target/
 
 #Ipython Notebook
 .ipynb_checkpoints
+
+bin/

.travis.yml

@@ -0,0 +1,19 @@
+sudo: false
+os:
+  - linux
+  - osx
+matrix:
+  allow_failures:
+    - os: osx
+language: python
+python:
+  - 2.7
+install:  # command to install dependencies
+  - pip install -r requirements.txt
+  - python setup.py develop
+script:  # command to run tests
+  - py.test --cov=./segmentator
+after_success:
+  - bash <(curl -s https://codecov.io/bash)
+notifications:
+  email: false

README.md

@@ -1,40 +1,62 @@
-# Segmentator
+[![DOI](https://zenodo.org/badge/59303623.svg)](https://zenodo.org/badge/latestdoi/59303623) [![Build Status](https://travis-ci.org/ofgulban/segmentator.svg?branch=master)](https://travis-ci.org/ofgulban/segmentator) [![Build status](https://ci.appveyor.com/api/projects/status/lkxp4y5ahssqv6ng?svg=true)](https://ci.appveyor.com/project/ofgulban/segmentator) [![codecov](https://codecov.io/gh/ofgulban/segmentator/branch/master/graph/badge.svg)](https://codecov.io/gh/ofgulban/segmentator) [![Code Health](https://landscape.io/github/ofgulban/segmentator/master/landscape.svg?style=flat)](https://landscape.io/github/ofgulban/segmentator/master) [![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/segmentator/Lobby)
 
-[![DOI](https://zenodo.org/badge/59303623.svg)](https://zenodo.org/badge/latestdoi/59303623)
-[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/segmentator/Lobby)
+# Segmentator
 
 <img src="logo/logo.png" width=420 align="right" />
 
-Segmentator is a free and open-source package for multi-dimensional data exploration and segmentation for 3D images. This application is mainly developed and tested using ultra-high field magnetic resonance imaging (MRI) brain data.  
+Segmentator is a free and open-source package for multi-dimensional data exploration and segmentation for 3D images. This application is mainly developed and tested using ultra-high field magnetic resonance imaging (MRI) brain data.
 
 
-The goal is to provide a complementary tool to the already available brain tissue segmentation methods (to the best of our knowledge) in other software packages (FSL, Freesurfer, SPM, Brainvoyager, itk-SNAP, etc.).  
+The goal is to provide a complementary tool to the already available brain tissue segmentation methods (to the best of our knowledge) in other software packages (FSL, Freesurfer, SPM, Brainvoyager, itk-SNAP, etc.).
 
 ## Core dependencies
 [**Python 2.7**](https://www.python.org/download/releases/2.7/)
 
 | Package                              | Tested version |
 |--------------------------------------|----------------|
-| [NumPy](http://www.numpy.org/)       | 1.11.1         |
-| [matplotlib](http://matplotlib.org/) | 1.5.3          |
+| [matplotlib](http://matplotlib.org/) | 2.0.2          |
+| [NumPy](http://www.numpy.org/)       | 1.13.1         |
 | [NiBabel](http://nipy.org/nibabel/)  | 2.1.0          |
+| [SciPy](http://scipy.org/)           | 0.19.1         |
 
 ## Installation & Quick Start
-Please visit [our wiki](https://github.com/ofgulban/segmentator/wiki/Installation) to see how to install and use Segmentator.
+- Make sure you have [**Python 2.7**](https://www.python.org/download/releases/2.7/) and [**pip**](https://en.wikipedia.org/wiki/Pip_(package_manager)) installed.
+- Change directory in your command line:
+```
+cd /path/to/segmentator
+```
+- Install the requirements by running the following command:
+```
+pip install -r requirements.txt
+```
+- Install Segmentator:
+```
+python setup.py install
+```
+- Simply call segmentator with a nifti file:
+```
+segmentator /path/to/file.nii.gz
+```
+- Or see the help for available options:
+```
+segmentator --help
+```
+
+Visit [our wiki](https://github.com/ofgulban/segmentator/wiki/Installation) to see alternative installation methods.
 
 ## Support
 Please use [GitHub issues](https://github.com/ofgulban/segmentator/issues) for questions, bug reports or feature requests.
 
 ## License
-The project is licensed under [GNU General Public License Version 3](http://www.gnu.org/licenses/gpl.html).
+Copyright © 2016, [Omer Faruk Gulban](https://github.com/ofgulban) and [Marian Schneider](https://github.com/MSchnei).
+Released under [GNU General Public License Version 3](http://www.gnu.org/licenses/gpl.html).
 
 ## References
 This application is based on the following work:
 
-* Kindlmann, G., & Durkin, J. W. (1998). Semi-automatic generation of transfer functions for direct volume rendering. In Proceedings of the 1998 IEEE symposium on Volume visualization - VVS ’98 (pp. 79–86). New York, New York, USA: ACM Press. http://doi.org/10.1145/288126.288167  
-* Kniss, J., Kindlmann, G., & Hansen, C. (2001). Interactive volume rendering using multi-dimensional transfer functions and direct manipulation widgets. In Proceedings Visualization, 2001. VIS ’01. (pp. 255–562). IEEE. http://doi.org/10.1109/VISUAL.2001.964519  
-* Kniss, J., Kindlmann, G., & Hansen, C. (2002). Multidimensional transfer functions for interactive volume rendering. IEEE Transactions on Visualization and Computer Graphics, 8(3), 270–285. http://doi.org/10.1109/TVCG.2002.1021579  
-* Kniss, J., Kindlmann, G., & Hansen, C. D. (2005). Multidimensional transfer functions for volume rendering. Visualization Handbook, 189–209. http://doi.org/10.1016/B978-012387582-2/50011-3  
-* Jianbo Shi, & Malik, J. (2000). Normalized cuts and image segmentation. IEEE Transactions on Pattern Analysis and Machine Intelligence, 22(8), 888–905. http://doi.org/10.1109/34.868688  
-* Ip, C. Y., Varshney, A., & Jaja, J. (2012). Hierarchical exploration of volumes using multilevel segmentation of the intensity-gradient histograms. IEEE Transactions on Visualization and Computer Graphics, 18(12), 2355–2363. http://doi.org/10.1109/TVCG.2012.231  
-
+* Kindlmann, G., & Durkin, J. W. (1998). Semi-automatic generation of transfer functions for direct volume rendering. In Proceedings of the 1998 IEEE symposium on Volume visualization - VVS ’98 (pp. 79–86). New York, New York, USA: ACM Press. http://doi.org/10.1145/288126.288167
+* Kniss, J., Kindlmann, G., & Hansen, C. (2001). Interactive volume rendering using multi-dimensional transfer functions and direct manipulation widgets. In Proceedings Visualization, 2001. VIS ’01. (pp. 255–562). IEEE. http://doi.org/10.1109/VISUAL.2001.964519
+* Kniss, J., Kindlmann, G., & Hansen, C. (2002). Multidimensional transfer functions for interactive volume rendering. IEEE Transactions on Visualization and Computer Graphics, 8(3), 270–285. http://doi.org/10.1109/TVCG.2002.1021579
+* Kniss, J., Kindlmann, G., & Hansen, C. D. (2005). Multidimensional transfer functions for volume rendering. Visualization Handbook, 189–209. http://doi.org/10.1016/B978-012387582-2/50011-3
+* Jianbo Shi, & Malik, J. (2000). Normalized cuts and image segmentation. IEEE Transactions on Pattern Analysis and Machine Intelligence, 22(8), 888–905. http://doi.org/10.1109/34.868688
+* Ip, C. Y., Varshney, A., & Jaja, J. (2012). Hierarchical exploration of volumes using multilevel segmentation of the intensity-gradient histograms. IEEE Transactions on Visualization and Computer Graphics, 18(12), 2355–2363. http://doi.org/10.1109/TVCG.2012.231

environment.yml

@@ -0,0 +1,11 @@
+name: segmentator
+channels:
+- conda-forge
+dependencies:
+- setuptools>=19.6*
+- pytest>=3*
+- pytest-cov>=2.5*
+- numpy>=1.13*
+- scipy>=0.19*
+- matplotlib>=2.0*
+- nibabel>=2.1*

requirements.txt

@@ -0,0 +1,5 @@
+numpy==1.13.1
+scipy==0.19.1
+matplotlib==2.0.2
+nibabel==2.1.0
+pytest-cov==2.5.1

segmentator/__init__.py

@@ -0,0 +1,18 @@
+"""All this stuff is to get the version from setup.py."""
+
+from pkg_resources import get_distribution, DistributionNotFound
+import os.path
+
+try:
+    _dist = get_distribution('segmentator')
+    # Normalize case for Windows systems
+    dist_loc = os.path.normcase(_dist.location)
+    here = os.path.normcase(__file__)
+    if not here.startswith(os.path.join(dist_loc, 'segmentator')):
+        # not installed, but there is another version that *is*
+        raise DistributionNotFound
+except DistributionNotFound:
+    __version__ = 'Version information not found. Please install this project \
+                   with setup.py)'
+else:
+    __version__ = _dist.version

segmentator/__main__.py

@@ -12,7 +12,8 @@
 
 import sys
 import argparse
-import config
+import config as cfg
+from segmentator import __version__
 
 
 def main(args=None):
@@ -26,43 +27,48 @@ def main(args=None):
         help="Path to input. Mostly a nifti file with image data."
         )
     parser.add_argument(
-        "--gramag", metavar='path', required=False,
-        help="Path to gradient magnitude (useful for deriche)"
+        "--gramag", metavar=str(cfg.gramag), required=False,
+        default=cfg.gramag,
+        help="'scharr', 'sobel', 'prewitt', 'numpy' \
+        or path to a gradient magnitude nifti."
         )
     parser.add_argument(
         "--ncut",  metavar='path', required=False,
         help="Path to nyp file with ncut labels"
         )
     parser.add_argument(
-        "--scale", metavar='500', required=False, type=float,
-        default=config.scale,
+        "--scale", metavar=str(cfg.scale), required=False, type=float,
+        default=cfg.scale,
         help="Data is scaled from 0 to this number."
         )
     parser.add_argument(
-        "--percmin", metavar='0.25', required=False, type=float,
-        default=config.perc_min,
+        "--percmin", metavar=str(cfg.perc_min), required=False, type=float,
+        default=cfg.perc_min,
         help="Minimum percentile used in truncation."
         )
     parser.add_argument(
-        "--percmax",  metavar='99.75', required=False,  type=float,
-        default=config.perc_max,
+        "--percmax",  metavar=str(cfg.perc_max), required=False,  type=float,
+        default=cfg.perc_max,
         help="Maximum percentile used in truncation."
         )
     parser.add_argument(
-        "--nogui", action='store_true',
-        help="Only save 2D histogram image without showing GUI."
+        "--cbar_max",  metavar=str(cfg.cbar_max), required=False,  type=float,
+        default=cfg.cbar_max,
+        help="Maximum value (power of 10) of the colorbar slider."
         )
-
-    # used in Deriche filter gradient magnitude computation
     parser.add_argument(
-        "--deriche_prepare", action='store_true',
-        help=("------------------(utility feature)------------------ \
-              Use this flag with the following arguments:")
+        "--cbar_init",  metavar=str(cfg.cbar_init), required=False,
+        type=float, default=cfg.cbar_init,
+        help="Initial value (power of 10) of the colorbar slider. \
+              Also used with --ncut_prepare flag."
+        )
+    parser.add_argument(
+        "--nogui", action='store_true',
+        help="Only save 2D histogram image without showing GUI."
         )
     parser.add_argument(
-        "--der_alpha", required=False, type=float,
-        default=2, metavar='2',
-        help="Alpha controls smoothing, lower -> smoother"
+        "--include_zeros", action='store_true',
+        help="Include image zeros in histograms. Not used by default."
         )
 
     # used in ncut preparation  (TODO: not yet tested after restructuring.)
@@ -77,17 +83,17 @@ def main(args=None):
         )
     parser.add_argument(
         "--ncut_maxRec", required=False, type=int,
-        default=config.max_rec, metavar=config.max_rec,
+        default=cfg.max_rec, metavar=cfg.max_rec,
         help="Maximum number of recursions."
         )
     parser.add_argument(
         "--ncut_nrSupPix", required=False, type=int,
-        default=config.nr_sup_pix, metavar=config.nr_sup_pix,
+        default=cfg.nr_sup_pix, metavar=cfg.nr_sup_pix,
         help="Number of regions/superpixels."
         )
     parser.add_argument(
         "--ncut_compactness", required=False, type=float,
-        default=config.compactness, metavar=config.compactness,
+        default=cfg.compactness, metavar=cfg.compactness,
         help="Compactness balances intensity proximity and space \
         proximity of the superpixels. \
         Higher values give more weight to space proximity, making \
@@ -96,35 +102,37 @@ def main(args=None):
         objects in the image."
         )
 
-    # set config file variables to be accessed from other scripts
+    # set cfg file variables to be accessed from other scripts
     args = parser.parse_args()
     # used in all
-    config.filename = args.filename
+    cfg.filename = args.filename
     # used in segmentator GUI (main and ncut)
-    config.gramag = args.gramag
-    config.scale = args.scale
-    config.perc_min = args.percmin
-    config.perc_max = args.percmax
-    # used in deriche filter
-    config.deriche_alpha = args.der_alpha
+    cfg.gramag = args.gramag
+    cfg.scale = args.scale
+    cfg.perc_min = args.percmin
+    cfg.perc_max = args.percmax
+    cfg.cbar_max = args.cbar_max
+    cfg.cbar_init = args.cbar_init
+    if args.include_zeros:
+        cfg.discard_zeros = False
     # used in ncut preparation
-    config.ncut_figs = args.ncut_figs
-    config.max_rec = args.ncut_maxRec
-    config.nr_sup_pix = args.ncut_nrSupPix
-    config.compactness = args.ncut_compactness
+    cfg.ncut_figs = args.ncut_figs
+    cfg.max_rec = args.ncut_maxRec
+    cfg.nr_sup_pix = args.ncut_nrSupPix
+    cfg.compactness = args.ncut_compactness
     # used in ncut
-    config.ncut = args.ncut
+    cfg.ncut = args.ncut
 
-    print("===========\nSegmentator\n===========")
+    welcome_str = 'Segmentator ' + __version__
+    welcome_decoration = '=' * len(welcome_str)
+    print(welcome_decoration + '\n' + welcome_str + '\n' + welcome_decoration)
 
     # Call other scripts with import method (couldn't find a better way).
     if args.nogui:
         print '--No GUI option is selected. Saving 2D histogram image...'
         import hist2d_counts
-    elif args.deriche_prepare:
-        import deriche
     elif args.ncut_prepare:
-        print '--Preparing n-cut related files...'
+        print '--Preparing N-cut related files...'
         import ncut_prepare
     elif args.ncut:
         print '--Experimental N-cut feature is selected.'

segmentator/config.py

@@ -11,13 +11,16 @@
 
 # segmentator main command line variables
 filename = 'sample_filename_here'
-gramag = 'gradient_magnitude_sample_here'
-perc_min = 0.25
-perc_max = 99.75
+gramag = 'scharr'
+perc_min = 2.5
+perc_max = 97.5
 scale = 400
+cbar_max = 5.0
+cbar_init = 3.0
+discard_zeros = True
 
-# used in Deriche filter
-deriche_alpha = 2
+# possible gradient magnitude computation keyword options
+gramag_options = ['scharr', 'sobel', 'prewitt', 'numpy']
 
 # used in segmentator ncut
 ncut = False