BasicCam Class Reference

This class implements and interfaces with the most common USB cameras and features. It is designed in such a way that multiple other classes/threads can safely call any method of an object of this class withing resource corruption or slowdown of the camera. More...

#include <BasicCam.h>

Inheritance diagram for BasicCam:

Collaboration diagram for BasicCam:

Public Member Functions
	BasicCam (const std::string szCameraPath, const int nPropResolutionX, const int nPropResolutionY, const int nPropFramesPerSecond, const PIXEL_FORMATS ePropPixelFormat, const double dPropHorizontalFOV, const double dPropVerticalFOV, const bool bEnableRecordingFlag, const int nNumFrameRetrievalThreads=10)
	Construct a new Basic Cam:: Basic Cam object.
	BasicCam (const int nCameraIndex, const int nPropResolutionX, const int nPropResolutionY, const int nPropFramesPerSecond, const PIXEL_FORMATS ePropPixelFormat, const double dPropHorizontalFOV, const double dPropVerticalFOV, const bool bEnableRecordingFlag, const int nNumFrameRetrievalThreads=10)
	Construct a new Basic Cam:: Basic Cam object. Overloaded for dev/video indexes.
	~BasicCam ()
	Destroy the Basic Cam:: Basic Cam object.
std::future< bool >	RequestFrameCopy (cv::Mat &cvFrame) override
	Puts a frame pointer into a queue so a copy of a frame from the camera can be written to it. Remember, this code will be ran in whatever, class/thread calls it.
bool	GetCameraIsOpen () override
	Accessor for the camera open status.
std::string	GetCameraLocation () const override
	Accessor for the cameras path or video index.
Public Member Functions inherited from BasicCamera
	BasicCamera (const std::string szCameraPath, const int nPropResolutionX, const int nPropResolutionY, const int nPropFramesPerSecond, const PIXEL_FORMATS ePropPixelFormat, const double dPropHorizontalFOV, const double dPropVerticalFOV, const bool bEnableRecordingFlag, const int nNumFrameRetrievalThreads)
	Construct a new Basic Camera object.
	BasicCamera (const int nCameraIndex, const int nPropResolutionX, const int nPropResolutionY, const int nPropFramesPerSecond, const PIXEL_FORMATS ePropPixelFormat, const double dPropHorizontalFOV, const double dPropVerticalFOV, const bool bEnableRecordingFlag, const int nNumFrameRetrievalThreads)
	Construct a new Basic Camera object. Overloaded for dev/video indexes.
virtual	~BasicCamera ()
	Destroy the Basic Camera object.
Public Member Functions inherited from Camera< cv::Mat >
	Camera (const int nPropResolutionX, const int nPropResolutionY, const int nPropFramesPerSecond, const PIXEL_FORMATS ePropPixelFormat, const double dPropHorizontalFOV, const double dPropVerticalFOV, const bool bEnableRecordingFlag, const int nNumFrameRetrievalThreads=5)
	Construct a new Camera object.
virtual	~Camera ()
	Destroy the Camera object.
cv::Size	GetPropResolution () const
	Accessor for the Prop Resolution private member.
int	GetPropFramesPerSecond () const
	Accessor for the Prop Frames Per Second private member.
PIXEL_FORMATS	GetPropPixelFormat () const
	Accessor for the Prop Pixel Format private member.
double	GetPropHorizontalFOV () const
	Accessor for the Prop Horizontal F O V private member.
double	GetPropVerticalFOV () const
	Accessor for the Prop Vertical F O V private member.
bool	GetEnableRecordingFlag () const
	Accessor for the Enable Recording Flag private member.
void	SetEnableRecordingFlag (const bool bEnableRecordingFlag)
	Mutator for the Enable Recording Flag private member.
Public Member Functions inherited from AutonomyThread< void >
	AutonomyThread ()
	Construct a new Autonomy Thread object.
virtual	~AutonomyThread ()
	Destroy the Autonomy Thread object. If the parent object or main thread is destroyed or exited while this thread is still running, a race condition will occur. Stopping and joining the thread here insures that the main program can't exit if the user forgot to stop and join the thread.
void	Start ()
	When this method is called, it starts a new thread that runs the code within the ThreadedContinuousCode method. This is the users main code that will run the important and continuous code for the class.
void	RequestStop ()
	Signals threads to stop executing user code, terminate. DOES NOT JOIN. This method will not force the thread to exit, if the user code is not written properly and contains WHILE statement or any other long-executing or blocking code, then the thread will not exit until the next iteration.
