Code documentation image proc

DlibLipsPredictor/dlibPredictor.py

@@ -1,6 +1,9 @@
 import cv2
 
-
+# ----------------------------------------------------------------------------
+# function used to detect faces in the frame and extract mouth ROI points
+# input: single Frame, Dlib Detector, Dlib Predictor
+# output: Frame, Mouth ROI points, Face Coords (x,y,h,w)
 def lipDetection(frame, detector, predictor):
     gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
     faces = detector(gray)

DlibLipsPredictor/mouthRegionExtraction.py

@@ -36,7 +36,8 @@ def mouthRegionExtraction(inputFrame, mouthRoi, faceCoords):
     mouthPart = cv2.resize(mouthPart, (150, 100))
     return inputFrame, mouthPart
 
-
+# ----------------------------------------------------------------------------
+# Main
 if "__main__" == __name__:
     videoPath = "../Prototype-Test-Videos/Adverb_1.mp4"
     frames, status = getVideoFrames(videoPath)

FunctionLevelLipsDetection/FunctionLevelLauncher.py

@@ -6,7 +6,10 @@
 from SkinExtraction import extractSkin, segmentSkin
 from SuportFunctions import resizeImage, smoothImg, binaryImage, getVideoFrames, readFrame
 
-
+# ----------------------------------------------------------------------------
+# Function used to call all module in order
+# input: Single Frame
+# output: Mouth ROI, Status (True: Success, False: Failure)
 def getMouth(img):
     resized = resizeImage(img)
     # smooth image to remove noise
@@ -37,6 +40,8 @@ def getMouth(img):
         return mouth_region, True
 
 
+# ----------------------------------------------------------------------------
+# Main
 if "__main__" == __name__:
     videoPath = "../Prototype-Test-Videos/Adverb_1.mp4"
     frames, status = getVideoFrames(videoPath)

FunctionLevelLipsDetection/LipsBoundry.py

@@ -5,6 +5,9 @@
 
 
 # ----------------------------------------------------------------------------
+# function used to extract Mouth ROI from Face Boundries
+# input: Single Frame, Face Coords (y, y+h, x, x+w)
+# output: frame with box drown, coord of box
 def extractMouthArea(img, y0, y1, x0, x1):
     N = y1 - y0
     M = x1 - x0
@@ -17,6 +20,9 @@ def extractMouthArea(img, y0, y1, x0, x1):
 
 
 # ----------------------------------------------------------------------------
+# function used to extract mouth skin mask from Mouth ROI
+# input: Mouth ROI (image)
+# output: Mouth skin mask
 def mouthExtraction(img):
     img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
     R = img[:, :, 0]
@@ -28,12 +34,18 @@ def mouthExtraction(img):
 
 
 # ----------------------------------------------------------------------------
+# function used to draw mouth contours according to the skin mask (testing use only)
+# input: skin mask
+# output: skin mask with box drown around mouth 
 def drawMouthContour(img):
     contours, hierarchy = cv2.findContours(img, cv2.RETR_TREE, cv2.CHAIN_APPROX_NONE)
     cv2.drawContours(img, contours, -1, (0, 255, 0), 3)
 
 
 # ----------------------------------------------------------------------------
+# function used to draw box around mouth in the original Frame
+# input: Single frame, boundry_boxes list (contain coords: x, y, h, w)
+# output: Exact mouth ROI
 def draw_RGB_with_Rect2(RGB_image, Boundary_boxes, cp):
     ret, thresh = cv2.threshold(cp, 127, 255, 0)
     contours, hierarchy = cv2.findContours(thresh, cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE)

HaarCascadeLipsDetector/FramesManipulations.py

@@ -13,7 +13,7 @@ def resizeImage(img, dim=(650, 650)):
 # ----------------------------------------------------------------------------
 # function used to extract frames from video
 # input: video
