Merge pull request #73 from ofgulban/devel

v1.5.0

.gitignore

@@ -5,7 +5,6 @@ __pycache__/
 
 # C extensions
 *.so
-*.c
 
 # Distribution / packaging
 .Python

README.md

@@ -16,14 +16,15 @@ The goal is to provide a complementary tool to the already available brain tissu
 <img src="visuals/animation_01.gif" width=840 align="center" />
 
 ## Core dependencies
-[**Python 2.7**](https://www.python.org/download/releases/2.7/)
+**[Python 2.7](https://www.python.org/download/releases/2.7/)** or **[Python 3.6](https://www.python.org/downloads/release/python-363/)** (compatible with both).
 
-| Package                              | Tested version |
-|--------------------------------------|----------------|
-| [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         |
+| Package                                        | Tested version |
+|------------------------------------------------|----------------|
+| [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         |
+| [Compoda](https://github.com/ofgulban/compoda) | 0.3.3          |
 
 ## Installation & Quick Start
 - 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.
@@ -59,11 +60,8 @@ Copyright © 2016, [Omer Faruk Gulban](https://github.com/ofgulban) and [Marian
 Released under [GNU General Public License Version 3](http://www.gnu.org/licenses/gpl.html).
 
 ## References
-This application is based on the following work:
+This application is mainly 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
+* 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>

contributing.md

@@ -0,0 +1,24 @@
+Contributing
+============
+If you want to contribute to Segmentator and make it better, your help is very welcome.
+
+## Opening an issue
+
+- Please post your quesions, bug reports and feature requests [here](https://github.com/ofgulban/segmentator/issues).
+- When reporting a bug, please specify your system and a complete copy of the error message that you are getting.
+
+## Making a pull request
+
+- Create a personal fork of the project on Github.
+- Clone the fork on your local machine.
+- Create a new branch to work on. Branch from `devel`.
+- Implement/fix your feature, comment your code.
+- Follow the code style of the project.
+- Add or change the documentation as needed.
+- Push your branch to your fork on Github.
+- From your fork open a pull request in the correct branch. Target `devel` branch of the original Segmentator repository.
+
+__Note:__ Please write your commit messages in the present tense. Your commit message should describe what the commit, when applied, does to the code – not what you did to the code.
+
+___
+This guideline is adapted from [link](https://github.com/MarcDiethelm/contributing/blob/master/README.md)

environment.yml

@@ -5,7 +5,7 @@ dependencies:
 - setuptools>=19.6*
 - pytest>=3*
 - pytest-cov>=2.5*
-- numpy>=1.13*
-- scipy>=0.19*
-- matplotlib>=2.0*
-- nibabel>=2.1*
+- numpy>=1.14*
+- scipy>=1.0*
+- matplotlib>=2.1*
+- nibabel>=2.2*

requirements.txt

@@ -1,5 +1,6 @@
-numpy==1.13.1
-scipy==0.19.1
-matplotlib==2.0.2
-nibabel==2.1.0
+numpy==1.14.2
+scipy==1.0.0
+matplotlib==2.2.2
+nibabel==2.2.1
 pytest-cov==2.5.1
+compoda>=0.3

sample_data/readme.md

@@ -0,0 +1,4 @@
+The dataset used for developing Segmentator can be found at:
+
+[https://doi.org/10.5281/zenodo.1117858](https://doi.org/10.5281/zenodo.1117858)
+

segmentator/__init__.py

@@ -1,18 +1,5 @@
-"""All this stuff is to get the version from setup.py."""
+"""Make the version number available."""
 
-from pkg_resources import get_distribution, DistributionNotFound
-import os.path
+import pkg_resources  # part of setuptools
 
-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
+__version__ = pkg_resources.require("segmentator")[0].version

segmentator/__main__.py

@@ -5,13 +5,11 @@
 https://chriswarrick.com/blog/2014/09/15/python-apps-the-right-way-entry_points-and-scripts/
 
 Use config.py to hold arguments to be accessed by imported scripts.
-
-TODO: Argument parsing can be better structured, maybe by using parents. help
-looks a bit messy as is.
 """
 
+from __future__ import print_function
 import argparse
-import config as cfg
+import segmentator.config as cfg
 from segmentator import __version__
 
 
@@ -28,12 +26,17 @@ def main():
     parser.add_argument(
         "--gramag", metavar=str(cfg.gramag), required=False,
         default=cfg.gramag,
-        help="'scharr', 'sobel', 'prewitt', 'numpy' \
+        help="'scharr', 'deriche', 'sobel', 'prewitt', 'numpy' \
         or path to a gradient magnitude nifti."
         )
+    # used in Deriche filter gradient magnitude computation
     parser.add_argument(
-        "--ncut",  metavar='path', required=False,
-        help="Path to nyp file with ncut labels"
+        "--deriche_alpha", required=False, type=float,
+        default=cfg.deriche_alpha, metavar=cfg.deriche_alpha,
+        help="Used only in Deriche gradient magnitude option. Smaller alpha \
+        values suppress more noise but can dislocate edges. Useful when there \
+        is strong noise in the input image or the features of interest are at \
+        a different scale compared to original image resolution."
         )
     parser.add_argument(
         "--scale", metavar=str(cfg.scale), required=False, type=float,
@@ -50,6 +53,16 @@ def main():
         default=cfg.perc_max,
         help="Maximum percentile used in truncation."
         )
+    parser.add_argument(
+        "--valmin", metavar=str(cfg.valmin), required=False, type=float,
+        default=cfg.valmin,
+        help="Minimum value, overwrites percentile."
+        )
+    parser.add_argument(
+        "--valmax",  metavar=str(cfg.valmax), required=False,  type=float,
+        default=cfg.valmax,
+        help="Maximum value, overwrites percentile."
+        )
     parser.add_argument(
         "--cbar_max",  metavar=str(cfg.cbar_max), required=False,  type=float,
         default=cfg.cbar_max,
@@ -61,6 +74,10 @@ def main():
         help="Initial value (power of 10) of the colorbar slider. \
               Also used with --ncut_prepare flag."
         )
+    parser.add_argument(
+        "--ncut",  metavar='path', required=False,
+        help="Path to nyp file with ncut labels. Initiates N-cut GUI mode."
+        )
     parser.add_argument(
         "--nogui", action='store_true',
         help="Only save 2D histogram image without showing GUI."
@@ -73,8 +90,13 @@ def main():
         "--export_gramag", action='store_true',
         help="Export the gradient magnitude image. Not used by default."
         )
+    parser.add_argument(
+        "--force_original_precision", action='store_true',
+        help="Do not change the data type of the input image. Can be useful \
+        for very large images. Off by default."
+        )
 
-    # used in ncut preparation  (TODO: not yet tested after restructuring.)
+    # used in ncut preparation
     parser.add_argument(
         "--ncut_prepare", action='store_true',
         help=("------------------(utility feature)------------------ \
@@ -114,35 +136,41 @@ def main():
     cfg.scale = args.scale
     cfg.perc_min = args.percmin
     cfg.perc_max = args.percmax
+    cfg.valmin = args.valmin
+    cfg.valmax = args.valmax
     cfg.cbar_max = args.cbar_max
     cfg.cbar_init = args.cbar_init
     if args.include_zeros:
         cfg.discard_zeros = False
     cfg.export_gramag = args.export_gramag
+    cfg.force_original_precision = args.force_original_precision
     # used in ncut preparation
     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
     cfg.ncut = args.ncut
+    # used in deriche filter
+    cfg.deriche_alpha = args.deriche_alpha
 
-    welcome_str = 'Segmentator ' + __version__
-    welcome_decoration = '=' * len(welcome_str)
-    print(welcome_decoration + '\n' + welcome_str + '\n' + welcome_decoration)
+    welcome_str = 'Segmentator {}'.format(__version__)
+    welcome_decor = '=' * len(welcome_str)
+    print('{}\n{}\n{}'.format(welcome_decor, welcome_str, welcome_decor))
 
     # 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
+        print('No GUI option is selected. Saving 2D histogram image...')
+        import segmentator.hist2d_counts
     elif args.ncut_prepare:
-        print('--Preparing N-cut related files...')
-        import ncut_prepare
+        print('Preparing N-cut file...')
+        import segmentator.ncut_prepare
     elif args.ncut:
-        print('--Experimental N-cut feature is selected.')
-        import segmentator_ncut
+        print('N-cut GUI is selected.')
+        import segmentator.segmentator_ncut
     else:
-        import segmentator_main
+        print('Default GUI is selected.')
+        import segmentator.segmentator_main
 
 
 if __name__ == "__main__":

segmentator/config.py

@@ -1,6 +1,6 @@
 """This file contains variables that are shared by several modules.
 
-Also useful to hold command line arguments.
+Useful to hold command line arguments.
 
 """
 
@@ -12,16 +12,20 @@
 # segmentator main command line variables
 filename = 'sample_filename_here'
 gramag = 'scharr'
+deriche_alpha = 3.0
 perc_min = 2.5
 perc_max = 97.5
+valmin = float('nan')
+valmax = float('nan')
 scale = 400
 cbar_max = 5.0
 cbar_init = 3.0
 discard_zeros = True
 export_gramag = False
+force_original_precision = False
 
 # possible gradient magnitude computation keyword options
-gramag_options = ['scharr', 'sobel', 'prewitt', 'numpy']
+gramag_options = ['scharr', 'sobel', 'prewitt', 'numpy', 'deriche']
 
 # used in segmentator ncut
 ncut = False

segmentator/config_filters.py

@@ -0,0 +1,13 @@
+"""This file contains variables that are used in filters."""
+
+filename = 'sample_filename_here'
+
+# filter defult parameters
+smoothing = 'STEDI'
+noise_scale = 0.5
+feature_scale = 0.5
+nr_iterations = 20
+save_every = 10
+edge_thr = 0.001
+gamma = 1
+downsampling = 0

segmentator/config_gui.py

@@ -0,0 +1,13 @@
+"""This file contains GUI related variables."""
+
+import matplotlib.pyplot as plt
+
+# Colormap for mask overlays
+palette = plt.cm.Reds
+palette.set_over('r', 1.0)
+palette.set_under('w', 0)
+palette.set_bad('m', 1.0)
+
+# Slider colors
+axcolor = '0.875'
+hovcolor = '0.975'