001/*******************************************************************************
002 * This software is provided as a supplement to the authors' textbooks on digital
003 * image processing published by Springer-Verlag in various languages and editions.
004 * Permission to use and distribute this software is granted under the BSD 2-Clause
005 * "Simplified" License (see http://opensource.org/licenses/BSD-2-Clause).
006 * Copyright (c) 2006-2023 Wilhelm Burger, Mark J. Burge. All rights reserved.
007 * Visit https://imagingbook.com for additional details.
008 ******************************************************************************/
009
010package imagingbook.common.sift;
011
012import java.util.Locale;
013
014/**
015 * <p>
016 * Represents a SIFT key point in hierarchical scale space. See Sec. 25.3 of [1] for more details. This class is
017 * non-public, instances are immutable.
018 * </p>
019 * <p>
020 * [1] W. Burger, M.J. Burge, <em>Digital Image Processing &ndash; An Algorithmic Introduction</em>, 3rd ed, Springer
021 * (2022).
022 * </p>
023 *
024 * @author WB
025 * @version 2022/11/20
026 */
027public class KeyPoint implements Cloneable, Comparable<KeyPoint> {
028        
029        /** octave index */
030        public final int p;
031        /** level index */
032        public final int q;
033        
034        /** lattice x-position */
035        public final int u;
036        
037        /** lattice y-position */
038        public final int v;
039        
040        /** interpolated lattice x-position */
041        public final float x;
042        
043        /** interpolated lattice y-position */
044        public final float y;
045        
046        /** real x-position (in image coordinates) */
047        public final float x_real;
048        
049        /** real y-position (in image coordinates) */   
050        public final float y_real;
051        
052        /** absolute scale */
053        public final float scale;
054        
055        /** magnitude of DoG response */
056        public final float magnitude;
057        
058        // --------------------------------------------
059        
060        /** for debugging only */
061        float[] orientation_histogram;
062        /** dominant orientation (for debugging only) */
063        double orientation;
064        
065        // --------------------------------------------
066        
067        /** Constructor (non-public). */
068        KeyPoint(int p, int q, int u, int v, float x, float y, float x_real, float y_real, float scale, float magnitude) {
069                this.p = p;
070                this.q = q;
071                this.u = u;
072                this.v = v;
073                this.x = x;
074                this.y = y;
075                this.x_real = x_real;
076                this.y_real = y_real;
077                this.scale = scale;
078                this.magnitude = magnitude;
079        }
080        
081        @Override
082        public String toString() {
083                return String.format(Locale.US, "%s[p=%d, q=%d, u=%d, v=%d, scale=%.2f, mag=%.2f]", 
084                                getClass().getSimpleName(), p, q, u, v, scale, magnitude);
085        }
086        
087        @Override
088        public KeyPoint clone() {
089                try {
090                        return (KeyPoint) super.clone();
091                } catch (CloneNotSupportedException e) {
092                        e.printStackTrace();
093                }
094                return null;
095        }
096
097        @Override //used for sorting keypoints by decreasing gradient magnitude
098        public int compareTo(KeyPoint other) {
099                return Float.compare(other.magnitude, this.magnitude);
100        }
101
102}