Updating documentation, minor clean-up

colormine/src/main/org/colormine/ColorMine.java

@@ -26,46 +26,48 @@ public class ColorMine {
 	 * 
 	 * @param a
 	 * @param b
-	 * @return Returns a score for how similar two colors are to each other, the
-	 *         lower the score the more similar the colors.
+	 * @return score for how similar two colors are to each other, the lower the
+	 *         score the more similar the colors.
 	 */
 
 	public static double calculateSimilarity(Color a, Color b) {
 		return ColorSpaceConverter.colorToLab(a).compare(ColorSpaceConverter.colorToLab(b));
 	}
 
 	/**
-	 * Determines if two given colors are complements of each other.
+	 * Determines if two given colors are complements of each other, the order
+	 * doesn't matter
 	 * 
-	 * @param firstColor
-	 * @param secondColor
-	 * @return Returns true if secondColor is a complement of first color.
+	 * @param a
+	 * @param b
+	 * @param tolerance
+	 * @return true if the colors are complements within passed in tolerance
 	 */
-	public static boolean isComplement(Color firstColor, Color secondColor, double tolerance) {
+	public static boolean isComplement(Color a, Color b, double tolerance) {
 
-		Color complementColor = getComplement(firstColor);
-		return ColorSpaceConverter.isNearMatch(complementColor, secondColor, tolerance);
+		Color complementColor = getComplement(a);
+		return ColorSpaceConverter.isNearMatch(complementColor, b, tolerance);
 	}
 
 	/**
 	 * Determines if two given colors are complements of each other using the
 	 * default tolerance of 1.0
 	 * 
-	 * @param firstColor
-	 * @param secondColor
-	 * @return Returns true if secondColor is a complement of first color.
+	 * @param a
+	 * @param b
+	 * @return true if the colors are complements within passed in tolerance
 	 */
-	public static boolean isComplement(Color firstColor, Color secondColor) {
+	public static boolean isComplement(Color a, Color b) {
 
-		Color complementColor = getComplement(firstColor);
-		return ColorSpaceConverter.isNearMatch(complementColor, secondColor, _defaultComplementTolerance);
+		Color complementColor = getComplement(a);
+		return ColorSpaceConverter.isNearMatch(complementColor, b, _defaultComplementTolerance);
 	}
 
 	/**
 	 * Gets the Complement of the given color.
 	 * 
 	 * @param color
-	 * @return Returns Color's complement
+	 * @return color representing the complement
 	 */
 	public static Color getComplement(Color color) {
 
@@ -81,8 +83,8 @@ public static Color getComplement(Color color) {
 	 * Returns a ColorProfile for a given Image.
 	 * 
 	 * @param image
-	 * @return Returns a profile containing a map of colors to how many times
-	 *         that color occurred in the image.
+	 * @return profile containing a map of colors to how many times that color
+	 *         occurred in the image.
 	 */
 
 	public static ColorProfile getColorProfile(Image image) {
@@ -103,7 +105,7 @@ public static Color[] getTriadic(Color color) {
 	 * Gets the Split Complements of the given color.
 	 * 
 	 * @param color
-	 * @return Array of the Split Complements colors for the given color
+	 * @return array of the split complements colors for the given color
 	 */
 	public static Color[] getSplitComplements(Color color) {
 		return getPointsOnColorWheel(color, 150, -150);

colormine/src/main/org/colormine/colorspace/ColorSpaceConverter.java

@@ -13,7 +13,7 @@ public class ColorSpaceConverter {
 	 * Converts a java.awt.Color to Lab color space
 	 * 
 	 * @param color
-	 * @return
+	 * @return color in Lab color space
 	 */
 	public static Lab colorToLab(Color color) {
 		Xyz xyz = colorToXyz(color);
@@ -24,7 +24,7 @@ public static Lab colorToLab(Color color) {
 	 * Converts a java.awt.Color to Xyz color space
 	 * 
 	 * @param color
-	 * @return
+	 * @return color in Xyz color space
 	 */
 	public static Xyz colorToXyz(Color color) {
 		double r = pivotRgb(color.getRed() / 255.0);
@@ -38,8 +38,8 @@ public static Xyz colorToXyz(Color color) {
 	/**
 	 * Converts Xyz to Lab color space
 	 * 
-	 * @param color
-	 * @return
+	 * @param xyz
+	 * @return color in Lab color space
 	 */
 	public static Lab xyzToLab(Xyz xyz) {
 		final double REF_X = 95.047; // Observer= 2°, Illuminant= D65
@@ -57,9 +57,8 @@ public static Lab xyzToLab(Xyz xyz) {
 	 * Converts a java.awt.Color to Hsl color space
 	 * 
 	 * @param color
-	 * @return
+	 * @return color in Hsl color space
 	 */
-
 	public static Hsl colorToHsl(Color color) {
 
 		double R = (color.getRed() / 255.0);
@@ -110,7 +109,7 @@ public static Hsl colorToHsl(Color color) {
 	 * Converts a Hsl color space to java.awt.Color
 	 * 
 	 * @param hsl
-	 * @return
+	 * @return color as java.awt.Color
 	 */
 
 	public static Color hslToColor(Hsl hsl) {
@@ -143,30 +142,38 @@ public static Color hslToColor(Hsl hsl) {
 	}
 
 	/**
-	 * Determines if two items are "close enough" given a tolerance
+	 * Determines if colors are "close enough" given a tolerance
 	 * 
 	 * @param firstColor
 	 * @param secondColor
 	 * @param nearMatchTolerance
-	 * @return
+	 * @return true if colors are "close enough"
 	 */
+
 	public static boolean isNearMatch(Color firstColor, Color secondColor, double nearMatchTolerance) {
 
 		int[] values = { firstColor.getRed(), firstColor.getGreen(), firstColor.getBlue() };
 		int[] values2 = { secondColor.getRed(), secondColor.getGreen(), secondColor.getBlue() };
 
 		return compareNearValue(values[0], values2[0], nearMatchTolerance) && compareNearValue(values[1], values2[1], nearMatchTolerance) && compareNearValue(values[2], values2[2], nearMatchTolerance);
+	}
 
+	public static boolean isNearMatch(ColorTuple firstColor, ColorTuple secondColor, double nearMatchTolerance) {
+		Double[] values = firstColor.getTuple();
+		Double[] values2 = secondColor.getTuple();
+		return compareNearValue(values[0], values2[0], nearMatchTolerance) && compareNearValue(values[1], values2[1], nearMatchTolerance) && compareNearValue(values[2], values2[2], nearMatchTolerance);
+	}
+
+	private static boolean compareNearValue(double value, double otherValue, double nearMatchTorrerance) {
+		return value == otherValue || Math.abs(value - otherValue) <= nearMatchTorrerance;
+	}
+
+	private final static double DoublePrecision = .000001;
+
+	private static boolean areCloseEnough(double a, double b) {
+		return Math.abs(a - b) < DoublePrecision;
 	}
 
-	/**
-	 * Helper method for converting hue to it's rgb value
-	 * 
-	 * @param v1
-	 * @param v2
-	 * @param vh
-	 * @return
-	 */
 	private static double hueToRgb(double v1, double v2, double vh) {
 		if (vh < 0.0) {
 			vh += 1.0;
@@ -191,73 +198,23 @@ private static double hueToRgb(double v1, double v2, double vh) {
 		return (v1);
 	};
 
-	private final static double DoublePrecision = .000001;
-
-	/**
-	 * Tells if doubles are close enough to the DoublePrecision
-	 * 
-	 * @param v1
-	 * @param v2
-	 * @param vh
-	 * @return
-	 */
-	private static boolean areCloseEnough(double a, double b) {
-		return Math.abs(a - b) < DoublePrecision;
-	}
-
-	/**
-	 * Helper function to improve readability
-	 * 
-	 * @param n
-	 * @return
-	 */
 	private static double pivotRgb(double n) {
 		return (n > 0.04045 ? Math.pow((n + 0.055) / 1.055, 2.4) : n / 12.92) * 100;
 	}
 
-	/**
-	 * Helper function to improve readability
-	 * 
-	 * @param n
-	 * @return
-	 */
 	private static double pivotXyz(double n) {
 		double i = Math.cbrt(n);
 		return n > 0.008856 ? i : 7.787 * n + 16 / 116;
 	}
 
-	/**
-	 * Get the largest number in an array
-	 * 
-	 * @param numbers
-	 * @return
-	 */
 	private static double max(double... numbers) {
 		Arrays.sort(numbers);
 		return numbers[numbers.length - 1];
 	}
 
-	/**
-	 * Get the smallest number in an array
-	 * 
-	 * @param numbers
-	 * @return
-	 */
 	private static double min(double... numbers) {
 		Arrays.sort(numbers);
 		return numbers[0];
 	}
 
-	/**
-	 * Determines if two values are close enough given a tolerance
-	 * 
-	 * @param value
-	 * @param otherValue
-	 * @param nearMatchTolerance
-	 * @return
-	 */
-	static boolean compareNearValue(double value, double otherValue, double nearMatchTorrerance) {
-		return value == otherValue || Math.abs(value - otherValue) <= nearMatchTorrerance;
-	}
-
 }

colormine/src/main/org/colormine/colorspace/ColorTuple.java

@@ -18,7 +18,7 @@ public abstract class ColorTuple implements Tuple<Double> {
 	 * formula in three dimensional space.
 	 * 
 	 * @param other
-	 * @return
+	 * @return the distance in 3d space
 	 */
 	public double compare(ColorTuple other) {
 		Double[] otherData = other.getTuple();
@@ -27,24 +27,22 @@ public double compare(ColorTuple other) {
 	}
 
 	/**
-	 * Determines if two items are "close enough" given a tolerance
+	 * Determines if two items are "close enough" given a tolerance.
 	 * 
-	 * @param firstColor
-	 * @param secondColor
-	 * @param nearMatchTolerance
-	 * @return
+	 * @param color
+	 * @param tolerance
+	 * @return true if images are "close enough"
 	 */
 	public boolean isNearMatch(ColorTuple color, double tolerance) {
-		Double[] values = color.getTuple();
-		Double[] values2 = this.getTuple();
-
-		return ColorSpaceConverter.compareNearValue(values[0], values2[0], tolerance) && ColorSpaceConverter.compareNearValue(values[1], values2[1], tolerance) && ColorSpaceConverter.compareNearValue(values[2], values2[2], tolerance);
+		return ColorSpaceConverter.isNearMatch(this, color, tolerance);
 	}
 
 	/**
 	 * Uses the result of the toString method so we can treat ColorTuples like a
 	 * value type, meaning that two ColorTuples of the same value will have the
 	 * same hash code even though they are different objects.
+	 * 
+	 * @return true if objects contain the same coordinates
 	 */
 	@Override
 	public boolean equals(Object o) {
@@ -58,14 +56,18 @@ public boolean equals(Object o) {
 	 * Uses the result of the toString method so we can treat ColorTuples like a
 	 * value type, meaning that two ColorTuples of the same value will have the
 	 * same hash code even though they are different objects.
+	 * 
+	 * @return hascode based on the value of the coordinates
 	 */
 	@Override
 	public int hashCode() {
 		return toString().hashCode();
 	}
 
 	/**
-	 * Returns a pretty-formatted version of the ColorTuple
+	 * Get easily readable string representation.
+	 * 
+	 * @return returns the coordinates in format %d-%d-%d for readability
 	 */
 	@Override
 	public String toString() {

colormine/src/main/org/colormine/colorspace/Hsl.java

@@ -24,6 +24,8 @@ public Hsl(double h, double s, double l) {
 	/**
 	 * Provides access to the coordinates that make up this color space in a
 	 * uniform way.
+	 * 
+	 * @return array containing the hsl coordinates
 	 */
 	@Override
 	public Double[] getTuple() {

colormine/src/main/org/colormine/colorspace/Lab.java

@@ -24,6 +24,8 @@ public Lab(double l, double a, double b) {
 	/**
 	 * Provides access to the coordinates that make up this color space in a
 	 * uniform way.
+	 * 
+	 * @return array containing the lab coordinates
 	 */
 	@Override
 	public Double[] getTuple() {

colormine/src/main/org/colormine/colorspace/Xyz.java

@@ -24,6 +24,8 @@ public Xyz(double x, double y, double z) {
 	/**
 	 * Provides access to the coordinates that make up this color space in a
 	 * uniform way.
+	 * 
+	 * @return array containing the xyz coordinates
 	 */
 	@Override
 	public Double[] getTuple() {

colormine/src/main/org/colormine/image/ColorImage.java

@@ -11,7 +11,7 @@ public class ColorImage implements Image {
 	private BufferedImage _image;
 
 	/**
-	 * Create from BufferedImage.
+	 * Create from BufferedImage
 	 * 
 	 * @param image
 	 */
@@ -20,31 +20,31 @@ public ColorImage(BufferedImage image) {
 	}
 
 	/**
-	 * Get image width.
+	 * Gets image width
 	 * 
-	 * @return
+	 * @return image width
 	 */
 	@Override
 	public int getWidth() {
 		return _image.getWidth();
 	}
 
 	/**
-	 * Get image height.
+	 * Gets image height
 	 * 
-	 * @return
+	 * @return image height
 	 */
 	@Override
 	public int getHeight() {
 		return _image.getHeight();
 	}
 
 	/**
-	 * Get Rgb value of a pixel specified by it's x and y coordinates.
+	 * Gets Rgb value of the pixel located at the position specified by x, y
 	 * 
 	 * @param x
 	 * @param y
-	 * @return
+	 * @return integer representation of the rgb value
 	 */
 	@Override
 	public int getRGB(int x, int y) {