This class implements an offline tracker able to detect and track a previously known 2D pattern. More...

#include <PatternTracker.h>

Inheritance diagram for Ocean::Tracking::Offline::PatternTracker:

Data Structures
class	FineTrackingComponent
	This class implements a tracking component that allows to determine an accurate pose and that further allows to optimized the camera parameters. More...

class	RoughCameraFovComponent
	This class implements a tracking component that determines a rough guess of the horizontal field of view of the camera. More...

class	RoughPoseBaseComponent
	This class implements the base class for all tracking components providing a rough pose. More...

class	RoughPoseComponent
	This class implements a tracking component that determines rough camera poses by application of 2D / 3D point correspondences. More...

Public Member Functions
	PatternTracker ()
	Creates a new pattern tracker object.

Vector2	patternDimension () const
	Returns the current dimension of the tracking pattern.

bool	setPattern (const Frame &frame, const Vector2 &dimension)
	Sets the tracking pattern that will be tracked in the video stream.

bool	setCamera (const PinholeCamera &pinholeCamera, const Scalar cameraPrecision, const bool optimizeCamera) override
	Sets a camera object that will be used by this tracker.

Public Member Functions inherited from Ocean::Tracking::Offline::FrameTracker
bool	succeeded () const override
	Returns whether the offline tracker has finished and succeeded since the last start or has not been started yet.

const PinholeCamera &	camera () const
	Returns the camera object this is applied by this tracker.

Scalar	cameraPrecision () const
	Returns the camera precision of this tracker.

bool	start () override
	Starts the offline tracker.

virtual bool	setFrameProviderInterface (const CV::FrameProviderInterfaceRef &frameProviderInterface)
	Sets the frame provider interface that allows to request the individual frames for the offline tracker.

virtual bool	setTrackingFrameRange (const unsigned int lowerFrameIndex, const unsigned int upperFrameIndex, const unsigned int startFrameIndex=(unsigned int)(-1))
	Sets the frame range of this frame tracker.

Public Member Functions inherited from Ocean::Tracking::Offline::OfflineTracker
virtual	~OfflineTracker ()
	Frees the offline tracker object.

virtual bool	stop (const unsigned int timeout=0u)
	Stops the offline tracker.

unsigned int	id () const
	Returns the unique id of this tracker object.

virtual bool	running () const
	Returns whether the tracker has been started (and is currently tracking).

virtual bool	finished () const
	Returns whether the offline tracker has finished since the last start or has not been started yet.

virtual OfflinePoses	poses () const
	Returns the currently determined poses of this tracker.

virtual OfflinePose	pose (const unsigned int index) const
	Returns one pose of this tracker.

void	addEventCallback (const EventCallback &callback)
	Adds a state event callback function.

void	removeEventCallback (const EventCallback &callback)
	Removes a state event callback function.

Public Member Functions inherited from Ocean::Tracking::Offline::PlaneTracker
virtual Plane3	plane () const
	Returns the plane of this tracker.

virtual bool	objectTransformation (HomogenousMatrix4 &transformation) const
	Determines the transformation that transforms points defined in the local coordinate of the tracked object into points defined in the world coordinate system.

Protected Member Functions
bool	applyFrameTracking (const FrameType &frameType) override
	Frame tracker run function.

bool	determineRoughCameraFov (const unsigned int lowerFrameIndex, const unsigned int initialFrameIndex, const unsigned int upperFrameIndex, const unsigned int cameraFovDeterminationFrames=10u)
	Guesses the rough field of view of the camera.

bool	determineRoughPoses (const unsigned int lowerFrameIndex, const unsigned int initialFrameIndex, const unsigned int upperFrameIndex)
	Determines the initial rough poses for the entire video stream.

bool	closeGaps (const unsigned int lowerFrameIndex, const unsigned int upperFrameIndex, const unsigned int minimalCorrespondences=50u)
	Closes the tracking gaps (break-downs) for the provided video stream.

bool	fineAdjustment (const unsigned iterations, const unsigned int detectionBorder, const unsigned int horizontalBinSize, const unsigned int verticalBinSize, const bool optimizeCamera, const unsigned int lowerFrameIndex, const unsigned int initialFrameIndex, const unsigned int upperFrameIndex)
	Applies a fine adjustment of the camera poses.

