ResultManager Class Reference

Class that handles data gathering and saving from QueuedTracker instances. More...

#include <ResultManager.h>

Classes
struct	FrameCounters
	Structure to keep track of frame counts. More...
struct	FrameResult
	Structure to save all bead results of a single frame in memory. More...

Public Member Functions
	ResultManager (const char *outfile, const char *frameinfo, ResultManagerConfig *cfg, std::vector< std::string > colnames)
	Create an instance of ResultManager. More...
	~ResultManager ()
	Destroy an instance of ResultManager. More...
void	SaveSection (int start, int end, const char *beadposfile, const char *infofile)
	Save an interval of frames to a file. More...
void	SetTracker (QueuedTracker *qtrk)
	Set the tracker from which to fetch results. More...
QueuedTracker *	GetTracker ()
	Get the tracker from which results are fetched. More...
int	GetBeadPositions (int startFrame, int endFrame, int bead, LocalizationResult *r)
	Get the positions of a single bead over an interval of frames. More...
int	GetResults (LocalizationResult *results, int startFrame, int numResults)
	Get the positions of all beads over an interval of frames. More...
void	Flush ()
	Write all available data regardless of ResultManagerConfig::writeInterval. More...
FrameCounters	GetFrameCounters ()
	Returns a FrameCounters structure with the current counts. More...
void	StoreFrameInfo (int frame, double timestamp, float *columns)
	Store metadata for a frame. This data will be saved in the info file. More...
int	GetFrameCount ()
	Returns the number of captured frames. More...
bool	RemoveBeadResults (int bead)
	Remove all results of a certain bead. More...
const ResultManagerConfig &	Config ()
	Returns a reference to the used configuration to review. More...

Protected Member Functions
bool	CheckResultSpace (int fr)
	Checks if a frame index is valid. More...
void	Write ()
	Write available results to output files. More...
void	WriteBinaryResults ()
	Write available data to a binary file. More...
void	WriteTextResults ()
	Write available data to a text file. More...
void	StoreResult (LocalizationResult *r)
	Copies results from QueuedTracker to internal data structures. More...
bool	Update ()
	General worker function called from ThreadLoop. More...
void	WriteBinaryFileHeader ()
	Writes metadata to the header of a binary data file. More...

Static Protected Member Functions
static void	ThreadLoop (void *param)
	The base loop of the gathering and saving thread. More...

Protected Attributes
Threads::Mutex	resultMutex
	Mutex to govern access to frameResults. More...
Threads::Mutex	trackerMutex
	Mutex to govern access to the linked QueuedTracker instance. More...
std::vector< std::string >	frameInfoNames
	Vector with frame info column names. See WriteBinaryFileHeader. More...
std::deque< FrameResult *>	frameResults
	Vector to hold the results for all frames. More...
FrameCounters	cnt
	Local instance of FrameCounters to maintain counts accross functions. More...
ResultManagerConfig	config
	Local instance of ResultManagerConfig with the settings used by this instance of ResultManager. More...
ResultFile *	resultFile
	Local instance of ResultFile to generalize output to text or binary files. Not used. More...
QueuedTracker *	qtrk
	Pointer to the QueuedTracker instance to check. More...
std::string	outputFile
	Path and filename of the main data output file. More...
std::string	frameInfoFile
	Path and filename of the frame info (metadata) file. More...
Threads::Handle *	thread
	Handle to the thread running the ThreadLoop. More...
Atomic< bool >	quit
	Flag to exit the threads. More...

Detailed Description

Class that handles data gathering and saving from QueuedTracker instances.

Creates a separate thread to check a linked QTrk instance for new data. Gathers data and saves to the disk at regular intervals. Mutexes used to ensure thread safety.
Results from QueuedTracker are sorted as [frame][bead] to enable saving data on a frame-per-line basis.

Definition at line 91 of file ResultManager.h.

Constructor & Destructor Documentation

ResultManager()

