InputFrameSeries Class Reference

A FrameSeries with additional facilities for reading input frames. More...

#include <Media/FrameSeries.H>

Inheritance diagram for InputFrameSeries:

[legend]

Collaboration diagram for InputFrameSeries:

[legend]

List of all members.

Classes
struct	Impl
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.
virtual void	setFrameDims (Dims d)
virtual Dims	getFrameDims ()
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.
FrameRange	getFrameRange () const
	Get a copy of the framerange.
bool	setFrameNumber (int n)
	Force the frame number to a new value.
Friends
struct	Impl

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.

Constructor & Destructor Documentation

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

Constructor.

Definition at line 668 of file FrameSeries.C.

InputFrameSeries::~InputFrameSeries ( ) [virtual]

Destructor.

Definition at line 693 of file FrameSeries.C.

Member Function Documentation

int InputFrameSeries::frame ( ) const

Get the current frame number.

Definition at line 986 of file FrameSeries.C.

References FrameCounter::currentFrame().

FrameRange InputFrameSeries::getFrameRange ( ) const

Get a copy of the framerange.

Definition at line 1001 of file FrameSeries.C.

References OModelParam< T >::getVal().

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

Get a reference to our frame source.

Definition at line 992 of file FrameSeries.C.

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 728 of file FrameSeries.C.

References ModelComponent::addSubComponent(), ModelComponent::getManager(), OModelParam< T >::getVal(), makeFrameOstream(), MC_RECURSE, 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 910 of file FrameSeries.C.

References ASSERT, FrameCounter::currentFrame(), Rectangle::dims(), OModelParam< T >::getVal(), Dims::isNonEmpty(), and GenericFrame::RGB_U8.

GenericFrame InputFrameSeries::readFrame ( ) [virtual]

Read a GenericFrame.

Implements FrameIstream.

Definition at line 955 of file FrameSeries.C.

References ModelComponent::started().

void InputFrameSeries::reset1 ( ) [virtual]

resets this FrameSeries to its state after construction

Reimplemented from ModelComponent.

Definition at line 699 of file FrameSeries.C.

References OModelParam< T >::getVal(), and FrameCounter::reset().

bool InputFrameSeries::setFrameNumber ( int n ) [virtual]

Force the frame number to a new value.

Reimplemented from FrameIstream.

Definition at line 1007 of file FrameSeries.C.

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

Set the frame source; same as doing --in=source on the command line.

Definition at line 964 of file FrameSeries.C.

References ModelComponent::addSubComponent(), OModelParam< T >::getOptionDef(), ModelOptionDef::longoptname, makeFrameIstream(), MC_RECURSE, ModelComponent::removeSubComponent(), 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 810 of file FrameSeries.C.

References OModelParam< T >::getVal().

void InputFrameSeries::startStream ( ) [virtual]

Optional call to efficiently prepare for frame streaming.

Reimplemented from FrameIstream.

Definition at line 943 of file FrameSeries.C.

References ASSERT, and ModelComponent::started().

FrameState InputFrameSeries::update ( const SimTime & stime )

Update internal state and return corresponding FrameState.

Parameters: