Base class of the CAVAPA calculations. More...

#include <analysiscontroller.h>

Inheritance diagram for cavapa_gui::AnalysisController:

Signals
void	calculationComplete ()
	Signals that calculation has ended. More...

void	error (const std::string &message, ErrorLevel level)
	Signals that something went wrong during the calculation. More...

void	updated (const std::vector< FrameCapture > &frames, const FrameStats &statistics)
	It signals frame updates or calculation updates. More...

Public Member Functions
	AnalysisController ()
	Creates the CAVAPA object.

	DISALLOW_COPY_AND_ASSIGN (AnalysisController)
	Copy and assign of the class is not allowed.

SourceID	addSource (const std::string &path, SourceID id=UNDEFINED_SOURCE, FrameTime start_point=0)
	Adds a custom video source. More...

bool	addSource (const std::vector< std::string > &paths, SourceID id=UNDEFINED_SOURCE, FrameTime start_point=0)
	Adds a custom source with multiple files and a fixed ID number. More...

bool	canChangeSourceResolution (SourceID id) const
	Checks if the source resolution can be changed. More...

bool	canPause () const
	Indicates if the running calculation can be paused. More...

int	countAvailableCameras () const
	Counts the available connected hardware cameras. More...

bool	exportResults (const ExportOptions &options) const
	Exports the current Results to the CSV File. More...

double	getCalculationFPS () const
	Retrieves the calculation framerate. More...

std::string	getLastError () const
	Retrieves the last error that occured. More...

std::vector< FrameStats >	getResults (FrameTime start, FrameTime stop, int points) const
	Returns calculation results from a given period. More...

int	getSourceCount () const
	Retrieves the total count of sources. More...

std::string	getSourceDescription (SourceID id) const
	Returns the description of the source. More...

std::vector< cv::Rect >	getSourceExcludes (SourceID id) const
	Returns the currently excluded rectangles from the source. More...

std::vector< std::string >	getSourceFilenames (SourceID id) const
	Returns the list of the files associated with the source. More...

std::vector< SourceID >	getSourceListing () const
	Returns a list of all sources in the class. More...

FrameTime	getSourcePosition (SourceID id) const
	Retrieves the current time position of a source. More...

cv::Size	getSourceResolution (SourceID id) const
	Retrieves the source's frame resolution. More...

SourceStats	getSourceStats (SourceID id) const
	Retrieves the source's current statistics. More...

SourceType	getSourceType (SourceID id) const
	Returns the type of the selected source. More...

FrameTime	getVideoLength (SourceID id) const
	Retrieves the length of the video source. More...

int	initCameras (int max_loops=10)
	Initializes the hardware cameras. More...

bool	isPaused () const
	Retrieves the current pause status. More...

bool	isRunning () const
	Retrieves the current status of the calculation. More...

bool	load (const std::string &path="results.cpa")
	Loads the calculation results and recorded file information. More...

bool	pause ()
	Pauses or unpauses the calculation. More...

bool	removeSource (SourceID id)
	Removes the source. More...

bool	reset ()
	Resets the calculation results. More...

bool	save (const std::string &path="results.cpa")
	Saves the calculation results and sightings. More...

bool	setCameraFPS (double fps)
	Sets the default FPS for camera sources. More...

void	setHighlight (bool highlight)
	Sets the individual sighting rectangle highlights. More...

void	setHighlightColor (const cv::Scalar &color)
	Sets the sighting's highlighting color. More...

bool	setPosition (FrameTime pos)
	Sets the current time position of all the sources. More...

bool	setRecorderCodec (const std::string &codec, const std::string &extension="avi")
	Sets the default camera recorder codec. More...

void	setRecordTimeLimit (unsigned int length)
	Sets the maximum length of one recording. More...

bool	setSourceBarrelCorrection (SourceID id, double amount)
	Sets the barrel correction on a source. More...

void	setSourceExcludes (SourceID id, const std::vector< cv::Rect > &rects)
	Sets the excluded rectangles for a source. More...

bool	setSourceResolution (SourceID id, const cv::Size &new_size)
	Sets the source resolution. More...

bool	setVideoSpeed (double ratio=1.0)
	Sets the video source speed. More...

void	setWorkDirectory (const std::string &path)
	Sets the path for the calculation directory. More...

bool	sourceCanRecord (SourceID id) const
	Checks if the source is capable of recording. More...

bool	sourcePlay (SourceID id)
	Starts playing a video source. More...

bool	sourceSeek (SourceID id, FrameTime position)
	Seeks the video source to a specific time. More...

bool	sourceStepBackward (SourceID id)
	Steps the source one frame back. More...

bool	sourceStepForward (SourceID id)
	Steps the source one frame forward. More...

bool	sourceStop (SourceID id)
	Stops playing the video source. More...

bool	start (const std::vector< SourceID > &calc_sources, const std::vector< cavapa::CameraSettings > &settings, const std::vector< cavapa::CalibrationPoint > &points, bool record=false, int calc_time=0)
	Starts the CAVAPA calculation. More...

void	stop ()
	Stops the current CAVAPA calculation. More...

Detailed Description

Base class of the CAVAPA calculations.

The class is the heart of the CAVAPA calculation handling. Its purpose is to retrieve frames from the sources and pass them to the CAVAPA algorithm. It also stores the calculation results and includes the frame update timer.

The class can detect connected hardware cameras with initCameras() but any other video source must be manually added with addSource(). Once the sources are selected the calculation can be started with start().

During the calculation the class sends signals updated() on each frame. The calculation can then be stopped with stop() or if the calculation terminates on its own signal calculationComplete() is sent. Any errors during the calculation can be catched from the signal error().

User can select the calculation framerate with setCameraFPS when cameras are used as a source. When video files are used the framerate cannot be selected. The individual sources can be played and altered when the calculation is not running.

Author: Petri Partanen

Member Function Documentation

SourceID cavapa_gui::AnalysisController::addSource	(	const std::string &	path,
		SourceID	id = `UNDEFINED_SOURCE`,
		FrameTime	start_point = `0`
	)

Adds a custom video source.

Network cameras or video files need to be added with the method. The base recognizes automatically only hardware cameras.

Parameters

path	The video source path can be url or video file.
id	The desired ID number of the new source. This source ID must not exist. Use UNDEFINED_SOURCE to get a new unique ID.
start_point	Source start point will be used as the initial position of the source. All calls to setPosition() will use this as base. This is not used for sourceSeek() or other methods. It also has no effect on any other than video files.

Returns: ID number that was assigned to the new source or UNDEFINED_SOURCE if failed. Use getLastError() to retrieve reason for failure.

bool cavapa_gui::AnalysisController::addSource	(	const std::vector< std::string > &	paths,
		SourceID	id = `UNDEFINED_SOURCE`,
		FrameTime	start_point = `0`
	)

Adds a custom source with multiple files and a fixed ID number.

It can be used to play existing results from video files.

Parameters

paths	The ordered list of the video filenames.
id	The desired ID number of the new source. The source ID must not exist. Use UNDEFINED_SOURCE to get a new unique ID.
start_point	The source start point. Will be used as the initial position of the source. All calls to setPosition() will use this as base. This is not used for sourceSeek() or other methods. It also has no effect on any other than video files.

Returns: True if all files were successfully opened or false otherwise. Use getLastError() to retrieve reason for failure.

Remarks: All video files must match in resolution and framerate.

void cavapa_gui::AnalysisController::calculationComplete ( )

signal

Signals that calculation has ended.

It is sent for example when the video file source has reached its last frame. It could also be sent when the disk has ran out of space.

Remarks: The last signal of updated() or error() is sent just before this.

bool cavapa_gui::AnalysisController::canChangeSourceResolution ( SourceID id ) const

Checks if the source resolution can be changed.

Parameters

id	The source ID number.

Returns: True if the resolution can be changed or false otherwise.

Remarks: You can expect that most likely only hardware cameras will return true.

bool cavapa_gui::AnalysisController::canPause ( ) const

Indicates if the running calculation can be paused.

Returns: True if pause is possible or false otherwise.

Remarks: Most likely will be true only if all sources are video files.

int cavapa_gui::AnalysisController::countAvailableCameras ( ) const

Counts the available connected hardware cameras.

The method only recognizes USB and other cameras. No network streams or other sources are counted. This will not re-attempt to open already open HW-devices.

Returns: The total amount of hardware cameras that are currently initialized.

void cavapa_gui::AnalysisController::error	(	const std::string &	message,
		ErrorLevel	level
	)

signal

Signals that something went wrong during the calculation.

It is used when there is no other way to indicate an error.

Parameters

message	The error message.
level	The error level.

Remarks: When an error happens during a call to a public method, they return failure value and that information can then be retrieved with getLastError(). Those errors do not raise this signal separately.

bool cavapa_gui::AnalysisController::exportResults ( const ExportOptions & options ) const

inline

Exports the current Results to the CSV File.

Parameters

options The parameters for export.