void	Join ()
	Waits for thread to finish executing and then closes thread. This method will block the calling code until thread is finished.
bool	Joinable () const
	Check if the code within the thread and all pools created by it are finished executing and the thread is ready to be closed.
AutonomyThreadState	GetThreadState () const
	Accessor for the Threads State private member.
IPS &	GetIPS ()
	Accessor for the Frame I P S private member.

Private Member Functions
void	ThreadedContinuousCode () override
	The code inside this private method runs in a separate thread, but still has access to this*. This method continuously get new frames from the OpenCV VideoCapture object and stores it in a member variable. Then a thread pool is started and joined once per iteration to mass copy the frames and/or measure to any other thread waiting in the queues.
void	PooledLinearCode () override
	This method holds the code that is ran in the thread pool started by the ThreadedLinearCode() method. It copies the data from the different data objects to references of the same type stored in a vector queued up by the Grab methods.

Private Attributes
cv::VideoCapture	m_cvCamera
cv::Mat	m_cvFrame

Additional Inherited Members
Public Types inherited from AutonomyThread< void >
enum	AutonomyThreadState
Protected Member Functions inherited from AutonomyThread< void >
void	RunPool (const unsigned int nNumTasksToQueue, const unsigned int nNumThreads=2, const bool bForceStopCurrentThreads=false)
	When this method is called, it starts/adds tasks to a thread pool that runs nNumTasksToQueue copies of the code within the PooledLinearCode() method using nNumThreads number of threads. This is meant to be used as an internal utility of the child class to further improve parallelization. Default value for nNumThreads is 2.
void	RunDetachedPool (const unsigned int nNumTasksToQueue, const unsigned int nNumThreads=2, const bool bForceStopCurrentThreads=false)
	When this method is called, it starts a thread pool full of threads that don't return std::futures (like a placeholder for the thread return type). This means the thread will not have a return type and there is no way to determine if the thread has finished other than calling the Join() method. Only use this if you want to 'set and forget'. It will be faster as it doesn't return futures. Runs PooledLinearCode() method code. This is meant to be used as an internal utility of the child class to further improve parallelization.
void	ParallelizeLoop (const int nNumThreads, const N tTotalIterations, F &&tLoopFunction)
	Given a ref-qualified looping function and an arbitrary number of iterations, this method will divide up the loop and run each section in a thread pool. This function must not return anything. This method will block until the loop has completed.
void	ClearPoolQueue ()
	Clears any tasks waiting to be ran in the queue, tasks currently running will remain running.
void	JoinPool ()
	Waits for pool to finish executing tasks. This method will block the calling code until thread is finished.
bool	PoolJoinable () const
	Check if the internal pool threads are done executing code and the queue is empty.
void	SetMainThreadIPSLimit (int nMaxIterationsPerSecond=0)
	Mutator for the Main Thread Max I P S private member.
int	GetPoolNumOfThreads ()
	Accessor for the Pool Num Of Threads private member.
int	GetPoolQueueLength ()
	Accessor for the Pool Queue Size private member.
std::vector< void >	GetPoolResults ()
	Accessor for the Pool Results private member. The action of getting results will destroy and remove them from this object. This method blocks if the thread is not finished, so no need to call JoinPool() before getting results.
int	GetMainThreadMaxIPS () const
	Accessor for the Main Thread Max I P S private member.
Protected Attributes inherited from BasicCamera
int	m_nCameraIndex
std::string	m_szCameraPath
bool	m_bCameraIsConnectedOnVideoIndex
Protected Attributes inherited from Camera< cv::Mat >
int	m_nPropResolutionX
int	m_nPropResolutionY
int	m_nPropFramesPerSecond
int	m_nNumFrameRetrievalThreads
PIXEL_FORMATS	m_ePropPixelFormat
double	m_dPropHorizontalFOV
double	m_dPropVerticalFOV
std::atomic_bool	m_bEnableRecordingFlag
std::queue< containers::FrameFetchContainer< cv::Mat > >	m_qFrameCopySchedule
std::shared_mutex	m_muPoolScheduleMutex
std::shared_mutex	m_muFrameCopyMutex
Protected Attributes inherited from AutonomyThread< void >
IPS	m_IPS

Detailed Description

This class implements and interfaces with the most common USB cameras and features. It is designed in such a way that multiple other classes/threads can safely call any method of an object of this class withing resource corruption or slowdown of the camera.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-09-21

Constructor & Destructor Documentation

BasicCam() [1/2]

