Abstract tracker interface, implemented by QueuedCUDATracker and QueuedCPUTracker. More...

#include <QueuedTracker.h>

Inheritance diagram for QueuedTracker:

Public Types
typedef std::map< std::string, std::string >	ConfigValueMap
	Datastructure used to return additional settings in a string-string key-value pair mapping. More...

Public Member Functions
	QueuedTracker ()

virtual	~QueuedTracker ()

virtual void	SetLocalizationMode (LocMode_t locType)=0
	Select which algorithm is to be used. More...

virtual void	SetPixelCalibrationImages (float offset, float gain)=0
	Set the pixel calibration images. More...

virtual void	SetPixelCalibrationFactors (float offsetFactor, float gainFactor)=0
	Set the pixel calibration factors. More...

virtual void	ScheduleLocalization (void data, int pitch, QTRK_PixelDataType pdt, const LocalizationJob jobInfo)=0
	Add a job to the queue to be processed. A job entails running the required algorithms on a single region of interest. More...

void	ScheduleImageData (ImageData data, const LocalizationJob jobInfo)
	Quick function to schedule a single ROI from an ImageData object. More...

virtual void	ClearResults ()=0
	Clear results. More...

virtual void	Flush ()=0
	Stop waiting for more jobs to do, and just process the current batch. More...

virtual int	ScheduleFrame (void imgptr, int pitch, int width, int height, ROIPosition positions, int numROI, QTRK_PixelDataType pdt, const LocalizationJob *jobInfo)
	Schedule an entire frame at once, allowing for further optimizations. More...

virtual void	SetRadialZLUT (float *data, int count, int planes)=0
	Set the radial lookup tables to be used for z tracking. More...

virtual void	GetRadialZLUT (float *dst)=0
	Get the radial lookup tables used for z tracking. More...

virtual void	GetRadialZLUTSize (int &count, int &planes, int &radialsteps)=0
	Get the dimensions of the radial lookup table data. More...

virtual void	SetRadialWeights (float *zcmp)=0
	Set radial weights used for comparing LUT profiles. More...

virtual void	EnableRadialZLUTCompareProfile (bool enabled)=0
	Set a flag to enable saving of error curves. More...

virtual void	GetRadialZLUTCompareProfile (float *dst)=0
	Get saved error curve. More...

virtual void	GetImageZLUTSize (int *dims)
	Get the dimensions of the image lookup table data. More...

virtual void	GetImageZLUT (float *dst)
	Get the image lookup tables used. More...

virtual bool	SetImageZLUT (float src, float radial_zlut, int *dims)
	Set the image lookup tables to be used for z tracking. More...

virtual void	BeginLUT (uint flags)=0
	Setup to begin building a lookup table. More...

virtual void	BuildLUT (void data, int pitch, QTRK_PixelDataType pdt, int plane, vector2f known_pos=0)=0
	Add a new lookup table plane. More...

virtual void	FinalizeLUT ()=0
	Finalize the lookup tables in memory. More...

virtual int	GetResultCount ()=0
	Get the number of finished localization jobs (=results) available in memory. More...

virtual int	FetchResults (LocalizationResult *results, int maxResults)=0
	Fetch available results. More...

virtual int	GetQueueLength (int *maxQueueLen=0)=0
	Get the lengths of the queue of jobs to be handled. More...

virtual bool	IsIdle ()=0
	Test to see if the tracker is idle. More...

virtual ConfigValueMap	GetConfigValues ()=0
	Get the used additional configurations. More...

virtual void	SetConfigValue (std::string name, std::string value)=0
	Set an additional setting. More...

virtual std::string	GetProfileReport ()
	Get the output of performance profiling. More...

virtual std::string	GetWarnings ()
	Get a report of encountered errors. More...

virtual bool	GetDebugImage (int ID, int w, int h, float **pData)
	Get the debug image for a specific thread. More...

ImageData	DebugImage (int ID)
	Get the debug image as an ImageData object. More...

void	ScheduleLocalization (uchar data, int pitch, QTRK_PixelDataType pdt, uint frame, uint timestamp, vector3f initial, uint zlutIndex)
	Add an image to the queue to be processed. Creates a job. More...

void	ComputeZBiasCorrection (int bias_planes, CImageData *result, int smpPerPixel, bool useSplineInterp)

float	ZLUTBiasCorrection (float z, int zlut_planes, int bead)

void	SetZLUTBiasCorrection (const CImageData &data)

CImageData *	GetZLUTBiasCorrection ()

Public Attributes
QTrkComputedConfig	cfg
	The settings used by this instance of QueuedTracker. More...

