Package dev.brachtendorf.jimagehash.matcher.persistent

Class PersitentBinaryTreeMatcher

java.lang.Object

dev.brachtendorf.jimagehash.matcher.TypedImageMatcher

dev.brachtendorf.jimagehash.matcher.persistent.PersistentImageMatcher

dev.brachtendorf.jimagehash.matcher.persistent.PersitentBinaryTreeMatcher

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ConsecutiveMatcher, CumulativeMatcher

public abstract class PersitentBinaryTreeMatcher
extends PersistentImageMatcher

* Persistent image matchers are a subset of TypedImageMatcher which can be saved to disk to be later reconstructed. They expose the method PersistentImageMatcher.serializeState(File) and PersistentImageMatcher.reconstructState(File, boolean).

The PersitentBinaryTreeMatcher implementation utilizes a binary tree as it's core to save hashes storing a reference to a unique identifier describing the hashed image. No data reference to the actual object is saved which allows to keep the data requirement small.

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 old hashes stay valid. This means that the matcher forbids changing the hashing algorithms used to created hashes as soon as a single hash was created.

Since:

3.0.0

Author:

Kilian

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class dev.brachtendorf.jimagehash.matcher.TypedImageMatcher

TypedImageMatcher.AlgoSettings

Field Summary

Fields

Modifier and Type	Field	Description
protected HashSet<String>	addedImages	keep track of images already added.
protected HashMap<HashingAlgorithm,BinaryTree<String>>	binTreeMap	Binary Tree holding results for each individual hashing algorithm
protected boolean	cacheAddedHashes
protected Map<HashingAlgorithm,Map<String,Hash>>	cachedHashes	Save the hashes of added images mapped to their unique id for fast retrieval.

Fields inherited from class dev.brachtendorf.jimagehash.matcher.persistent.PersistentImageMatcher

addedImageMap, lockedState

Fields inherited from class dev.brachtendorf.jimagehash.matcher.TypedImageMatcher

steps

Constructor Summary

Constructors

Constructor	Description
PersitentBinaryTreeMatcher(boolean cacheAddedHashes)	TODO handle serialization empty constructor?

Method Summary

Modifier and Type	Method	Description
void	addHashingAlgorithm(HashingAlgorithm algo, double threshold, boolean normalized)	Append a new hashing algorithm which will be executed after all hash algorithms passed the test.
protected void	addImageInternal(String uniqueId, BufferedImage image)	Add this image to the image matcher.
void	clearHashingAlgorithms()	Remove all hashing algorithms used by this image matcher instance.
boolean	equals(Object obj)
protected Hash	getHash(HashingAlgorithm algo, String uniqueId, BufferedImage bImage)
PriorityQueue<Result<String>>	getMatchingImages(BufferedImage image)	Search for all similar images passing the algorithm filters supplied to this matcher.
PriorityQueue<Result<String>>	getMatchingImages(File image)	Return a list of images that are considered matching by the definition of this matcher.
protected abstract PriorityQueue<Result<String>>	getMatchingImagesInternal(BufferedImage bi, String uniqueId)	Return a list of images that are considered matching by the definition of this matcher.
int	hashCode()
void	printAllTrees()	Print all binary trees currently in use by this image matcher.
boolean	removeHashingAlgo(HashingAlgorithm algo)	Removes the hashing algorithms from the image matcher.

Methods inherited from class dev.brachtendorf.jimagehash.matcher.persistent.PersistentImageMatcher

addHashingAlgorithm, addImage, addImage, addImage, addImages, checkLockedState, reconstructState, serializeState

Methods inherited from class dev.brachtendorf.jimagehash.matcher.TypedImageMatcher

getAlgorithms

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

addedImages

protected HashSet<String> addedImages

keep track of images already added. No reason to rehash

binTreeMap

protected HashMap<HashingAlgorithm,BinaryTree<String>> binTreeMap

Binary Tree holding results for each individual hashing algorithm

cacheAddedHashes

protected boolean cacheAddedHashes

cachedHashes

protected Map<HashingAlgorithm,Map<String,Hash>> cachedHashes

Save the hashes of added images mapped to their unique id for fast retrieval.

Constructor Detail

PersitentBinaryTreeMatcher

public PersitentBinaryTreeMatcher(boolean cacheAddedHashes)

TODO handle serialization empty constructor?

Parameters:

cacheAddedHashes - Additionally to the binary tree hashes of added images will be mapped to their uniqueId. This allows to retrieve matches of added images without loading the image file from disk speeding up the operation Immensely. Saving the hash in a hashmap increases memory overhead.

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

Method Detail

getMatchingImages

public PriorityQueue<Result<String>> getMatchingImages(File image)
                                                throws IOException

Description copied from class: PersistentImageMatcher

Return a list of images that are considered matching by the definition of this matcher.

Overrides:

getMatchingImages in class PersistentImageMatcher

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 PriorityQueue<Result<String>> getMatchingImages(BufferedImage image)

Description copied from class: PersistentImageMatcher

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

Specified by:

getMatchingImages in class PersistentImageMatcher

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

getMatchingImagesInternal

protected abstract PriorityQueue<Result<String>> getMatchingImagesInternal(BufferedImage bi,
                                                                           String uniqueId)

Return a list of images that are considered matching by the definition of this matcher.

This method is propagated by the super class allowing to utilize caching techniques to avoid reloading known images. Either the bufferedImage or the uniqueId argument is send depending on if the uniqueId is enough to query the hashes using the getHash(HashingAlgorithm, String, BufferedImage) method call.

Parameters:

bi - the buffered image to match or null

uniqueId - the uniqueId of a previously cached image or null

Returns:

a list of unique id's identifying the previously matched images sorted by distance.

addHashingAlgorithm

public void addHashingAlgorithm(HashingAlgorithm algo,
                                double threshold,
                                boolean normalized)

Append a new hashing algorithm which will be executed after all hash algorithms passed the test.

Overrides:

addHashingAlgorithm in class PersistentImageMatcher

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

removeHashingAlgo

public boolean removeHashingAlgo(HashingAlgorithm algo)

Removes the hashing algorithms from the image matcher.

Overrides:

removeHashingAlgo in class TypedImageMatcher

Parameters:

algo - the algorithm to be removed

Returns:

true if the algorithms was removed, false otherwise

clearHashingAlgorithms

public void clearHashingAlgorithms()

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 PersistentImageMatcher

addImageInternal

protected void addImageInternal(String uniqueId,
                                BufferedImage image)

Description copied from class: PersistentImageMatcher

Add this image to the image matcher.

Specified by:

addImageInternal in class PersistentImageMatcher

Parameters:

uniqueId - the unique id to refer to during lookup

image - the image to add

hashCode

public int hashCode()

Overrides:

hashCode in class TypedImageMatcher

equals

public boolean equals(Object obj)

Overrides:

equals in class TypedImageMatcher

getHash

protected Hash getHash(HashingAlgorithm algo,
                       String uniqueId,
                       BufferedImage bImage)

printAllTrees

public void printAllTrees()

Print all binary trees currently in use by this image matcher. This gives an internal view of the saved images