finalize opaque image handling fixes #38

Author: KilianB

Diff for: README.md

@@ -5,19 +5,19 @@
 [![Travis](https://travis-ci.org/KilianB/JImageHash.svg?branch=master)](https://travis-ci.org/KilianB/JImageHash)
 [![GitHub license](https://img.shields.io/github/license/KilianB/JImageHash.svg)](https://github.com/KilianB/JImageHash/blob/master/LICENSE)
 [![Download](https://api.bintray.com/packages/kilianb/maven/JImageHash/images/download.svg)](https://bintray.com/kilianb/maven/JImageHash/_latestVersion)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/3c7db745b9ff4dd9b89484a6aa46ad2f)](https://www.codacy.com/app/KilianB/JImageHash?utm_source=github.com&utm_medium=referral&utm_content=KilianB/JImageHash&utm_campaign=Badge_Grade)
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/3c7db745b9ff4dd9b89484a6aa46ad2f)](https://www.codacy.com/app/KilianB/JImageHash?utm_source=github.com&utm_medium=referral&utm_content=KilianB/JImageHash&utm_campaign=Badge_Grade)
 
 JImageHash is a performant perceptual image fingerprinting library entirely written in Java. The library returns a similarity score aiming to identify entities which are likely modifications of the original source while being robust various attack vectors ie. color, rotation and scale transformation.
 
->  A perceptual hash is a fingerprint of a multimedia file derived from various features from its content. Unlike cryptographic hash functions which rely on the avalanche effect of small changes in input leading to drastic changes in the output, perceptual hashes are "close" to one another if the features are similar.
+> A perceptual hash is a fingerprint of a multimedia file derived from various features from its content. Unlike cryptographic hash functions which rely on the avalanche effect of small changes in input leading to drastic changes in the output, perceptual hashes are "close" to one another if the features are similar.
 
-This library was inspired by _Dr. Neal Krawetz_ blog post "<a href="http://www.hackerfactor.com/blog/index.php?/archives/529-Kind-of-Like-That.html">kind of like that</a>" and incorporates several improvements. A comprehensive overview of perceptual image hashing can be found in this <a href="https://www.phash.org/docs/pubs/thesis_zauner.pdf">paper</a> by Christoph Zauner. 
+This library was inspired by _Dr. Neal Krawetz_ blog post "<a href="http://www.hackerfactor.com/blog/index.php?/archives/529-Kind-of-Like-That.html">kind of like that</a>" and incorporates several improvements. A comprehensive overview of perceptual image hashing can be found in this <a href="https://www.phash.org/docs/pubs/thesis_zauner.pdf">paper</a> by Christoph Zauner.
 
 ## Maven
 
-The project is hosted on maven central. __Please be aware that migrating from one major version to another usually invalidates created hashes in order to retain validity when persistently storing the hashes.__
+The project is hosted on maven central. **Please be aware that migrating from one major version to another usually invalidates created hashes in order to retain validity when persistently storing the hashes.**
 
-````XML
+```XML
 <dependency>
 	<groupId>dev.brachtendorf</groupId>
 	<artifactId>JImageHash</artifactId>
@@ -30,40 +30,61 @@ The project is hosted on maven central. __Please be aware that migrating from on
 	<artifactId>h2</artifactId>
 	<version>1.4.197</version>
 </dependency>
-````
+```
 
 ## Hello World
 
-````Java
+```Java
 File img0 = new File("path/to/file.png");
 File img1 = new File("path/to/secondFile.jpg");
-		
+
 HashingAlgorithm hasher = new PerceptiveHash(32);
-		
+
 Hash hash0 = hasher.hash(img0);
 Hash hash1 = hasher.hash(img1);
-		
+
 double similarityScore = hash0.normalizedHammingDistance(hash1);
-		
+
 if(similarityScore < .2) {
     //Considered a duplicate in this particular case
 }
-		
+
 //Chaining multiple matcher for single image comparison
 
 SingleImageMatcher matcher = new SingleImageMatcher();
 matcher.addHashingAlgorithm(new AverageHash(64),.3);
 matcher.addHashingAlgorithm(new PerceptiveHash(32),.2);
-		
+
 if(matcher.checkSimilarity(img0,img1)) {
     //Considered a duplicate in this particular case
 }
-````
+```
 
 ## Examples
 
-Examples and convenience methods can be found in the [examples repository](https://github.com/KilianB/JImageHash-Examples) 
+Examples and convenience methods can be found in the [examples repository](https://github.com/KilianB/JImageHash-Examples)
+
+## Transparent image support
+
+Support for transparent images has to be enabled specifically due to backwards compatibility and force users of the libraries to understand the implication of this setting.
+
+The `setOpaqueHandling(Color? replacementColor, int alphaThreshold)` will replace transparent pixels with the specified color before calculating the hash.
+
+### Be aware of the following culprits: 
 
+- the replacement color must be consistent throughout hash calculation for the entire sample space to ensure robustness against color transformations of the images.
+- the replacement color should be a color that does not appear often in the input space to avoid masking out available information.
+- when not specified `Orange` will be used as replacement. This choice was arbitrary and ideally, a default color should be chosen which results in 0 and 1 bits being computed in 50% of the time in respect to all other pixels and hashing algorithms.
+- supplying a replacement value of null will attempt to either use black or white as a replacement color conflicting with the advice given above. Computing the contrast color will fail if the transparent area of an image covers a large space and comes with a steep performance penalty.
+
+```java
+HashingAlgorithm hasher = new PerceptiveHash(32);
+
+//Replace all pixels with alpha values smaller than 0-255. The alpha value cutoff is taken into account after down scaling the image, therefore choose a reasonable value.  
+int alphaThreshold = 253;
+hasher.setOpaqueHandling(alphaThreshold)
+
+```
 
 ## Multiple types image matchers are available for each situation
 
@@ -89,15 +110,15 @@ The `exotic` package features BloomFilter, and the SingleImageMatcher used to ma
 	<td><p align="center"><image src="https://via.placeholder.com/30/228B22?text=+"/></p></td> 
 	<td><p align="center"><image src="https://via.placeholder.com/30/228B22?text=+"/></p></td> 
 	<td><p align="center"><image src="https://via.placeholder.com/30/DC143C?text=+"/></p></td>
-</tr> 
+</tr>
 
  <tr> <td>Altered Copyright</td>  <td><img width= 75% src="https://user-images.githubusercontent.com/9025925/36542411-0438eb36-17e1-11e8-9a59-2c69937560bf.jpg"> </td> 
 <td><p align="center"><image src="https://via.placeholder.com/30/228B22?text=+"/></p></td> 
 	<td><p align="center"><image src="https://via.placeholder.com/30/228B22?text=+"/></p></td> 
 	<td><p align="center"><image src="https://via.placeholder.com/30/228B22?text=+"/></p></td> 
 	<td><p align="center"><image src="https://via.placeholder.com/30/228B22?text=+"/></p></td> 
 	<td><p align="center"><image src="https://via.placeholder.com/30/DC143C?text=+"/></p></td>
-</tr> 
+</tr>
 
 <tr> <td>Thumbnail</td>  <td><img src="https://user-images.githubusercontent.com/9025925/36542415-04ca8078-17e1-11e8-9be4-9a90b08c404b.jpg"></td> 
 <td><p align="center"><image src="https://via.placeholder.com/30/228B22?text=+"/></p></td> 
@@ -117,10 +138,10 @@ The `exotic` package features BloomFilter, and the SingleImageMatcher used to ma
 
 </table>
 
-
 ## Hashing algorithm
 
 Image matchers can be configured using different algorithm. Each comes with individual properties
+
 <table>
   <tr><th>Algorithm</th>  <th>Feature</th><th>Notes</th> </tr>
   <tr><td><a href="https://github.com/KilianB/JImageHash/wiki/Hashing-Algorithms#averagehash-averagekernelhash-medianhash-averagecolorhash">AverageHash</a></td>  <td>Average Luminosity</td> <td>Fast and good all purpose algorithm</td> </tr>
@@ -143,8 +164,7 @@ Image clustering with fuzzy hashes allowing to represent hashes with probability
 
 ![1_fxpw79yoon8xo3slqsvmta](https://user-images.githubusercontent.com/9025925/51272388-439d9600-19ca-11e9-8220-fe3539ed6061.png)
 
-
-### Algorithm benchmarking 
+### Algorithm benchmarking
 
 See the wiki page on how to test different hashing algorithms with your set of images
 

Diff for: src/main/java/com/github/kilianB/hashAlgorithms/HashingAlgorithm.java

@@ -13,6 +13,7 @@
 import javax.imageio.ImageIO;
 
 import dev.brachtendorf.Require;
+import dev.brachtendorf.graphics.ColorUtil;
 import dev.brachtendorf.graphics.FastPixel;
 import dev.brachtendorf.graphics.ImageUtil;
 
@@ -69,10 +70,10 @@ public abstract class HashingAlgorithm implements Serializable {
 	private int algorithmId;
 
 	/** Color used in replacement of opaque pixels */
-	protected Color opaqueReplacementColor = Color.WHITE;
+	protected Color opaqueReplacementColor = Color.orange;
 
 	/** Maximum alpha value a pixel must have in order to be replaced */
-	protected int opaqueReplacementThreshold = 2;
+	protected int opaqueReplacementThreshold = -1;
 
 	/**
 	 * After a hash was created or the id was calculated the object may not be
@@ -110,7 +111,10 @@ public HashingAlgorithm(int bitResolution) {
 	 * entirely black image while for the user these images are perceptually
 	 * different.
 	 * 
-	 * @param replacementColor The color used to replace opaque values
+	 * @param replacementColor The color used to replace opaque values. A color
+	 *                         should be chosen which is unlikely to be part of the
+	 *                         target images. By default an orange color is
+	 *                         selected. If a value of null is provided
 	 * @param alphaThreshold   All colors with a value lower or equal value [0-255]
 	 *                         will be replaced.
 	 *                         <ul>
@@ -127,11 +131,35 @@ public void setOpaqueHandling(Color replacementColor, int alphaThreshold) {
 		if (immutableState) {
 			throw new IllegalStateException(LOCKED_MODIFICATION_EXCEPTION);
 		}
-
 		this.opaqueReplacementColor = replacementColor;
 		this.opaqueReplacementThreshold = alphaThreshold;
 	}
 
+	/**
+	 * Define how the algorithm shall handle images with alpha value. Hashing
+	 * algorithms usually depend on the luminosity value, which by default will be
+	 * treated as being black.
+	 * <p>
+	 * Sometimes display software may choose to display missing pixels in a
+	 * different color e.g. white. For the algorithm this would result in an
+	 * entirely black image while for the user these images are perceptually
+	 * different.
+	 * 
+	 * @param alphaThreshold All colors with a value lower or equal value [0-255]
+	 *                       will be replaced.
+	 *                       <ul>
+	 *                       <li>0 means only invisible (entirely opaque pixels will
+	 *                       be replaced)</li>
+	 *                       <li></li>
+	 *                       </ul>
+	 * @throws IllegalStateException if a hash was already created and the object is
+	 *                               considered immutable.
+	 * @since 3.0.1
+	 */
+	public void setOpaqueHandling(int alphaThreshold) {
+		setOpaqueHandling(this.opaqueReplacementColor, alphaThreshold);
+	}
+
 	/**
 	 * @return color used in replacement of opaque pixels
 	 * @since 3.0.1
@@ -266,9 +294,26 @@ public Hash hash(File imageFile) throws IOException {
 	protected abstract BigInteger hash(BufferedImage image, HashBuilder hashBuilder);
 
 	protected FastPixel createPixelAccessor(BufferedImage image, int width, int height) {
-		FastPixel fp = FastPixel.create(ImageUtil.getScaledInstance(image, width, height));
-		if (this.opaqueReplacementThreshold > 0) {
-			fp.setReplaceOpaqueColors(this.opaqueReplacementThreshold, this.opaqueReplacementColor);
+
+		BufferedImage scaledInstance = ImageUtil.getScaledInstance(image, width, height);
+		FastPixel fp = FastPixel.create(scaledInstance);
+
+		// If opaque handling is specified and the image has an alpha channel
+		if (this.opaqueReplacementThreshold >= 0 && fp.hasAlpha()) {
+			/**
+			 * If no color is specified grab the contrast color. This operation might not be
+			 * the best for hash calculation depending on how the color is interpolated. The
+			 * interpolated Color might be black for white images if the alpha is in the
+			 * majority.
+			 */
+			if (this.opaqueReplacementColor == null) {
+
+				javafx.scene.paint.Color interpolatedColor = ImageUtil.interpolateColor(image);
+				Color replacementColor = ColorUtil.getContrastColor(ColorUtil.fxToAwtColor(interpolatedColor));
+				fp.setReplaceOpaqueColors(this.opaqueReplacementThreshold, replacementColor);
+			} else {
+				fp.setReplaceOpaqueColors(this.opaqueReplacementThreshold, this.opaqueReplacementColor);
+			}
 		}
 		return fp;
 	}
@@ -291,6 +336,13 @@ public final int algorithmId() {
 			algorithmId = 31 * precomputeAlgoId();
 			// Make sure the algo id doesn't collide with version 2.0.0 id's
 			algorithmId = 31 * algorithmId + 5 + preProcessing.hashCode();
+
+			// Change hash code only if transparency is supported
+			if (this.opaqueReplacementThreshold >= 0) {
+				algorithmId = 31 * algorithmId
+						+ Objects.hash(this.opaqueReplacementThreshold, this.opaqueReplacementColor);
+			}
+
 			immutableState = true;
 		}
 		return algorithmId;
@@ -442,6 +494,22 @@ public boolean equals(Object obj) {
 		HashingAlgorithm other = (HashingAlgorithm) obj;
 		if (algorithmId() != other.algorithmId())
 			return false;
+
+		if (this.opaqueReplacementThreshold >= 0 && other.opaqueReplacementThreshold >= 0) {
+
+			if (this.opaqueReplacementThreshold != other.opaqueReplacementThreshold) {
+				return false;
+			}
+			if (!this.opaqueReplacementColor.equals(other.opaqueReplacementColor)) {
+				return false;
+			}
+
+		} else if (this.opaqueReplacementThreshold < 0 && other.opaqueReplacementThreshold < 0) {
+
+		} else {
+			return false;
+		}
+
 		return true;
 	}
 }

Diff for: src/main/java/com/github/kilianB/hashAlgorithms/experimental/HogHash.java

@@ -161,9 +161,7 @@ public HogHash(int bitResolution) {
 
 	@Override
 	protected BigInteger hash(BufferedImage image, HashBuilder hash) {
-
-		BufferedImage bi = ImageUtil.getScaledInstance(image, width, height);
-		FastPixel fp = FastPixel.create(bi);
+		FastPixel fp = createPixelAccessor(image, width, height);
 
 		int[][] lum = fp.getLuma();
 

Diff for: src/main/java/com/github/kilianB/hashAlgorithms/experimental/HogHashAngularEncoded.java

@@ -59,9 +59,7 @@ public HogHashAngularEncoded(int width, int height, int cellWidth, int numBins)
 
 	@Override
 	protected BigInteger hash(BufferedImage image, HashBuilder hash) {
-
-		BufferedImage bi = ImageUtil.getScaledInstance(image, width, height);
-		FastPixel fp = FastPixel.create(bi);
+		FastPixel fp = createPixelAccessor(image, width, height);
 
 		int[][] lum = fp.getLuma();
 

Diff for: src/main/java/com/github/kilianB/hashAlgorithms/experimental/HogHashDual.java

@@ -66,10 +66,7 @@ public HogHashDual(int bitResolution) {
 
 	@Override
 	protected BigInteger hash(BufferedImage image, HashBuilder hash) {
-
-		
-		BufferedImage bi = ImageUtil.getScaledInstance(image, width, height);
-		FastPixel fp = FastPixel.create(bi);
+		FastPixel fp = createPixelAccessor(image, width, height);
 
 		int[][] lum = fp.getLuma();
 

Diff for: src/test/java/com/github/kilianB/TestResources.java

@@ -25,13 +25,19 @@ public class TestResources {
 	public static BufferedImage highQuality;
 	public static BufferedImage lowQuality;
 	public static BufferedImage thumbnail;
+
 	public static BufferedImage lenna;
 	public static BufferedImage lenna90;
 	public static BufferedImage lenna180;
 	public static BufferedImage lenna270;
 
 	public static BufferedImage white;
 
+	public static BufferedImage transparent0;
+	public static BufferedImage transparent1;
+	public static BufferedImage transparent0White;
+	public static BufferedImage transparent1White;
+
 	static {
 		try {
 			ballon = ImageIO.read(TestResources.class.getClassLoader().getResourceAsStream("ballon.jpg"));
@@ -45,6 +51,15 @@ public class TestResources {
 			lenna270 = ImageIO.read(TestResources.class.getClassLoader().getResourceAsStream("Lenna270.png"));
 
 			white = ImageIO.read(TestResources.class.getClassLoader().getResourceAsStream("white.jpg"));
+
+			transparent0 = ImageIO.read(TestResources.class.getClassLoader().getResourceAsStream("transparent0.png"));
+			transparent1 = ImageIO.read(TestResources.class.getClassLoader().getResourceAsStream("transparent1.png"));
+
+			transparent0White = ImageIO
+					.read(TestResources.class.getClassLoader().getResourceAsStream("transparent0White.png"));
+			transparent1White = ImageIO
+					.read(TestResources.class.getClassLoader().getResourceAsStream("transparent1White.png"));
+
 		} catch (IOException e) {
 			e.printStackTrace();
 		}
@@ -71,6 +86,14 @@ public void allResourcesLoaded() {
 			assertTrue(lenna180.getWidth() > 0);
 		}, () -> {
 			assertTrue(lenna270.getWidth() > 0);
+		}, () -> {
+			assertTrue(transparent0.getWidth() > 0);
+		}, () -> {
+			assertTrue(transparent1.getWidth() > 0);
+		}, () -> {
+			assertTrue(transparent0White.getWidth() > 0);
+		}, () -> {
+			assertTrue(transparent1White.getWidth() > 0);
 		}, () -> {
 			assertTrue(white.getWidth() > 0);
 		});