Protected Attributes
CImageData *	zlut_bias_correction

Detailed Description

Abstract tracker interface, implemented by QueuedCUDATracker and QueuedCPUTracker.

In general, it holds a queue of "jobs" (LocalizationJob) to perform. These jobs are created and automatically queued using ScheduleLocalization(uchar*, int, QTRK_PixelDataType, uint, uint, vector3f*, uint). Internally, a scheduling thread divides the work over multiple threads to speed up the calculations. When jobs are completed, their results become available to retrieve from memory. Usage of the ResultManager class is recommended to handle this process.

Queue and result related functionalities are exposed to an API, see API - LabVIEW and API - C.

Definition at line 86 of file QueuedTracker.h.

Member Typedef Documentation

§ ConfigValueMap

typedef std::map<std::string, std::string> QueuedTracker::ConfigValueMap

Datastructure used to return additional settings in a string-string key-value pair mapping.

Currently only two settings are available: use_texturecache for CUDA and trace for CPU.

Definition at line 299 of file QueuedTracker.h.

Constructor & Destructor Documentation

§ QueuedTracker()

QueuedTracker::QueuedTracker ( )

Definition at line 94 of file QueuedTracker.cpp.

 {
     zlut_bias_correction=0;
 }

§ ~QueuedTracker()

QueuedTracker::~QueuedTracker ( )

virtual

Definition at line 99 of file QueuedTracker.cpp.

100 {

101 }

Member Function Documentation

§ BeginLUT()

virtual void QueuedTracker::BeginLUT ( uint flags )

pure virtual

Setup to begin building a lookup table.

Sets the flags by which the lookup table is built. Flags are defined in a uint bitmask format as:

Name	Value	Description
	0	Default, no special flags.
BUILDLUT_IMAGELUT	1 (2^0)	Build an image LUT. An image LUT seems to be a work in progress to save ROIs rather than profiles in the LUT.
BUILDLUT_FOURIER	2 (2^1)	Build a fourier LUT.
BUILDLUT_NORMALIZE	4 (2^2)	Normalize radial profiles. Irrelevant, since FinalizeLUT always normalizes.
BUILDLUT_BIASCORRECT	8 (2^3)	Enable bias correction. Currently only partly implemented, don't use.

Parameters

[in] flags UINT interpreted as a series of bits to set settings.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ BuildLUT()

virtual void QueuedTracker::BuildLUT	(	void *	data,
		int	pitch,
		QTRK_PixelDataType	pdt,
		int	plane,
		vector2f *	known_pos = `0`
	)

pure virtual

Add a new lookup table plane.

Takes a stack of ROI images through data. Determines and adds the profile for each ROI to its respective LUT.

Parameters

[in]	data	Pointer to the start of an image stack.
[in]	pitch	Width of the data in memory so offsets can be calculated.
[in]	pdt	Pixel data type for the data. See QTRK_PixelDataType.
[in]	plane	The plane number the ROIs are taken for.
[in]	known_pos	Center position from which to start making the radial profile. A standard QI localization with applied settings is performed if 0 (default).

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ ClearResults()

virtual void QueuedTracker::ClearResults ( )

pure virtual

Clear results.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ DebugImage()

ImageData QueuedTracker::DebugImage ( int ID )

Get the debug image as an ImageData object.

Parameters

[in] ID Thread number from which to grab the image.

Returns: An ImageData instance with the debug image.

Definition at line 118 of file QueuedTracker.cpp.

 {
     ImageData img;
     GetDebugImage(ID, &img.w, &img.h, &img.data);
     return img;
 }

§ EnableRadialZLUTCompareProfile()

virtual void QueuedTracker::EnableRadialZLUTCompareProfile ( bool enabled )

pure virtual

Set a flag to enable saving of error curves.

Errors obtained by comparing a radial profile to a ZLUT will be kept in memory rather than destroyed. Only saves for one localization. Error curve can be retreived by GetRadialZLUTCompareProfile.

Note: Not implemented for CUDA.

Parameters

[in] enabled Flag (boolean) to save error curves. Default is false.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ FetchResults()

virtual int QueuedTracker::FetchResults	(	LocalizationResult *	results,
		int	maxResults
	)

pure virtual

Fetch available results.

Note: Removes results from internal QueuedTracker memory.

Parameters

[in]	results	Array of pre-allocated LocalizationResult to which to add the results.
[in]	maxResults	Maximum number of results to fetch. Corresponds to maximum size of `dstResult`.