ResultManager::ResultManager	(	const char *	outfile,
		const char *	frameinfo,
		ResultManagerConfig *	cfg,
		std::vector< std::string >	colnames
	)

Create an instance of ResultManager.

Parameters

[in]	outfile	String (char array) with full path and filename of desired output file for data.
[in]	frameinfo	String (char array) with full path and filename of desired output file for frame metadata.
[in]	cfg	Pointer to structure ResultManagerConfig with settings to use.
[in]	colnames	Vector of names for the columns in the frame info file. Size must equal ResultManagerConfig::numFrameInfoColumns. Only used for binary files.

Definition at line 42 of file ResultManager.cpp.

{
    config = *cfg;
    outputFile = outfile;
    this->frameInfoFile = frameInfoFile;

    qtrk = 0;

    thread = Threads::Create(ThreadLoop, this);
    quit=false;

    if (!outputFile.empty())
        remove(outfile);
    if (!this->frameInfoFile.empty())
        remove(frameInfoFile);

    frameInfoNames = colnames;

    if (config.binaryOutput) {
        WriteBinaryFileHeader();
    }

    dbgprintf("Allocating ResultManager with %d beads, %d motor columns and writeinterval %d\n", cfg->numBeads, cfg->numFrameInfoColumns, cfg->writeInterval);
}

~ResultManager()

ResultManager::~ResultManager

(

)

Destroy an instance of ResultManager.

Sets a flag to stop the thread and frees all results from memory.

Definition at line 95 of file ResultManager.cpp.

{
    quit = true;
    Threads::WaitAndClose(thread);

    DeleteAllElems(frameResults);
}

Member Function Documentation

CheckResultSpace()

bool ResultManager::CheckResultSpace ( int  fr )

protected

Checks if a frame index is valid.

Frame index is valid if within bounds of the current frames allowed in memory. Initializes the required FrameResult to store data for the frame fr if it is valid.

Parameters

[in]

fr

Frame index to be checked.

Return values

True	Index is fine. New FrameResult initialized and added to results vector.
False	Index is invalid. Can't process this frame index.

Definition at line 361 of file ResultManager.cpp.

{
    if(fr < cnt.startFrame)
        return false; // already removed, ignore

    if (fr > cnt.processedFrames + 20000) {

        dbgprintf("ResultManager: Ignoring suspiciously large frame number (%d).\n", fr);

        return false;
    }

    while ((uint)fr >= cnt.startFrame + frameResults.size()) {
        frameResults.push_back (new FrameResult( config.numBeads, config.numFrameInfoColumns));
    }
    return true;
}

Config()

const ResultManagerConfig& ResultManager::Config ( )

inline

Returns a reference to the used configuration to review.

Returns

The ResultManagerConfig structure used for this instance of ResultManager. Read-only.

Definition at line 208 of file ResultManager.h.

{ return config; }

Flush()

void ResultManager::Flush

(

)

Write all available data regardless of ResultManagerConfig::writeInterval.

Use to write unsaved frames from memory when no new ones are expected anymore. Writes all leftover data after waiting for the linked QueuedTracker to finish its queued localizations.

Definition at line 307 of file ResultManager.cpp.

{
    trackerMutex.lock();
    if (qtrk) qtrk->Flush();
    trackerMutex.unlock();

    Update();

    resultMutex.lock();

    Write();

    // Dump stats about unfinished frames for debugging
#ifdef _DEBUG
    for (uint i=0;i<frameResults.size();i++) {
        FrameResult *fr = frameResults[i];
//      dbgprintf("Frame %d. TS: %f, Count: %d\n", i, fr->timestamp, fr->count);
        if (fr->count != config.numBeads) {
            for (int j=0;j<fr->results.size();j++) {
                if( fr->results[j].job.frame == 0)
                    dbgprintf("%d, ", j );
            }
            dbgprintf("\n");
        }
    }
#endif
    resultMutex.unlock();
}

GetBeadPositions()

int ResultManager::GetBeadPositions	(	int	startFrame,
		int	endFrame,
		int	bead,
		LocalizationResult *	r
	)