BasicCam::BasicCam	(	const std::string	szCameraPath,
		const int	nPropResolutionX,
		const int	nPropResolutionY,
		const int	nPropFramesPerSecond,
		const PIXEL_FORMATS	ePropPixelFormat,
		const double	dPropHorizontalFOV,
		const double	dPropVerticalFOV,
		const bool	bEnableRecordingFlag,
		const int	nNumFrameRetrievalThreads = 10
	)

Construct a new Basic Cam:: Basic Cam object.

Parameters

szCameraPath	- The file path to the camera hardware.
nPropResolutionX	- X res of camera.
nPropResolutionY	- Y res of camera.
nPropFramesPerSecond	- FPS camera is running at.
ePropPixelFormat	- The pixel layout/format of the image.
dPropHorizontalFOV	- The horizontal field of view.
dPropVerticalFOV	- The vertical field of view.
bEnableRecordingFlag	- Whether or not this camera should be recorded.
nNumFrameRetrievalThreads	- The number of threads to use for frame queueing and copying.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-08-20

                                                        :
    BasicCamera(szCameraPath,
                nPropResolutionX,
                nPropResolutionY,
                nPropFramesPerSecond,
                ePropPixelFormat,
                dPropHorizontalFOV,
                dPropVerticalFOV,
                bEnableRecordingFlag,
                nNumFrameRetrievalThreads)
{
    // Initialize the OpenCV mat to a black/empty image the size of the camera resolution.
    m_cvFrame = cv::Mat::zeros(nPropResolutionY, nPropResolutionX, CV_8UC4);
 
    // Set video cap properties.
    m_cvCamera.set(cv::CAP_PROP_FRAME_WIDTH, nPropResolutionX);
    m_cvCamera.set(cv::CAP_PROP_FRAME_HEIGHT, nPropResolutionY);
    m_cvCamera.set(cv::CAP_PROP_FPS, nPropFramesPerSecond);
 
    // Attempt to open camera with OpenCV's VideoCapture and print if successfully opened or not.
    if (m_cvCamera.open(szCameraPath))
    {
        // Submit logger message.
        LOG_INFO(logging::g_qSharedLogger, "Camera {} at path/URL {} has been successfully opened.", m_cvCamera.getBackendName(), szCameraPath);
    }
    else
    {
        // Submit logger message.
        LOG_ERROR(logging::g_qSharedLogger, "Unable to open camera at path/URL {}", szCameraPath);
    }
 
    // Set max FPS of the ThreadedContinuousCode method.
    this->SetMainThreadIPSLimit(nPropFramesPerSecond);
}

Here is the call graph for this function:

BasicCam() [2/2]

BasicCam::BasicCam	(	const int	nCameraIndex,
		const int	nPropResolutionX,
		const int	nPropResolutionY,
		const int	nPropFramesPerSecond,
		const PIXEL_FORMATS	ePropPixelFormat,
		const double	dPropHorizontalFOV,
		const double	dPropVerticalFOV,
		const bool	bEnableRecordingFlag,
		const int	nNumFrameRetrievalThreads = 10
	)

Construct a new Basic Cam:: Basic Cam object. Overloaded for dev/video indexes.

Parameters

nCameraIndex	- The video index that the camera is connected on.
nPropResolutionX	- X res of camera.
nPropResolutionY	- Y res of camera.
nPropFramesPerSecond	- FPS camera is running at.
ePropPixelFormat	- The pixel layout/format of the image.
dPropHorizontalFOV	- The horizontal field of view.
dPropVerticalFOV	- The vertical field of view.
bEnableRecordingFlag	- Whether or not this camera should be recorded.
nNumFrameRetrievalThreads	- The number of threads to use for frame queueing and copying.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-08-20

                                                        :
    BasicCamera(nCameraIndex,
                nPropResolutionX,
                nPropResolutionY,
                nPropFramesPerSecond,
                ePropPixelFormat,
                dPropHorizontalFOV,
                dPropVerticalFOV,
                bEnableRecordingFlag,
                nNumFrameRetrievalThreads)
{
    // Initialize the OpenCV mat to a black/empty image the size of the camera resolution.
    m_cvFrame = cv::Mat::zeros(nPropResolutionY, nPropResolutionX, CV_8UC4);
 
    // Set video cap properties.
    m_cvCamera.set(cv::CAP_PROP_FRAME_WIDTH, nPropResolutionX);
    m_cvCamera.set(cv::CAP_PROP_FRAME_HEIGHT, nPropResolutionY);
    m_cvCamera.set(cv::CAP_PROP_FPS, nPropFramesPerSecond);
 
    // Attempt to open camera with OpenCV's VideoCapture.
    m_cvCamera.open(m_nCameraIndex);
    // Check if the camera was successfully opened.
    if (m_cvCamera.isOpened())
    {
        // Submit logger message.
        LOG_INFO(logging::g_qSharedLogger, "Camera {} at video index {} has been successfully opened.", m_cvCamera.getBackendName(), m_nCameraIndex);
    }
    else
    {
        // Submit logger message.
        LOG_ERROR(logging::g_qSharedLogger, "Unable to open camera at video index {}", m_nCameraIndex);
    }
 
    // Set max FPS of the ThreadedContinuousCode method.
    this->SetMainThreadIPSLimit(nPropFramesPerSecond);
}

Here is the call graph for this function:

~BasicCam()

BasicCam::~BasicCam

(

)

Destroy the Basic Cam:: Basic Cam object.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-08-20

{
    // Stop threaded code.
    this->RequestStop();
    this->Join();
 
    // Release camera capture object.
    m_cvCamera.release();
 
    // Check if camera was connected on a video index.
    if (m_bCameraIsConnectedOnVideoIndex)
    {
        // Submit logger message.
        LOG_INFO(logging::g_qSharedLogger, "Basic camera at video index {} has been successfully closed.", m_nCameraIndex);
    }
    else
    {
        // Submit logger message.
        LOG_INFO(logging::g_qSharedLogger, "Basic camera at path/URL {} has been successfully closed.", m_szCameraPath);
    }
}

Here is the call graph for this function:

Member Function Documentation

RequestFrameCopy()

std::future< bool > BasicCam::RequestFrameCopy ( cv::Mat &  cvFrame )

overridevirtual

Puts a frame pointer into a queue so a copy of a frame from the camera can be written to it. Remember, this code will be ran in whatever, class/thread calls it.

Parameters

cvFrame

- A reference to the cv::Mat to store the frame in.

Returns

std::future<bool> - A future that should be waited on before the passed in frame is used. Value will be true if frame was successfully retrieved.

Author

ClayJay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-09-09

Implements BasicCamera.

{
    // Assemble the FrameFetchContainer.
    containers::FrameFetchContainer<cv::Mat> stContainer(cvFrame, m_ePropPixelFormat);
 
    // Acquire lock on frame copy queue.
    std::unique_lock<std::shared_mutex> lkScheduler(m_muPoolScheduleMutex);
    // Append frame fetch container to the schedule queue.
    m_qFrameCopySchedule.push(stContainer);
    // Release lock on the frame schedule queue.
    lkScheduler.unlock();
 
    // Return the future from the promise stored in the container.
    return stContainer.pCopiedFrameStatus->get_future();
}

GetCameraIsOpen()

bool BasicCam::GetCameraIsOpen ( )

overridevirtual

Accessor for the camera open status.

Returns

true - The camera has been successfully opened.

false - The camera has not been successfully opened.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-08-20

Implements Camera< cv::Mat >.

{
    // Get camera status from OpenCV.
    return m_cvCamera.isOpened();
}

Here is the call graph for this function:

Here is the caller graph for this function:

GetCameraLocation()

std::string BasicCam::GetCameraLocation ( ) const

overridevirtual

Accessor for the cameras path or video index.

Returns

std::string - The path or index of the camera.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-08-20

Reimplemented from BasicCamera.

{
    // Check if camera location is a hardware path or video index.
    if (m_bCameraIsConnectedOnVideoIndex)
    {
        // If video index, return index integer.
        return std::to_string(m_nCameraIndex);
    }
    else
    {
        // If video path, return path string.
        return m_szCameraPath;
    }
}

Here is the caller graph for this function:

ThreadedContinuousCode()

void BasicCam::ThreadedContinuousCode ( )

overrideprivatevirtual

The code inside this private method runs in a separate thread, but still has access to this*. This method continuously get new frames from the OpenCV VideoCapture object and stores it in a member variable. Then a thread pool is started and joined once per iteration to mass copy the frames and/or measure to any other thread waiting in the queues.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-09-16

Reimplemented from BasicCamera.