Scalar	projectedPatternArea (const HomogenousMatrix4 &pose, const PinholeCamera &pinholeCamera) const
	Calculates the projection area of the defined 3D object pattern.

Triangles2	projectedPatternTriangles (const HomogenousMatrix4 &pose, const PinholeCamera &pinholeCamera) const
	Returns projected 2D triangles that cover the area of the 3D tracking pattern.

bool	updatePatternDimension (const Vector2 &dimension)
	Updates the pattern dimension of this tracker and invokes the corresponding state event(s).

Protected Member Functions inherited from Ocean::Tracking::Offline::FrameTracker
	FrameTracker ()=default
	Creates a new offline frame tracker object.

	FrameTracker (const CV::FrameProviderInterfaceRef &frameProviderInterface)
	Creates a new offline frame tracker object.

void	threadRun () override
	Thread run function.

FrameType	applyFrameTrackingInitialization ()
	Applies the initialization of the frame tracker.

virtual void	updateCamera (const PinholeCamera &pinholeCamera)
	Updates the camera of this tracker and invokes the corresponding state event(s).

Protected Member Functions inherited from Ocean::Tracking::Offline::OfflineTracker
	OfflineTracker ()
	Creates a new offline tracker object.

void	updateTrackerProgress (const Scalar localProgress)
	Updates the tracker process progress value of this tracker.

void	updatePoses (const OfflinePoses &poses)
	Updates all poses of this tracker and invokes the corresponding state event(s).

void	removeIrregularPoses (const Scalar factor=Scalar(5))
	Removes irregular poses at the boundary between valid and invalid poses.

void	extrapolatePoses (const unsigned int number, const unsigned int base)
	Extrapolates poses at the boundary between valid and invalid poses.

Protected Member Functions inherited from Ocean::Thread
	Thread (const Thread &thread)=delete
	Disabled copy constructor.

void	createThread ()
	Creates the thread itself.

void	destroyThread ()
	Destroys the thread itself.

void	stopThreadExplicitly (const unsigned int timeout=5000u)
	Tries to stop the thread gracefully.

Thread &	operator= (const Thread &thread)=delete
	The disabled assign operator.

	Thread (const std::string &name=std::string())
	Creates a new thread object.

	Thread (const unsigned int randomNumberSeedValue, const std::string &name=std::string())
	Creates a new thread object.

virtual	~Thread ()
	Destructs a thread object.

bool	startThread ()
	Starts the thread.

void	stopThread ()
	Informs the thread to stop.

bool	terminateThread ()
	Terminates the thread.

bool	joinThread (const unsigned int timeout=(unsigned int)(-1))
	Waits until this thread has been stopped.

bool	shouldThreadStop () const
	Returns whether this thread should stop.

bool	isThreadInvokedToStart () const
	Returns whether this thread has been invoked to start immediately.

bool	isThreadActive () const
	Returns whether this thread is active.

Protected Member Functions inherited from Ocean::Tracking::Offline::PlaneTracker
	PlaneTracker ()=default
	Creates a new plane tracker object.

	PlaneTracker (const Plane3 &plane)
	Creates a new plane tracker object.

virtual void	updatePlane (const Plane3 &plane)
	Updates the plane of this tracker and invokes the corresponding state event(s).

Protected Attributes
Frame	patternFrame_
	The frame pattern that is tracked during the video stream.

Vector2	patternDimension_ = Vector2(0, 0)
	Dimension of the frame pattern in meter.

Vector3	patternCorners_ [4]
	The four corners of the tracking pattern.

Protected Attributes inherited from Ocean::Tracking::Offline::FrameTracker
CV::FrameProviderInterfaceRef	frameProviderInterface_
	Frame provider interface that allows to request the individual frames for this offline tracker.

unsigned int	lowerFrameIndex_ = (unsigned int)(-1)
	Index of the lower frame range.

unsigned int	startFrameIndex_ = (unsigned int)(-1)
	Index of the frame at that the tracking will start, or -1 if no specific frame is specified.

unsigned int	upperFrameIndex_ = (unsigned int)(-1)
	Index of the upper frame range.