Get the positions of a single bead over an interval of frames.

Parameters

[in]	startFrame	Framenumber of the start of the interval to save.
[in]	endFrame	Framenumber of the end of the interval to save.
[in]	bead	Beadnumber of the bead for which the results are requested.
[out]	r	Array of LocalizationResult in which to store the data. Has to be initialized before calling this function. Size has to be equal to endFrame - startFrame.

Returns

Number of results obtained.

Definition at line 285 of file ResultManager.cpp.

{
    int count = end-startfr;

    resultMutex.lock();
    if (end > cnt.processedFrames)
        end = cnt.processedFrames;

    int start = startfr - cnt.startFrame;
    if (start < 0) start = 0;
    if (count > cnt.processedFrames-cnt.startFrame)
        count = cnt.processedFrames-cnt.startFrame;

    for (int i=0;i<count;i++){
        results[i] = frameResults[i+start]->results[bead];
    }
    resultMutex.unlock();

    return count;
}

GetFrameCount()

int ResultManager::GetFrameCount

(

)

Returns the number of captured frames.

Returns

Number of captured frames

Definition at line 399 of file ResultManager.cpp.

{
    resultMutex.lock();
    int nfr = cnt.capturedFrames;
    resultMutex.unlock();
    return nfr;
}

GetFrameCounters()

ResultManager::FrameCounters ResultManager::GetFrameCounters

(

)

Returns a FrameCounters structure with the current counts.

Definition at line 337 of file ResultManager.cpp.

{
    resultMutex.lock();
    FrameCounters c = cnt;
    resultMutex.unlock();
    return c;
}

GetResults()

int ResultManager::GetResults	(	LocalizationResult *	results,
		int	startFrame,
		int	numResults
	)

Get the positions of all beads over an interval of frames.

Parameters

[in]	startFrame	Framenumber of the start of the interval to save.
[in]	numResults	Number of frames to save.
[out]	results	Array of LocalizationResult in which to store the data. Has to be initialized before calling this function. Size has to be equal to numResults.

Returns

Number of results obtained.

Definition at line 345 of file ResultManager.cpp.

{
    resultMutex.lock();

    if (startFrame >= cnt.startFrame && numFrames+startFrame <= cnt.processedFrames)  {
        for (int f=0;f<numFrames;f++) {
            int index = f + startFrame - cnt.startFrame;
            for (int j=0;j<config.numBeads;j++)
                results[config.numBeads*f+j] = frameResults[index]->results[j];
        }
    }
    resultMutex.unlock();

    return numFrames;
}

GetTracker()

QueuedTracker * ResultManager::GetTracker

(

)

Get the tracker from which results are fetched.

Returns

Pointer to the current QueuedTracker instance.

Definition at line 207 of file ResultManager.cpp.

{
    trackerMutex.lock();
    QueuedTracker* trk = qtrk;
    trackerMutex.unlock();
    return trk;
}

RemoveBeadResults()

bool ResultManager::RemoveBeadResults

(

int

bead

)

Remove all results of a certain bead.

Currently only removes from memory.

Parameters

[in]

bead

The index of the bead for which to remove the data.

Todo:

We need to modify the saved data file

Definition at line 407 of file ResultManager.cpp.

{

    for (uint i=0;i<frameResults.size();i++) {
        auto fr = frameResults[i];

        fr->count--;
        fr->results.erase(fr->results.begin()+bead);
    }

    return true;
}

SaveSection()

void ResultManager::SaveSection	(	int	start,
		int	end,
		const char *	beadposfile,
		const char *	infofile
	)

Save an interval of frames to a file.

Warning

Unimplemented.

Parameters

[in]	start	Framenumber of the start of the interval to save.
[in]	end	Framenumber of the end of the interval to save.
[in]	beadposfile	String (char array) with full path and filename of desired output file for data.
[in]	infofile	String (char array) with full path and filename of desired output file for frame metadata.

SetTracker()

void ResultManager::SetTracker

(

QueuedTracker *

qtrk

)

