function [ allImages ] = runRegionGrowing( directoryName,...
                            thresholdBegin, thresholdEnd, increment )
%runRegionGrowing 
%   Summary: Run the region growing code based on the parameters provided
%       at the end, an array of all image segmentations will be returned
%   param directoryName
%       pass a string directory name that contains dicom images to be used
%       for segmentation
%   param thresholdBegin
%       pass the beginning threshold value that will do the following:
%           "Start region growing until distance between region and posible 
%           new pixels become higher than a certain treshold"
%       From here, the threshold will be passed to regiongrowing and
%       incremented on by the increment variable
%   param thresholdEnd
%       pass the end threshold value that will do the following:
%       "Start region growing until distance between region and posible 
%           new pixels become higher than a certain treshold"
%       This will mark the end of the incrementation, no more region
%       growing will be run
%   param increment
%       pass value in which the threshold will be incremented on.
%       Example: thresholdBegin = 0.2 and increment = .05 
%             first iteration threshold = 0.2
%             second iteration threshold = 0.25
%             third iteration threshold = 0.3
%             etc...
%
%   return allSegmentations
%       returns all segmentations created by region growth as a
%       two-dimensional cell array
%
%   return originalImages
%       return all original dicom images as a one-dimensional cell array
%
%   Author: Patrick Stein 7/1/2013


    %% Parameter validation

    % Validate the following parameters: 
    % thresholdBegin, thresholdEnd, increment
    % thresholdBegin and thresholdEnd > 0
    % thresholdBegin != thresholdEnd
    % thresholdEnd > thresholdBegin
    % increment > 0
    % Directory is an actual directory

    %Test the following conditions: 
    %"thresholdBegin != thresholdEnd && thresholdEnd > thresholdBegin"
    if(thresholdEnd <= thresholdBegin)
        invalidParam = MException('RunRegionGrowing:InvalidParam:p2_3', ...
            'Invalid Parameter: thresholdEnd must be >= thresholdBegin');
        throw(invalidParam);
    end

    %Test the following condition: increment > 0
    if(increment <= 0)
        invalidParam = MException('RunRegionGrowing:InvalidParam:p4', ...
            'Invalid Parameter: increment must be >= 0'); 
        throw(invalidParam);
    end

    %Test the following condition: thresholdBegin and thresholdEnd > 0
    if(thresholdBegin <= 0 || thresholdEnd <= 0)
        invalidParam = MException('RunRegionGrowing:InvalidParam:p2_3', ...
        'Invalid Parameter: thresholdBegin/End must >= 0');
        throw(invalidParam);
    end

    %Test to see if directoryName is a folder
    %exists docs: http://www.mathworks.com/help/matlab/ref/exist.html
    if(exist(directoryName,'dir') ~= 7)
        invalidParam = MException('RunRegionGrowing:InvalidParam:p1', ...
        'Invalid Parameter: directoryName is not a  valid directory');
        throw(invalidParam);
    end

    %% Pre-processing
    
    %append \*.dcm to the end of the string so it will only load dicom
    %files
    directoryNameNew = strcat(directoryName,'\*.dcm');
    
    % set the directory where nodule crops are stored
    imageFiles = dir(directoryNameNew);
    
  
    %get size of directory
    sizeDir = size(imageFiles,1);
   
    %create structure array of all dicom info and segmentations
    allImages = struct('imageNumber',0,'imageName',char,...
                       'originalImage',[],'segmentations',cell(1,1),...
                       'dicomInfo',struct([]),'map',[],'alpha',[],...
                       'overlay',[],'segmentationType',char,'masks',...
                       cell(1,1));
    %Segmentation type    
    sg = 'rg';
    %% DICOM Segmentation
    
    %for each file in the directory, do the following
    parfor i = 1:sizeDir
        
        %get image name
        in = char(imageFiles(i).name);
        
        %Construct the file name and path needed to open the file
        fn = sprintf('%s/%s', directoryName, in);
        
        %Load dicom image into matlab, see loadDicom for more information
        try
            [dicomImage,info,m,a,o] = loadDicom(fn);
        catch ME
            % TODO: Handle this exception
            %rethrow(ME);
        end 
             
        %save segmentation type
        allImages(i).segmentationType = sg; 
        %save name
        allImages(i).imageName = in;
        %save image number
        allImages(i).imageNumber = str2num( in(1:(strfind(in,'.')-1)) );           
        %save dicom image
        allImages(i).originalImage = dicomImage;
        %save org dicom information
        allImages(i).dicomInfo = info;
        %save org dicom map
        allImages(i).map = m;
        %save org dicom alpha
        allImages(i).alpha = a;
        %save org dicom overlay
        allImages(i).overlay = o;
        allImages(i).segmentations = getAllSegsRG(dicomImage,thresholdBegin,...
                                        thresholdEnd, increment);
    end

    %% Wrap up
    %sort the structure array
    allImages = nestedSortStruct(allImages, 'imageNumber');
       
end