PinholeCamera	camera_
	The camera object of this tracker.

Scalar	cameraPrecision_ = Scalar(-1)
	The precision of the camera object in squared pixel errors.

bool	optimizeCamera_ = true
	True, if the camera needs to be optimized during the tracking process.

bool	succeeded_ = true
	Succeeded state of the tracker.

Protected Attributes inherited from Ocean::Tracking::Offline::OfflineTracker
unsigned int	id_ = 0u
	The unique id that identifies this tracker.

bool	finished_ = true
	Finished state of the tracker.

bool	shouldStop_ = false
	Stop-request state of the tracker, this state should have the same state as the threadShouldStop variable but will be accessible in all trackers.

OfflinePoses	offlinePoses_
	Offline poses of this tracker.

EventCallbacks	eventCallbacks_
	State event callback functions.

Lock	lock_
	Tracker lock object.

EventStack	eventStack_
	The stack with progress event layers allowing for a convenient process progress event handling.

Lock	eventStackLock_
	The lock for the progress event layer stack.

Scalar	previousProcessProgress_ = Scalar(0)
	The previous process progress.

Protected Attributes inherited from Ocean::Tracking::Offline::PlaneTracker
Plane3	plane_
	The plane of this tracker.

HomogenousMatrix4	objectTransformation_ = HomogenousMatrix4(false)
	The tracker object transformation the tracker coordinate system into the world coordinate system.

Additional Inherited Members
Public Types inherited from Ocean::Tracking::Offline::OfflineTracker
enum	TrackingQuality { TQ_LOW , TQ_MODERATE , TQ_HIGH , TQ_ULTRA , TQ_INSANE , TQ_AUTOMATIC , TQ_COARSE , TQ_FINE }
	Definition of individual tracking qualities. More...

enum	AbstractMotionType { AMT_UNKNOWN , AMT_PURE_ROTATIONAL , AMT_COMPLEX }
	Definition of individual abstract camera motion types. More...

enum	CameraModel { CM_INVALID , CM_LOW_QUALITY , CM_MEDIUM_QUALITY , CM_HIGH_QUALITY }
	Definition of individual camera models. More...

typedef Callback< void, const TrackerEvent & >	EventCallback
	Definition of a component event callback function.

Protected Types inherited from Ocean::Tracking::Offline::OfflineTracker
typedef std::vector< EventStackLayer >	EventStack
	Definition of a vector holding EventStackLayer objects which actually is used to implement a stack of these objects.

typedef ConcurrentCallbacks< EventCallback >	EventCallbacks
	Definition of a vector holding event callback functions.

Protected Types inherited from Ocean::Thread
typedef std::pair< pthread_t, bool >	TimedJoinPair
	Definition of a pair holding a thread id and a boolean state.

enum	ThreadPriority { PRIORITY_IDLE , PRIORTY_BELOW_NORMAL , PRIORTY_NORMAL , PRIORTY_ABOVE_NORMAL , PRIORTY_HIGH , PRIORTY_REALTIME }
	Definition of different thread priority values. More...

Static Protected Member Functions inherited from Ocean::Tracking::Offline::OfflineTracker
static bool	isPlausibleCamera (const PinholeCamera &pinholeCamera, const CameraModel model)
	Checks whether the camera parameters of a given camera profiles matches to the specified camera model.

static void	extrapolateSinglePose (const OfflinePoses::Index invalidIndex, OfflinePoses &offlinePoses)
	Interpolates the pose of a single invalid pose which is enclosed by two valid poses.

static void	extrapolateLeftPoses (const OfflinePoses::Index invalidIndex, const unsigned int number, const unsigned int base, OfflinePoses &offlinePoses)
	Interpolates some poses to the left of a gap with invalid poses.

static void	extrapolateRightPoses (const OfflinePoses::Index invalidIndex, const unsigned int number, const unsigned int base, OfflinePoses &offlinePoses)
	Interpolates some poses to the right of a gap with invalid poses.

static void	extrapolateCenterPoses (const OfflinePoses::Index invalidIndex, const unsigned int number, const unsigned int base, OfflinePoses &offlinePoses)
	Interpolates some poses to the left or to the right of a gap with invalid poses.