-# output: frames
+# output: frames, Status
 def getVideoFrames(videoPath):
     """Function to return a video's frames in a list
     :type videoPath: String

HaarCascadeLipsDetector/HaarCascadeLuncher.py

@@ -2,6 +2,8 @@
 from FramesManipulations import getVideoFrames
 from HaarDetector import extractLipsHaarCascade
 
+# ----------------------------------------------------------------------------
+# Main
 if "__main__" == __name__:
     faceCascade = cv2.CascadeClassifier("haarcascade_frontalface_default.xml")
     videoPath = "../Prototype-Test-Videos/Colors_2.mp4"

HaarCascadeLipsDetector/HaarDetector.py

@@ -1,6 +1,9 @@
 import cv2
 
-
+# ----------------------------------------------------------------------------
+# function used to extract Face, Mouth ROI from frame 
+# input: Haar Cascade Detector, Single Frame
+# output: Mouth ROI, Status (True: Success, False: Failure)
 def extractLipsHaarCascade(haarDetector, frame):
     """Function to extract lips from a frame"""
     gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)

PixelLevelLipsDetection/FR.py

@@ -1,7 +1,7 @@
 import cv2
 import numpy as np
 
-
+# ----------------------------------------------------------------------------
 # function used to read a frame from file
 # input: none
 # output: image
@@ -10,7 +10,7 @@ def readFrame():
     cv2.imshow('img', img)
     return img
 
-
+# ----------------------------------------------------------------------------
 # function used to smooth from image
 # input: image
 # output: image
@@ -19,7 +19,7 @@ def smoothImg(img):
     cv2.imshow('blur', blur)
     return blur
 
-
+# ----------------------------------------------------------------------------
 # function used to resize image
 # input: image, dim = (x,y)
 # output: image
@@ -39,7 +39,7 @@ def binaryImage(img):
     return binary_image
 
 
-# -----------------------------------------------------------------------------------------
+# ----------------------------------------------------------------------------
 # function that add padding to an image
 # input: image, padding, kernal, operation type
 # output: image
@@ -94,7 +94,7 @@ def operation(image, kernel, padding=0, operation=None):
 # -----------------------------------------------------------------------------------------
 # function that extract frames from video
 # input: video path
-# output: List Of Images
+# output: List Of Images, status
 def getVideoFrames(videoPath):
     """Function to return a video's frames in a list
     :type videoPath: String

PixelLevelLipsDetection/FaceDetection.py

@@ -4,8 +4,8 @@
 
 # ----------------------------------------------------------------------------
 # function used to get box of the face from image
-# input: image
-# output: image
+# input: skin mask, single frame
+# output: bounding boxes list, skin image
 def get_box(img, RGB_img):
     bounding_boxes = []
     masks = np.zeros(img.shape).astype("uint8")
@@ -51,7 +51,10 @@ def get_box(img, RGB_img):
         cv2.waitKey(0)
         return bounding_boxes, img
 
-
+# ----------------------------------------------------------------------------
+# function used to draw face bounding box on frame
+# input: single frame, bounding boxes list, cut place (mask)
+# output: frame with box drawn around face, face bounding coords (y, y+h, x, x+w)
 def draw_RGB_with_Rect(RGB_image, Boundary_boxes, cp):
     ret, thresh = cv2.threshold(cp, 127, 255, 0)
     contours, hierarchy = cv2.findContours(thresh, cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE)

PixelLevelLipsDetection/PixelLevelLauncher.py

@@ -5,6 +5,9 @@
 from SkinSegmentation import segmentSkin, extractSkin
 from mouthDetection import extractMouthArea
 
+# -----------------------------------------------------------------------------------------
+# Main
+# -----------------------------------------------------------------------------------------
 # frames reading
 # function that calls (FR.py) functions that is used to inquire a filter cleared image of frame (preprossesing)
 img = readFrame()

PixelLevelLipsDetection/canny.py

@@ -4,7 +4,10 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-
+# -----------------------------------------------------------------------------------------
+# function that preform second degree convolution (2nd order) 
+# input: image, kernal, average status (True: output values are averged), Verbose (True: to observe output in each step [Testing use only (Removed)])
+# output: convoluved image with kernel
 def convolution(image, kernel, average=False, verbose=False):
     if len(image.shape) == 3:
         image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
@@ -28,11 +31,17 @@ def convolution(image, kernel, average=False, verbose=False):
                 output[row, col] /= kernel.shape[0] * kernel.shape[1]
     return output
 
