InputFrameSeries Class Reference

#include <Media/FrameSeries.H>

Inheritance diagram for InputFrameSeries:

[legend]Collaboration diagram for InputFrameSeries:

[legend]List of all members.

---

Detailed Description

A FrameSeries with additional facilities for reading input frames.

General notes for InputFrameSeries and OutputFrameSeries: these classes keep track of a range of frames ([first..last]) and an interframe delay in seconds (see FrameRange.H). The key behavior is the update() function, which takes the current simulation time in seconds and the simulation step in s, and returns a status code indicating whether the frame series (a) was unchanged, (b) will require that the next frame be loaded just before the simulation time is advanced by the current simulation step, or (c) is finished.

InputFrameSeries implements a number of helper functions to facilitate reading frames in a standardized manner, with possible on-the-fly rescaling and visualization.

NOTE: if we're in test mode (because --test-mode was given on the command line), we will turn off all displays even though they may be on here (actually what happens is that ImageDisplayStream refuses to do anything if in --test-mode).

NOTE: when start() is called, we will set the "FOAradius", "FoveaRadius", "InputFrameDims", "SCinitialEyePosition" and "SCinitialHeadPosition" model parameters from input image dims, if someone wants them and they have not been set.

NOTES on controlling InputFrameSeries and OutputFrameSeries from the command-line:

Examples:

      --in=raster:foo.ppm
      --in=raster:#.png   [to get foo000000.ppm, foo000001.ppm, etc.]
      --in=mpeg:/path/to/file.mpg
      --in=random:512x512
      --in=colorbars

      --out=display
      --out=qt
      --out=mpeg
      --out=png:/path/to/basestem
      --out=pnm:/path/to/basestem
      --out=none
      --out=hash

      --io=raster:path/to/framestem
      --io=mpeg:file.mpg
    

Any time you use an InputFrameSeries or OutputFrameSeries, you can automatically use input/output in any of the formats that we support. That means:

• your InputFrameSeries can take input from a series of raster files (the previous default behavior), or from any movie file that is readable by avcodec, or from an in-memory random number generator. Other input formats are possible, please write your own subclass of FrameIstream and add command-line support for it to InputFrameSeries.

• your OutputFrameSeries can generate output going to series of raster files (the previous default behavior), or to mpeg files, or to onscreen windows, or to nowhere at all. Again, other output formats are possible, please write your own subclass of FrameOstream and add command-line support for it to OutputFrameSeries.

The simplest behavior (which matches the historical behavior of the ezvision executable in which input and output both deal with raster file series using the same filename stem) can be gotten like this:

./bin/ezvision --bunch --of --options --io=raster:myinputfilestem

To get to the more advanced features, you can use --in and --out instead of --io (note that --io=foo is just an alias for --in=foo --out=foo). For any of the options, you want to pass something of the form "type:spec", where 'type' is one of <raster|mpeg|random> for input options, or <raster|mpeg|display|none> for output options. The 'spec' part is type-dependent; for raster or mpeg the spec gives the filename or filename stem; for random, the spec is the desired image size as WWWxHHH (e.g. 512x512); for display and none, the spec is not required.

As a shorthand convenience, you can eliminate either the type or spec if it can be inferred from the other part. E.g., if your spec ends in a raster file extension (.ppm, .pnm, .png, .pgm) or mpeg file extension (.mpg, .mpeg, .m4v), you can skip the 'type' and just do --in=file.ppm or --out=file.mpg, which will be interpreted as --in=raster:file.ppm or --out=mpeg:file.mpg. Likewise, for the types that don't require any extra spec info, you can just do --out=display or --out=none, which are shorthand for --out=display: and --out=none:.

Note that you can only have one input source, so if you have multiple --in or --io options on your command-line, the last such option will override all previous ones.

On the other hand, you can reasonably have multiple output destinations, so if there are multiple --out or --io options on the command-line, the output will be sent to all destinations in parallel. So, if you want to save your results to files but also watch them onscreen as the computation progresses, you could do --out=mpeg --out=display. As a special case, if you do --out=none, it will cancel any previous --out options (though later --out options will still take effect).