{
    // Check if camera is NOT open.
    if (!m_cvCamera.isOpened())
    {
        // If this is the first iteration of the thread the camera probably isn't present so stop thread to save resources.
        if (this->GetThreadState() == AutonomyThreadState::eStarting)
        {
            // Shutdown threads for this BasicCam.
            this->RequestStop();
 
            // Submit logger message.
            LOG_CRITICAL(logging::g_qSharedLogger, "Camera start was attempted for BasicCam at {}/{}, but camera was never opened!", m_nCameraIndex, m_szCameraPath);
        }
        else
        {
            // Create instance variables.
            bool bCameraReopened                  = false;
            static bool bReopenAlreadyChecked     = false;
            std::chrono::time_point tmCurrentTime = std::chrono::system_clock::now();
            // Convert time point to seconds since epoch
            int nTimeSinceEpoch = std::chrono::duration_cast<std::chrono::seconds>(tmCurrentTime.time_since_epoch()).count();
 
            // Only try to reopen camera every 5 seconds.
            if (nTimeSinceEpoch % 5 == 0 && !bReopenAlreadyChecked)
            {
                // Check if camera was opened with an index or path.
                if (m_nCameraIndex == -1)
                {
                    // Attempt to reopen camera.
                    bCameraReopened = m_cvCamera.open(m_szCameraPath);
                }
                else
                {
                    // Attempt to reopen camera.
                    bCameraReopened = m_cvCamera.open(m_nCameraIndex);
                }
 
                // Check if camera was reopened.
                if (bCameraReopened)
                {
                    // Submit logger message.
                    LOG_INFO(logging::g_qSharedLogger, "Camera {}/{} has been reconnected and reopened!", m_nCameraIndex, m_szCameraPath);
                }
                else
                {
                    // Submit logger message.
                    LOG_WARNING(logging::g_qSharedLogger, "Attempt to reopen Camera {}/{} has failed! Trying again in 5 seconds...", m_nCameraIndex, m_szCameraPath);
                    // Sleep for five seconds.
                }
 
                // Set toggle.
                bReopenAlreadyChecked = true;
            }
            else if (nTimeSinceEpoch % 5 != 0)
            {
                // Reset toggle.
                bReopenAlreadyChecked = false;
            }
        }
    }
    else
    {
        // Check if new frame was computed successfully.
        if (m_cvCamera.read(m_cvFrame))
        {
            // Resize the frame.
            cv::resize(m_cvFrame, m_cvFrame, cv::Size(m_nPropResolutionX, m_nPropResolutionY), 0.0, 0.0, constants::BASICCAM_RESIZE_INTERPOLATION_METHOD);
        }
        else
        {
            // Submit logger message.
            LOG_ERROR(logging::g_qSharedLogger, "Unable to read new frame for camera {}, {}! Closing camera...", m_nCameraIndex, m_szCameraPath);
            // Release camera capture.
            m_cvCamera.release();
 
            // Fill camera frame member variable with zeros. This ensures a non-corrupt, black image.
            m_cvFrame = cv::Mat::zeros(m_nPropResolutionY, m_nPropResolutionX, CV_8UC3);
        }
    }
 
    // Acquire a shared_lock on the frame copy queue.
    std::shared_lock<std::shared_mutex> lkSchedulers(m_muPoolScheduleMutex);
    // Check if the frame copy queue is empty.
    if (!m_qFrameCopySchedule.empty())
    {
        // Start the thread pool to store multiple copies of the sl::Mat into the given cv::Mats.
        this->RunDetachedPool(m_qFrameCopySchedule.size(), m_nNumFrameRetrievalThreads);
        // Wait for thread pool to finish.
        this->JoinPool();
        // Release lock on frame copy queue.
        lkSchedulers.unlock();
    }
}

Here is the call graph for this function:

PooledLinearCode()

void BasicCam::PooledLinearCode ( )

overrideprivatevirtual

This method holds the code that is ran in the thread pool started by the ThreadedLinearCode() method. It copies the data from the different data objects to references of the same type stored in a vector queued up by the Grab methods.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2023-09-16

Reimplemented from BasicCamera.

{
    // Acquire mutex for getting frames out of the queue.
    std::unique_lock<std::shared_mutex> lkFrameQueue(m_muFrameCopyMutex);
    // Check if the queue is empty.
    if (!m_qFrameCopySchedule.empty())
    {
        // Get frame container out of queue.
        containers::FrameFetchContainer<cv::Mat> stContainer = m_qFrameCopySchedule.front();
        // Pop out of queue.
        m_qFrameCopySchedule.pop();
        // Release lock.
        lkFrameQueue.unlock();
 
        // Copy frame to data container.
        *(stContainer.pFrame) = m_cvFrame.clone();
        // Signal future that the frame has been successfully retrieved.
        stContainer.pCopiedFrameStatus->set_value(true);
    }
    else
    {
        // Release lock.
        lkFrameQueue.unlock();
    }
}

Here is the call graph for this function:

---

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

• src/vision/cameras/BasicCam.h
• src/vision/cameras/BasicCam.cpp