static Lock &	idCounterLock ()
	Returns a reference to the lock for the tracker id counter.

Static Protected Member Functions inherited from Ocean::Thread
static void	sleep (unsigned int ms)
	Sleeps the calling thread for a given time.

static void	giveUp ()
	Gives up the remaining thread time.

static ThreadId	currentThreadId ()
	Returns the thread id of the current (calling) thread.

static ThreadPriority	threadPriority ()
	Returns the priority of the current thread.

static bool	setThreadPriority (const ThreadPriority priority)
	Sets the priority of the current thread.

template<typename TObject , typename TExpectedValue >
static bool	waitForValue (TObject &object, const TExpectedValue &expectedValue, const double timeout=-1.0)
	Waits until an object/variable has an expected value.

template<typename TObject , typename TExpectedValue >
static bool	waitForValue (TObject &object, const TExpectedValue &expectedValue, TemporaryScopedLock &temporaryScopedLock, const double timeout=-1.0)
	Waits until an object/variable has an expected value.

static int	pthread_timedjoin_np (pthread_t thread, void *retval, const struct timespec abstime)
	Implements a thread join function with timeout value.

Static Protected Attributes inherited from Ocean::Tracking::Offline::OfflineTracker
static unsigned int	idCounter_
	The tracker id counter.

Detailed Description

This class implements an offline tracker able to detect and track a previously known 2D pattern.

The tracker does not provide real-time performance but creates tracking results with high accuracy.
The given video stream is passed through several times to increase the tracking quality.

See also: PatternTrackerRef.

Constructor & Destructor Documentation

◆ PatternTracker()

Ocean::Tracking::Offline::PatternTracker::PatternTracker ( )

Creates a new pattern tracker object.

Member Function Documentation

◆ applyFrameTracking()

bool Ocean::Tracking::Offline::PatternTracker::applyFrameTracking ( const FrameType & frameType )

overrideprotectedvirtual

Frame tracker run function.

See also: OfflineFrameTracker::applyFrameTracking().

Implements Ocean::Tracking::Offline::FrameTracker.

◆ closeGaps()

bool Ocean::Tracking::Offline::PatternTracker::closeGaps	(	const unsigned int	lowerFrameIndex,
		const unsigned int	upperFrameIndex,
		const unsigned int	minimalCorrespondences = `50u`
	)

protected

Closes the tracking gaps (break-downs) for the provided video stream.

Parameters

lowerFrameIndex	Index of the frame defining the lower (including) tracking boundary
upperFrameIndex	Index of the frame defining the upper (including) tracking boundary
minimalCorrespondences	Minimal number of correspondences that need to be exceeded so that a pose counts as valid (and not as gap)

Returns: True, if succeeded

◆ determineRoughCameraFov()

bool Ocean::Tracking::Offline::PatternTracker::determineRoughCameraFov	(	const unsigned int	lowerFrameIndex,
		const unsigned int	initialFrameIndex,
		const unsigned int	upperFrameIndex,
		const unsigned int	cameraFovDeterminationFrames = `10u`
	)

protected

Guesses the rough field of view of the camera.

Parameters

lowerFrameIndex	Index of the frame defining the lower (including) tracking boundary
initialFrameIndex	Index of the frame at that the tracking process will start
upperFrameIndex	Index of the frame defining the upper (including) tracking boundary
cameraFovDeterminationFrames	Number of initial frames that are used to determine a rough approximation of the camera's field of view, 0 to avoid the determination

Returns: True, if succeeded

◆ determineRoughPoses()

bool Ocean::Tracking::Offline::PatternTracker::determineRoughPoses	(	const unsigned int	lowerFrameIndex,
		const unsigned int	initialFrameIndex,
		const unsigned int	upperFrameIndex
	)

protected

Determines the initial rough poses for the entire video stream.

Parameters

lowerFrameIndex	Index of the frame defining the lower (including) tracking boundary
initialFrameIndex	Index of the frame at that the tracking process will start
upperFrameIndex	Index of the frame defining the upper (including) tracking boundary

Returns: True, if succeeded

◆ fineAdjustment()

