FrameIstream.H

Go to the documentation of this file.
00001 /*!@file Transport/FrameIstream.H */
00002 
00003 // //////////////////////////////////////////////////////////////////// //
00004 // The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2000-2005   //
00005 // by the University of Southern California (USC) and the iLab at USC.  //
00006 // See http://iLab.usc.edu for information about this project.          //
00007 // //////////////////////////////////////////////////////////////////// //
00008 // Major portions of the iLab Neuromorphic Vision Toolkit are protected //
00009 // under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
00010 // in Visual Environments, and Applications'' by Christof Koch and      //
00011 // Laurent Itti, California Institute of Technology, 2001 (patent       //
00012 // pending; application number 09/912,225 filed July 23, 2001; see      //
00013 // http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
00014 // //////////////////////////////////////////////////////////////////// //
00015 // This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
00016 //                                                                      //
00017 // The iLab Neuromorphic Vision C++ Toolkit is free software; you can   //
00018 // redistribute it and/or modify it under the terms of the GNU General  //
00019 // Public License as published by the Free Software Foundation; either  //
00020 // version 2 of the License, or (at your option) any later version.     //
00021 //                                                                      //
00022 // The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope  //
00023 // that it will be useful, but WITHOUT ANY WARRANTY; without even the   //
00024 // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      //
00025 // PURPOSE.  See the GNU General Public License for more details.       //
00026 //                                                                      //
00027 // You should have received a copy of the GNU General Public License    //
00028 // along with the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
00029 // to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
00030 // Boston, MA 02111-1307 USA.                                           //
00031 // //////////////////////////////////////////////////////////////////// //
00032 //
00033 // Primary maintainer for this file: Rob Peters <rjpeters at usc dot edu>
00034 // $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Transport/FrameIstream.H $
00035 // $Id: FrameIstream.H 13273 2010-04-21 22:08:00Z rand $
00036 //
00037 
00038 #ifndef TRANSPORT_FRAMEISTREAM_H_DEFINED
00039 #define TRANSPORT_FRAMEISTREAM_H_DEFINED
00040 
00041 #include "Component/ModelComponent.H"
00042 #include "Util/Types.H" // for byte
00043 
00044 class Dims;
00045 class GenericFrame;
00046 class GenericFrameSpec;
00047 class SimTime;
00048 class FrameRange;
00049 template <class T> class Image;
00050 template <class T> class PixRGB;
00051 
00052 // ######################################################################
00053 /// Listener class that can get called each time a FrameIstream grabs a frame
00054 /** Different FrameIstream subclasses may use their FrameListener
00055     differently, or possibly even ignore the FrameListener. */
00056 class FrameListener
00057 {
00058 public:
00059   virtual ~FrameListener();
00060 
00061   virtual void onRawFrame(const GenericFrame& frame) = 0;
00062 };
00063 
00064 //! Abstract interface class representing a source of Image frames
00065 /*! Concrete classes might implement this interface so that the real
00066     source is a series of bitmap files (RasterInputSeries), or a movie
00067     file (InputMPEGSeries), or an external device (V4Lgrabber,
00068     IEEE1394grabber).
00069 
00070     See also FrameOstream for the analogous output interface. */
00071 class FrameIstream : public ModelComponent
00072 {
00073 public:
00074   //! Constructor
00075   FrameIstream(OptionManager& mgr,
00076                const std::string& descrName,
00077                const std::string& tagName);
00078 
00079   //! Virtual destructor
00080   virtual ~FrameIstream();
00081 
00082   //! Configure the FrameIstream object in a type-dependent manner
00083   /*! The string is expected to be some piece of user input (e.g. from
00084       the command-line) specifying key information for the
00085       FrameIstream (e.g., the filename for an input movie).
00086 
00087       The default implementation does nothing; derived classes can
00088       override if they need to receive such user input.
00089   */
00090   virtual void setConfigInfo(const std::string& cfg);
00091 
00092   /// Install a FrameListener; default implementation does nothing
00093   /** Subclasses may override this method if they want to actually
00094       pass some information to the listener. */
00095   virtual void setListener(rutz::shared_ptr<FrameListener> listener);
00096 
00097   //! Advise the FrameIstream object of the current frame number
00098   /*! NOTE: the default implementation does nothing -- it just ignores
00099       the frame number. This is allowed for subclasses, too, since for
00100       certain input formats (e.g., framegrabbers) it doesn't make any
00101       sense to specify a frame number, since the format doesn't
00102       support random-access reading. On the other hand, certain
00103       subclasses require a frame number to function properly (e.g.,
00104       for writing a series of consecutively-numbered raster
00105       files). So, the bottom line is: clients of FrameIstream must be
00106       sure to call setFrameNumber(), but should make no assumptions
00107       about what it will actually do.
00108 
00109       @return Whether the frame number was succesfully set as
00110       requested. The function may fail, for instance, in the case of
00111       an input source like a movie file that has only a limited number
00112       of frames.
00113   */
00114   virtual bool setFrameNumber(int n);
00115 
00116   //! Return the specifications of the next frame
00117   /*! Subclasses may have to load the next frame in order to peek at
00118       the dimensions, then cache that frame and return it the next
00119       time readRGB(), readGray(), or readFloat() is called. */
00120   virtual GenericFrameSpec peekFrameSpec() = 0;
00121 
00122   //! Get the natural inter-frame time for this frame source
00123   /*! A return value of 0 means that there is no particular natural
00124       inter-frame time; the default implementation returns 0 so
00125       subclasses should override if they need to specify a different
00126       inter-frame time.
00127 
00128       This information should be treated as advisory only; for
00129       instance, callers might use this information to try to display
00130       frames to the user at the "natural" framerate.
00131   */
00132   virtual SimTime getNaturalFrameTime() const;
00133 
00134   //! Convenience function to get the frame dims from peekFrameSpec()
00135   Dims peekDims();
00136 
00137   //! Convenience function to get the frame width from peekFrameSpec()
00138   int getWidth();
00139 
00140   //! Convenience function to get the frame height from peekFrameSpec()
00141   int getHeight();
00142 
00143   //! Optional call to efficiently prepare for frame streaming
00144   /*! Some FrameIstream subclasses may require some preparatory work
00145       before they can start returning image frames, and this function
00146       lets that work be done outside of the application's main
00147       frame-reading loop.
00148 
00149       A good example of this is streaming-mode frame-grabbers, such as
00150       the video4linux driver. To use that driver in streaming mode,
00151       each of the internal frame buffers must be started, but they
00152       shouldn't be started "too soon" either; so, it's best to call
00153       startStream() just before the main loops starts calling
00154       readFrame() (or readRGB(), etc.).
00155 
00156       Subclass authors should design their classes so that readFrame()
00157       always "just works", regardless of whether the user has called
00158       startStream() or not, typically by keeping a flag to mark
00159       whether startStream() has been called, and then calling
00160       startStream() from within the first readFrame() call, if
00161       needed.
00162 
00163       The default implementation of startStream() is a no-op.
00164   */
00165   virtual void startStream();
00166 
00167   //! Read a frame from the input source
00168   /*! The actual input source could be a raster file, a movie file, or
00169       some external device, etc., depending on the concrete subclass. */
00170   virtual GenericFrame readFrame() = 0;
00171 
00172   //! Read an image from the input source
00173   /*! The actual input source could be a raster file, a movie file, or
00174       some external device, etc., depending on the concrete subclass.
00175 
00176       The default implementation just returns readFrame().asRgb(). */
00177   virtual Image<PixRGB<byte> > readRGB();
00178 
00179   //! the specific 12 bit depth (actually any uint16 data type) implemtation
00180   //! return from readFrame().asRgb16().
00181   virtual Image<PixRGB<uint16> > readRGBU16();
00182 
00183   //! Read an image from the input source
00184   /*! The actual input source could be a raster file, a movie file, or
00185       some external device, etc., depending on the concrete subclass.
00186 
00187       The default implementation just returns readFrame().asGray(). */
00188   virtual Image<byte> readGray();
00189 
00190   //! the specific 12 bit depth (actually any uint16 data type) implemtation
00191   //! return from readFrame().asRgb16().
00192   virtual Image<uint16> readGrayU16();
00193 
00194   //! Read an image from the input source
00195   /*! The actual input source could be a raster file, a movie file, or
00196       some external device, etc., depending on the concrete subclass.
00197 
00198       The default implementation just returns readFrame().asFloat(). */
00199   virtual Image<float> readFloat();
00200 
00201   //! Read a frame from the stream and discard it
00202   /*! Subclasses may be able to implement this function more
00203       efficiently than the other functions that actually return an
00204       Image object (since they might avoid converting from some raw
00205       representation to Image). So, if you know you are going to
00206       discard the frame (e.g. to skip ahead to a certain frame number,
00207       or to count the frame), then it is more efficient to call
00208       readAndDiscardFrame() than to call readVideoFrame() or readRGB()
00209       but ignore the result.
00210 
00211       The return value will be true if a frame was actually read, or
00212       false if no frame was found (e.g., end-of-stream was reached).
00213 
00214       The default implementation just calls readRGB() but ignores the
00215       result.
00216   */
00217   virtual bool readAndDiscardFrame();
00218 
00219   //! Return whether or not this stream supports seek operations
00220   /*! This function should be reimplemented in subclasses to let
00221       users know whether or not random frame access is supported.
00222       The default implementation returns false.
00223   */
00224   virtual bool supportsSeek();
00225 
00226   //! Return the frame range for this particular input stream. 
00227   /*! This is particuarly applicable for FrameIstreams dealing with video files
00228       and image directories, in which case it may be easier to get this value
00229       from the underlying FrameIstream, rather than the command line. The default
00230       behavior is to just return the default empty FrameRange, but should be overloaded
00231       for stream sources which can return sensical ranges.
00232    */
00233   virtual FrameRange getFrameRange();
00234 };
00235 
00236 // ######################################################################
00237 /* So things look consistent in everyone's emacs... */
00238 /* Local Variables: */
00239 /* indent-tabs-mode: nil */
00240 /* End: */
00241 
00242 #endif // TRANSPORT_FRAMEISTREAM_H_DEFINED
Generated on Sun May 8 08:42:24 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3