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.image.analysis.pyramid;
031
032import java.util.Iterator;
033
034import org.openimaj.image.FImage;
035import org.openimaj.image.Image;
036import org.openimaj.image.processor.SinglebandImageProcessor;
037import org.openimaj.util.array.ArrayIterator;
038
039/**
040 * An octave is an interval in scale space, typically corresponding to a 
041 * doubling of sigma. Octaves contain a stack of one or more images, 
042 * with each image typically at a higher scale than the previous.
043 * 
044 * Octaves are Iterable for easy access to each of the images in turn.
045 * 
046 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
047 *
048 * @param <OPTIONS> Type of options object
049 * @param <PYRAMID> Type of parent pyramid
050 * @param <IMAGE> Type of underlying image
051 */
052public abstract class Octave<
053                OPTIONS extends PyramidOptions<?, IMAGE>, 
054                PYRAMID extends Pyramid<OPTIONS,?,IMAGE>, 
055                IMAGE extends Image<?,IMAGE> & SinglebandImageProcessor.Processable<Float,FImage,IMAGE>> 
056        implements 
057                Iterable<IMAGE> 
058{
059        /** The options used for the pyramid construction */
060        public OPTIONS options;
061        
062        /** The images that make up this Octave */
063        public IMAGE [] images;
064        
065        /** The pyramid that contains this Octave */
066        public PYRAMID parentPyramid;
067        
068        /** The size of the octave relative to the original image. */
069        public float octaveSize;
070        
071        /**
072         * Construct a Gaussian octave with the provided parent Pyramid
073         * and octaveSize. The octaveSize parameter is the size of 
074         * the octave's images compared to the original image used
075         * to construct the pyramid. An octaveSize of 1 means the 
076         * same size as the original, 2 means half size, 4 means 
077         * quarter size, etc.
078         * 
079         * @param parent the pyramid that this octave belongs to
080         * @param octaveSize the size of the octave relative to
081         *                      the original image.
082         */
083        public Octave(PYRAMID parent, float octaveSize) {
084                parentPyramid = parent;
085                if (parent != null) this.options = parent.options;
086                this.octaveSize = octaveSize;
087        }
088        
089        /**
090         * Populate the octave, starting from the provided image.
091         * @param image the image.
092         */
093        public abstract void process(IMAGE image);
094        
095        /**
096         * Get the image that starts the next octave. 
097         * Usually this is the image that has twice the sigma 
098         * of the image used to initialise this octave.
099         * 
100         * @return image image to start next octave.
101         */
102        public abstract IMAGE getNextOctaveImage();
103
104        /* (non-Javadoc)
105         * @see java.lang.Iterable#iterator()
106         */
107        @Override
108        public Iterator<IMAGE> iterator() {
109                return new ArrayIterator<IMAGE>(images);
110        }
111}