Package dev.brachtendorf.jimagehash.matcher.persistent

Class CumulativeMatcher

  • All Implemented Interfaces:
    Serializable
    public class CumulativeMatcher
extends PersitentBinaryTreeMatcher
    Instead of early aborting if one algorithm fails like the ConsecutiveMatcher, this class looks at the summed distance and decides if images match. 
     Example:
 A CumulativeInMemoryMatcher with a threshold of 0.6 (may be any value desired)
 
 Pass:
 Hasher  computes a distance of 0.1
 Hasher1 computes a distance of 0.4
 -------
 Since the summed distance of 0.5 is smaller than 0.6, the two images are considered a match
 
 Fail:
 Hasher computes a distance of 0.7
 Hasher1 not executed since distance already greater than threshold
 -----------------------------
 Not considered a match
    Additionally each hashing algorithm may be appointed a weight value which transforms the returned hash value accordingly, increasing or decreasing the importance of this algorithm.
    Since:
    2.0.0
    Author:
    Kilian
    See Also:
    Serialized Form

    • Constructor Detail

      • CumulativeMatcher

        public CumulativeMatcher​(boolean cacheAddedHashes,
                         double threshold)
        Create a cumulative in memory image matcher with the specified normalized threshold
        Parameters:
        cacheAddedHashes - Additionally to the binary tree, hashes of added images will be mapped to their uniqueId allowing to retrieve matches of added images without loading the image file from disk. This setting increases memory overhead in exchange for performance.

        Use this setting if calls to PersitentBinaryTreeMatcher.getMatchingImages(java.io.File) likely contains an image already added to the match prior.

        threshold - The cutoff threshold of the summed and scaled distances of all hashing algorithm until an image is considered a match.

        If a negative threshold is supplied no images will ever be returned.

        If additional algorithms are added an increase in the threshold parameter is justified.

      • CumulativeMatcher

        public CumulativeMatcher​(boolean cacheAddedHashes,
                         double threshold,
                         boolean normalized)
        Create a cumulative in memory image matcher with the specified threshold
        Parameters:
        cacheAddedHashes - Additionally to the binary tree, hashes of added images will be mapped to their uniqueId allowing to retrieve matches of added images without loading the image file from disk. This setting increases memory overhead in exchange for performance.

        Use this setting if calls to PersitentBinaryTreeMatcher.getMatchingImages(java.io.File) likely contains an image already added to the match prior.

        threshold - The cutoff threshold of the summed and scaled distances of all hashing algorithm until an image is considered a match.

        If a negative threshold is supplied no images will ever be returned.

        If additional algorithms are added an increase in the threshold parameter is justified.

        normalized - If true the threshold is considered the normalized distance created by each added Hashing algorithm.

    • Method Detail

      • addHashingAlgorithm

        public void addHashingAlgorithm​(HashingAlgorithm algo)
        Add a hashing algorithm to the matcher with a weight multiplier of 1. In order for images to match they have to be beneath the threshold of the summed distances of all added hashing algorithms.
        Parameters:
        algo - The algorithm to add to the matcher.

      • addHashingAlgorithm

        public void addHashingAlgorithm​(HashingAlgorithm algo,
                                double weight)
        Add a hashing algorithm to the matcher with the given weight multiplier. In order for images to match they have to be beneath the threshold of the summed distances of all added hashing algorithms.

        The weight parameter scales the returned hash distance. For example a weight multiplier of 2 means that the returned distance is multiplied by 2. If the total allowed distance of this matcher is 0.7 and the returned hash is 0.3 * 2 the next algorithm only may return a distance of 0.1 or smaller in order for the image to pass.

        Overrides:
        addHashingAlgorithm in class PersistentImageMatcher
        Parameters:
        algo - The algorithms to be added
        weight - The weight multiplier of this algorithm.

      • addHashingAlgorithm

        public void addHashingAlgorithm​(HashingAlgorithm algo,
                                double weight,
                                boolean dummy)
        Add a hashing algorithm to the matcher with the given weight multiplier. In order for images to match they have to be beneath the threshold of the summed distances of all added hashing algorithms. *

        The weight parameter scales the returned hash distance. For example a weight multiplier of 2 means that the returned distance is multiplied by 2. If the total allowed distance of this matcher is 0.7 and the returned hash is 0.3 * 2 the next algorithm only may return a distance of 0.1 or smaller in order for the image to pass.

        Overrides:
        addHashingAlgorithm in class PersitentBinaryTreeMatcher
        Parameters:
        algo - The algorithms to be added
        weight - The weight multiplier of this algorithm.
        dummy - not used by this type of image matcher. This method signature is only available due to inheritance.