Set the tracker from which to fetch results.

Parameters

[in]

qtrk

Pointer to the QueuedTracker instance to fetch results from.

Definition at line 215 of file ResultManager.cpp.

{
    trackerMutex.lock();
    this->qtrk = qtrk;
    trackerMutex.unlock();
}

StoreFrameInfo()

void ResultManager::StoreFrameInfo	(	int	frame,
		double	timestamp,
		float *	columns
	)

Store metadata for a frame. This data will be saved in the info file.

Parameters

[in]	frame	Frame number for which to store the data.
[in]	timestamp	Timestamp for the frame.
[in]	columns	Array of float values for the metadata columns. Size must equal ResultManagerConfig::numFrameInfoColumns.

Definition at line 379 of file ResultManager.cpp.

{
    resultMutex.lock();

    if (CheckResultSpace(frame)) {
        FrameResult* fr = frameResults[frame-cnt.startFrame];       

        if (!fr->hasFrameInfo) {
            fr->timestamp = timestamp;
            for(int i=0;i<config.numFrameInfoColumns;i++)
                fr->frameInfo[i]=columns[i];
            ++cnt.capturedFrames;
            fr->hasFrameInfo=true;
        }
    }

    resultMutex.unlock();
}

StoreResult()

void ResultManager::StoreResult ( LocalizationResult *  r )

protected

Copies results from QueuedTracker to internal data structures.

Adds a result to the pre-allocated memory of frame results so it can later be saved on a per-frame basis.

Note

Results are changed from pixel to physical values here, using input given on initialization through ResultManagerConfig.

Parameters

[in]

r

A pointer to a LocalizationResult of a single localization.

Definition at line 104 of file ResultManager.cpp.

{
    if (CheckResultSpace(r->job.frame)) {

        LocalizationResult scaled = *r;
        // Make roi-centered pos
        scaled.pos = scaled.pos - vector3f( qtrk->cfg.width*0.5f, qtrk->cfg.height*0.5f, 0);
        scaled.pos = ( scaled.pos + config.offset ) * config.scaling;
        FrameResult* fr = frameResults[r->job.frame - cnt.startFrame];
        fr->results[r->job.zlutIndex] = scaled;
        fr->count++;

        // Advance processedFrames, either because measurements have been completed or because frames have been lost
        while (cnt.processedFrames - cnt.startFrame < (int) frameResults.size() && 
            (frameResults[cnt.processedFrames-cnt.startFrame]->count == config.numBeads || cnt.capturedFrames - cnt.processedFrames > 1000 ))
        {
            if (frameResults[cnt.processedFrames-cnt.startFrame]->count < config.numBeads)
                cnt.lostFrames ++;

            cnt.processedFrames ++;
        }

        cnt.localizationsDone ++;
    } else
        cnt.lostFrames++;
}

ThreadLoop()

void ResultManager::ThreadLoop ( void *  param )

staticprotected

The base loop of the gathering and saving thread.

Called when initialization is done.

Parameters

[in]

param

Pointer to the instance of ResultManager to work for.

Definition at line 272 of file ResultManager.cpp.

{
    ResultManager* rm = (ResultManager*)param;

    while(true) {
        if (!rm->Update())
            Threads::Sleep(20);

        if (rm->quit)
            break;
    }
}

Update()

bool ResultManager::Update ( )

protected

General worker function called from ThreadLoop.

Fetches results from QueuedTracker (FetchResults), sorts them (StoreResult) and saves them if needed (Write).

Definition at line 222 of file ResultManager.cpp.

