iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
VideoReaderBase.H
Go to the documentation of this file.
1 /*! @file
2  @author Randolph Voorhies
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_IMAGEPROC_IO_IMAGESOURCE_VIDEOREADERS_DETAILS_VIDEOREADERBASE_H
37 #define INCLUDE_NRT_IMAGEPROC_IO_IMAGESOURCE_VIDEOREADERS_DETAILS_VIDEOREADERBASE_H
38 
42 
43 namespace nrt
44 {
45  //! A base class for video readers
46  /*! VideoReaderBase is an abstract base class for video file readers. A class which inherits from VideoReaderBase can be registered with
47  the VideoSource (and thus, the ImageSource) framework, allowing users to easily read video files handled by your class.
48 
49  In order to make a new video file reader, you should derive from this class (implementing all of the necessary pure-virtual methods)
50  and then register the class using the NRT_REGISTER_VIDEO_READER(CLASSNAME) macro. Additionally, you must implement:
51 
52  \li A static std::string id() method which returns the file extensions that your video reader can parse. Multiple choices can be
53  specified by separating them with a '|' character, e.g. "mpg|mpeg".
54 
55  \li A static std::string description() method which returns a helpful description of your video reader/format.
56 
57  Optionally, you should also consider implementing a writer class which derives from VideoWriterBase so that users can write as well as
58  read your new video format.
59 
60  \see VideoSource
61  \see ImageSource */
63  {
64  public:
65  //! Open the given filename, and prepare to start reading frames
66  /*! This method must completely prepare the class such that an
67  immediately subsequent call to in() should not fail. Additionally,
68  this method may be called repeatedly with different filenames so it
69  must clean up any allocated resources. */
70  virtual void open(std::string const& filename) = 0;
71 
72  //! Destructor
73  /*! The destructor must clean up any allocated resources*/
74  virtual ~VideoReaderBase() {};
75 
76  //! Seek to the requested frame such that the next call to in() will read that frame
77  /*! If the given frameNumber is out of bounds, then this method should
78  return false and take no other action.*/
79  virtual bool const seek(size_t const frameNumber) = 0;
80 
81  //! Read the current frame, and seek to the next frame
82  virtual GenericImage const in() = 0;
83 
84  //! Get the frame range of the video file
85  virtual FrameRange const frameRange() = 0;
86 
87  //! Get the number of the frame that will be returned by the next call to in()
88  virtual size_t const nextFrameNumber() = 0;
89 
90  //! Return whether or not a subsequent call to in() will return a valid frame
91  /*! Gennerally, this function should check to make sure that the video file is open,
92  and that the current frame number is within the bounds returned by frameRange() */
93  virtual bool const ok() = 0;
94  };
95 
96  //! A Singleton Factory used to keep track of video writers used by VideoSink.
97  /*! Developers who wish to create their own video writer classes should
98  register them with the NRT_REGISTER_VIDEO_WRITER(CLASSNAME) macro so that they may be
99  recognized by VideoSink
100  \see VideoReaderBase
101  \see VideoSource
102  \see ImageSource */
103  typedef Factory<
104  std::shared_ptr<VideoReaderBase>,
105  std::string,
106  std::function<std::shared_ptr<VideoReaderBase>()>,
107  std::map<std::string, std::string>
109 }
110 
111 /*! \def NRT_REGISTER_VIDEO_READER(CLASSNAME)
112  Register a video reader with a global Factory.
113 
114  When creating a new video reader class that inherits from VideoReaderBase to
115  parse a video file type, you should register that class with the
116  VideoReaderFactory using this macro so that your new parser will be called
117  whenever users try to open your associated video type with an ImageSource or
118  a VideoSource.
119  \see VideoReaderBase
120  \see VideoSource
121  \see ImageSource
122 */
123 #define NRT_REGISTER_VIDEO_READER(CLASSNAME) \
124  std::shared_ptr<nrt::VideoReaderBase> create##CLASSNAME() \
125  { return std::shared_ptr<nrt::VideoReaderBase>(new CLASSNAME); } \
126  bool videoReaderRegister##CLASSNAME() \
127  { \
128  std::map<std::string,std::string> metadata; \
129  metadata["id"] = CLASSNAME::id(); \
130  metadata["description"] = CLASSNAME::description(); \
131  nrt::VideoReaderFactory::instance().registerType( \
132  metadata["id"], \
133  create##CLASSNAME, \
134  metadata \
135  ); \
136  return true; \
137  } \
138  const bool CLASSNAME##Registered __attribute__ ((unused)) = \
139  videoReaderRegister##CLASSNAME();
140 
141 #endif // INCLUDE_NRT_IMAGEPROC_IO_IMAGESOURCE_VIDEOREADERS_DETAILS_VIDEOREADERBASE_H
142