Returns: True if the export was successful or false otherwise.

double cavapa_gui::AnalysisController::getCalculationFPS ( ) const

inline

Retrieves the calculation framerate.

It retrieves only the current running calculation framerate. It may not be what was given with setFPS() as it is adjusted to match the selected source framerates.

Returns: The current framerate or 0.0 if no calculation is running.

std::string cavapa_gui::AnalysisController::getLastError ( ) const

inline

Retrieves the last error that occured.

Some of the class methods return failure values and this method can be used to retrieve more detailed information on what happened.

Returns: The error description.

std::vector<FrameStats> cavapa_gui::AnalysisController::getResults	(	FrameTime	start,
		FrameTime	stop,
		int	points
	)		const

inline

Returns calculation results from a given period.

It can be used to return frame results from a certain period. Average values are calculated automatically from the returned period points.

Parameters

start	The period start time. If 0, the period will start from the first possible frame.
stop	The period end time. If 0, the period will end at the last possible frame.
points	The number of points to return from the specified period.

Returns: The calculation results from a given period. There will be [0, 'points'] number of FrameStats returned.

int cavapa_gui::AnalysisController::getSourceCount ( ) const

inline

Retrieves the total count of sources.

It just sums up all the sources in the class, similarly as retrieving the source listing with getSourceListing() and checking its size.

Returns: The total available source count, including hardware cameras and other sources.

string cavapa_gui::AnalysisController::getSourceDescription ( SourceID id ) const

Returns the description of the source.

Parameters

id	The source ID number.

Returns: The camera name for the hardware cameras, the path for video files and the network streams.

Remarks: Similar hardware cameras will have the same description due to the model name. Some cameras may return just an empty string.

std::vector<cv::Rect> cavapa_gui::AnalysisController::getSourceExcludes ( SourceID id ) const

Returns the currently excluded rectangles from the source.

Parameters

id	The source ID number.

Returns: The list of rectangles that are currently drawn on the top of each frame before they are passed to the algorithm.

vector< string > cavapa_gui::AnalysisController::getSourceFilenames ( SourceID id ) const

Returns the list of the files associated with the source.

With the cameras these will be the names of the files that were recorded.

Parameters

id	The source ID number.

Returns: The list of the files.

vector< SourceID > cavapa_gui::AnalysisController::getSourceListing ( ) const

Returns a list of all sources in the class.

Returns: List of the source ID numbers.

FrameTime cavapa_gui::AnalysisController::getSourcePosition ( SourceID id ) const

Retrieves the current time position of a source.

This will be the current time on the video files. Cameras and other sources will always return 0.

Parameters

id	The source ID number.

Returns: FrameTime of the source's current position. 0 for cameras or sources that do not exist.

Size cavapa_gui::AnalysisController::getSourceResolution ( SourceID id ) const

Retrieves the source's frame resolution.

Parameters

id	The source ID number.

Returns: The frame size or (0, 0) if it is not found or error is encountered.

SourceStats cavapa_gui::AnalysisController::getSourceStats ( SourceID id ) const

Retrieves the source's current statistics.

The statistics can be used to get information on the missed, recorded etc. frames, and can provide insight on possible source lag or other problems. This is also the way to know how many frames a video file has.

Parameters

id	The source ID number.

Returns: The statistics of the source.

Remarks: Some frames may be buffered in which case they might not appear on the statistics.

SourceType cavapa_gui::AnalysisController::getSourceType ( SourceID id ) const

Returns the type of the selected source.

Parameters

id	The source ID number.

Returns: The type of the source.

FrameTime cavapa_gui::AnalysisController::getVideoLength ( SourceID id ) const

Retrieves the length of the video source.

Parameters

id	The source ID number.

Returns: The length of the video in milliseconds or 0 if failed.

int cavapa_gui::AnalysisController::initCameras ( int max_loops = 10 )

Initializes the hardware cameras.

Parameters

max_loops The maximum number of the devices to be checked for HW cameras. This should always be more than the actual number of cameras that are expected to be connected.

Returns: The number of new hardware cameras discovered.

Remarks: This is of course not necessary to call if the calculation is only going to consist of video files.

bool cavapa_gui::AnalysisController::isPaused ( ) const

inline

Retrieves the current pause status.

Returns: True if paused or false otherwise.

bool cavapa_gui::AnalysisController::isRunning ( ) const

inline

Retrieves the current status of the calculation.

Returns: True if calculation is running or false otherwise.

bool cavapa_gui::AnalysisController::load ( const std::string & path = "results.cpa" )

