/**
 * Copyright (c) 2011, The University of Southampton and the individual contributors.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 *   *  Redistributions of source code must retain the above copyright notice,
 *      this list of conditions and the following disclaimer.
 *
 *   *  Redistributions in binary form must reproduce the above copyright notice,
 *      this list of conditions and the following disclaimer in the documentation
 *      and/or other materials provided with the distribution.
 *
 *   *  Neither the name of the University of Southampton nor the names of its
 *      contributors may be used to endorse or promote products derived from this
 *      software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.openimaj.image.feature.local.detector.dog.extractor;

import org.openimaj.feature.OrientedFeatureVector;
import org.openimaj.image.FImage;
import org.openimaj.image.feature.local.descriptor.gradient.GradientFeatureProvider;
import org.openimaj.image.feature.local.descriptor.gradient.GradientFeatureProviderFactory;
import org.openimaj.image.feature.local.descriptor.gradient.SIFTFeatureProvider;
import org.openimaj.image.feature.local.extraction.GradientScaleSpaceImageExtractorProperties;
import org.openimaj.image.feature.local.extraction.ScaleSpaceImageExtractorProperties;
import org.openimaj.image.processing.convolution.FImageGradients;

/**
 * <p>
 * Class capable of extracting local descriptors from a circular region in an
 * image defined by its scale and centre. The actual feature extracted is
 * determined by the {@link GradientFeatureProvider} that is provided by the
 * {@link GradientFeatureProviderFactory} set during construction.
 * </p>
 * <p>
 * The GradientFeatureExtractor first calculates the dominant orientation of the
 * image patch described by the {@link ScaleSpaceImageExtractorProperties} and
 * then iterates over the pixels in an oriented square, centered on the interest
 * point, passing the gradient and magnitude values of the respective pixel to
 * the {@link GradientFeatureProvider}.
 * </p>
 * <p>
 * The size of the sampling square, relative to scale is set by a single
 * parameter, magnification. For some types of feature provider, this number
 * might need to be set based on the internal settings of the provider. For
 * example, with a {@link SIFTFeatureProvider} this will probably be set to a
 * constant multiplied by the number of spatial bins of the feature. For SIFT,
 * this constant is typically around 3, so with a standard 4-spatial binned SIFT
 * provider, the magnification factor of the extractor should be about 12.
 * </p>
 *
 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
 *
 */
public class GradientFeatureExtractor implements ScaleSpaceFeatureExtractor<OrientedFeatureVector, FImage> {
        AbstractDominantOrientationExtractor dominantOrientationExtractor;

        GradientFeatureProviderFactory factory;

        private GradientScaleSpaceImageExtractorProperties<FImage> currentGradientProperties = new GradientScaleSpaceImageExtractorProperties<FImage>();

        /**
         * The magnification factor determining the size of the sampling region
         * relative to the scale of the interest point.
         */
        protected float magnification = 12;

        /**
         * Construct with the given orientation extractor and gradient feature
         * provider. The default magnification factor of 12 is used.
         *
         * @param dominantOrientationExtractor
         *            the orientation extractor
         * @param factory
         *            the gradient feature provider
         */
        public GradientFeatureExtractor(AbstractDominantOrientationExtractor dominantOrientationExtractor,
                        GradientFeatureProviderFactory factory)
        {
                this.dominantOrientationExtractor = dominantOrientationExtractor;
                this.factory = factory;
        }

        /**
         * Construct with the given orientation extractor, gradient feature provider
         * and magnification factor determining the size of the sampling region
         * relative to the scale of the interest point.
         *
         * @param dominantOrientationExtractor
         *            the orientation extractor
         * @param factory
         *            the gradient feature provider
         * @param magnification
         *            the magnification factor.
         */
        public GradientFeatureExtractor(AbstractDominantOrientationExtractor dominantOrientationExtractor,
                        GradientFeatureProviderFactory factory, float magnification)
        {
                this(dominantOrientationExtractor, factory);
                this.magnification = magnification;
        }

        @Override
        public OrientedFeatureVector[] extractFeature(ScaleSpaceImageExtractorProperties<FImage> properties) {
                final GradientScaleSpaceImageExtractorProperties<FImage> gprops = getCurrentGradientProps(properties);

                final float[] dominantOrientations = dominantOrientationExtractor.extractFeatureRaw(gprops);

                final OrientedFeatureVector[] ret = new OrientedFeatureVector[dominantOrientations.length];

                for (int i = 0; i < dominantOrientations.length; i++) {
                        ret[i] = createFeature(dominantOrientations[i]);
                }

                return ret;
        }

