Package dev.brachtendorf.jimagehash.matcher.categorize

Interface CategoricalImageMatcher

  • All Known Implementing Classes:
    AbstractCategoricalMatcher, CategoricalMatcher, KMeansClassifier, RandomForestCategorizer, WeightedCategoricalMatcher
    public interface CategoricalImageMatcher
    Image matcher allowing to group images into similar categories.

    Usually cluster results are requested immediately and images may get added over time resulting in clusters being moved around depending on the implementation details.

    Classes shall make a best effort to provide current clusters but usually require a call to recomputeCategories() be made to reflect changes of newly added images to be fully incorporated.

    Images are only referenced by a string identifier to allow computation with many images.

    Since:
    3.0.0
    Author:
    Kilian

    • Method Detail

      • categorizeImage

        default CategorizationResult categorizeImage​(File imageFile)
                                      throws IOException
        Compute the category of the supplied image. A category is a collection of similar images mapped to a common hash which minimizes the distance of all hashes mapped to this category.
        Parameters:
        imageFile - The image to categorize
        Returns:
        a pair whose first value returns the category and second value returns a distance measure between the category and the supplied image. Smaller distances meaning a closer match
        Throws:
        IOException - if an error occurs during file reading

      • categorizeImage

        CategorizationResult categorizeImage​(BufferedImage bi)
        Compute the category of the supplied image. A category is a collection of similar images mapped to a common hash which minimizes the distance of all hashes mapped to this category.
        Parameters:
        bi - The buffered image to categorize
        Returns:
        a pair whose first value returns the category and second value returns a distance measure between the category and the supplied image. Smaller distances meaning a closer match

      • categorizeImageAndAdd

        CategorizationResult categorizeImageAndAdd​(BufferedImage bi,
                                           String uniqueId)
        Compute the closest category of an image and afterwards add it to the internal categorization queue. Some matchers may choose to immediately update the current category to reflect the changes.

        The add action is implementation depended. Some categorizers may choose to directly incorporate the image and update it's category representation other algorithms may require a call to recomputeCategories() before the addition takes effect.

        Parameters:
        bi - the image to categorize
        uniqueId - the unique id to reference the image by.
        Returns:
        the currently closest cluster for this image.

      • categorizeImageAndAdd

        default CategorizationResult categorizeImageAndAdd​(File imageFile)
                                            throws IOException
        Compute the closest category of an image and afterwards add it to the internal categorization queue. Some matchers may choose to immediately update the current category to reflect the changes.

        The add action is implementation depended. Some categorizers may choose to directly incorporate the image and update it's category representation other algorithms may require a call to recomputeCategories() before the addition takes effect.

        The image will be referenced by the absolute file path as uniqueId.

        Parameters:
        imageFile - the image file to categorize
        Returns:
        the currently closest cluster for this image.
        Throws:
        IOException - if an error occurs during file reading operation

      • getCategories

        List<Integer> getCategories()
        Get a list of available categories this matcher matched images to. Each category represents a set of images with high similarity.
        Returns:
        A list of id's

      • recomputeCategories

        void recomputeCategories()
        Recompute the category definition of this clustering matcher and it's nested matchers.

        Recomputing categories will take recently added images into account and update image/category affiliation if necessary. This operation needs to be called manually due to the potential high cost of this method call.

        Unless otherwise noted the matcher makes no guarantee that the image category does not change with this method execution.

      • getImagesInCategory

        List<String> getImagesInCategory​(int category)
        Get the unique id's of all images mapped to this category
        Parameters:
        category - to check for
        Returns:
        a list of all unique id's mapped to this category

      • getCategory

        int getCategory​(String uniqueId)
        Get the current category of the image described by this unique id. A category usually maps an image to a cluster.
        Parameters:
        uniqueId - the id of a previously added image
        Returns:
        the category