/**
 * 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.video.processing.shotdetector;

import gnu.trove.list.array.TDoubleArrayList;

import java.awt.HeadlessException;
import java.util.ArrayList;
import java.util.List;

import org.openimaj.feature.DoubleFV;
import org.openimaj.image.Image;
import org.openimaj.video.Video;
import org.openimaj.video.VideoDisplay;
import org.openimaj.video.VideoDisplay.EndAction;
import org.openimaj.video.VideoDisplayListener;
import org.openimaj.video.processor.VideoProcessor;
import org.openimaj.video.timecode.HrsMinSecFrameTimecode;
import org.openimaj.video.timecode.VideoTimecode;

/**
 *      Video shot detector class implemented as a video display listener. This
 *      means that shots can be detected as the video plays. The class also
 *      supports direct processing of a video file (with no display).
 *      <p>
 *      The default threshold boundary should be set by implementing methods
 *      as the distances returned by those implementations will only sensibly understand
 *      where the threshold should be.
 *      <p>
 *      Only the last keyframe is stored during processing, so if you want to store
 *      a list of keyframes you must store this list yourself by listening to the
 *      ShotDetected event which provides a VideoKeyframe which has a timecode
 *      and an image. Each event will receive the same VideoKeyframe instance
 *      containing different information. Use VideoKeyframe#clone() to make a copy.
 *
 *  @author David Dupplaw (dpd@ecs.soton.ac.uk)
 *      @param <I> The type of image
 *      @created 1 Jun 2011
 */