{
    trackerMutex.lock();

    if (!qtrk) {
        trackerMutex.unlock();
        return 0;
    }

    const int NResultBuf = 40;
    LocalizationResult resultbuf[NResultBuf];

    int count = qtrk->FetchResults( resultbuf, NResultBuf );

    resultMutex.lock();
    for (int i=0;i<count;i++)
        StoreResult(&resultbuf[i]);

    trackerMutex.unlock();

    if (cnt.processedFrames - cnt.lastSaveFrame >= config.writeInterval) {
        Write();
    }

    if (config.maxFramesInMemory>0 && frameResults.size () > config.maxFramesInMemory) {

        int del = frameResults.size()-config.maxFramesInMemory;

        if (cnt.processedFrames < cnt.startFrame) {
            // write away any results that might be in there, unfinished localizations will be zero.
            int lost = cnt.startFrame-cnt.processedFrames;
            cnt.processedFrames += lost;
            cnt.lostFrames += lost;

            Write();
        }

        //dbgprintf("Removing %d frames from memory\n", del);
        
        for (int i=0;i<del;i++)
            delete frameResults[i];
        frameResults.erase(frameResults.begin(), frameResults.begin()+del);

        cnt.startFrame += del;
    }
    resultMutex.unlock();

    return count>0;
}

Write()

void ResultManager::Write ( )

protected

Write available results to output files.

Chooses between WriteBinaryResults and WriteTextResults depending on settings.

Definition at line 193 of file ResultManager.cpp.

{
    resultMutex.lock();
    if (config.binaryOutput)
        WriteBinaryResults();
    else
        WriteTextResults();

    dbgprintf("Saved frame %d to %d\n", cnt.lastSaveFrame, cnt.processedFrames);
    cnt.lastSaveFrame = cnt.processedFrames;

    resultMutex.unlock();
}

WriteBinaryFileHeader()

void ResultManager::WriteBinaryFileHeader ( )

protected

Writes metadata to the header of a binary data file.

The saved header for file version 3 is:

Name	Description	Size (bytes)
version	Binary file version	4 (int)
numBead	Number of beads in the file	4 (int)
numFrameInfoColumns	Number of metadata columns	4 (int)
data_offset	File offset to starting point of frame data	8 (long)
frameInfoNames	The names/identifiers for the metadata columns	variable (numFrameInfoColumns * strings)

Definition at line 67 of file ResultManager.cpp.

{
    FILE* f = fopen(outputFile.c_str(), "wb");
    if (!f) {
        throw std::runtime_error( SPrintf("Unable to open file %s", outputFile.c_str()));
    }

    // Write file header
    int version = BINFILE_VERSION;
    fwrite(&version, sizeof(int), 1, f);
    fwrite(&config.numBeads, sizeof(int), 1, f);
    fwrite(&config.numFrameInfoColumns, sizeof(int), 1, f);
    long data_offset_pos = ftell(f);
    long tmp=1234;
    fwrite(&tmp, sizeof(long), 1,f);
    for (int i=0;i<config.numFrameInfoColumns;i++) {
        auto& n = frameInfoNames[i];
        fwrite(n.c_str(), n.length()+1, 1, f);
    }
    long data_offset = ftell(f);
    dbgprintf("frame data offset: %d\n", data_offset);
    fseek(f, data_offset_pos, SEEK_SET);
    fwrite(&data_offset, sizeof(long), 1, f);
    
    dbgprintf("writing %d beads and %d frame-info columns into file %s\n", config.numBeads, config.numFrameInfoColumns, outputFile.c_str());
    fclose(f);
}

WriteBinaryResults()

void ResultManager::WriteBinaryResults ( )

protected

Write available data to a binary file.

Warning

Does not update frame counters. Use Write and proper settings instead.

Definition at line 131 of file ResultManager.cpp.

{
    if (outputFile.empty())
        return;

    FILE* f = fopen(outputFile.c_str(), "ab");
    if (!f) {
        dbgprintf("ResultManager::WriteBinaryResult() Unable to open file %s\n", outputFile.c_str());
        cnt.fileError ++;
        return;
    }

    for (int j=cnt.lastSaveFrame; j<cnt.processedFrames;j++)
    {
        auto fr = frameResults[j-cnt.startFrame];
        if (f) {
            fwrite(&j, sizeof(uint), 1, f);
            fwrite(&fr->timestamp, sizeof(double), 1, f);
            fwrite(&fr->frameInfo[0], sizeof(float), config.numFrameInfoColumns, f);
            for (int i=0;i<config.numBeads;i++) 
            {
                LocalizationResult *r = &fr->results[i];
                fwrite(&r->pos, sizeof(vector3f), 1, f);
            }
            for (int i=0;i<config.numBeads;i++)
                fwrite(&fr->results[i].error, sizeof(int), 1, f);
            for (int i=0;i<config.numBeads;i++) {
                fwrite(&fr->results[i].imageMean, sizeof(float), 1, f);
            }
        }
    }
    fclose(f);
}