Loads the calculation results and recorded file information.

It loads existing results from a file. Once a result file has been opened, you cannot modify the sources. You can only play the recorded calculation and observe the results. You need to call reset() to be able to start a new calculation or add sources.

Parameters

path	The path of the results file.

Returns: True if load was successful or false otherwise. Use getLastError() to retrieve reason for failure.

bool cavapa_gui::AnalysisController::pause ( )

Pauses or unpauses the calculation.

Returns: True if pause/unpause was successful or false otherwise. Use getLastError() to retrieve reason for failure.

Remarks: Use canPause() to see if the calculation can be paused.

bool cavapa_gui::AnalysisController::removeSource ( SourceID id )

Removes the source.

Parameters

id	The source ID number.

Returns: True if the source was removed or false otherwise. use getLastError() to retrieve reason for failure.

bool cavapa_gui::AnalysisController::reset ( )

Resets the calculation results.

After this call, all the saved results are entirely gone.

Returns: True if the reset was successful or false otherwise. Use getLastError() to retrieve reason for failure.

Remarks: The calculation must be stopped to reset.

bool cavapa_gui::AnalysisController::save ( const std::string & path = "results.cpa" )

Saves the calculation results and sightings.

It saves the current CAVAPA calculation into a file. It does not save recorded filenames or any information on the sources.

Parameters

path	The path of the results file.

Returns: True if save was successful or false otherwise. Use getLastError() to retrieve reason for failure.

bool cavapa_gui::AnalysisController::setCameraFPS ( double fps )

Sets the default FPS for camera sources.

It will not have any effect if there are any cameras in the calculation that report a lower framerate than what has been set manually. Only HW cameras are able to report framerates. FPS can only be changed when calculation is not running.

Parameters

fps	The framerate to be set.

Returns: True if the framerate set was succesful or false otherwise. Use getLastError() to retrieve the reason for failure.

Remarks: It is important to understand that when setting the recording framerate for hardware cameras, it is MUCH better to have a lower framerate than a very high. This is due to the fact that if too many retrieval calls are send to the camera it starts to lag, and retrieval times become extremely high. 10 ms retrieval times can become 100 ms if the previous retrieval was not finished in time.

void cavapa_gui::AnalysisController::setHighlight ( bool highlight )

inline

Sets the individual sighting rectangle highlights.

This will affect all incoming source frames. The detected sightings will be highlighted with a rectangle.

Parameters

highlight True if the sightings should be highlighted or false if they should not.

void cavapa_gui::AnalysisController::setHighlightColor ( const cv::Scalar & color )

inline

Sets the sighting's highlighting color.

The color is used in the rectangles that are drawn around detected individuals on source frames.

Parameters

color The color in BGR value (not RGB!).

bool cavapa_gui::AnalysisController::setPosition ( FrameTime pos )

Sets the current time position of all the sources.

The purpose of the method is to seek the calculation result point for every video source. Video sources will use their initialized start point as a base for the time seek. The position can only be changed when the calculation is not running.

Parameters

pos	Desired time position.

Returns: True if successful or false if any of the videos files failed to seek to the new position.

bool cavapa_gui::AnalysisController::setRecorderCodec	(	const std::string &	codec,
		const std::string &	extension = `"avi"`
	)

Sets the default camera recorder codec.

It only affects new recordings, not the ones that are already running.

Parameters

codec	The 4 character code for the video (FourCC). See http://www.fourcc.org/codecs.php
extension	The file extension that is used for new recordings. It MUST match the codec, otherwise files will fail to load.

Returns: True if the codec was set or false otherwise.

Remarks: For linux and Windows compatibility it seems that "DIVX" is a safe codec to use. OS X support is unknown.

void cavapa_gui::AnalysisController::setRecordTimeLimit ( unsigned int length )

inline

Sets the maximum length of one recording.

Parameters

length The length of the recording in seconds or 0 if no limit.

bool cavapa_gui::AnalysisController::setSourceBarrelCorrection	(	SourceID	id,
		double	amount
	)

Sets the barrel correction on a source.

It will add the given effect on all frames returned from the source from now on. These frames will also be passed on the calculation.

Parameters

id	The source ID number.
amount	The amount of barrel correction to be applied. 0.0 means no effect. Positive values increase the effect. Amount can't be negative.

Returns: True if the new barrel correction value was set or false otherwise. Use getLastError() to retrieve reason for failure.

Remarks: This can be changed during the calculation, but it is highly not recommended as it might produce lag due to multithreaded image retrievals.

