Package dev.brachtendorf.jimagehash.matcher.persistent

Class PersistentImageMatcher

  • All Implemented Interfaces:
    Serializable
    Direct Known Subclasses:
    PersitentBinaryTreeMatcher
    public abstract class PersistentImageMatcher
extends TypedImageMatcher
implements Serializable
    Persistent image matchers are a subset of TypedImageMatcher which can be saved to disk to be later reconstructed. They expose the method serializeState(File) and reconstructState(File, boolean).

    Since serialized hashes can not be updated or recreated due to the source of the hash not being available anymore the persistent matcher needs to ensure that the binary tree stays in a valid state. This means that the matcher forbids adding new hashing algorithms as soon as a single hash was created.

    Implnote: classes extending persistent image matcher need to ensure that their internal state can be serialized.

    Since:
    3.0.0
    Author:
    Kilian
    See Also:
    Serialized Form

    • Field Detail

      • lockedState

        protected boolean lockedState

    • Constructor Detail

      • PersistentImageMatcher

        protected PersistentImageMatcher()
        Non args constructor for serialization

    • Method Detail

      • addHashingAlgorithm

        public void addHashingAlgorithm​(HashingAlgorithm algo,
                                double threshold)
        Description copied from class: TypedImageMatcher
        Append a new hashing algorithm which will be executed after all hash algorithms passed the test.

        The same algorithm may only be added once. Attempts to add an identical algorithm will instead update the settings of the old instance.

        This method assumes the normalized hamming distance. If the definite distance shall be used take a look at TypedImageMatcher.addHashingAlgorithm(HashingAlgorithm, double, boolean)

        Overrides:
        addHashingAlgorithm in class TypedImageMatcher
        Parameters:
        algo - The algorithms to be added
        threshold - maximum normalized hamming distance between hashes in order to pass as identical image

      • addHashingAlgorithm

        public void addHashingAlgorithm​(HashingAlgorithm algo,
                                double threshold,
                                boolean normalized)
        Description copied from class: TypedImageMatcher
        Append a new hashing algorithm which will be executed after all hash algorithms passed the test.

        The same algorithm may only be added once to an image hasher. Attempts to add an identical algorithm will instead update the settings of the old instance.

        Overrides:
        addHashingAlgorithm in class TypedImageMatcher
        Parameters:
        algo - The algorithms to be added
        threshold - the threshold the hamming distance may be in order to pass as identical image.
        normalized - Weather the normalized or default hamming distance shall be used. The normalized hamming distance will be in range of [0-1] while the hamming distance depends on the length of the hash

      • clearHashingAlgorithms

        public void clearHashingAlgorithms()
        Description copied from class: TypedImageMatcher
        Remove all hashing algorithms used by this image matcher instance. At least one algorithm has to be supplied before imaages can be checked for similarity
        Overrides:
        clearHashingAlgorithms in class TypedImageMatcher

      • addImage

        public void addImage​(File imageFile)
              throws IOException
        Index the image. This enables the image matcher to find the image in future searches. The database image matcher does not store the image data itself but indexes the hash bound to the absolute path of the image.

        The path of the file has to be unique in order for this operation to return deterministic results.

        Parameters:
        imageFile - The image whose hash will be added to the matcher
        Throws:
        IOException - if an error exists reading the file

      • addImages

        public void addImages​(File... imagesToAdd)
               throws IOException
        Add the images to the matcher allowing the image to be found in future searches.
        Parameters:
        imagesToAdd - The images whose hash will be added to the matcher
        Throws:
        IOException - if an error exists reading the image files

      • addImage

        public void addImage​(String uniqueId,
                     File imageFile)
              throws IOException
        Index the image. This enables the image matcher to find the image in future searches. The database image matcher does not store the image data itself but indexes the hash bound to the absolute path of the image.

        The uniqueId has to be globally unique in order for this operation to return deterministic results.

        Parameters:
        uniqueId - a unique identifier returned if querying for the image
        imageFile - The image whose hash will be added to the matcher
        Throws:
        IOException - if an error exists reading the file
        Since:
        2.0.2

      • addImage

        public void addImage​(String uniqueId,
                     BufferedImage image)

        Implnote: if this method is overwritten the class has to make sure that the field lockedState is correctly updated when ever an image was added to the matcher.

        Parameters:
        uniqueId - a unique identifier describing the image
        image - The image whose hash will be added to the matcher

      • addImageInternal

        protected abstract void addImageInternal​(String uniqueId,
                                         BufferedImage image)
        Add this image to the image matcher.
        Parameters:
        uniqueId - the unique id to refer to during lookup
        image - the image to add

      • getMatchingImages

        public PriorityQueue<Result<String>> getMatchingImages​(File image)
                                                throws IOException
        Return a list of images that are considered matching by the definition of this matcher.
        Parameters:
        image - the image to check all saved images against
        Returns:
        a list of unique id's identifying the previously matched images sorted by distance.
        Throws:
        IOException - if an error occurs reading the file

      • getMatchingImages

        public abstract PriorityQueue<Result<String>> getMatchingImages​(BufferedImage image)
        Search for all similar images passing the algorithm filters supplied to this matcher. If the image itself was added to the tree it will be returned with a distance of 0
        Parameters:
        image - the image to check all saved images against
        Returns:
        a list of unique id's identifying the previously matched images sorted by distance of the last applied algorithm

      • serializeState

        public void serializeState​(File saveLocation)
                    throws IOException
        Serialize this image matcher to a file. Serialized matchers keep their internal state and can be reconstructed at a later stage without needing to rehash all images.

        To reconstruct the matcher take a look at reconstructState(File, boolean);

        Parameters:
        saveLocation - the location to save the matcher object to
        Throws:
        IOException - if an io error occurs during serialzation.

      • reconstructState

        public static PersistentImageMatcher reconstructState​(File saveLocation,
                                                      boolean deleteSerFile)
                                               throws ClassNotFoundException,
                                                      IOException
        Construct a persistent image matcher from a serialization file and rebuild it's internal state.
        Parameters:
        saveLocation - the serialization file as specified in serializeState(File)
        deleteSerFile - If true deletes the serialization file after reading the object
        Returns:
        the matcher saved to the file
        Throws:
        ClassNotFoundException - Class of a serialized object cannot be found
        IOException - if an IOerror occurs during reading the file

      • checkLockedState

        protected void checkLockedState()