add doxygen comments

src/lib/Irregularity.h

@@ -8,6 +8,7 @@ using std::string;
 using json = nlohmann::json;
 
 /**
+ * @class Irregularity
  * @brief an irregularity of the tape detected by the system
  * 
  */

src/lib/IrregularityFile.h

@@ -6,6 +6,11 @@
 
 using json = nlohmann::json;
 
+/**
+ * @class IrregularityFile
+ * @brief An IrregularityFile is a collection of Irregularities detected on a tape.
+ * 
+ */
 class IrregularityFile
 {
 private:

src/lib/colors.h

+/**
+ * @file colors.h
+ * @author Matteo Spanio (dev2@audioinnova.com)
+ * @brief Header file containing a set of ANSI escape codes to print colored text in the terminal.
+ * @version 1.0
+ * @date 2023-05-13
+ * 
+ * @copyright Copyright (c) 2023
+ * 
+ */
+
+#ifndef COLORS_H
+#define COLORS_H
 #include <stdlib.h>
 #include <string>
 
@@ -12,4 +25,5 @@ string YELLOW = "\033[93m";
 string RED = "\033[91m";
 string BOLD = "\033[1m";
 string UNDERLINE = "\033[4m";
-string END = "\033[0m";
\ No newline at end of file
+string END = "\033[0m";
+#endif // COLORS_H
\ No newline at end of file

src/lib/enums.h

+/**
+ * @file enums.h
+ * @author Matteo Spanio (dev2@audioinnova.com)
+ * @brief A collection of enums and functions to handle them.
+ * @version 1.0
+ * @date 2023-05-13
+ * 
+ * @copyright Copyright (c) 2023
+ * 
+ * This file contains a set of enums to define properties of an Irregularity.
+ * The enums are:
+ * - Source: the source of the Irregularity (Audio, Video or Both)
+ * - IrregularityType: the type of Irregularity (Brands on tape, Splice, etc.) that can be present on the tape.
+ * 
+ * The file also contains functions to convert from enum to string and viceversa (useful when saving the Irregularity to a file).
+ * 
+ */
+#ifndef ENUMS_H
+#define ENUMS_H
 #include<string>
 
+/**
+ * @enum Source
+ * @brief The source of the Irregularity (Audio, Video or Both)
+ * 
+ * An Irregularity can be detected by the Audio analyser, the Video analyser or both.
+ * 
+ */
 enum Source{
     Audio,
     Video,
     Both
 };
 
+/**
+ * @enum IrregularityType
+ * @brief The type of Irregularity (Brands on tape, Splice, etc.) that can be present on the tape.
+ * 
+ * The types of Irregularities are:
+ * - BRANDS_ON_TAPE: Brands on tape
+ * - SPLICE: Splice
+ * - START_OF_TAPE: Start of tape
+ * - ENDS_OF_TAPE: End of tape
+ * - DAMAGED_TAPE: Damaged tape
+ * - DIRT: Dirt
+ * - MARKS: Marks
+ * - SHADOWS: Shadows
+ * - WOW_AND_FLUTTER: Wow and flutter
+ * - PLAY_PAUSE_STOP: Play, pause, stop
+ * - SPEED: Speed
+ * - EQUALIZATION: Equalization
+ * - SPEED_AND_EQUALIZATION: Speed and equalization
+ * - BACKWARD: Backward
+ * 
+ * @note Speed, Equalization and Speed and equalization are detected only by the Audio analyser,
+ * while the other Irregularities are detected only by the Video analyser.
+ * 
+ */
 enum IrregularityType {
     BRANDS_ON_TAPE,
     SPLICE,
@@ -27,3 +77,4 @@ std::string sourceToString(Source source);
 Source sourceFromString(std::string source);
 std::string irregularityTypeToString(IrregularityType type);
 IrregularityType irregularityTypeFromString(std::string type);
+#endif // ENUMS_H
\ No newline at end of file

src/lib/files.h

+/**
+ * @file files.h
+ * @author Matteo Spanio (dev2@audioinnova.com)
+ * @brief A collection of functions to handle files.
+ * @version 1.0
+ * @date 2023-05-13
+ * 
+ * @copyright Copyright (c) 2023
+ * 
+ */
+
+#ifndef FILES_H
+#define FILES_H
 #include <filesystem>
 #include <fstream>
 #include <string>
 #include <iostream>
 #include <stdlib.h>
 
+/**
+ * @namespace files
+ * @brief A collection of functions to handle files.
+ * 
+ */
 namespace files {
     /**
+     * @fn void saveFile(std::filesystem::path fileName, std::string content, bool append)
      * @brief Save content to a file
      * 
      * @param fileName the name of the file
@@ -15,6 +34,7 @@ namespace files {
     void saveFile(std::filesystem::path fileName, std::string content, bool append);
 
     /**
+     * @fn void findFileNameFromPath(std::string* path, std::string* fileName, std::string* extension)
      * @brief Separates video file name from its extension.
      *
      * @param[in] path Full video path;
@@ -24,6 +44,7 @@ namespace files {
     void findFileNameFromPath(std::string* path, std::string* fileName, std::string* extension);
 
     /**
+     * @fn int findFileName(std::string videoPath, std::string &fileName, std::string &extension)
      * @brief Check if the specified input video file exists and is supported.
      *
      * @param[in] videoPath Full video path;
@@ -32,4 +53,5 @@ namespace files {
      * @return int -1 if the format is not supported, 0 otherwise.
      */
     int findFileName(std::string videoPath, std::string &fileName, std::string &extension);
-}
\ No newline at end of file
+}
+#endif // FILES_H
\ No newline at end of file

src/lib/time.cpp

 #include "time.h"
 
-/**
- * @brief Convert an int representing milliseconds to the corresponding Time Label string.
- *
- * @param ms the number of milliseconds.
- * @param delim the time separator
- * @return string the corresponding Time Label string.
- */
 std::string getTimeLabel(int ms, std::string delim) {
 
 	int mil = ms % 1000;

src/lib/time.h

@@ -4,6 +4,14 @@
 #include <stdlib.h>
 #include <string>
 
+/**
+ * @fn std::string getTimeLabel(int ms, std::string delim = ":")
+ * @brief Convert an int representing milliseconds to the corresponding Time Label string.
+ *
+ * @param ms the number of milliseconds.
+ * @param delim the time separator
+ * @return string the corresponding Time Label string.
+ */
 std::string getTimeLabel(int ms, std::string delim = ":");
 
 #endif
\ No newline at end of file

src/main.cpp

 /**
+ * @file main.cpp
  *  MPAI CAE-ARP Video Analyser.
  *
  *	Implements MPAI CAE-ARP Video Analyser Technical Specification.
@@ -114,6 +115,7 @@ double rotatedRectArea(RotatedRect rect) {
 }
 
 /**
+ * @fn void pprint(string text, string color)
  * @brief Prints a text in a given color.
  * 
  * @param text
@@ -124,6 +126,7 @@ void pprint(string text, string color) {
 }
 
 /**
+ * @fn bool getArguments(int argc, char** argv)
  * @brief Get operation arguments from command line or config.json file.
  *
  * @param argc Command line arguments count;
@@ -209,6 +212,7 @@ bool getArguments(int argc, char** argv) {
 
 
 /**
+ * @fn std::tuple<int, int, double, double, vector<Vec4f>, vector<Vec4f>> findObject(Mat model, SceneObject object)
  * @brief Find the model in the scene using the Generalized Hough Transform. It returns the best matches.
  * Find the best matches for positive and negative angles.
  * If there are more than one shapes, then choose the one with the highest score.
@@ -270,6 +274,7 @@ std::tuple<int, int, double, double, vector<Vec4f>, vector<Vec4f>> findObject(Ma
 }
 
 /**
+ * @fn bool findProcessingAreas(Mat myFrame)
  * @brief Identifies the Regions Of Interest (ROIs) on the video,
  * which are:
  * - The reading head;
@@ -445,6 +450,13 @@ bool findProcessingAreas(Mat myFrame) {
 	return true;
 }
 
+/**
+ * @fn RotatedRect check_skew(RotatedRect roi)
+ * @brief Check if the region of interest is skewed and correct it
+ * 
+ * @param roi the region of interest
+ * @return RotatedRect the corrected region of interest
+ */
 RotatedRect check_skew(RotatedRect roi) {
 	// get angle and size from the bounding box
 	// thanks to http://felix.abecassis.me/2011/10/opencv-rotation-deskewing/
@@ -460,6 +472,7 @@ RotatedRect check_skew(RotatedRect roi) {
 }
 
 /**
+ * @fn Frame get_difference_for_roi(Frame previous, Frame current, RotatedRect roi)
  * @brief Look for differences in two consecutive frames in a specific region of interest
  * 
  * @param previous the reference frame
@@ -479,6 +492,7 @@ Frame get_difference_for_roi(Frame previous, Frame current, RotatedRect roi) {
 }
 
 /**
+ * @fn bool frameDifference(cv::Mat prevFrame, cv::Mat currentFrame, int msToEnd)
  * @brief Compares two consecutive video frames and establish if there potentially is an Irregularity.
  * The comparison is pixel-wise and based on threshold values set on config.json file.
  *
@@ -489,6 +503,7 @@ Frame get_difference_for_roi(Frame previous, Frame current, RotatedRect roi) {
  * @return false otherwise.
  */
 bool frameDifference(cv::Mat prevFrame, cv::Mat currentFrame, int msToEnd) {
+	bool result = false;
 
 	/********************************** Capstan analysis *****************************************/
 
@@ -559,13 +574,11 @@ bool frameDifference(cv::Mat prevFrame, cv::Mat currentFrame, int msToEnd) {
 
 	/************************************* Decision stage ****************************************/
 
-	bool isIrregularity = false;
-
 	if (blackPixels > tapeDifferentPixelsThreshold) { // The threshold must be passed
 
 		/***** AVERAGE_COLOR-BASED DECISION *****/
 		if (mediaPrevFrame > (mediaCurrFrame + 7) || mediaPrevFrame < (mediaCurrFrame - 7)) { // They are not similar for color average
-			isIrregularity = true;
+			result = true;
 		}
 
 		/***** BRANDS MANAGEMENT *****/
@@ -576,7 +589,7 @@ bool frameDifference(cv::Mat prevFrame, cv::Mat currentFrame, int msToEnd) {
 				if (firstInstant - msToEnd > 5000) {
 					firstBrand = false;
 					savingBrand = true;
-					isIrregularity = true;
+					result = true;
 				}
 			// In the following iterations reset savingBrand, since we are no longer interested in brands.
 			} else
@@ -588,11 +601,12 @@ bool frameDifference(cv::Mat prevFrame, cv::Mat currentFrame, int msToEnd) {
 	// Update mediaPrevFrame
 	mediaPrevFrame = mediaCurrFrame;
 
-	return isIrregularity;
+	return result;
 }
 
 
 /**
+ * @fn void processing(cv::VideoCapture videoCapture)
  * @brief video processing phase, where each frame is analysed.
  * It saves the IrregularityImages and updates the IrregularityFiles if an Irregularity is found
  *
@@ -711,6 +725,7 @@ void processing(cv::VideoCapture videoCapture) {
 
 
 /**
+ * @fn int main(int argc, char** argv)
  * @brief main program, organised as:
  * - Get input from command line or config.json file;
  * - Check input parameters;

src/utility.h

@@ -7,9 +7,15 @@ using namespace cv;
 using namespace std;
 namespace fs = std::filesystem;
 
+/**
+ * @brief Namespace containing a set of utility functions used in the project.
+ * The functions are mainly used to perform operations on images.
+ * 
+ */
 namespace utility {
 
 	/**
+	 * @class Frame
 	 * @brief Class that extends the OpenCV Mat class, adding some useful methods frequently used in the project.
 	 * 
 	 */
@@ -30,6 +36,7 @@ namespace utility {
 
 
 	/**
+	 * @fn void detectShape(Ptr<GeneralizedHoughGuil> alg, Mat templateShape, int posThresh, vector<Vec4f> &positivePositions, Mat &positiveVotes, vector<Vec4f> &negativePositions, Mat &negativeVotes, Mat processingArea)
 	 * @brief Detects a given shape in an image, using a the OpenCV algorithm GeneralizedHoughGuil.
 	 *
 	 * @param[in] alg the algorithm instance;
@@ -44,6 +51,7 @@ namespace utility {
 	void detectShape(Ptr<GeneralizedHoughGuil> alg, Mat templateShape, int posThresh, vector<Vec4f> &positivePositions, Mat &positiveVotes, vector<Vec4f> &negativePositions, Mat &negativeVotes, Mat processingArea);
 
 	/**
+	 * @fn RotatedRect drawShapes(Mat frame, Vec4f &positions, Scalar color, int width, int height, int offsetX, int offsetY, float processingScale)
 	 * @brief Draw rectangles on an image.
 	 *
 	 * @param frame Frame on which the rectangles will be drawn;
@@ -60,6 +68,7 @@ namespace utility {
 
 
 	/**
+	 * @fn void separateFrame(cv::Mat frame, cv::Mat &odd_frame, cv::Mat &even_frame)
 	 * @brief Function to deinterlace the current image.
 	 *
 	 * @param[in] frame image to be processed;
@@ -70,6 +79,7 @@ namespace utility {
 
 
 	/**
+	 * @fn void separateFrame(cv::Mat frame, cv::Mat &odd_frame, cv::Mat &even_frame)
 	 * @brief Compute the number of different pixels between two frames.
 	 *
 	 * @param prevFrame the first frame;