001/**
002 * Copyright (c) 2011, The University of Southampton and the individual contributors.
003 * All rights reserved.
004 *
005 * Redistribution and use in source and binary forms, with or without modification,
006 * are permitted provided that the following conditions are met:
007 *
008 *   *  Redistributions of source code must retain the above copyright notice,
009 *      this list of conditions and the following disclaimer.
010 *
011 *   *  Redistributions in binary form must reproduce the above copyright notice,
012 *      this list of conditions and the following disclaimer in the documentation
013 *      and/or other materials provided with the distribution.
014 *
015 *   *  Neither the name of the University of Southampton nor the names of its
016 *      contributors may be used to endorse or promote products derived from this
017 *      software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
020 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
021 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
022 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
023 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
026 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
028 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package org.openimaj.feature;
031
032import java.io.Serializable;
033
034import org.openimaj.io.ReadWriteable;
035
036/**
037 * Interface for objects that represent feature vectors.
038 *
039 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
040 *
041 */
042public interface FeatureVector extends Cloneable, Serializable, ReadWriteable {
043        /**
044         * Get the underlying data array.
045         *
046         * @return underlying data
047         */
048        public Object getVector();
049
050        /**
051         * Get the length of this vector
052         *
053         * @return the length of this vector
054         */
055        public int length();
056
057        /**
058         * Element-wise normalisation to 0..1 using separated expected minimum and
059         * maximum values for each element of the underlying feature vector.
060         *
061         * @param min
062         *            an array containing the minimum expected values
063         * @param max
064         *            an array containing the maximum expected values
065         * @return copy of the feature vector with each value normalised to 0..1
066         */
067        public DoubleFV normaliseFV(double[] min, double[] max);
068
069        /**
070         * Min-Max normalisation of the FV. Each element of the underlying feature
071         * vector is normalised to 0..1 based on the provided minimum and maximum
072         * expected values.
073         *
074         * @param min
075         *            the minimum expected value
076         * @param max
077         *            the maximum expected value
078         * @return copy of the feature vector with each value normalised to 0..1
079         */
080        public DoubleFV normaliseFV(double min, double max);
081
082        /**
083         * Normalise the FV to unit length
084         *
085         * @return a copy of the feature vector as a DoubleFV, normalised to unit
086         *         length
087         */
088        public DoubleFV normaliseFV();
089
090        /**
091         * Convert the FV to a DoubleFV representation
092         *
093         * @return a copy of the feature vector as a DoubleFV
094         */
095        public DoubleFV asDoubleFV();
096
097        /**
098         * Convert the FV to a 1-dimensional double array representation
099         *
100         * @return a copy of the feature vector as a double array
101         */
102        public double[] asDoubleVector();
103
104        /**
105         * Lp Norm of the FV.
106         *
107         * @param p
108         *            the norm to compute
109         *
110         * @return feature vector normalised using the Lp norm
111         */
112        public DoubleFV normaliseFV(double p);
113
114        /**
115         * Get an element of the feature as a double value
116         *
117         * @param i
118         *            the element index
119         * @return the value as a double
120         */
121        public double getAsDouble(int i);
122
123        /**
124         * Set an element of the feature from a double value
125         *
126         * @param i
127         *            the element index
128         * @param v
129         *            the value
130         */
131        public void setFromDouble(int i, double v);
132
133        /**
134         * Construct a new instance of this featurevector. Implementors must return
135         * an instance of themselves (rather than a different type of feature).
136         *
137         * @return a new instance.
138         */
139        public FeatureVector newInstance();
140}