Merge pull request #35 from albanjoseph/docs-update

Docs update, #11

.github/workflows/cmake_build.yml

@@ -2,9 +2,9 @@ name: Build and Test
 
 on:
   push:
-    branches: [ dev ]
+    branches: [ dev main docs-update]
   pull_request:
-    branches: [ dev ]
+    branches: [ dev main]
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)

.github/workflows/docs.yml

@@ -6,9 +6,9 @@ name: Docs
 # events but only for the master branch
 on:
   push:
-    branches: [ dev ]
+    branches: [ dev docs-update]
   pull_request:
-    branches: [ dev ]
+    branches: [ dev main]
 
 
 

dconfig

@@ -963,7 +963,7 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE =  src/MultiThreadedSchedulableLink.* src/BatchCNNProcessor.* src/NThreadedCNNProcessor.*
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

src/BlockingQueue.cpp

@@ -2,7 +2,11 @@
 // Blocking queue implementation, currently only blocks when Get is attempted while there are no elements inside the queue. In the future and max size could be defined and blocking could be added when the queue is full
 //
 #include "BlockingQueue.h"
-
+/*!
+ * Pop method, uses mutex lock to sleep the current thread until data are available on the queue. This may be used to synchonise and schedule threads.
+ * @tparam T
+ * @return Element on deque back
+ */
 template <typename T>
 T BlockingQueue<T>::Pop() {
     std::unique_lock<std::mutex> lock(mutex);
@@ -11,17 +15,31 @@ T BlockingQueue<T>::Pop() {
     internalQueue.pop_back();
     return ret;
 }
-
+/*!
+ *
+ * @tparam T
+ * @return true if internal queue empty, false otherwise
+ */
 template <typename T>
 bool BlockingQueue<T>::IsEmpty(){
     return internalQueue.empty();
 }
 
+/*!
+ * Gets the current length of elements in the queue.
+ * @tparam T
+ * @return size of internal deque
+ */
 template <typename T>
 int BlockingQueue<T>::Size(){
     return internalQueue.size();
 }
 
+/*!
+  * adds element to the queue.
+  * @tparam T
+  * @param toPush
+  */
 template <typename T>
 void BlockingQueue<T>::Push(T toPush) {
     {

src/BlockingQueue.h

@@ -15,6 +15,11 @@ template <typename T>
 /*!
     
 */
+
+/*!
+ * Class to wrap around std::deque and block thread execution when no data is available at the output.
+ * @tparam T Type of elements in the queue
+ */
 class BlockingQueue {
 public:
     void Push(T toPush);

src/CNNProcessor.cpp

@@ -1,5 +1,9 @@
 #include "CNNProcessor.h"
 
+/*!
+ * Loads neural network from location on disk
+ * @param modelPath
+ */
 void CNNProcessor::LoadModel(std::string modelPath){
     net = cv::dnn::readNetFromTensorflow(modelPath);
 }
@@ -9,6 +13,11 @@ CNNProcessor::CNNProcessor(CNNProcessorSettings* s) {
     LoadModel(settings->ModelPath);
 }
 
+/*!
+ * Makes OpenCV image "blob" from the region of interest in the frame. Blob format is required for inference.
+ * @param scene
+ * @return matrix image blob, ready for inference
+ */
 cv::Mat CNNProcessor::MakeBlob(Scene scene){
     int x  = scene.regionOfInterest.UpperLeft.x; int y = scene.regionOfInterest.UpperLeft.y;
     int width = scene.regionOfInterest.LowerRight.x - x;
@@ -21,6 +30,11 @@ cv::Mat CNNProcessor::MakeBlob(Scene scene){
     return blob;
 }
 
+/*!
+ * Executed network inference on given scene, populates the scene with results.
+ * @param scene input scene
+ * @return output processed scene
+ */
 Scene CNNProcessor::ProcessScene(Scene scene){
     if(scene.frame.empty()) return scene;
     cv::Mat blob = MakeBlob(scene);
@@ -34,11 +48,4 @@ Scene CNNProcessor::ProcessScene(Scene scene){
     return scene;
 }
 
-//void CNNProcessor::NextScene(Scene next) {
-//    Scene updatedFrame = ProcessScene(next);
-//    if(!sceneCallback) return;
-//    sceneCallback->NextScene(updatedFrame);
-//}
-
-
 

src/CNNProcessor.h

@@ -14,10 +14,9 @@
 #include "SignapseUtils.h"
 
 
-//!  CNNProcessor class.
 /*!
-    Class for interfacing with convolutional neural network
-*/
+ * Schedulable Pipeline Link which performs network inference on each Scene, populating the results field.
+ */
 class CNNProcessor : public SchedulableLink{
 public:
     Scene ProcessScene(Scene s);

src/CNNProcessorSettings.h

@@ -5,6 +5,9 @@
 #define MOBNET_V2_INPUT_DIM_Y 224
 #define MOBNET_V2_PATH "models/asl-mobilenetv2.pb"
 
+/*!
+ * A simple struct to store default configurations for CNNProcessor settings.
+ */
 struct CNNProcessorSettings {
     CNNProcessorSettings(std::string network = "mobnetv2"){
         if(network == "mobnetv2") {

src/Camera.cpp

@@ -1,19 +1,32 @@
 #include "Camera.h"
 
+/*!
+ * Camera constructor, sets isOn to true.
+ */
 Camera::Camera() {
     isOn=true;
 }
 
+/*!
+ * Sets the isOn state of the camera
+ * @param state
+ */
 void Camera::setOn(bool state){
     isOn = state;
 }
 
+/*!
+ * Loops while camera is on to add frames to the pipeline
+ */
 void Camera::threadLoop(){
     while(isOn){
         postFrame();
     }
 }
 
+/*!
+ * Gets the next available frame and passes it on to the registered callback. Relies on the videoCapture.read() OpenCV method which is understood to wait for an intra-frame delay.
+ */
 void Camera::postFrame(){
     if(!sceneCallback) return;
     cv::Mat cap;
@@ -28,17 +41,27 @@ void Camera::postFrame(){
     sceneCallback->NextScene(s);
 }
 
+/*!
+ * Starts the worker thread recording
+ */
 void Camera::Start(){
     videoCapture.open(deviceID, apiID);
     cameraThread = std::thread(&Camera::threadLoop, this);
 }
 
+/*!
+ * Frees thread resources and stops recording, must be called prior to program exit.
+ */
 void Camera::Stop(){
     isOn=false;
     cameraThread.join();
 
 }
 
+/*!
+ * Returns the isON state of the camera
+ * @return true if on; false otherwise
+ */
 bool Camera::getOn() {
     return isOn;
 }

src/Camera.h

@@ -8,46 +8,22 @@
 #include "PipelineLink.h"
 
 
-//!  Camera class which inherits from Reel.
 /*!
-    Class for reading web cam data, and creating a Reel of scenes.
-*/
+ * Simple Pipeline element which integrates frame acquisition from the camera feed.
+ */
 class Camera: public PipelineLink{
 public:
-    //! Constructor.
-    /*!
-        Turns the camera object "ON" and configures the video capture.
-    */
     Camera();
     ~Camera();
     bool getOn();
-
     void setOn(bool state);
-
-    //! Member function for starting video capturing thread.
-    /*!
-        Starts "Stream" private member function as a thread.
-    */
     void Start();
     void Stop();
 
-
-
 private:
     void postFrame();
-
     void threadLoop();
-
-    //! Private member object.
-    /*!
-        OpenCV object for reading web cam data.
-    */
     cv::VideoCapture videoCapture;
-    //! Private member variable containing web cam device ID.
-    /*!
-        0 = open default camera
-        
-    */
     int deviceID = 0;
     //! Private member variable containing web cam API ID.
     /*!

src/Gui.cpp

@@ -3,6 +3,11 @@
 #define UI_WDH 1000
 #define UI_HGT 700
 
+/*!
+ * Constructor sets up GUI, makes signal connections
+ * @param win points to QMainWindow from main thread
+ * @param ui_win points to Ui_MainWindow from main thread
+ */
 Gui::Gui(QMainWindow* win, Ui_MainWindow* ui_win) {
     widget = win;
     widget->setFixedSize(UI_WDH, UI_HGT);
@@ -11,7 +16,10 @@ Gui::Gui(QMainWindow* win, Ui_MainWindow* ui_win) {
     SetTask("A");
     makeConnections();
 }
-
+/*!
+ * Handles the next scene from the video processing pipeline. If the result is empty, the viewing pane is updated, otherwise, the progress bar is updated.
+ * @param next The Scene to be processed
+ */
 void Gui::NextScene(Scene next) {
     //flip frame
     if(next.result == "") {
@@ -28,30 +36,36 @@ void Gui::NextScene(Scene next) {
     }
 
 }
-
+/*!
+ * Sets underlying widget visibility.
+ * @param visible
+ */
 void Gui::SetVisible(bool visible) {
     widget->setVisible(visible);
 }
-
-void Gui::SetTargetImage(int target) {
-    std::string letter = SignapseUtils::getLetterFromDigit(target);
-    SetTargetImage(letter);
-    progressChanged(0);
-}
-
+/*!
+ * Sets the target to match with user sign
+ * @param letter string represenation of the target sign
+ */
 void Gui::SetTargetImage(std::string letter) {
     std::string impath = testFolder + letter + "_test.jpg";
     cv::Mat img = cv::imread(impath);
     setDemoImage(img);
     setTaskText(letter);
 }
+/*!
+ * Method handler for when the next task button is pressed, sets new task and resets the progress bar.
+ */
 void Gui::ButtonPressed(){
-    std::string new_task = SignapseUtils::getLetterFromDigit(SignapseUtils::makeTask());
+    std::string new_task = SignapseUtils::makeTask();
     SetTargetImage(new_task);
     currentTask = new_task;
     progress_bar.reset_progress();
 }
 
+/*!
+ * Makes signal connections for the GUI interrupts.
+ */
 void Gui::makeConnections() {
     QObject::connect(ui->pushButton, &QPushButton::released, this, &Gui::ButtonPressed);
     QObject::connect(this, &Gui::progressChanged, ui->progressBar, &QProgressBar::setValue);

src/Gui.h

@@ -16,7 +16,8 @@
 #define testFolder "test/asl_alphabet_test/"
 
 /*
- * A class to wrap the QT generated header file and handle GUI functionality
+ * A class to wrap the QT generated header file and handle GUI functionality.
+ * Inherits from QWidget and SceneCallback
  */
 class Gui : public QWidget, public SceneCallback{
     Q_OBJECT

src/LinkSplitter.cpp

@@ -1,11 +1,17 @@
 #include "LinkSplitter.h"
 
-
+/*!
+ * Override of NextScene to pass scene reference to a maximum of two registered callbacks
+ * @param s scene
+ */
 void LinkSplitter::NextScene(Scene s) {
     if(sceneCallback) sceneCallback->NextScene(s);
     if(secondarySceneCallback) secondarySceneCallback->NextScene(s);
 }
-
+/*!
+ * Used to register a secondary callback.
+ * @param scb callback to register.
+ */
 void LinkSplitter::RegisterSecondaryCallback(SceneCallback *scb) {
     secondarySceneCallback = scb;
 }

src/LinkSplitter.h

@@ -3,6 +3,10 @@
 
 #include "PipelineLink.h"
 
+/*!
+ * A pipeline element which extends PipelineLink to add a secondary callback. The NextScene function is overridden to pass on the scene reference to both registered callbacks.
+ * N.B. this does not duplicate the scene, merely copies the reference to another element. No extra memory is allocated!
+ */
 class LinkSplitter : public PipelineLink{
 public:
     void NextScene(Scene s);

src/PipelineLink.cpp

@@ -1,9 +1,16 @@
 #include "PipelineLink.h"
 
+/*!
+ * Used to register the next pipeline element.
+ * @param scb reference to the next pipeline element
+ */
 void PipelineLink::RegisterCallback(SceneCallback *scb) {
     sceneCallback = scb;
 }
-
+/*!
+ * Default NextScene implementation, simply passes the scene on to the registered callback
+ * @param scene
+ */
 void PipelineLink::NextScene(Scene scene) {
     if(!sceneCallback) return;
     sceneCallback->NextScene(scene);