freak docs, bug fixes

Author: mronian

docs/src/tutorials/brief.md

@@ -3,11 +3,12 @@
 To build a BRIEF descriptor of length `n`, we need to determine `n` pairs `(Xi,Yi)`. Denote by `X` and `Y` the vectors of point `Xi` and `Yi`, respectively.
 
 In ImageFeatures.jl we have five methods to determine the vectors `X` and `Y` :
-- [`random_uniform`] : `X` and `Y` are randomly uniformly sampled
-- [`gaussian`] : `X` and `Y` are randomly sampled using a Gaussian distribution, meaning that locations that are closer to the center of the patch are preferred
-- [`gaussian_local`] : `X` and `Y` are randomly sampled using a Gaussian distribution where first `X` is sampled with a standard deviation of `0.04*S^2` and then the `Yi’s` are sampled using a Gaussian distribution – Each `Yi` is sampled with mean `Xi` and standard deviation of `0.01 * S^2`
-- [`random_coarse`] : `X and `Y` are randomly sampled from discrete location of a coarse polar grid
-- [`centered`] : For each `i`, `Xi` is `(0, 0)` and `Yi` takes all possible values on a coarse polar grid
+
+- [random_uniform](`random_uniform`) : `X` and `Y` are randomly uniformly sampled
+- [gaussian](`gaussian`) : `X` and `Y` are randomly sampled using a Gaussian distribution, meaning that locations that are closer to the center of the patch are preferred
+- [gaussian_local](`gaussian_local`) : `X` and `Y` are randomly sampled using a Gaussian distribution where first `X` is sampled with a standard deviation of `0.04*S^2` and then the `Yi’s` are sampled using a Gaussian distribution – Each `Yi` is sampled with mean `Xi` and standard deviation of `0.01 * S^2`
+- [random_coarse](`random_coarse`) : `X` and `Y` are randomly sampled from discrete location of a coarse polar grid
+- [centered](`centered`) : For each `i`, `Xi` is `(0, 0)` and `Yi` takes all possible values on a coarse polar grid
 
 As with all the binary descriptors, BRIEF’s distance measure is the number of different bits between two binary strings which can also be computed as the sum of the XOR operation between the strings.
 

docs/src/tutorials/brisk.md

@@ -4,9 +4,6 @@ The *BRISK* descriptor has a predefined sampling pattern as compared to [BRIEF](
 
 Two types of pairs are used for sampling, short and long pairs. Short pairs are those where the distance is below a set threshold distmax while the long pairs have distance above distmin. Long pairs are used for orientation and short pairs are used for calculating the descriptor by comparing intensities.
 
-![BRISK Long Pairs](/img/brisk_long_pairs.jpg = 50x50)
-![BRISK Short Pairs](/img/brisk_short_pairs.jpg = 50x50)
-
 BRISK achieves rotation invariance by trying the measure orientation of the keypoint and rotating the sampling pattern by that orientation. This is done by first calculating the local gradient `g(pi,pj)` between sampling pair `(pi,pj)` where `I(pj, pj)` is the smoothed intensity after applying gaussian smoothing.
 
 `g(pi, pj) = (pi - pj) . I(pj, j) -I(pj, j)pj - pi2`

docs/src/tutorials/glcm.md

@@ -2,7 +2,7 @@
 
 Once a spatial relationship is defined, we create a GLCM of size (Range of Intensities x Range of Intensities) all initialised to `0`. For eg, a `8` bit single channel Image will have a `256x256` GLCM. We then traverse through the image and for every pair of intensities we find for the defined spatial relationship, we increment that cell of the matrix. 
 
-![Gray Level Co-occurence Matrix](/img/glcm.png = 50x50)
+![Gray Level Co-occurence Matrix](/img/glcm.png)
 
 Each entry of the GLCM[i,j] holds the count of the number of times that pair of intensities appears in the image with the defined spatial relationship.
 

docs/src/tutorials/lbp.md

@@ -1,6 +1,6 @@
 *Local Binary Pattern (LBP)* is a very efficient texture operator which labels the pixels of an image by thresholding the neighborhood of each pixel and considers the result as a binary number. The LBP feature vector, in its simplest form, is created in the following manner :
 
-![Local Binary Pattern](/img/lbp.png = 50x50)
+![Local Binary Pattern](/img/lbp.png)
 
 - Divide the examined window into cells (e.g. 16x16 pixels for each cell).
 - For each pixel in a cell, compare the pixel to each of its 8 neighbors (on its left-top, left-middle, left-bottom, right-top, etc.). Follow the pixels along a circle, i.e. clockwise or counterclockwise.
@@ -16,12 +16,12 @@ The feature vector can now then be processed using some machine-learning algorit
 
 ImageFeatures.jl provides the following types of local binary patterns :
 
-#### [`lbp`]
+#### [lbp](`lbp`)
 
 The original local binary patterns 
 
-#### [`modified_lbp`]
+#### [modified_lbp](`modified_lbp`)
 
-#### [`direction_coded_lbp`]
+#### [direction_coded_lbp](`direction_coded_lbp`)
 
-#### [`multi_block_lbp`]
+#### [multi_block_lbp](`multi_block_lbp`)

src/brief.jl

@@ -1,11 +1,3 @@
-type BRIEF{F} <: DescriptorParams
-    size::Int
-    window::Int
-    sigma::Float64
-    sampling_type::F
-    seed::Int
-end
-
 """
 ```
 brief_params = BRIEF([size = 128], [window = 9], [sigma = 2 ^ 0.5], [sampling_type = gaussian], [seed = 123])