        /**
         * Get the GradientScaleSpaceImageExtractorProperties for the given
         * properties. The returned properties are the same as the input properties,
         * but with the gradient images added.
         *
         * For efficiency, this method always returns the same cached
         * GradientScaleSpaceImageExtractorProperties, and internally updates this
         * as necessary. The gradient images are only recalculated when the input
         * image from the input properties is different to the cached one.
         *
         * @param properties
         *            input properties
         * @return cached GradientScaleSpaceImageExtractorProperties
         */
        public GradientScaleSpaceImageExtractorProperties<FImage> getCurrentGradientProps(
                        ScaleSpaceImageExtractorProperties<FImage> properties)
        {
                if (properties.image != currentGradientProperties.image) {
                        currentGradientProperties.image = properties.image;

                        // only if the size of the image has changed do we need to reset the
                        // gradient and orientation images.
                        if (currentGradientProperties.orientation == null ||
                                        currentGradientProperties.orientation.height != currentGradientProperties.image.height ||
                                        currentGradientProperties.orientation.width != currentGradientProperties.image.width)
                        {
                                currentGradientProperties.orientation = new FImage(currentGradientProperties.image.width,
                                                currentGradientProperties.image.height);
                                currentGradientProperties.magnitude = new FImage(currentGradientProperties.image.width,
                                                currentGradientProperties.image.height);
                        }

                        FImageGradients.gradientMagnitudesAndOrientations(currentGradientProperties.image,
                                        currentGradientProperties.magnitude, currentGradientProperties.orientation);
                }

                currentGradientProperties.x = properties.x;
                currentGradientProperties.y = properties.y;
                currentGradientProperties.scale = properties.scale;

                return currentGradientProperties;
        }

        /*
         * Iterate over the pixels in a sampling patch around the given feature
         * coordinates and pass the information to a feature provider that will
         * extract the relevant feature vector.
         */
        protected OrientedFeatureVector createFeature(final float orientation) {
                final float fx = currentGradientProperties.x;
                final float fy = currentGradientProperties.y;
                final float scale = currentGradientProperties.scale;

                // create a new feature provider and initialise it with the dominant
                // orientation
                final GradientFeatureProvider sfe = factory.newProvider();
                sfe.setPatchOrientation(orientation);

                // the integer coordinates of the patch
                final int ix = Math.round(fx);
                final int iy = Math.round(fy);

                final float sin = (float) Math.sin(orientation);
                final float cos = (float) Math.cos(orientation);

                // get the amount of extra sampling outside the unit square requested by
                // the feature
                final float oversampling = sfe.getOversamplingAmount();

                // this is the size of the unit bounding box of the patch in the image
                // in pixels
                final float boundingBoxSize = magnification * scale;

                // the amount of extra sampling per side in pixels
                final float extraSampling = oversampling * boundingBoxSize;

                // the actual sampling area is bigger than the boundingBoxSize by an
                // extraSampling on each side
                final float samplingBoxSize = extraSampling + boundingBoxSize + extraSampling;

                // In the image, the box (with sides parallel to the image frame) that
                // contains the
                // sampling box is:
                final float orientedSamplingBoxSize = Math.abs(sin * samplingBoxSize) + Math.abs(cos * samplingBoxSize);

                // now half the size and round to an int so we can iterate
                final int orientedSamplingBoxHalfSize = Math.round(orientedSamplingBoxSize / 2.0f);

                // get the images and their size
                final FImage mag = currentGradientProperties.magnitude;
                final FImage ori = currentGradientProperties.orientation;
                final int width = mag.width;
                final int height = mag.height;

                // now pass over all the pixels in the image that *might* contribute to
                // the sampling area
                for (int y = -orientedSamplingBoxHalfSize; y <= orientedSamplingBoxHalfSize; y++) {
                        for (int x = -orientedSamplingBoxHalfSize; x <= orientedSamplingBoxHalfSize; x++) {
                                final int px = x + ix;
                                final int py = y + iy;

                                // check if the pixel is in the image bounds; if not ignore it
                                if (px >= 0 && px < width && py >= 0 && py < height) {
                                        // calculate the actual position of the sample in the patch
                                        // coordinate system
                                        final float sx = 0.5f + ((-sin * y + cos * x) - (fx - ix)) / boundingBoxSize;
                                        final float sy = 0.5f + ((cos * y + sin * x) - (fy - iy)) / boundingBoxSize;

                                        // if the pixel is in the bounds of the sampling area then
                                        // add it
                                        if (sx > -oversampling && sx < 1 + oversampling && sy > -oversampling && sy < 1 + oversampling) {
                                                sfe.addSample(sx, sy, mag.pixels[py][px], ori.pixels[py][px]);
                                        }
                                }
                        }
                }

                return sfe.getFeatureVector();
        }
}