ORB tutorial

Author: mronian

docs/src/tutorials/brief.md

@@ -16,7 +16,8 @@ BRIEF is a very simple feature descriptor and does not provide scale or rotation
 
 ## Example 
 
-Let us take a look at a simple example where the BRIEF descriptor is used to match two images where one has been translated by `(10, 20)` pixels. 
+Let us take a look at a simple example where the BRIEF descriptor is used to match two images where one has been translated by `(10, 20)` pixels. We will use the `lena_gray` image from the [TestImages](https://github.com/timholy/TestImages.jl) package for this example.
+
 
 First, let us define a warping function to transform the image.
 

docs/src/tutorials/orb.md

@@ -10,4 +10,89 @@ The vector from the corner’s center to the centroid gives the orientation of t
 
 ORB tries to take sampling pairs which are uncorrelated so that each new pair will bring new information to the descriptor, thus maximizing the amount of information the descriptor carries. We also want high variance among the pairs making a feature more discriminative, since it responds differently to inputs. To do this, we consider the sampling pairs over keypoints in standard datasets and then do a greedy evaluation of all the pairs in order of distance from mean till the number of desired pairs are obtained i.e. the size of the descriptor.
 
-The descriptor is built using intensity comparisons of the pairs. For each pair if the first point has greater intensity than the second, then 1 is written else 0 is written to the corresponding bit of the descriptor.
+The descriptor is built using intensity comparisons of the pairs. For each pair if the first point has greater intensity than the second, then 1 is written else 0 is written to the corresponding bit of the descriptor.
+
+## Example 
+
+Let us take a look at a simple example where the ORB descriptor is used to match two images where one has been translated by `(50, 40)` pixels and then rotated by an angle of 75 degrees. We will use the `lighthouse` image from the [TestImages](https://github.com/timholy/TestImages.jl) package for this example.
+
+First, lets define warping functions to transform and rotate the image.
+
+```@example 1
+function _warp(img, transx, transy)
+    res = zeros(eltype(img), size(img))
+    for i in 1:size(img, 1) - transx
+        for j in 1:size(img, 2) - transy
+            res[i + transx, j + transy] = img[i, j]
+        end
+    end
+    res = shareproperties(img, res)
+    res
+end
+
+function _warp(img, angle)
+	cos_angle = cos(angle)
+	sin_angle = sin(angle)
+    res = zeros(eltype(img), size(img))
+    cx = size(img, 1) / 2
+    cy = size(img, 2) / 2
+	for i in 1:size(res, 1)
+		for j in 1:size(res, 2)
+			i_rot = ceil(Int, cos_angle * (i - cx) - sin_angle * (j - cy) + cx)
+			j_rot = ceil(Int, sin_angle * (i - cx) + cos_angle * (j - cy) + cy)
+			if checkbounds(Bool, img, i_rot, j_rot) res[i, j] = bilinear_interpolation(img, i_rot, j_rot) end
+		end
+	end
+    res = shareproperties(img, res)
+	res
+end	
+nothing # hide
+```
+
+Now, let us create the two images we will match using ORB. 
+
+```@example 1
+
+using ImageFeatures, TestImages, Images, ImageDraw
+
+img = testimage("lighthouse")
+img_temp_2 = _warp(img_array_1, 5 * pi / 6)
+img_array_2 = _warp(img_temp_2, 50, 40)
+        
+nothing # hide
+```
+
+The ORB descriptor calculates the keypoints as well as the descriptor, unlike [BRIEF](brief). To create the ORB descriptor, we first need to define the parameters by calling the [`ORB`](@ref) constructor.
+
+```@example 1
+orb_params = ORB(num_keypoints = 1000)
+nothing # hide
+```
+
+Now pass the image with the parameters to the [`create_descriptor`](@ref) function.
+
+```@example 1
+desc_1, ret_keypoints_1 = create_descriptor(img_array_1, orb_params)
+desc_2, ret_keypoints_2 = create_descriptor(img_array_2, orb_params)
+nothing # hide
+```
+
+The obtained descriptors can be used to find the matches between the two images using the [`match_keypoints`](@ref) function.
+
+```@example 1
+matches = match_keypoints(ret_keypoints_1, ret_keypoints_2, desc_1, desc_2, 0.2)
+nothing # hide
+```
+
+We can use the [ImageDraw.jl](https://github.com/JuliaImages/ImageDraw.jl) package to view the results.
+
+```@example 1
+
+grid = hcat(img_array_1, img_array_2)
+offset = CartesianIndex(0, 768)
+map(m_i -> line!(grid, m_i[1], m_i[2] + offset), matches)
+save("orb_example.jpg", grid); nothing # hide
+
+```
+
+![](orb_example.jpg)