Finally, you can use the --in-echo option to specify one or more destinations to which copies of the input should be sent. The --in-echo option accepts the same types of values as does --out, so e.g. if you want to see your input stream in an onscreen window, you can do --in=mpeg:myfile.mpg --in-echo=display.

A couple other miscellaneous things:

• the [no]display-input frames and [no]display-output-frames options have been superseded by the new, more flexible behavior -- if you want to mimic --nodisplay-input-frames or --nodisplay-output-frames, just do nothing since the default is for the frames to not be displayed onscreen. If you do want display, you can use --in-copy=display and/or --out=display.

• there is a new command-line flag, --[no]wait, that controls the result of InputFrameSeries::shouldWait() and OutputFrameSeries::shouldWait(), which is used to determine whether we do a Raster::waitForKey() in the main loop after processing a new input or output frame; the default is --nowait, so if you want the pause, then you should do an explicit --wait on the command-line

Definition at line 185 of file FrameSeries.H.

Public Member Functions
	InputFrameSeries (OptionManager &mgr, const std::string &descrName="Frame Series", const std::string &tagName="FrameSeries")
	Constructor.
virtual	~InputFrameSeries ()
	Destructor.
virtual void	reset1 ()
	resets this FrameSeries to its state after construction
virtual void	paramChanged (ModelParamBase *const param, const bool valueChanged, ParamClient::ChangeStatus *status)
	Override the base version so that we can trap --in and --in-echo options.
FrameState	update (const SimTime &stime)
	Update internal state and return corresponding FrameState.
FrameState	updateNext ()
	Update by moving to the next frame and not worrying about time counts.
bool	shouldWait () const
	Have we displayed frames and need to wait for a user keypress?
virtual GenericFrameSpec	peekFrameSpec ()
	Get specifications of the image frames.
virtual void	startStream ()
	Optional call to efficiently prepare for frame streaming.
virtual GenericFrame	readFrame ()
	Read a GenericFrame.
void	setFrameSource (const std::string &source)
	Set the frame source; same as doing --in=source on the command line.
int	frame () const
	Get the current frame number.
nub::ref< FrameIstream >	getFrameSource () const
	Get a reference to our frame source.
Friends
struct	Impl
Classes
struct	Impl

---

Constructor & Destructor Documentation

InputFrameSeries::InputFrameSeries (  OptionManager &  mgr, const std::string &  descrName = "Frame Series", const std::string &  tagName = "FrameSeries" )

Constructor. Definition at line 624 of file FrameSeries.C. References init_manager, istream_init(), istream_init_once, ostream_init(), and ostream_init_once.

InputFrameSeries::~InputFrameSeries (   )  [virtual]

Destructor. Definition at line 648 of file FrameSeries.C.

---

Member Function Documentation

int InputFrameSeries::frame (   )  const

Get the current frame number. Definition at line 885 of file FrameSeries.C. References InputFrameSeries::Impl::counter, and FrameCounter::currentFrame().

nub::ref< FrameIstream > InputFrameSeries::getFrameSource (   )  const

Get a reference to our frame source. Definition at line 891 of file FrameSeries.C. References nub::soft_ref< T >::is_valid(), LFATAL, and InputFrameSeries::Impl::source.

void InputFrameSeries::paramChanged (  ModelParamBase *const   param, const bool  valueChanged, ParamClient::ChangeStatus *  status )  [virtual]

Override the base version so that we can trap --in and --in-echo options. Reimplemented from ModelComponent. Definition at line 666 of file FrameSeries.C. References ModelComponent::addSubComponent(), InputFrameSeries::Impl::counter, InputFrameSeries::Impl::echoes, ModelComponent::getManager(), OModelParam< T >::getVal(), makeFrameOstream(), MC_RECURSE, mgr, ModelComponent::paramChanged(), FrameCounter::reset(), and setFrameSource().