Returns: Number of fetched results.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ FinalizeLUT()

virtual void QueuedTracker::FinalizeLUT ( )

pure virtual

Finalize the lookup tables in memory.

Normalizes the profiles for radial lookup tables and calculates derivates and adds boundary conditions for image LUTs.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ Flush()

virtual void QueuedTracker::Flush ( )

pure virtual

Stop waiting for more jobs to do, and just process the current batch.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ GetConfigValues()

virtual ConfigValueMap QueuedTracker::GetConfigValues ( )

pure virtual

Get the used additional configurations.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ GetDebugImage()

virtual bool QueuedTracker::GetDebugImage	(	int	ID,
		int *	w,
		int *	h,
		float **	pData
	)

inlinevirtual

Get the debug image for a specific thread.

Debug image can be set in trackers by copying data into debugImage, for instance:

#ifdef _DEBUG
    std::copy(srcImage, srcImage+width*height, debugImage);
#endif

Warning: pData has to be cleared with delete[] in the calling function!

Parameters

[in]	ID	Thread number from which to grab the image.
[out]	w	Pointer to an integer in which the image width will be stored.
[out]	h	Pointer to an integer in which the image height will be stored.
[out]	pData	Reference to where the data array will be saved.

Returns: Boolean indicating if the debug image was succesfully returned.

Reimplemented in QueuedCPUTracker.

Definition at line 344 of file QueuedTracker.h.

344 { return false; } // deallocate result with delete[]

§ GetImageZLUT()

virtual void QueuedTracker::GetImageZLUT ( float * dst )

inlinevirtual

Get the image lookup tables used.

Note: Use of image LUT is currently not clear. Radial ZLUT is always used.

Parameters

[out] dst Pointer to the pre-allocated memory in which to save the data.

Reimplemented in QueuedCPUTracker.

Definition at line 212 of file QueuedTracker.h.

212 {}

§ GetImageZLUTSize()

virtual void QueuedTracker::GetImageZLUTSize ( int * dims )

inlinevirtual

Get the dimensions of the image lookup table data.

Note: Use of image LUT is currently not clear. Radial ZLUT is always used.

Parameters

[out] dims Reference to pre-allocated int array. Returns [ count, planes, height, width ].

Reimplemented in QueuedCPUTracker.

Definition at line 204 of file QueuedTracker.h.

204 {}

§ GetProfileReport()

virtual std::string QueuedTracker::GetProfileReport ( )

inlinevirtual

Get the output of performance profiling.

Note: Profiling is only implemented in CUDA at the moment.

Returns: String with the parsed profiling output.

Reimplemented in QueuedCUDATracker, and QueuedCPUTracker.

Definition at line 317 of file QueuedTracker.h.

317 { return ""; }

§ GetQueueLength()

virtual int QueuedTracker::GetQueueLength ( int * maxQueueLen = 0 )

pure virtual

Get the lengths of the queue of jobs to be handled.

Parameters

[out] maxQueueLen Pre-allocated integer that returns the maximum size of the queue if nonzero.

Returns: Number of jobs currently being handled and in the queue.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ GetRadialZLUT()

virtual void QueuedTracker::GetRadialZLUT ( float * dst )

pure virtual

Get the radial lookup tables used for z tracking.

Parameters

[out] dst Pointer to the pre-allocated memory in which to save the data.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ GetRadialZLUTCompareProfile()

virtual void QueuedTracker::GetRadialZLUTCompareProfile ( float * dst )

pure virtual

Get saved error curve.

See EnableRadialZLUTCompareProfile.

Note: Not implemented for CUDA.

Parameters

[in] dst Pointer to the pre-allocated memory in which to save the error curve. Size is count * planes.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ GetRadialZLUTSize()

virtual void QueuedTracker::GetRadialZLUTSize	(	int &	count,
		int &	planes,
		int &	radialsteps
	)

pure virtual

Get the dimensions of the radial lookup table data.

Parameters

[out]	count	Reference to pre-allocated int. Returns number of lookup tables.
[out]	planes	Reference to pre-allocated int. Returns number of planes per lookup table.
[out]	radialsteps	Reference to pre-allocated int. Returns number of steps per plane.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ GetResultCount()

virtual int QueuedTracker::GetResultCount ( )

pure virtual

Get the number of finished localization jobs (=results) available in memory.

Returns: The number of available results.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ GetWarnings()

virtual std::string QueuedTracker::GetWarnings ( )

inlinevirtual

Get a report of encountered errors.

Note: Placeholder function, no warnings are generated or returned anywhere for now.

Returns: String with the parsed warning output.

