added comments and reference

Author: vernwalrahul

src/houghtransform.jl

@@ -103,6 +103,54 @@ threshold::Integer, linesMax::Integer) where T<:Union{Bool,Gray{Bool}}
 
 end
 
+"""
+```
+lines = hough_line_probabilistic(image, ρ, θ, threshold, lineLength, lineGap, linesMax)
+```
+
+Returns lines :
+      vector of lines identified, lines in format ((r0, c0), (r1, c1))
+      indicating line start and end.
+
+The lines are generated by applying hough transform on the image.
+
+Parameters:
+-    `image`       = Image to be transformed (eltype should be `Bool`)
+-    `ρ`           = Discrete step size for perpendicular length of line
+-    `θ`           = List of angles for which the transform is computed
+-    `threshold`   = Accumulator threshold for line detection
+-    'lineLength'  = minimum length of a good_line
+-    'lineGap'     = minimum gap between two different lines.
+-    `linesMax`    = Maximum no of lines to return
+
+# Example
+```julia
+julia> img = load("line.jpg");
+
+julia> img_edges = canny(img, (Percentile(0.99), Percentile(0.97)), 1);
+
+julia> lines = hough_line_probabilistic(img_edges, 1, linspace(0,π,180),30,30,10,10)
+10-element Array{NTuple{4,Int64},1}:
+ (186, 283, 20, 283) 
+ (186, 20, 20, 20)   
+ (200, 218, 200, 291)
+ (20, 68, 20, 180)   
+ (186, 85, 186, 197) 
+ (48, 59, 69, 199)   
+ (50, 58, 65, 160)   
+ (200, 35, 200, 147) 
+ (20, 186, 20, 282)  
+ (155, 138, 75, 198)  
+```
+May use LineSegment of ImageDraw to draw lines.
+
+References
+    ----------
+    .. [1] C. Galamhos, J. Matas and J. Kittler, "Progressive probabilistic
+           Hough transform for line detection", in IEEE Computer Society
+           Conference on Computer Vision and Pattern Recognition, 1999.
+"""
+
 function hough_line_probabilistic(
 img::AbstractArray{T,2},
 ρ::Real, θ::Range,
@@ -123,6 +171,7 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
     nzloc = Vector{Tuple{Int64,Int64}}(0)
     lines = Vector{Tuple{Int64, Int64, Int64, Int64}}(0)
 
+    #collect non-zero image points
     for pix in CartesianRange(size(img))
         pix1 = (pix[1], pix[2])
         if(img[pix])
@@ -134,9 +183,12 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
     end
 
     count_ = size(nzloc)[1]+1
+
+    # stage 2. process all the points in random order
     while(count_>1)
         count_-=1
         good_line = false
+        # choose random point out of the remaining ones
         idx = rand(1:count_)
         max_val = threshold-1
         max_n = 1
@@ -147,12 +199,14 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
         x0, y0, dx0, dy0, xflag = 0, 0, 0, 0, 0
         const shift = 16
 
+        # "remove" it by overriding it with the last element
         nzloc[idx] = nzloc[count_]
 
         if(!(mask[point[1], point[2]]))
             continue
         end
 
+        # update accumulator, find the most probable line
         for n in 0:numangle-1
                 dist = round(Int, point[2]*cosθ[n+1] + point[1]*sinθ[n+1])
                 dist += constadd
@@ -165,10 +219,12 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
                 end    
         end
 
+        # if it is too "weak" candidate, continue with another point
         if(max_val < threshold)
             continue
         end
 
+        # from the current point walk in each direction along the found line
         a = -sinθ[max_n]
         b = cosθ[max_n]
         x0 = j
@@ -187,6 +243,7 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
             x0 = (x0 << shift) + (1 << (shift-1));    
         end   
 
+        # pass 1: walk the line, merging lines less than specified gap length
         for k = 1:2
             gap = 0
             x = x0
@@ -209,26 +266,30 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
                     j1 = x>>shift
                     i1 = y
                 end
-                
+
+                # check when line exits image boundary
                 if( j1 < 0 || j1 >= w || i1 < 0 || i1 >= h )
                     break;
                 end
                 gap+=1
+
+                # if non-zero point found, continue the line
                 if(mask[i1+1, j1+1])
                     gap = 0
                     line_end[k][1] = i1+1
                     line_end[k][2] = j1+1
-                    
+                 # if gap to this point was too large, end the line    
                 elseif(gap > lineGap)
                     break
                 end
                 x = Int64(x+dx)
                 y = Int64(y+dy)
             end
         end
-        
+        # confirm line length is sufficient
         good_line = abs(line_end[2][1] - line_end[1][1]) >= lineLength || abs(line_end[2][2] - line_end[1][2]) >= lineLength              
 
+        # pass 2: walk the line again and reset accumulator and mask
         for k = 1:2
             x = x0
             y = y0
@@ -240,6 +301,7 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
                 dy = -dy
             end
 
+            # walk along the line using fixed-point arithmetics,
             while(true)
                 i1, j1 = 0,0
 
@@ -250,6 +312,8 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
                     j1 = x >>shift
                     i1 = y
                 end
+
+                # if non-zero point found, continue the line
                 if(mask[i1+1, j1+1])
                     if(good_line)
                         for n = 0:numangle-1
@@ -260,7 +324,7 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
                         end
                     end
                 end
-                
+                # exit when the point is the line end                
                 if((i1+1) == line_end[k][1] && (j1+1) == line_end[k][2])
                     break
                 end
@@ -269,6 +333,7 @@ threshold::Integer, lineLength::Integer, lineGap::Integer, linesMax::Integer) wh
             end
 
         end    
+        # add line to the result
         if(good_line)
             push!(lines, (line_end[1][1], line_end[1][2], line_end[2][1], line_end[2][2]))