GenericFrameSpec InputFrameSeries::peekFrameSpec (   )  [virtual]

Get specifications of the image frames. It is okay to call this before the model is started(). If input resizing is being done, the returned dimensions will be the resized dims. All in all, this will return the size of whatever you will get when calling readFrame(), readRGB(), etc. Implements FrameIstream. Definition at line 809 of file FrameSeries.C. References ASSERT, InputFrameSeries::Impl::counter, FrameCounter::currentFrame(), Rectangle::dims(), GenericFrameSpec::dims, OModelParam< T >::getVal(), nub::soft_ref< T >::is_valid(), Dims::isNonEmpty(), isRectEmpty(), LFATAL, GenericFrameSpec::nativeType, GenericFrame::RGB_U8, InputFrameSeries::Impl::source, and InputFrameSeries::Impl::sourceDescription.

GenericFrame InputFrameSeries::readFrame (   )  [virtual]

Read a GenericFrame. Implements FrameIstream. Definition at line 854 of file FrameSeries.C. References LFATAL, and InputFrameSeries::Impl::readFrame().

void InputFrameSeries::reset1 (   )  [virtual]

resets this FrameSeries to its state after construction Reimplemented from ModelComponent. Definition at line 654 of file FrameSeries.C. References InputFrameSeries::Impl::counter, OModelParam< T >::getVal(), InputFrameSeries::Impl::inputEof, InputFrameSeries::Impl::numEchoed, FrameCounter::reset(), and ModelComponent::reset1().

void InputFrameSeries::setFrameSource (  const std::string &  source  )

Set the frame source; same as doing --in=source on the command line. Definition at line 863 of file FrameSeries.C. References ModelComponent::addSubComponent(), ModelComponent::getManager(), OModelParam< T >::getOptionDef(), nub::soft_ref< T >::is_valid(), LFATAL, ModelOptionDef::longoptname, makeFrameIstream(), MC_RECURSE, ModelComponent::removeSubComponent(), InputFrameSeries::Impl::source, InputFrameSeries::Impl::sourceDescription, and ModelOptionDef::validvals. Referenced by paramChanged().

bool InputFrameSeries::shouldWait (   )  const

Have we displayed frames and need to wait for a user keypress? This is reset to false on each call to update(), and becomes true if (1) any frames were written AND (2) itsWaitForUser is true (which the use can control with --wait/--nowait). You can check it in order to decide whether you should pause and wait for the user after each series of displays at a given time step). Definition at line 747 of file FrameSeries.C. References OModelParam< T >::getVal(), and InputFrameSeries::Impl::numEchoed. Referenced by Inputframeseries_Init().

void InputFrameSeries::startStream (   )  [virtual]

Optional call to efficiently prepare for frame streaming. Reimplemented from FrameIstream. Definition at line 842 of file FrameSeries.C. References ASSERT, nub::soft_ref< T >::is_valid(), LFATAL, and InputFrameSeries::Impl::source.

FrameState InputFrameSeries::update (  const SimTime &  stime  )

Update internal state and return corresponding FrameState. Parameters: stime  current time in seconds sdelay  time step in seconds Definition at line 710 of file FrameSeries.C. References InputFrameSeries::Impl::counter, FrameCounter::currentFrame(), OModelParam< T >::getVal(), InputFrameSeries::Impl::inputEof, InputFrameSeries::Impl::lastUpdateTime, LDEBUG, SimTime::msecs(), InputFrameSeries::Impl::numEchoed, InputFrameSeries::Impl::source, and FrameCounter::update(). Referenced by Inputframeseries_Init().

FrameState InputFrameSeries::updateNext (   )

Update by moving to the next frame and not worrying about time counts. Definition at line 741 of file FrameSeries.C. References InputFrameSeries::Impl::counter, and FrameCounter::updateNext(). Referenced by Inputframeseries_Init().

---

The documentation for this class was generated from the following files:

• src/Media/FrameSeries.H
• src/Media/FrameSeries.C

---