From f262a9eb11adada948e3a05939aee5dec2da9715 Mon Sep 17 00:00:00 2001
From: "T. van der Zwan" <zwantvd@gmail.com>
Date: Wed, 21 Aug 2013 14:52:03 +0000
Subject: [PATCH] Updated the scan-algorithm to only use half of each border.
 Added doxygen comments to the header file.

---
 libsrc/hyperion/BlackBorderDetector.cpp | 34 ++++++++++-------------
 libsrc/hyperion/BlackBorderDetector.h   | 37 ++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 23 deletions(-)

diff --git a/libsrc/hyperion/BlackBorderDetector.cpp b/libsrc/hyperion/BlackBorderDetector.cpp
index 5f7ea7fe..f0bcad62 100644
--- a/libsrc/hyperion/BlackBorderDetector.cpp
+++ b/libsrc/hyperion/BlackBorderDetector.cpp
@@ -2,6 +2,7 @@
 
 BlackBorderDetector::BlackBorderDetector()
 {
+	// empty
 }
 
 BlackBorder BlackBorderDetector::process(const RgbImage& image)
@@ -9,7 +10,8 @@ BlackBorder BlackBorderDetector::process(const RgbImage& image)
 	int firstNonBlackPixelTop  = -1;
 	int firstNonBlackPixelLeft = -1;
 
-	for (unsigned x=0; x<image.width(); ++x)
+	// Find the non-black pixel at the top-half border
+	for (unsigned x=0; x<image.width()/2; ++x)
 	{
 		const RgbColor& color = image(x, 0);
 		if (!isBlack(color))
@@ -18,7 +20,8 @@ BlackBorder BlackBorderDetector::process(const RgbImage& image)
 			break;
 		}
 	}
-	for (unsigned y=0; y<image.height(); ++y)
+	// Find the non-black pixel at the left-half border
+	for (unsigned y=0; y<image.height()/2; ++y)
 	{
 		const RgbColor& color = image(0, y);
 		if (!isBlack(color))
@@ -28,6 +31,7 @@ BlackBorder BlackBorderDetector::process(const RgbImage& image)
 		}
 	}
 
+	// Construct 'unknown' result
 	BlackBorder detectedBorder;
 	detectedBorder.type = BlackBorder::unknown;
 
@@ -45,27 +49,23 @@ BlackBorder BlackBorderDetector::process(const RgbImage& image)
 	}
 	else if (firstNonBlackPixelTop < 0)
 	{
-		if (firstNonBlackPixelLeft < 0 || firstNonBlackPixelLeft > (int)(image.height()/2) )
+		if (firstNonBlackPixelLeft < 0)
 		{
 			// We don't know
-			// B-B-B-B ... B-B-B-B
-			// B +---- ... ----- ?
+			// B-B-B-B ...
+			// B +---- ...
 			// B |
 			// B |
 			// :
-			// B |
-			// B |
-			// B |
-			// B ?
 
 			detectedBorder.type = BlackBorder::unknown;
 			detectedBorder.size = -1;
 		}
-		else //(firstNonBlackPixelLeft > 0 && firstNonBlackPixelLeft < image.height()/2)
+		else //(firstNonBlackPixelLeft > 0)
 		{
 			// Border at top of screen
-			// B-B-B-B ... B-B-B-B
-			// B +---- ... ----- ?
+			// B-B-B-B ...
+			// B +---- ...
 			// C |
 			// ? |
 			// :
@@ -76,23 +76,19 @@ BlackBorder BlackBorderDetector::process(const RgbImage& image)
 	}
 	else // (firstNonBlackPixelTop > 0)
 	{
-		if (firstNonBlackPixelTop < int(image.width()/2) && firstNonBlackPixelLeft < 0)
+		if (firstNonBlackPixelLeft < 0)
 		{
 			// Border at left of screen
 			// B-B-C-? ...
-			// B +---- ... ----- ?
+			// B +---- ...
 			// B |
 			// B |
 			// :
-			// B |
-			// B |
-			// B |
-			// B ?
 
 			detectedBorder.type = BlackBorder::vertical;
 			detectedBorder.size = firstNonBlackPixelTop;
 		}
-		else //(firstNonBlackPixelTop > int(mage.width()/2) || firstNonBlackPixelLeft > 0)
+		else //(firstNonBlackPixelLeft > 0)
 		{
 			// No black border
 			// B-B-C-? ...
diff --git a/libsrc/hyperion/BlackBorderDetector.h b/libsrc/hyperion/BlackBorderDetector.h
index 1ca1ac09..ebd4bccd 100644
--- a/libsrc/hyperion/BlackBorderDetector.h
+++ b/libsrc/hyperion/BlackBorderDetector.h
@@ -4,8 +4,14 @@
 // Utils includes
 #include <utils/RgbImage.h>
 
+///
+/// Result structure of the detected blackborder.
+///
 struct BlackBorder
 {
+	///
+	/// Enumeration of the possible types of detected borders
+	///
 	enum Type
 	{
 		none,
@@ -14,25 +20,48 @@ struct BlackBorder
 		unknown
 	};
 
+	/// The type of detected border
 	Type type;
-	int size;
 
+	/// The size of detected border (negative if not applicable)
+	int size;
 };
 
+///
+/// The BlackBorderDetector performs detection of black-borders on a single image.
+/// The detector will scan the border of the upper-left quadrant of an image. Based on detected
+/// black pixels it will give an estimate of the black-border.
+///
 class BlackBorderDetector
 {
 public:
+	///
+	/// Constructs a black-border detector
+	///
 	BlackBorderDetector();
 
+	///
+	/// Performs the actual black-border detection on the given image
+	///
+	/// @param[in] image  The image on which detection is performed
+	///
+	/// @return The detected (or not detected) black border info
+	///
 	BlackBorder process(const RgbImage& image);
 
-
 private:
 
+	///
+	/// Checks if a given color is considered black and therefor could be part of the border.
+	///
+	/// @param[in] color  The color to check
+	///
+	/// @return True if the color is considered black else false
+	///
 	inline bool isBlack(const RgbColor& color)
 	{
+		// Return the simple compare of the color against black
 		return RgbColor::BLACK == color;
+		// TODO[TvdZ]: We could add a threshold to check that the color is close to black
 	}
-
-
 };