bool Ocean::Tracking::Offline::PatternTracker::fineAdjustment	(	const unsigned	iterations,
		const unsigned int	detectionBorder,
		const unsigned int	horizontalBinSize,
		const unsigned int	verticalBinSize,
		const bool	optimizeCamera,
		const unsigned int	lowerFrameIndex,
		const unsigned int	initialFrameIndex,
		const unsigned int	upperFrameIndex
	)

protected

Applies a fine adjustment of the camera poses.

Parameters

iterations	Number of adjustment iterations for each frame
detectionBorder	Border in the tracking pattern in which no feature points will be tracked
horizontalBinSize	Size of each horizontal bins (the bin widths) in pixel
verticalBinSize	Size of each vertical bins (the bin heights) in pixel
optimizeCamera	True to apply a camera profile optimization after the fine tracking has been applied
lowerFrameIndex	Index of the frame defining the lower (including) tracking boundary
initialFrameIndex	Index of the frame at that the tracking process will start
upperFrameIndex	Index of the frame defining the upper (including) tracking boundary

◆ patternDimension()

Vector2 Ocean::Tracking::Offline::PatternTracker::patternDimension ( ) const

inline

Returns the current dimension of the tracking pattern.

Returns: Current tracking pattern dimension

◆ projectedPatternArea()

Scalar Ocean::Tracking::Offline::PatternTracker::projectedPatternArea	(	const HomogenousMatrix4 &	pose,
		const PinholeCamera &	pinholeCamera
	)		const

protected

Calculates the projection area of the defined 3D object pattern.

Parameters

pose	The camera pose
pinholeCamera	The pinhole camera object

Returns: Resulting projection area

◆ projectedPatternTriangles()

Triangles2 Ocean::Tracking::Offline::PatternTracker::projectedPatternTriangles	(	const HomogenousMatrix4 &	pose,
		const PinholeCamera &	pinholeCamera
	)		const

protected

Returns projected 2D triangles that cover the area of the 3D tracking pattern.

Parameters

pose	The camera pose
pinholeCamera	The pinhole camera object

Returns: Set of 2D triangles

◆ setCamera()

bool Ocean::Tracking::Offline::PatternTracker::setCamera	(	const PinholeCamera &	pinholeCamera,
		const Scalar	cameraPrecision,
		const bool	optimizeCamera
	)

overridevirtual

Sets a camera object that will be used by this tracker.

See also: OfflineTracker::setCamera().

Reimplemented from Ocean::Tracking::Offline::FrameTracker.

◆ setPattern()

bool Ocean::Tracking::Offline::PatternTracker::setPattern	(	const Frame &	frame,
		const Vector2 &	dimension
	)

Sets the tracking pattern that will be tracked in the video stream.

Parameters

frame	The frame pattern
dimension	The dimension of the given pattern in meter

Returns: True, if succeeded

◆ updatePatternDimension()

bool Ocean::Tracking::Offline::PatternTracker::updatePatternDimension ( const Vector2 & dimension )

protected

Updates the pattern dimension of this tracker and invokes the corresponding state event(s).

Parameters

dimension The dimension of the given pattern in meter

Returns: True, if succeeded

Field Documentation

◆ patternCorners_

Vector3 Ocean::Tracking::Offline::PatternTracker::patternCorners_[4]

protected

The four corners of the tracking pattern.

◆ patternDimension_

Vector2 Ocean::Tracking::Offline::PatternTracker::patternDimension_ = Vector2(0, 0)

protected

Dimension of the frame pattern in meter.

◆ patternFrame_

Frame Ocean::Tracking::Offline::PatternTracker::patternFrame_

protected

The frame pattern that is tracked during the video stream.

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

PatternTracker.h

Data Structures

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PatternTracker()

Member Function Documentation

◆ applyFrameTracking()

◆ closeGaps()

◆ determineRoughCameraFov()

◆ determineRoughPoses()

◆ fineAdjustment()

◆ patternDimension()

◆ projectedPatternArea()

◆ projectedPatternTriangles()

◆ setCamera()

◆ setPattern()

◆ updatePatternDimension()

Field Documentation

◆ patternCorners_

◆ patternDimension_

◆ patternFrame_