Package dev.brachtendorf.jimagehash.datastructures.tree.binaryTree

Class BinaryTree<T>

  • All Implemented Interfaces:
    Serializable
    public class BinaryTree<T>
extends AbstractBinaryTree<T>
    A not thread safe binary tree implementation used to quickly compute the hamming distance of multiple hashes. The tree can be used to keep all hashes in memory, if a persistent storage is required take a look at the database examples.

    To keep storage space minimal the tree is lazily populated and creates nodes on the fly only if the node is required to represent a hash.

    Example Hash(1011011)
    • The left child of a node represents a 1 bit
    • The right child of a node represents a 0 bit
    • Padding bit 1 is ignored as it's the same
           root
              0
           1
        1
           0
        1
   leaf
    Using a tree like structure allows to prune searches once the distance of the current branch deviates further away than the threshold would allow.

    Currently the tree only allows traversal from the root node allowing to search all hashes which are within a given distance from a needle. A more performant optimization might save the leaves in a hash structure and keep a reference to the parent nodes allowing to start searching from the leaf instead.

    Author:
    Kilian
    See Also:
    Serialized Form

    • Constructor Detail

      • BinaryTree

        public BinaryTree​(boolean ensureHashConsistency)
        Parameters:
        ensureHashConsistency - If true adding and matching hashes will check weather they are generated by the same algorithms as the first hash added to the tree

      • BinaryTree

        protected BinaryTree()

    • Method Detail

      • addHash

        public void addHash​(Hash hash,
                    T value)
        Description copied from class: AbstractBinaryTree
        Insert a value associated with the supplied hash in the binary tree (similar to a map). Saved values can be found by invoking AbstractBinaryTree.getElementsWithinHammingDistance(dev.brachtendorf.jimagehash.hash.Hash, int).

        Nodes which do not exist will be created. Please be aware that similar to comparing different hashes for images only hashes produced by the same algorithms will return useable results.

        If the tree is configured to ensureHashConsistency this function will throw an unchecked IlleglStateException if the added hash does not comply with the first hash added to the tree.

        Overrides:
        addHash in class AbstractBinaryTree<T>
        Parameters:
        hash - The hash used to save the value in the tree
        value - The value which will be returned if the hash . Common values point to the image used to create the hash or an id in a SQL table

      • getElementsWithinHammingDistance

        public PriorityQueue<Result<T>> getElementsWithinHammingDistance​(Hash hash,
                                                                 int maxDistance)
        Return all elements of the tree whose hamming distance is smaller or equal than the supplied max distance. If the tree is configured to ensureHashConsistency this function will throw an unchecked IlleglStateException if the checked hash does not comply with the first hash added to the tree.
        Specified by:
        getElementsWithinHammingDistance in class AbstractBinaryTree<T>
        Parameters:
        hash - The hash to search for
        maxDistance - The maximal hamming distance deviation all found hashes may possess. A distance of 0 will return all objects added whose hash is exactly the hash supplied as the first argument
        Returns:
        Search results contain objects and distances matching the search criteria. The results returned are ordered to return the closest match first.

      • getNearestNeighbour

        public List<Result<T>> getNearestNeighbour​(Hash hash)
        Retrieve the hash that is the most similar to the queried hash. The closest hash is the hash with the smallest distance.
        Specified by:
        getNearestNeighbour in class AbstractBinaryTree<T>
        Parameters:
        hash - to search the neighbor for.
        Returns:
        the closest hash saved in this tree.
        Since:
        3.0.0