Definition at line 325 of file QueuedTracker.h.

325 { return ""; }

§ IsIdle()

virtual bool QueuedTracker::IsIdle ( )

pure virtual

Test to see if the tracker is idle.

That is, GetQueueLength == 0.

Returns: Boolean indicating if the tracker is idle.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ ScheduleFrame()

int QueuedTracker::ScheduleFrame	(	void *	imgptr,
		int	pitch,
		int	width,
		int	height,
		ROIPosition *	positions,
		int	numROI,
		QTRK_PixelDataType	pdt,
		const LocalizationJob *	jobInfo
	)

virtual

Schedule an entire frame at once, allowing for further optimizations.

Queues each ROI within the frame seperatly with ScheduleLocalization.

Parameters

[in]	imgptr	Pointer to the top-left pixel of the frame.
[in]	pitch	Size in bytes of one row in memory.
[in]	width	Width of the frame in pixels.
[in]	height	Height of the frame in pixels.
[in]	positions	Array of ROIPosition with the top-left pixel of each ROI to be queued.
[in]	numROI	Number of ROIs to handle within the frame.
[in]	pdt	Data type of the image given through `imgptr`.
[in]	jobInfo	LocalizationJob with information about the frame.

Returns: Amount of ROIs queued.

Definition at line 125 of file QueuedTracker.cpp.

 {
     uchar* img = (uchar*)imgptr;
     int bpp = PDT_BytesPerPixel(pdt);
     int count=0;
     for (int i=0;i<numROI;i++){
         ROIPosition& pos = positions[i];
 
         if (pos.x < 0 || pos.y < 0 || pos.x + cfg.width > width || pos.y + cfg.height > height) {
             dbgprintf("Skipping ROI %d. Outside of image.\n", i);
             continue;
         }
 
         uchar *roiptr = &img[pitch * pos.y + pos.x * bpp];
         LocalizationJob job = *jobInfo;
         job.zlutIndex = i + jobInfo->zlutIndex; // used as offset
         ScheduleLocalization(roiptr, pitch, pdt, &job);
         count++;
     }
     return count;
 }

§ ScheduleImageData()

void QueuedTracker::ScheduleImageData	(	ImageData *	data,
		const LocalizationJob *	jobInfo
	)

Quick function to schedule a single ROI from an ImageData object.

Definition at line 103 of file QueuedTracker.cpp.

 {
     ScheduleLocalization(data->data, data->pitch(), QTrkFloat, job);
 }

§ ScheduleLocalization() [1/2]

virtual void QueuedTracker::ScheduleLocalization	(	void *	data,
		int	pitch,
		QTRK_PixelDataType	pdt,
		const LocalizationJob *	jobInfo
	)

pure virtual

Add a job to the queue to be processed. A job entails running the required algorithms on a single region of interest.

If a localization can not be added to the queue because it is full, the thread will be put to sleep and periodically try again.

Parameters

[in]	data	Pointer to the data. Type specified by `pdt`.
[in]	pitch	Distance in bytes between two successive rows of pixels (e.g. address of (0,0) - address of (0,1)).
[in]	pdt	Type of `data`, specified by QTRK_PixelDataType.
[in]	jobInfo	Structure with metadata for the ROI to be handled. See LocalizationJob.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ ScheduleLocalization() [2/2]

void QueuedTracker::ScheduleLocalization	(	uchar *	data,
		int	pitch,
		QTRK_PixelDataType	pdt,
		uint	frame,
		uint	timestamp,
		vector3f *	initial,
		uint	zlutIndex
	)

Add an image to the queue to be processed. Creates a job.

Creates a job and then calls ScheduleLocalization(void*, int, QTRK_PixelDataType, const LocalizationJob*).

Parameters

[in]	data	Pointer to the data. Type specified by `pdt`.
[in]	pitch	Distance in bytes between two successive rows of pixels (e.g. address of (0,0) - address of (0,1)).
[in]	pdt	Type of `data`, specified by QTRK_PixelDataType.
[in]	frame	Frame number this localization belongs to.
[in]	timestamp	Timestamp for this job.
[in]	initial	Initial position for the algorithms requiring one. If none is specified, a COM track is performed to determine one.
[in]	zlutIndex	Number of the bead. Used to determine which ZLUT to use.

Definition at line 108 of file QueuedTracker.cpp.

 {
     LocalizationJob j;
     j.frame= frame;
     j.timestamp = timestamp;
     if (initial) j.initialPos = *initial;
     j.zlutIndex = zlutIndex;
     ScheduleLocalization(data,pitch,pdt,&j);
 }