void cavapa_gui::AnalysisController::setSourceExcludes	(	SourceID	id,
		const std::vector< cv::Rect > &	rects
	)

Sets the excluded rectangles for a source.

The given rectangles will be drawn black on all frames that the source produces. These are used to exclude specific areas from the source frame. The rectangles are always drawn on the frame before analysing them, but after they are written to a file.

Parameters

id	The source ID number.
rects	The rectangles to be excluded.

bool cavapa_gui::AnalysisController::setSourceResolution	(	SourceID	id,
		const cv::Size &	new_size
	)

Sets the source resolution.

Parameters

id	The source ID number.
new_size	The desired size.

Returns: True if the new size was set, false otherwise. Use getLastError() to retrieve reason for failure.

Remarks: Use canChangeSourceResolution() to check if a change is even possible. Mainly hardware cameras can only have their resolution changed.

bool cavapa_gui::AnalysisController::setVideoSpeed ( double ratio = 1.0 )

Sets the video source speed.

If all the sources are video files this will multiply the framerate, otherwise this has no effect.

Parameters

ratio The desired video speed ratio. Negative or 0.0 will indicate as fast as possible.

Returns: True if the speed was changed successfully or false otherwise. Use getLastError() to get more information on failure.

void cavapa_gui::AnalysisController::setWorkDirectory ( const std::string & path )

Sets the path for the calculation directory.

The directory will be used to store recordings, calculation results etc.

Parameters

path	The directory path.

bool cavapa_gui::AnalysisController::sourceCanRecord ( SourceID id ) const

Checks if the source is capable of recording.

Parameters

id	The source ID number.

Returns: True if the recording is supported or false otherwise.

bool cavapa_gui::AnalysisController::sourcePlay ( SourceID id )

Starts playing a video source.

Parameters

id	The source ID number.

Returns: True if successfull or false otherwise. Use getLastError() to retrieve failure message.

bool cavapa_gui::AnalysisController::sourceSeek	(	SourceID	id,
		FrameTime	position
	)

Seeks the video source to a specific time.

Parameters

id	The source ID number.
position	The time position of the video.

Returns: True if seeking was successul or false otherwise. Use getLastError() to retrieve failure message.

Remarks: Video can't be seeked during the calculation.

bool cavapa_gui::AnalysisController::sourceStepBackward ( SourceID id )

inline

Steps the source one frame back.

Parameters

id	Source ID number.

Returns: True if the step was successful or false otherwise. Use getLastError() to retrieve failure message.

Remarks: The video files can be stepped only while the calculation is not running or the video is not playing.

bool cavapa_gui::AnalysisController::sourceStepForward ( SourceID id )

inline

Steps the source one frame forward.

Parameters

id	The source ID number.

Returns: True if the step was successful or false otherwise. Use getLastError() to retrieve failure message.

Remarks: The video files can be stepped only while the calculation is not running or the video is not playing.

bool cavapa_gui::AnalysisController::sourceStop ( SourceID id )

Stops playing the video source.

Parameters

id	The source ID number.

Returns: True if successfull or false otherwise. Use getLastError() to retrieve failure message.

bool cavapa_gui::AnalysisController::start	(	const std::vector< SourceID > &	calc_sources,
		const std::vector< cavapa::CameraSettings > &	settings,
		const std::vector< cavapa::CalibrationPoint > &	points,
		bool	record = `false`,
		int	calc_time = `0`
	)

Starts the CAVAPA calculation.

Parameters

calc_sources	The sources to be included in the calculation.
settings	The source settings. The resolution and the barrel values have no effect as AnalysisController will fill them in automatically.
points	Calibration points.
record	If the video sources should be recorded or not.
calc_time	Maximum runtime in seconds. Infinite if 0.

Returns: True if calculation was started or false otherwise. Use getLastError() to retrieve reason for failure.

void cavapa_gui::AnalysisController::stop ( )

Stops the current CAVAPA calculation.

Remarks: It does not destroy the results.

void cavapa_gui::AnalysisController::updated	(	const std::vector< FrameCapture > &	frames,
		const FrameStats &	statistics
	)

signal

It signals frame updates or calculation updates.

When the calculation is in progress, only the sources selected to the calculation will perform frame updates. When the calculation is not in progress, all the sources will return the current frame.

Parameters

frames	The current frames of the video sources.
statistics	Holds the frame statistics.

Remarks: The frame statistics will be empty when the calculation is not running.

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

analysiscontroller.h
analysiscontroller.cpp

Signals

Public Member Functions

Detailed Description

Member Function Documentation