public abstract class VideoShotDetector<I extends Image<?,I>>
        extends VideoProcessor<I>
        implements VideoDisplayListener<I>
{
        /** The current keyframe */
        private VideoKeyframe<I> currentKeyframe = null;

        /** The list of shot boundaries */
        private final List<ShotBoundary<I>> shotBoundaries =
                new ArrayList<ShotBoundary<I>>();

        /** Differences between consecutive frames */
        private final TDoubleArrayList differentials = new TDoubleArrayList();

        /** The frame we're at within the video */
        private int frameCounter = 0;

        /** The video being processed */
        private Video<I> video = null;

        /** Whether to find keyframes */
        private boolean findKeyframes = true;

        /** Whether to store all frame differentials */
        private boolean storeAllDiffs = false;

        /** Whether an event is required to be fired next time */
        private boolean needFire = false;

        /** Whether the last processed frame was a boundary */
        protected boolean lastFrameWasBoundary = false;

        /** A list of the listeners that want to know about new shots */
        private final List<ShotDetectedListener<I>> listeners = new ArrayList<ShotDetectedListener<I>>();

        /** The number of frames per second of the source material */
        private double fps = 25;

        /** Whether the first frame is being processed */
        private boolean firstFrame = true;

        /** Whether to generate a shot boundary for the first frame of a video */
        private final boolean generateStartShot = true;

        /** The threshold to use to determine a shot boundary - this default is arbitrary */
        protected double threshold = 100;

        /**
         *      This constructor assumes that you will set the number of
         *      frames per second your video uses (using {@link #setFPS(double)})
         *      when you know what that will be, otherwise your timecodes will
         *      all be messed up.
         */
        public VideoShotDetector()
        {
        }

        /**
         *      Default constructor that allows the processor to be used ad-hoc
         *      on frames from any source. The number of FPS is required so that
         *      timecodes can be generated for the shot boundaries. Be aware that if
         *      your source material does not have a specific number of frames per
         *      second then the timecodes will not have any meaning in the detected
         *      shot boundaries.
         *
         *      @param fps The number of frames per second of the source material
         */
        public VideoShotDetector( final double fps )
        {
                this.fps = fps;
        }

        /**
         *      Constructor that takes the video file to process.
         *
         *  @param video The video to process.
         */
        public VideoShotDetector( final Video<I> video )
        {
                this( video, false );
        }

        /**
         *      Default constructor that takes the video file to process and
         *      whether or not to display the video as it's being processed.
         *
         *  @param video The video to process
         *  @param display Whether to display the video during processing.
         */
        public VideoShotDetector( final Video<I> video, final boolean display )
    {
                this.video = video;
                this.fps = video.getFPS();
                if( display )
                {
                        try
                {
                        final VideoDisplay<I> vd = VideoDisplay.createVideoDisplay( video );
                                vd.addVideoListener( this );
                                vd.setEndAction( EndAction.STOP_AT_END );
                }
                catch( final HeadlessException e )
                {
                        e.printStackTrace();
                }
                }
    }

        /**
         *      Returns whether the last processed frame was a shot boundary - that is
         *      the last processed frame marks a new scene.
         *      @return Whether the last frame was a boundary.
         */
        public boolean wasLastFrameBoundary()
        {
                return this.lastFrameWasBoundary;
        }

        /**
         *      Process the video.
         */
        @Override
        public void process()
        {
                super.process( this.video );
        }

        /**
         *  {@inheritDoc}
         *  @see org.openimaj.video.VideoDisplayListener#afterUpdate(org.openimaj.video.VideoDisplay)
         */
        @Override
        public void afterUpdate( final VideoDisplay<I> display )
    {
    }

        /**
         *  {@inheritDoc}
         *  @see org.openimaj.video.VideoDisplayListener#beforeUpdate(org.openimaj.image.Image)
         */
        @Override
        public void beforeUpdate( final I frame )
    {
                this.checkForShotBoundary( frame );
    }

        /**
         *      Add the given shot detected listener to the list of listeners in this
         *      object
         *
         *  @param sdl The shot detected listener to add
         */
        public void addShotDetectedListener( final ShotDetectedListener<I> sdl )
        {
                this.listeners.add( sdl );
        }

        /**
         *      Remove the given shot detected listener from this object.
         *
         *  @param sdl The shot detected listener to remove
         */
        public void removeShotDetectedListener( final ShotDetectedListener<I> sdl )
        {
                this.listeners.remove( sdl );
        }

        /**
         *      Return the last shot boundary in the list.
         *      @return The last shot boundary in the list.
         */
        public ShotBoundary<I> getLastShotBoundary()
        {
                if( this.shotBoundaries.size() == 0 )
                        return null;
                return this.shotBoundaries.get( this.shotBoundaries.size()-1 );
        }

        /**
         *      Returns the last video keyframe that was generated.
         *      @return The last video keyframe that was generated.
         */
        public VideoKeyframe<I> getLastKeyframe()
        {
                return this.currentKeyframe;
        }

        /**
         *      Checks whether a shot boundary occurred between the given frame
         *      and the previous frame, and if so, it will add a shot boundary
         *      to the shot boundary list.
         *
         *  @param frame The new frame to process.
         */
        private void checkForShotBoundary( final I frame )
        {
                this.lastFrameWasBoundary = false;
                final double dist = this.getInterframeDistance( frame );

                if( this.storeAllDiffs )
                {
                        this.differentials.add( dist );
                        this.fireDifferentialCalculated( new HrsMinSecFrameTimecode(
                                        this.frameCounter, this.video.getFPS() ), dist, frame );
                }

//              System.out.println( "is "+dist+" > "+this.threshold+"? "+(dist>this.threshold) );

                // We generate a shot boundary if the threshold is exceeded or we're
                // at the very start of the video.
                if( dist > this.threshold || (this.generateStartShot && this.firstFrame) )
                {
                        this.needFire = true;

                        // The timecode of this frame
                        final VideoTimecode tc = new HrsMinSecFrameTimecode(
                                        this.frameCounter, this.fps );

                        // The last shot boundary we created
                        final ShotBoundary<I> sb = this.getLastShotBoundary();

                        // If this frame is sequential to the last
                        if( sb != null &&
                                tc.getFrameNumber() - sb.getTimecode().getFrameNumber() < 4  )
                        {
                                // If the shot boundary is a fade, we simply change the end
                                // timecode, otherwise we replace the given shot boundary
                                // with a new one.
                                if( sb instanceof FadeShotBoundary )
                                                ((FadeShotBoundary<I>)sb).setEndTimecode( tc );
                                else
                                {
                                        // Remove the old one.
                                        this.shotBoundaries.remove( sb );

                                        // Change it to a fade.
                                        final FadeShotBoundary<I> fsb = new FadeShotBoundary<I>( sb );
                                        fsb.setEndTimecode( tc );

                                        this.lastFrameWasBoundary = true;

                                        if( this.findKeyframes )
                                        {
                                                if( this.currentKeyframe == null )
                                                        this.currentKeyframe = new VideoKeyframe<I>( tc, frame );
                                                else
                                                {
                                                        this.currentKeyframe.timecode = tc;
                                                        this.currentKeyframe.imageAtBoundary = frame.clone();
                                                }
                                                fsb.keyframe = this.currentKeyframe.clone();
                                        }

                                        this.shotBoundaries.add( fsb );
                                }
                        }
                        else
                        {
                                // Create a new shot boundary
                                final ShotBoundary<I> sb2 = new ShotBoundary<I>( tc );

                                if( this.findKeyframes )
                                {
                                        if( this.currentKeyframe == null )
                                                this.currentKeyframe = new VideoKeyframe<I>( tc, frame );
                                        else
                                        {
                                                this.currentKeyframe.timecode = tc;
                                                this.currentKeyframe.imageAtBoundary = frame;
                                        }
                                        sb2.keyframe = this.currentKeyframe.clone();
                                }

                                this.lastFrameWasBoundary = true;
                                this.shotBoundaries.add( sb2 );
                                this.fireShotDetected( sb2, this.currentKeyframe );
                        }
                }
                else
                {
                        // The frame matches with the last (no boundary) but we'll check whether
                        // the last thing added to the shot boundaries was a fade and its
                        // end time was the timecode before this one. If so, we can fire a
                        // shot detected event.
                        if( this.frameCounter > 0 && this.needFire )
                        {
                                this.needFire = false;

                                final VideoTimecode tc = new HrsMinSecFrameTimecode(
                                                this.frameCounter-1, this.fps );

                                final ShotBoundary<I> lastShot = this.getLastShotBoundary();

                                if( lastShot != null && lastShot instanceof FadeShotBoundary )
                                        if( ((FadeShotBoundary<I>)lastShot).getEndTimecode().equals( tc ) )
                                                this.fireShotDetected( lastShot, this.getLastKeyframe() );
                        }
                }

                this.frameCounter++;
                this.firstFrame = false;
    }

        /**
         *      Returns the inter-frame distance between this frame and the last.
         *      @return The inter-frame distance
         */
        protected abstract double getInterframeDistance( I thisFrame );

        /**
         *      Get the list of shot boundaries that have been extracted so far.
         *  @return The list of shot boundaries.
         */
        public List<ShotBoundary<I>> getShotBoundaries()
        {
                return this.shotBoundaries;
        }

        /**
         *      Set the threshold that will determine a shot boundary.
         *
         *  @param threshold The new threshold.
         */
        public void setThreshold( final double threshold )
        {
                this.threshold = threshold;
        }

        /**
         *      Returns the current threshold value.
         *      @return The current threshold
         */
        public double getThreshold()
        {
                return this.threshold;
        }

        /**
         *      Set whether to store keyframes of boundaries when they
         *      have been found.
         *
         *      @param k TRUE to store keyframes; FALSE otherwise
         */
        public void setFindKeyframes( final boolean k )
        {
                this.findKeyframes = k;
        }

        /**
         *      Set whether to store differentials during the processing
         *      stage.
         *
         *      @param d TRUE to store all differentials; FALSE otherwise
         */
        public void setStoreAllDifferentials( final boolean d )
        {
                this.storeAllDiffs = d;
        }

        /**
         *      Get the differentials between frames (if storeAllDiff is true).
         *      @return The differentials between frames as a List of Double.
         */
        public DoubleFV getDifferentials()
        {
                return new DoubleFV( this.differentials.toArray() );
        }

        /**
         *  {@inheritDoc}
         *  @see org.openimaj.video.processor.VideoProcessor#processFrame(org.openimaj.image.Image)
         */
        @Override
    public I processFrame( final I frame )
    {
                if( frame == null ) return null;
                this.checkForShotBoundary( frame );
                return frame;
    }

        /**
         *      Fire the event to the listeners that a new shot has been detected.
         *  @param sb The shot boundary defintion
         *  @param vk The video keyframe
         */
        protected void fireShotDetected( final ShotBoundary<I> sb, final VideoKeyframe<I> vk )
        {
                for( final ShotDetectedListener<I> sdl : this.listeners )
                        sdl.shotDetected( sb, vk );
        }

        /**
         *      Fired each time a differential is calculated between frames.
         *      @param vt The timecode of the differential
         *      @param d The differential value
         *      @param frame The different frame
         */
        protected void fireDifferentialCalculated( final VideoTimecode vt, final double d, final I frame )
        {
                for( final ShotDetectedListener<I> sdl : this.listeners )
                        sdl.differentialCalculated( vt, d, frame );
        }

        /**
         *      {@inheritDoc}
         *      @see org.openimaj.video.processor.VideoProcessor#reset()
         */
        @Override
        public void reset()
        {
        }

        /**
         *      Set the frames per second value for the video being processed.
         *      @param fps The number of frames per second.
         */
        public void setFPS( final double fps )
        {
                this.fps = fps;
        }
}