§ SetConfigValue()

virtual void QueuedTracker::SetConfigValue	(	std::string	name,
		std::string	value
	)

pure virtual

Set an additional setting.

Parameters

[in]	name	Name of the setting.
[in]	value	Value of the setting.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ SetImageZLUT()

virtual bool QueuedTracker::SetImageZLUT	(	float *	src,
		float *	radial_zlut,
		int *	dims
	)

inlinevirtual

Set the image lookup tables to be used for z tracking.

Note: Use of image LUT is currently not clear. Radial ZLUT is always used.

Parameters

[in]	src	Pointer to the data for the image LUT.
[in]	radial_zlut	Pointer to the data for the radial LUT.
[in]	dims	Array of dimension sizes for the image LUT. See GetImageZLUTSize.

Reimplemented in QueuedCPUTracker.

Definition at line 222 of file QueuedTracker.h.

222 { return false; }

§ SetLocalizationMode()

virtual void QueuedTracker::SetLocalizationMode ( LocMode_t locType )

pure virtual

Select which algorithm is to be used.

Parameters

[in] locType An integer used as a bitmask for settings based on LocalizeModeEnum.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ SetPixelCalibrationFactors()

virtual void QueuedTracker::SetPixelCalibrationFactors	(	float	offsetFactor,
		float	gainFactor
	)

pure virtual

Set the pixel calibration factors.

The factors can be used to increase or decrease the effects of the images supplied through SetPixelCalibrationImages for further finetuning. These only have an effect when an image is actually set through that function.

Parameters

[in]	offsetFactor	Factor by which to scale the offset values.
[in]	gainFactor	Factor by which to scale the gain values.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ SetPixelCalibrationImages()

virtual void QueuedTracker::SetPixelCalibrationImages	(	float *	offset,
		float *	gain
	)

pure virtual

Set the pixel calibration images.

These images are used to scale the input image to get rid of background influences in the image. The values are per-pixel-per-ROI. Result = gain*(pixel+offset).

Parameters

[in]	offset	Array with the offset values to use per pixel. Size and order is [widthheightnumbeads].
[in]	gain	Array with gain values to use per pixel. Size and order is [widthheightnumbeads].

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ SetRadialWeights()

virtual void QueuedTracker::SetRadialWeights ( float * zcmp )

pure virtual

Set radial weights used for comparing LUT profiles.

Parameters

[in] zcmp Array of radial weights to use. zcmp has to have zlut_radialsteps elements.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

§ SetRadialZLUT()

virtual void QueuedTracker::SetRadialZLUT	(	float *	data,
		int	count,
		int	planes
	)

pure virtual

Set the radial lookup tables to be used for z tracking.

Data can be zero to allocate ZLUT data. LUTs should have been created before by BuildLUT, but not necessarily by the current instance as long as setting match.

Parameters

[in]	data	Pointer to the start of the ZLUT data.
[in]	count	Number of ZLUTs in the dataset.
[in]	planes	Number of planes per ZLUT.

Implemented in QueuedCUDATracker, and QueuedCPUTracker.

Member Data Documentation

§ cfg

QTrkComputedConfig QueuedTracker::cfg

The settings used by this instance of QueuedTracker.

Definition at line 356 of file QueuedTracker.h.

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

cputrack/QueuedTracker.h
cputrack/QueuedTracker.cpp

Public Types

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

§ ConfigValueMap

Constructor & Destructor Documentation

§ QueuedTracker()

§ ~QueuedTracker()

Member Function Documentation

§ BeginLUT()

§ BuildLUT()

§ ClearResults()

§ DebugImage()

§ EnableRadialZLUTCompareProfile()

§ FetchResults()

§ FinalizeLUT()

§ Flush()

§ GetConfigValues()

§ GetDebugImage()

§ GetImageZLUT()

§ GetImageZLUTSize()

§ GetProfileReport()

§ GetQueueLength()

§ GetRadialZLUT()

§ GetRadialZLUTCompareProfile()

§ GetRadialZLUTSize()

§ GetResultCount()

§ GetWarnings()

§ IsIdle()

§ ScheduleFrame()

§ ScheduleImageData()

§ ScheduleLocalization() [1/2]

§ ScheduleLocalization() [2/2]

§ SetConfigValue()

§ SetImageZLUT()

§ SetLocalizationMode()

§ SetPixelCalibrationFactors()

§ SetPixelCalibrationImages()

§ SetRadialWeights()

§ SetRadialZLUT()

Member Data Documentation

§ cfg