@@ -20,6 +12,14 @@ brief_params = BRIEF([size = 128], [window = 9], [sigma = 2 ^ 0.5], [sampling_ty
 | `seed` | `Int` | Random seed used for generating the sampling pairs. For matching two descriptors, the seed used to build both should be same. | 
 
 """
+type BRIEF{F} <: DescriptorParams
+    size::Int
+    window::Int
+    sigma::Float64
+    sampling_type::F
+    seed::Int
+end
+
 function BRIEF(; size::Integer = 128, window::Integer = 9, sigma::Float64 = 2 ^ 0.5, sampling_type::Function = gaussian, seed::Int = 123)
     BRIEF(size, window, sigma, sampling_type, seed)
 end

src/core.jl

@@ -1,15 +1,45 @@
 abstract Detector
 abstract DescriptorParams
+
+"""
+```
+keypoint = Keypoint(y, x)
+```
+
+The `Keypoint` type.
+"""
 typealias Keypoint CartesianIndex{2}
+
+"""
+```
+keypoints = Keypoints(boolean_img)
+```
+
+Creates a `Vector{Keypoint}` of the true values in the `boolean_img`.
+"""
 typealias Keypoints Vector{CartesianIndex{2}}
 
 function Keypoints(img::AbstractArray)
     r, c, _ = findnz(img)
     map((ri, ci) -> Keypoint(ri, ci), r, c)
 end
 
+"""
+```
+distance = hamming_distance(desc_1, desc_2)
+```
+
+Calculates the hamming distance between two descriptors.
+"""
 hamming_distance(desc_1, desc_2) = mean(desc_1 $ desc_2)
 
+"""
+```
+matches = match_keypoints(keypoints_1, keypoints_2, desc_1, desc_2, threshold = 0.1)
+```
+
+Finds matched keypoints using the [hamming_distance](`hamming_distance`) function having distance value less than `threshold`.
+"""
 function match_keypoints(keypoints_1::Keypoints, keypoints_2::Keypoints, desc_1, desc_2, threshold::Float64 = 0.1)
     smaller = desc_1
     larger = desc_2

src/corner.jl

@@ -9,9 +9,9 @@ Returns the orientations of corner patches in an image. The orientation of a cor
 is denoted by the orientation of the vector between intensity centroid and the corner.
 The intensity centroid can be calculated as `C = (m01/m00, m10/m00)` where mpq is defined as -
 
-	mpq = (x^p)(y^q)I(y, x) for each p, q in the corner patch
+	`mpq = (x^p)(y^q)I(y, x) for each p, q in the corner patch`
 
-The kernel used for the patch can be given through the `kernel` argument.
+The kernel used for the patch can be given through the `kernel` argument. The default kernel used is a gaussian kernel of size `5x5`.
 """
 function corner_orientations{T<:Gray, K<:Real}(img::AbstractArray{T, 2}, corners::Keypoints, kernel::Array{K, 2})
 	h, w = size(kernel)

src/freak.jl

@@ -1,3 +1,12 @@
+"""
+```
+freak_params = FREAK([pattern_scale = 22.0])
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `pattern_scale` | `Float64` | Scaling factor for the sampling window | 
+"""
 type FREAK{S, T, O} <: DescriptorParams
     pattern_scale::Float64
     pattern_table::Array{Array{S, 1}, 1}

src/orb.jl

@@ -1,13 +1,3 @@
-type ORB <: DescriptorParams
-    num_keypoints::Int
-    n_fast::Int
-    threshold::Float64
-    harris_factor::Float64
-    downsample::Float64
-    levels::Int
-    sigma::Float64
-end
-
 """
 ```
 orb_params = ORB([num_keypoints = 500], [n_fast = 12], [threshold = 0.25], [harris_factor = 0.04], [downsample = 1.3], [levels = 8], [sigma = 1.2])
@@ -23,6 +13,16 @@ orb_params = ORB([num_keypoints = 500], [n_fast = 12], [threshold = 0.25], [harr
 | `levels` | `Int` | Number of levels in the gaussian pyramid.  See [`gaussian_pyramid`] in Images.jl | 
 | `sigma` | `Float64` | Used for gaussian smoothing in each level of the gaussian pyramid.  See [`gaussian_pyramid`] in Images.jl | 
 """
+type ORB <: DescriptorParams
+    num_keypoints::Int
+    n_fast::Int
+    threshold::Float64
+    harris_factor::Float64
+    downsample::Float64
+    levels::Int
+    sigma::Float64
+end
+
 function ORB(; num_keypoints::Int = 500, n_fast::Int = 12, threshold::Float64 = 0.25, harris_factor::Float64 = 0.04, downsample::Real = 1.3, levels::Int = 8, sigma::Float64 = 1.2)
     ORB(num_keypoints, n_fast, threshold, harris_factor, downsample, levels, sigma)
 end