-
+# -----------------------------------------------------------------------------------------
+# function that normalize kernel valuse according to sigma 
+# input: kernel single value, mu (always zero), sigma
+# output: normalized value 
 def dnorm(x, mu, sd):
     return 1 / (np.sqrt(2 * np.pi) * sd) * np.e ** (-np.power((x - mu) / sd, 2) / 2)
 
-
+# -----------------------------------------------------------------------------------------
+# function that applies gaussian blur (averaging) on kernel 
+# input: size of kernel, sigma used for normalizing, Verbose (True: to observe output in each step [Testing use only (Removed)])
+# output: kernel used in the convolution with the image (2D kernel)
 def gaussian_kernel(size, sigma=1, verbose=False):
     kernel_1D = np.linspace(-(size // 2), size // 2, size)
     for i in range(size):
@@ -43,17 +52,26 @@ def gaussian_kernel(size, sigma=1, verbose=False):
 
     return kernel_2D
 
-
+# -----------------------------------------------------------------------------------------
+# function that applies calls gaussian_kernel to create a kernel and then apply the convolution on the image using the created kernel
+# input: image, kernel size (int value), Verbose (True: to observe output in each step [Testing use only (Removed)])
+# output: convoloved image
 def gaussian_blur1(image, kernel_size, verbose=False):
     kernel = gaussian_kernel(kernel_size, sigma=int(math.sqrt(kernel_size)), verbose=verbose)
     return convolution(image, kernel, average=True, verbose=verbose)
 
-
+# -----------------------------------------------------------------------------------------
+# function that applies calls gaussian_kernel to create a kernel and then apply the convolution on the image using the created kernel
+# input: image, kernel size (int value), Verbose (True: to observe output in each step [Testing use only (Removed)])
+# output: convoloved image
 def gaussian_blur2(image, kernel_size, stig, verbose=False):
     kernel = gaussian_kernel(kernel_size, sigma=int(math.sqrt(kernel_size)), verbose=verbose)
     return convolution(image, kernel, average=True, verbose=verbose)
 
-
+# -----------------------------------------------------------------------------------------
+# function that applies Sobel edge detection on image
+# input: image, kernel, convert_to_degree (True: to shift gradiant direction output of sobel to degrees), Verbose (True: to observe output in each step [Testing use only (Removed)])
+# output: gradient_magnitude of image (edges), gradient_direction of image (edges direction)
 def sobel_edge_detection(image, filt, convert_to_degree=False, verbose=False):
     new_image_x = convolution(image, filt, verbose)
 
@@ -87,7 +105,10 @@ def sobel_edge_detection(image, filt, convert_to_degree=False, verbose=False):
     return gradient_magnitude, gradient_direction
 
 
-# ------------------------------------------------------------------------
+# -----------------------------------------------------------------------------------------
+# function that is used to thin out the edges
+# input: gradient_magnitude of image (edges), gradient_direction of image (edges direction), Verbose (True: to observe output in each step [Testing use only])
+# output: thined edges
 def non_max_suppression(gradient_magnitude, gradient_direction, verbose):
     image_row, image_col = gradient_magnitude.shape
 
@@ -126,7 +147,10 @@ def non_max_suppression(gradient_magnitude, gradient_direction, verbose):
 
     return output
 
-
+# -----------------------------------------------------------------------------------------
+# function that is used to filter out edge pixels with a weak gradient value and preserve edge pixels with a high gradient value
+# input: image, low threshold bound value, high threshold bound value, weak value (for weak edges below low threshold), Verbose (True: to observe output in each step [Testing use only])
+# output: image thresholded
 def threshold(image, low, high, weak, verbose=False):
     output = np.zeros(image.shape)
 
@@ -145,7 +169,10 @@ def threshold(image, low, high, weak, verbose=False):
 
     return output
 
-
+# -----------------------------------------------------------------------------------------
+# function that is used to remove the weak edges caused by the latter reasons
+# input: image, weak value
+# output: final image after removing weak edges
 def hysteresis(image, weak):
     image_row, image_col = image.shape
 
@@ -212,7 +239,10 @@ def hysteresis(image, weak):
 
     return final_image
 
-
+# -----------------------------------------------------------------------------------------
+# function that is used to to extract gray image from original image
+# input: original image
+# output: gray image
 def getGrayImage(img):
     B = img[:, :, 0]
     G = img[:, :, 1]
@@ -221,7 +251,10 @@ def getGrayImage(img):
     gray = np.array(gray, dtype=np.uint8)
     return gray
 
-
+# -----------------------------------------------------------------------------------------
+# function that applies canny edge detection functions in order
+# input: image, lower bound threshold, upper bound threshold
+# output: gradient_magnitude (edges)
 def cannyDetection(img, CANNY_THRESH_1, CANNY_THRESH_2):
     blurred_image = gaussian_blur1(img, kernel_size=9, verbose=False)
     filt1 = np.array([[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]])

PixelLevelLipsDetection/colorspace.py

@@ -1,13 +1,19 @@
 import numpy as np
 
-
+# -----------------------------------------------------------------------------------------
+# function that is used to extract R, G, B channels of image
+# input: image
+# output: R, G, B Channels
 def extractBGRChannels(img):
     B = img[:, :, 0]
     G = img[:, :, 1]
     R = img[:, :, 2]
     return R, G, B
 
-
+# -----------------------------------------------------------------------------------------
+# function that is used to extract h, s, v values from r, g, b
+# input: R, G, B values
+# output: h, s, v values
 def rgb_to_hsv(r, g, b):
     r, g, b = r / 255.0, g / 255.0, b / 255.0
     mx = max(r, g, b)
@@ -28,7 +34,10 @@ def rgb_to_hsv(r, g, b):
     v = mx * 100
     return h, s, v
 
-
+# -----------------------------------------------------------------------------------------
+# function that is used to extract H, S, V channels from R, G, B
+# input: R, G, B Channels
+# output: H, S, V Channels
 def getHSV(img):
     R, G, B = extractBGRChannels(img)
     H = np.zeros((R.shape[0], R.shape[1]))

PixelLevelLipsDetection/mouthDetection.py

@@ -1,6 +1,9 @@
 import cv2
 
-
+# -----------------------------------------------------------------------------------------
+# function that is used to draw boxes around mouth ROI (extract mouth ROI) from face coords
+# input: single frame, face bounding coords (y, y+h, x, x+w)
+# output: frame with box drawn around face and another box drawn around mouth ROI
 def extractMouthArea(img, y0, y1, x0, x1):
     N = y1 - y0
     M = x1 - x0

RGBFilterLipsDetection/GaborLauncher.py

@@ -5,7 +5,10 @@
 from SkinModel import getSkin
 from SkinRegion import extractSkinRegions
 
-
+# ----------------------------------------------------------------------------
+# function used to call algorithm functions to extract mouth ROI
+# input: Single frame
+# output: Mouth ROI, Status
 def startProcess(img):
     # -----------------------------------------------
     # img = readFrame()
@@ -25,7 +28,8 @@ def startProcess(img):
         return mouthROI, True
 
 
-# -----------------------------------------------
+# ----------------------------------------------------------------------------
+# Main
 if __name__ == "__main__":
     startTime = time.time()
     videoPath = "../Prototype-Test-Videos/Colors_2.mp4"

RGBFilterLipsDetection/GaborSupportFunctions.py

@@ -64,7 +64,9 @@ def binaryImage2(img):
 
 
 # ----------------------------------------------------------------------------
-# dev
+# function used to read single image from file (testing use only)
+# input: None
+# output: Image
 def readFrame():
     img = cv2.imread('DataSet-Trial/face3.jpg')
     return img

RGBFilterLipsDetection/MouthModel.py

@@ -1,3 +1,7 @@
+# ----------------------------------------------------------------------------
+# function used to extract mouth ROI from image using face coords
+# input: Single frame, Face coords (y, y+h, x, x+w)
+# output: Mouth ROI
 def extractMouthROI(img, y0, y1, x0, x1):
     N = y1 - y0
     M = x1 - x0