Class PCTSignatures


  • public class PCTSignatures
    extends Algorithm
    Class implementing PCT (position-color-texture) signature extraction as described in CITE: KrulisLS16. The algorithm is divided to a feature sampler and a clusterizer. Feature sampler produces samples at given set of coordinates. Clusterizer then produces clusters of these samples using k-means algorithm. Resulting set of clusters is the signature of the input image. A signature is an array of SIGNATURE_DIMENSION-dimensional points. Used dimensions are: weight, x, y position; lab color, contrast, entropy. CITE: KrulisLS16 CITE: BeecksUS10
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected PCTSignatures​(long addr)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static PCTSignatures __fromPtr__​(long addr)  
      void computeSignature​(Mat image, Mat signature)
      Computes signature of given image.
      void computeSignatures​(List<Mat> images, List<Mat> signatures)
      Computes signatures for multiple images in parallel.
      static PCTSignatures create()
      Creates PCTSignatures algorithm using sample and seed count.
      static PCTSignatures create​(int initSampleCount)
      Creates PCTSignatures algorithm using sample and seed count.
      static PCTSignatures create​(int initSampleCount, int initSeedCount)
      Creates PCTSignatures algorithm using sample and seed count.
      static PCTSignatures create​(int initSampleCount, int initSeedCount, int pointDistribution)
      Creates PCTSignatures algorithm using sample and seed count.
      static PCTSignatures create​(MatOfPoint2f initSamplingPoints, int initSeedCount)
      Creates PCTSignatures algorithm using pre-generated sampling points and number of clusterization seeds.
      static PCTSignatures create​(MatOfPoint2f initSamplingPoints, MatOfInt initClusterSeedIndexes)
      Creates PCTSignatures algorithm using pre-generated sampling points and clusterization seeds indexes.
      static void drawSignature​(Mat source, Mat signature, Mat result)
      Draws signature in the source image and outputs the result.
      static void drawSignature​(Mat source, Mat signature, Mat result, float radiusToShorterSideRatio)
      Draws signature in the source image and outputs the result.
      static void drawSignature​(Mat source, Mat signature, Mat result, float radiusToShorterSideRatio, int borderThickness)
      Draws signature in the source image and outputs the result.
      protected void finalize()  
      static void generateInitPoints​(MatOfPoint2f initPoints, int count, int pointDistribution)
      Generates initial sampling points according to selected point distribution.
      int getClusterMinSize()
      This parameter multiplied by the index of iteration gives lower limit for cluster size.
      int getDistanceFunction()
      Distance function selector used for measuring distance between two points in k-means.
      float getDropThreshold()
      Remove centroids in k-means whose weight is lesser or equal to given threshold.
      int getGrayscaleBits()
      Color resolution of the greyscale bitmap represented in allocated bits (i.e., value 4 means that 16 shades of grey are used).
      int getInitSeedCount()
      Number of initial seeds (initial number of clusters) for the k-means algorithm.
      MatOfInt getInitSeedIndexes()
      Initial seeds (initial number of clusters) for the k-means algorithm.
      int getIterationCount()
      Number of iterations of the k-means clustering.
      float getJoiningDistance()
      Threshold euclidean distance between two centroids.
      int getMaxClustersCount()
      Maximal number of generated clusters.
      int getSampleCount()
      Number of initial samples taken from the image.
      MatOfPoint2f getSamplingPoints()
      Initial samples taken from the image.
      float getWeightA()
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      float getWeightB()
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      float getWeightContrast()
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      float getWeightEntropy()
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      float getWeightL()
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      float getWeightX()
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      float getWeightY()
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      int getWindowRadius()
      Size of the texture sampling window used to compute contrast and entropy (center of the window is always in the pixel selected by x,y coordinates of the corresponding feature sample).
      void setClusterMinSize​(int clusterMinSize)
      This parameter multiplied by the index of iteration gives lower limit for cluster size.
      void setDistanceFunction​(int distanceFunction)
      Distance function selector used for measuring distance between two points in k-means.
      void setDropThreshold​(float dropThreshold)
      Remove centroids in k-means whose weight is lesser or equal to given threshold.
      void setGrayscaleBits​(int grayscaleBits)
      Color resolution of the greyscale bitmap represented in allocated bits (i.e., value 4 means that 16 shades of grey are used).
      void setInitSeedIndexes​(MatOfInt initSeedIndexes)
      Initial seed indexes for the k-means algorithm.
      void setIterationCount​(int iterationCount)
      Number of iterations of the k-means clustering.
      void setJoiningDistance​(float joiningDistance)
      Threshold euclidean distance between two centroids.
      void setMaxClustersCount​(int maxClustersCount)
      Maximal number of generated clusters.
      void setSamplingPoints​(MatOfPoint2f samplingPoints)
      Sets sampling points used to sample the input image.
      void setTranslation​(int idx, float value)
      Translations of the individual axes of the feature space.
      void setTranslations​(MatOfFloat translations)
      Translations of the individual axes of the feature space.
      void setWeight​(int idx, float value)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space.
      void setWeightA​(float weight)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      void setWeightB​(float weight)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      void setWeightContrast​(float weight)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      void setWeightEntropy​(float weight)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      void setWeightL​(float weight)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      void setWeights​(MatOfFloat weights)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space.
      void setWeightX​(float weight)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      void setWeightY​(float weight)
      Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast.
      void setWindowRadius​(int radius)
      Size of the texture sampling window used to compute contrast and entropy (center of the window is always in the pixel selected by x,y coordinates of the corresponding feature sample).
    • Constructor Detail

      • PCTSignatures

        protected PCTSignatures​(long addr)
    • Method Detail

      • __fromPtr__

        public static PCTSignatures __fromPtr__​(long addr)
      • create

        public static PCTSignatures create​(int initSampleCount,
                                           int initSeedCount,
                                           int pointDistribution)
        Creates PCTSignatures algorithm using sample and seed count. It generates its own sets of sampling points and clusterization seed indexes.
        Parameters:
        initSampleCount - Number of points used for image sampling.
        initSeedCount - Number of initial clusterization seeds. Must be lower or equal to initSampleCount
        pointDistribution - Distribution of generated points. Default: UNIFORM. Available: UNIFORM, REGULAR, NORMAL.
        Returns:
        Created algorithm.
      • create

        public static PCTSignatures create​(int initSampleCount,
                                           int initSeedCount)
        Creates PCTSignatures algorithm using sample and seed count. It generates its own sets of sampling points and clusterization seed indexes.
        Parameters:
        initSampleCount - Number of points used for image sampling.
        initSeedCount - Number of initial clusterization seeds. Must be lower or equal to initSampleCount Available: UNIFORM, REGULAR, NORMAL.
        Returns:
        Created algorithm.
      • create

        public static PCTSignatures create​(int initSampleCount)
        Creates PCTSignatures algorithm using sample and seed count. It generates its own sets of sampling points and clusterization seed indexes.
        Parameters:
        initSampleCount - Number of points used for image sampling. Must be lower or equal to initSampleCount Available: UNIFORM, REGULAR, NORMAL.
        Returns:
        Created algorithm.
      • create

        public static PCTSignatures create()
        Creates PCTSignatures algorithm using sample and seed count. It generates its own sets of sampling points and clusterization seed indexes. Must be lower or equal to initSampleCount Available: UNIFORM, REGULAR, NORMAL.
        Returns:
        Created algorithm.
      • create

        public static PCTSignatures create​(MatOfPoint2f initSamplingPoints,
                                           int initSeedCount)
        Creates PCTSignatures algorithm using pre-generated sampling points and number of clusterization seeds. It uses the provided sampling points and generates its own clusterization seed indexes.
        Parameters:
        initSamplingPoints - Sampling points used in image sampling.
        initSeedCount - Number of initial clusterization seeds. Must be lower or equal to initSamplingPoints.size().
        Returns:
        Created algorithm.
      • create

        public static PCTSignatures create​(MatOfPoint2f initSamplingPoints,
                                           MatOfInt initClusterSeedIndexes)
        Creates PCTSignatures algorithm using pre-generated sampling points and clusterization seeds indexes.
        Parameters:
        initSamplingPoints - Sampling points used in image sampling.
        initClusterSeedIndexes - Indexes of initial clusterization seeds. Its size must be lower or equal to initSamplingPoints.size().
        Returns:
        Created algorithm.
      • computeSignature

        public void computeSignature​(Mat image,
                                     Mat signature)
        Computes signature of given image.
        Parameters:
        image - Input image of CV_8U type.
        signature - Output computed signature.
      • computeSignatures

        public void computeSignatures​(List<Mat> images,
                                      List<Mat> signatures)
        Computes signatures for multiple images in parallel.
        Parameters:
        images - Vector of input images of CV_8U type.
        signatures - Vector of computed signatures.
      • drawSignature

        public static void drawSignature​(Mat source,
                                         Mat signature,
                                         Mat result,
                                         float radiusToShorterSideRatio,
                                         int borderThickness)
        Draws signature in the source image and outputs the result. Signatures are visualized as a circle with radius based on signature weight and color based on signature color. Contrast and entropy are not visualized.
        Parameters:
        source - Source image.
        signature - Image signature.
        result - Output result.
        radiusToShorterSideRatio - Determines maximal radius of signature in the output image.
        borderThickness - Border thickness of the visualized signature.
      • drawSignature

        public static void drawSignature​(Mat source,
                                         Mat signature,
                                         Mat result,
                                         float radiusToShorterSideRatio)
        Draws signature in the source image and outputs the result. Signatures are visualized as a circle with radius based on signature weight and color based on signature color. Contrast and entropy are not visualized.
        Parameters:
        source - Source image.
        signature - Image signature.
        result - Output result.
        radiusToShorterSideRatio - Determines maximal radius of signature in the output image.
      • drawSignature

        public static void drawSignature​(Mat source,
                                         Mat signature,
                                         Mat result)
        Draws signature in the source image and outputs the result. Signatures are visualized as a circle with radius based on signature weight and color based on signature color. Contrast and entropy are not visualized.
        Parameters:
        source - Source image.
        signature - Image signature.
        result - Output result.
      • generateInitPoints

        public static void generateInitPoints​(MatOfPoint2f initPoints,
                                              int count,
                                              int pointDistribution)
        Generates initial sampling points according to selected point distribution.
        Parameters:
        initPoints - Output vector where the generated points will be saved.
        count - Number of points to generate.
        pointDistribution - Point distribution selector. Available: UNIFORM, REGULAR, NORMAL. Note: Generated coordinates are in range [0..1)
      • getSampleCount

        public int getSampleCount()
        Number of initial samples taken from the image.
        Returns:
        automatically generated
      • getGrayscaleBits

        public int getGrayscaleBits()
        Color resolution of the greyscale bitmap represented in allocated bits (i.e., value 4 means that 16 shades of grey are used). The greyscale bitmap is used for computing contrast and entropy values.
        Returns:
        automatically generated
      • setGrayscaleBits

        public void setGrayscaleBits​(int grayscaleBits)
        Color resolution of the greyscale bitmap represented in allocated bits (i.e., value 4 means that 16 shades of grey are used). The greyscale bitmap is used for computing contrast and entropy values.
        Parameters:
        grayscaleBits - automatically generated
      • getWindowRadius

        public int getWindowRadius()
        Size of the texture sampling window used to compute contrast and entropy (center of the window is always in the pixel selected by x,y coordinates of the corresponding feature sample).
        Returns:
        automatically generated
      • setWindowRadius

        public void setWindowRadius​(int radius)
        Size of the texture sampling window used to compute contrast and entropy (center of the window is always in the pixel selected by x,y coordinates of the corresponding feature sample).
        Parameters:
        radius - automatically generated
      • getWeightX

        public float getWeightX()
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Returns:
        automatically generated
      • setWeightX

        public void setWeightX​(float weight)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Parameters:
        weight - automatically generated
      • getWeightY

        public float getWeightY()
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Returns:
        automatically generated
      • setWeightY

        public void setWeightY​(float weight)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Parameters:
        weight - automatically generated
      • getWeightL

        public float getWeightL()
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Returns:
        automatically generated
      • setWeightL

        public void setWeightL​(float weight)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Parameters:
        weight - automatically generated
      • getWeightA

        public float getWeightA()
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Returns:
        automatically generated
      • setWeightA

        public void setWeightA​(float weight)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Parameters:
        weight - automatically generated
      • getWeightB

        public float getWeightB()
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Returns:
        automatically generated
      • setWeightB

        public void setWeightB​(float weight)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Parameters:
        weight - automatically generated
      • getWeightContrast

        public float getWeightContrast()
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Returns:
        automatically generated
      • setWeightContrast

        public void setWeightContrast​(float weight)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Parameters:
        weight - automatically generated
      • getWeightEntropy

        public float getWeightEntropy()
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Returns:
        automatically generated
      • setWeightEntropy

        public void setWeightEntropy​(float weight)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy)
        Parameters:
        weight - automatically generated
      • getSamplingPoints

        public MatOfPoint2f getSamplingPoints()
        Initial samples taken from the image. These sampled features become the input for clustering.
        Returns:
        automatically generated
      • setWeight

        public void setWeight​(int idx,
                              float value)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space.
        Parameters:
        idx - ID of the weight
        value - Value of the weight Note: WEIGHT_IDX = 0; X_IDX = 1; Y_IDX = 2; L_IDX = 3; A_IDX = 4; B_IDX = 5; CONTRAST_IDX = 6; ENTROPY_IDX = 7;
      • setWeights

        public void setWeights​(MatOfFloat weights)
        Weights (multiplicative constants) that linearly stretch individual axes of the feature space.
        Parameters:
        weights - Values of all weights. Note: WEIGHT_IDX = 0; X_IDX = 1; Y_IDX = 2; L_IDX = 3; A_IDX = 4; B_IDX = 5; CONTRAST_IDX = 6; ENTROPY_IDX = 7;
      • setTranslation

        public void setTranslation​(int idx,
                                   float value)
        Translations of the individual axes of the feature space.
        Parameters:
        idx - ID of the translation
        value - Value of the translation Note: WEIGHT_IDX = 0; X_IDX = 1; Y_IDX = 2; L_IDX = 3; A_IDX = 4; B_IDX = 5; CONTRAST_IDX = 6; ENTROPY_IDX = 7;
      • setTranslations

        public void setTranslations​(MatOfFloat translations)
        Translations of the individual axes of the feature space.
        Parameters:
        translations - Values of all translations. Note: WEIGHT_IDX = 0; X_IDX = 1; Y_IDX = 2; L_IDX = 3; A_IDX = 4; B_IDX = 5; CONTRAST_IDX = 6; ENTROPY_IDX = 7;
      • setSamplingPoints

        public void setSamplingPoints​(MatOfPoint2f samplingPoints)
        Sets sampling points used to sample the input image.
        Parameters:
        samplingPoints - Vector of sampling points in range [0..1) Note: Number of sampling points must be greater or equal to clusterization seed count.
      • getInitSeedIndexes

        public MatOfInt getInitSeedIndexes()
        Initial seeds (initial number of clusters) for the k-means algorithm.
        Returns:
        automatically generated
      • setInitSeedIndexes

        public void setInitSeedIndexes​(MatOfInt initSeedIndexes)
        Initial seed indexes for the k-means algorithm.
        Parameters:
        initSeedIndexes - automatically generated
      • getInitSeedCount

        public int getInitSeedCount()
        Number of initial seeds (initial number of clusters) for the k-means algorithm.
        Returns:
        automatically generated
      • getIterationCount

        public int getIterationCount()
        Number of iterations of the k-means clustering. We use fixed number of iterations, since the modified clustering is pruning clusters (not iteratively refining k clusters).
        Returns:
        automatically generated
      • setIterationCount

        public void setIterationCount​(int iterationCount)
        Number of iterations of the k-means clustering. We use fixed number of iterations, since the modified clustering is pruning clusters (not iteratively refining k clusters).
        Parameters:
        iterationCount - automatically generated
      • getMaxClustersCount

        public int getMaxClustersCount()
        Maximal number of generated clusters. If the number is exceeded, the clusters are sorted by their weights and the smallest clusters are cropped.
        Returns:
        automatically generated
      • setMaxClustersCount

        public void setMaxClustersCount​(int maxClustersCount)
        Maximal number of generated clusters. If the number is exceeded, the clusters are sorted by their weights and the smallest clusters are cropped.
        Parameters:
        maxClustersCount - automatically generated
      • getClusterMinSize

        public int getClusterMinSize()
        This parameter multiplied by the index of iteration gives lower limit for cluster size. Clusters containing fewer points than specified by the limit have their centroid dismissed and points are reassigned.
        Returns:
        automatically generated
      • setClusterMinSize

        public void setClusterMinSize​(int clusterMinSize)
        This parameter multiplied by the index of iteration gives lower limit for cluster size. Clusters containing fewer points than specified by the limit have their centroid dismissed and points are reassigned.
        Parameters:
        clusterMinSize - automatically generated
      • getJoiningDistance

        public float getJoiningDistance()
        Threshold euclidean distance between two centroids. If two cluster centers are closer than this distance, one of the centroid is dismissed and points are reassigned.
        Returns:
        automatically generated
      • setJoiningDistance

        public void setJoiningDistance​(float joiningDistance)
        Threshold euclidean distance between two centroids. If two cluster centers are closer than this distance, one of the centroid is dismissed and points are reassigned.
        Parameters:
        joiningDistance - automatically generated
      • getDropThreshold

        public float getDropThreshold()
        Remove centroids in k-means whose weight is lesser or equal to given threshold.
        Returns:
        automatically generated
      • setDropThreshold

        public void setDropThreshold​(float dropThreshold)
        Remove centroids in k-means whose weight is lesser or equal to given threshold.
        Parameters:
        dropThreshold - automatically generated
      • getDistanceFunction

        public int getDistanceFunction()
        Distance function selector used for measuring distance between two points in k-means.
        Returns:
        automatically generated
      • setDistanceFunction

        public void setDistanceFunction​(int distanceFunction)
        Distance function selector used for measuring distance between two points in k-means. Available: L0_25, L0_5, L1, L2, L2SQUARED, L5, L_INFINITY.
        Parameters:
        distanceFunction - automatically generated