WriteTextResults()

void ResultManager::WriteTextResults ( )

protected

Write available data to a text file.

Warning

Does not update frame counters. Use Write and proper settings instead.

Definition at line 165 of file ResultManager.cpp.

{
    FILE* f = outputFile.empty () ? 0 : fopen(outputFile.c_str(), "a");
    FILE* finfo = frameInfoFile.empty() ? 0 : fopen(frameInfoFile.c_str(), "a");

    for (int k=cnt.lastSaveFrame; k<cnt.processedFrames;k++)
    {
        auto fr = frameResults[k-cnt.startFrame];
        if (f) {
            fprintf(f,"%d\t%f\t", k, fr->timestamp);
            for (int i=0;i<config.numBeads;i++) 
            {
                LocalizationResult *r = &fr->results[i];
                fprintf(f, "%.7f\t%.7f\t%.7f\t", r->pos.x,r->pos.y,r->pos.z);
            }
            fputs("\n", f);
        }
        if (finfo) {
            fprintf(finfo,"%d\t%f\t", k, fr->timestamp);
            for (int i=0;i<config.numFrameInfoColumns;i++)
                fprintf(finfo, "%.7f\t", fr->frameInfo[i]);
            fputs("\n", finfo);
        }
    }
    if(finfo) fclose(finfo);
    if(f) fclose(f);
}

Member Data Documentation

cnt

FrameCounters ResultManager::cnt

protected

Local instance of FrameCounters to maintain counts accross functions.

Definition at line 299 of file ResultManager.h.

config

ResultManagerConfig ResultManager::config

protected

Local instance of ResultManagerConfig with the settings used by this instance of ResultManager.

Definition at line 300 of file ResultManager.h.

frameInfoFile

std::string ResultManager::frameInfoFile

protected

Path and filename of the frame info (metadata) file.

Definition at line 307 of file ResultManager.h.

frameInfoNames

std::vector<std::string> ResultManager::frameInfoNames

protected

Vector with frame info column names. See WriteBinaryFileHeader.

Definition at line 296 of file ResultManager.h.

frameResults

std::deque< FrameResult* > ResultManager::frameResults

protected

Vector to hold the results for all frames.

Definition at line 298 of file ResultManager.h.

outputFile

std::string ResultManager::outputFile

protected

Path and filename of the main data output file.

Definition at line 306 of file ResultManager.h.

qtrk

QueuedTracker* ResultManager::qtrk

protected

Pointer to the QueuedTracker instance to check.

Definition at line 304 of file ResultManager.h.

quit

Atomic<bool> ResultManager::quit

protected

Flag to exit the threads.

Definition at line 309 of file ResultManager.h.

resultFile

ResultFile* ResultManager::resultFile

protected

Local instance of ResultFile to generalize output to text or binary files. Not used.

Definition at line 302 of file ResultManager.h.

resultMutex

Threads::Mutex ResultManager::resultMutex

protected

Mutex to govern access to frameResults.

Definition at line 293 of file ResultManager.h.

thread

Threads::Handle* ResultManager::thread

protected

Handle to the thread running the ThreadLoop.

Definition at line 308 of file ResultManager.h.

trackerMutex

Threads::Mutex ResultManager::trackerMutex

protected

Mutex to govern access to the linked QueuedTracker instance.

Definition at line 294 of file ResultManager.h.

---

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

• cputrack/ResultManager.h
• cputrack/ResultManager.cpp