1 /**
2 * Copyright (c) 2011, The University of Southampton and the individual contributors.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
7 *
8 * * Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
10 *
11 * * Redistributions in binary form must reproduce the above copyright notice,
12 * this list of conditions and the following disclaimer in the documentation
13 * and/or other materials provided with the distribution.
14 *
15 * * Neither the name of the University of Southampton nor the names of its
16 * contributors may be used to endorse or promote products derived from this
17 * software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package org.openimaj.image.analysis.pyramid;
31
32 import java.util.ArrayList;
33 import java.util.Iterator;
34 import java.util.List;
35
36 import org.openimaj.image.FImage;
37 import org.openimaj.image.Image;
38 import org.openimaj.image.analyser.ImageAnalyser;
39 import org.openimaj.image.processor.SinglebandImageProcessor;
40
41 /**
42 * An image pyramid consisting of a stack of octaves.
43 *
44 * Octaves are processed by an OctaveProcessor as they are created
45 * if the processor is set in the options object.
46 *
47 * The pyramid will only hold onto its octaves if either the
48 * keepOctaves option is set to true, or if a PyramidProcessor is
49 * set in the options. The PyramidProcessor will called after all
50 * the octaves are created.
51 *
52 * Pyramids are Iterable for easy access to the octaves; however this
53 * will only work if the pyramid has already been populated with the
54 * octaves retained.
55 *
56 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
57 *
58 * @param <OPTIONS> Type of options object
59 * @param <OCTAVE> Type of underlying octave
60 * @param <IMAGE> Type of underlying image
61 */
62 public abstract class Pyramid<
63 OPTIONS extends PyramidOptions<OCTAVE,IMAGE>,
64 OCTAVE extends Octave<OPTIONS,?,IMAGE>,
65 IMAGE extends Image<?,IMAGE> & SinglebandImageProcessor.Processable<Float,FImage,IMAGE>>
66 implements
67 ImageAnalyser<IMAGE>, Iterable<OCTAVE>
68 {
69 /**
70 * Options for the pyramid
71 */
72 protected OPTIONS options;
73
74 /**
75 * A list of all the octaves should you want to keep them.
76 * @see PyramidOptions#keepOctaves
77 */
78 protected List<OCTAVE> octaves;
79
80 /**
81 * Construct a Pyramid with the given options.
82 * @param options the options
83 */
84 public Pyramid(OPTIONS options) {
85 this.options = options;
86
87 if (options.keepOctaves || options.pyramidProcessor!=null)
88 octaves = new ArrayList<OCTAVE>();
89 }
90
91 /**
92 * Process the image and construct a pyramid applying any specified
93 * OctaveProcessor and/or PyramidProcessor along the way. If a
94 * PyramidProcessor is specified or the options have keepOctaves set
95 * to true, then the octaves of the pyramid will be retained.
96 *
97 * @param img image to build pyramid from.
98 */
99 public abstract void process(IMAGE img);
100
101 /* (non-Javadoc)
102 * @see org.openimaj.image.analyser.ImageAnalyser#analyseImage(org.openimaj.image.Image)
103 */
104 @Override
105 public void analyseImage(IMAGE image) {
106 process(image);
107 }
108
109 /**
110 * Get the options used to initialise this pyramid
111 * @return the options
112 */
113 public OPTIONS getOptions() {
114 return options;
115 }
116
117 /**
118 * Set the options used to initialise this pyramid
119 * @param options the options
120 */
121 public void setOptions(OPTIONS options) {
122 this.options = options;
123 }
124
125 /**
126 * Get the octaves of this pyramid if they have
127 * been retained by the processing.
128 *
129 * @return the octaves
130 */
131 public List<OCTAVE> getOctaves() {
132 return octaves;
133 }
134
135 /* (non-Javadoc)
136 * @see java.lang.Iterable#iterator()
137 */
138 @Override
139 public Iterator<OCTAVE> iterator() {
140 if (octaves == null) return null;
141 return octaves.iterator();
142 }
143 }