Code Documentation
This is the documentation guide for running our algorithms and experimentation methods. Our project code contains implementations of our algorithms, evaluation metrics, and other miscelaneous parsing and experimentation files.
Algorithm Implementations
All methods to run our algorithms take in a color PIL image and return a 2D numpy array of segment numbers for each pixel.
Thresholding
thresholding.py
This file contains our baseline implementation of the thresholding algorithm and helper functions.
baseline_thresholding(image)Given a color image, converts to grayscale and thresholds using a threshold defined by the average grayscale value of all pixels, scaled by 1.5.
multi_threshold.py
This file contains our more sophisticated implementation of the thresholding algorithm, which finds a threshold using Otsu's method.
otsu_greyspace_thresholding(image)Given a color image, converts to grayscale and thresholds on a grayscale value histogram using Otsu's method.
otsu_multi_greyspace_thresholding(image, segments)Given a color image and a number of segments, converts to grayscale and thresholds into the specified number of segments on a grayscale value histogram using Otsu's method.
Region Growing
regionGrowing.py
This file contains our implementation of the region growing algorithm and helper methods.
region_growing(img,seed,threshold)Given an image, a seed, and a threshold, perform region growing and output a segmentation. The seed is a tuple indicating the seed pixel to start growing out from, and the threshold determines how similar pixels must be to the seed to be added to the same region.
Split and Merge
regionsplit.py
This file contains our partial implementation of the split and merge algorithm and helper methods. Currently, this algorithm splits correctly but does not merge all regions that should be merged.
regionSplitAndMerge(image,threshold)Takes in a color PIL image and integer threshold and performs split and merge on that image. The integer threshold gives a cutoff for the acceptable level of variance within a region. In our testing, a threshold of 450 produced good results.
K-Means
kmeans.py
This file contains our implementations of several k-means algorithm variants and helper methods. We list here only one version of k-means, since our other versions are not fully tested.
kmeans(image, seed='random')Runs k-means using the elbow method with a maximum k value of 10. The elbow method runs k-means with increasing values of k, finding the value of k for which the in-cluster variance no longer significantly decreases.
Watershed
watershed.py
This file contains our naive implementation of the watershed algorithm, as well as a version using wolf pruning, and helper methods.
naive_watershed(image,blur=None)Runs watershed algorithm on PIL image input, blurring the image first if specified.
watershed_with_wolf(image,depththreshold,blur=None)Runs the watershed variant with wolf pruning on input image, blurring the image first if specified.
Minimum Cut
mincut.py
This file contains our (probably buggy) implementation of the minimum cut algorithm and helper methods.
mincut(img, edge_weight_function, connectivity=12)Runs minimum cut algorithm on a PIL image.
Specify an edge weight function that captures your desired pixel similarity/difference metric, and number of surrounding pixels
to be connected in the graph (our trials used 12). Two difference metrics are included (see differenceMetricRGBAndDist and differenceMetricRGB),
or you can create your own.
These two parameters will impact the exact output of the algorithm.
differenceMetricRGBAndDist(coords1, coords2,pixels)Compute difference between two pixels at specified coordinates in a numpy array using Euclidean distance between RGB values and Euclidean distance between their locations.
differenceMetricRGB(coords1, coords2, pixels)Compute difference between two pixels at specified coordinates in a numpy array using Euclidean distance between RGB values.
Evaluation Metric Implementations
Implementations of our region and edge based evaluation metrics.
Each metric method takes in a 2D numpy array of ground truth segment labels and
a 2D numpy array of generated segmentation segment labels. Our datasets provide ground truths in different formats, so when evaluating segmentations against ground truths,
it is necessary to convert these ground truths into a comparable format (see parser.py below).
eval.py
This file contains our evaluation metric methods and helper methods.
bde(segmentation,groundtruth)Calculate the BDE value for a segmentation and ground truth.
region_based_eval(truth,generated)Calculates the Jaccard score for a segmentation and ground truth.
Miscellaneous Experimentation Methods
These files contain methods for parsing ground truth files from our datasets into 2D numpy arrays, running algorithms on batches of files, and evaluating batches of segmentations.
Ground Truth Parsing
parser.py
This file contains methods to parse a Weizmann or Berkeley ground truth segmentaitons into a 2D numpy array.
import_berkeley(filename)Given the path to a file containing a Berkeley encoding of a ground truth, return a numpy array version.
import_weizmann(filename)Given the path to a file containing a Weizmann encoding of a ground truth, return a numpy array version.
display_segmentation(image,number_of_segments)Given a numpy array version of a segmentation, display a grayscale image representation of that segmentation.
Testing Scripts
operations.py
This file contains scripts to run a segmentation algorithm on and evaluate a batch of images.
evaluate_all_images(dataset,metric,location_segments, location_truths, output_filename)Given a dataset (WEIZMANN or BERKELEY) and an evaluation metric (BDE or JACCARD), run this metric on segmentations from location_segments and location_truths, and output results into a CSV file named output_filename.
segment_all_images(location, algorithm, output_folder)Segment all images in the indicated location folder using the indicated algorithm, and save segmentations in indicated output_folder.