Merge pull request #79 from JuliaImages/teh/newdocs

Minor improvements to docs

Author: timholy

docs/Project.toml

@@ -5,3 +5,6 @@ ImageDraw = "4381153b-2b60-58ae-a1ba-fd683676385f"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
+
+[compat]
+Documenter = "0.24"

docs/make.jl

@@ -3,6 +3,7 @@ using Documenter, ImageFeatures
 makedocs(sitename = "ImageFeatures",
          format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
          pages    = ["Home" => "index.md",
+                     "Framework" => "framework.md",
                      "Tutorials" => [
                          "BRIEF" => "tutorials/brief.md",
                          "ORB" => "tutorials/orb.md",

docs/src/framework.md

@@ -0,0 +1,15 @@
+# High-level overview of the framework
+
+The `Feature` and `Keypoint` types are the main fundamental types in ImageFeatures.jl.
+`Feature` stores the `keypoint` and its `orientation` and `scale`. A vector of the `Feature` type is denoted by the `Features` type and similary a vector of `Keypoint` type is denoted by the `Keypoints` type. We provide multiple methods for easily transitioning between the two types.
+
+`Keypoints` or `Features` can be generated from an image of boolean values by `Keypoints(boolean_image)` or `Features(boolean_image)` where the boolean_image may be obtained from a feature detection algorithm for, e.g., the result of a corner detector. All feature detectors in ImageFeatures.jl directly return `Features`.
+
+A keypoint may be converted to a feature or vice versa by directly passing it to the respective method eg. `Keypoint(feature_A)` or `Feature(keypoint_A)`.
+
+```julia
+descriptor, ret_keypoints = create_descriptor(img, params)
+descriptor, ret_keypoints = create_descriptor(img, keypoints, params)
+```
+
+Depending on the algorithm , the `create_descriptor` API can be used to directly create a feature descriptor from the image (eg. ORB, BRISK) or from the keypoints (eg. BRIEF, FREAK). In case of the latter, the keypoints can be obtained using algorithms such as FAST. The `params` argument is dependent on the algorithm chosen and its type is the name of the algorithm.

docs/src/function_reference.md

@@ -15,10 +15,13 @@ FREAK
 BRISK
 ```
 
-## Corners
+## Corners and edges
 
 ```@docs
 corner_orientations
+fastcorners
+canny
+phase
 ```
 
 ## BRIEF Sampling Patterns
@@ -87,6 +90,7 @@ multi_block_lbp
 # Misc
 
 ```@docs
+HOG
 hough_transform_standard
 hough_circle_gradient
 ```

docs/src/tutorials/brief.md

@@ -31,7 +31,7 @@ img2 = warp(img1, trans, axes(img1));
 nothing # hide
 ```
 
-To calculate the descriptors, we first need to get the keypoints. For this tutorial, we will use the FAST corners to generate keypoints (see [`fastcorners`](@ref).
+To calculate the descriptors, we first need to get the keypoints. For this tutorial, we will use the FAST corners to generate keypoints (see [`fastcorners`](@ref)).
 
 ```@example 1
 keypoints_1 = Keypoints(fastcorners(img1, 12, 0.4))

docs/src/tutorials/brisk.md

@@ -1,4 +1,4 @@
-The *BRISK* descriptor has a predefined sampling pattern as compared to [BRIEF](brief.md) or [ORB](orb.md). Pixels are sampled over concentric rings. For each sampling point, a small patch is considered around it. Before starting the algorithm, the patch is smoothed using gaussian smoothing.
+The *BRISK* (Binary Robust Invariant Scalable Keypoints) descriptor has a predefined sampling pattern as compared to [BRIEF](brief.md) or [ORB](orb.md). Pixels are sampled over concentric rings. For each sampling point, a small patch is considered around it. Before starting the algorithm, the patch is smoothed using gaussian smoothing.
 
 ![BRISK Sampling Pattern](../img/brisk_pattern.png)
 
@@ -29,7 +29,7 @@ img2 = warp(img1, tform, axes(img1))
 nothing # hide
 ```
 
-To calculate the descriptors, we first need to get the keypoints. For this tutorial, we will use the FAST corners to generate keypoints (see [`fastcorners`](@ref).
+To calculate the descriptors, we first need to get the keypoints. For this tutorial, we will use the FAST corners to generate keypoints (see [`fastcorners`](@ref)).
 
 ```@example 4
 features_1 = Features(fastcorners(img1, 12, 0.35))

docs/src/tutorials/freak.md

@@ -1,4 +1,4 @@
-*FREAK* has a defined sampling pattern like [BRISK](brisk.md). It uses a retinal sampling grid with more density of points near the centre
+*FREAK* (Fast REtinA Keypoint) has a defined sampling pattern like [BRISK](brisk.md). It uses a retinal sampling grid with more density of points near the centre
 with the density decreasing exponentially with distance from the centre.
 
 ![FREAK Sampling Pattern](../img/freak_pattern.png)
@@ -25,7 +25,7 @@ img2 = warp(img1, tform, axes(img1))
 nothing # hide
 ```
 
-To calculate the descriptors, we first need to get the keypoints. For this tutorial, we will use the FAST corners to generate keypoints (see [`fastcorners`](@ref).
+To calculate the descriptors, we first need to get the keypoints. For this tutorial, we will use the FAST corners to generate keypoints (see [`fastcorners`](@ref)).
 
 ```@example 3
 keypoints_1 = Keypoints(fastcorners(img1, 12, 0.35))

docs/src/tutorials/object_detection.md

@@ -13,15 +13,15 @@ Download the script to get the training data [here](https://drive.google.com/fil
 ```julia
 using Images, ImageFeatures
 
-path_to_tutorial = ""
-pos_examples = "path_to_tutorial/tutorial/humans/"
-neg_examples = "path_to_tutorial/tutorial/not_humans/"
+path_to_tutorial = ""    # specify this path
+pos_examples = "$path_to_tutorial/tutorial/humans/"
+neg_examples = "$path_to_tutorial/tutorial/not_humans/"
 
 n_pos = length(readdir(pos_examples))   # number of positive training examples
 n_neg = length(readdir(neg_examples))   # number of negative training examples
 n = n_pos + n_neg                       # number of training examples 
-data = Array{Float64}(3780, n)          # Array to store HOG descriptor of each image. Each image in our training data has size 128x64 and so has a 3780 length 
-labels = Vector{Int}(n)                 # Vector to store label (1=human, 0=not human) of each image.
+data = Array{Float64}(undef, 3780, n)   # Array to store HOG descriptor of each image. Each image in our training data has size 128x64 and so has a 3780 length 
+labels = Vector{Int}(undef, n)          # Vector to store label (1=human, 0=not human) of each image.
 
 for (i, file) in enumerate([readdir(pos_examples); readdir(neg_examples)])
     filename = "$(i <= n_pos ? pos_examples : neg_examples )/$file"

docs/src/tutorials/orb.md

@@ -1,4 +1,4 @@
-The *ORB* descriptor is a somewhat similar to [BRIEF](brief.md). It doesn’t have an elaborate sampling pattern as [BRISK](brisk.md) or [FREAK](freak.md).
+The *ORB* (Oriented Fast and Rotated Brief) descriptor is a somewhat similar to [BRIEF](brief.md). It doesn’t have an elaborate sampling pattern as [BRISK](brisk.md) or [FREAK](freak.md).
 
 However, there are two main differences between ORB and BRIEF:
 

src/glcm.jl

@@ -1,3 +1,13 @@
+"""
+    glcm = glcm(img, distance, angle, mat_size=16)
+    glcm = glcm(img, distances, angle, mat_size=16)
+    glcm = glcm(img, distance, angles, mat_size=16)
+    glcm = glcm(img, distances, angles, mat_size=16)
+
+Calculates the GLCM (Gray Level Co-occurence Matrix) of an image. The `distances` and `angles` arguments may be 
+a single integer or a vector of integers if multiple GLCMs need to be calculated. The `mat_size` argument is used
+to define the granularity of the GLCM.
+"""
 function glcm(img::AbstractArray{T, 2}, distance::Integer, angle::Real, mat_size::Integer = 16) where T<:Real
     max_img = maximum(img)
     img_rescaled = map(i -> max(1, Int(ceil(i * mat_size / max_img))), img)
@@ -45,31 +55,58 @@ function _glcm(img::AbstractArray{T, 2}, distance::Integer, angle::Number, mat_s
     co_oc_matrix
 end
 
-function glcm_symmetric(img::AbstractArray, distance::Integer, angle::Real, mat_size)
+"""
+    glcm = glcm_symmetric(img, distance, angle, mat_size=16)
+    glcm = glcm_symmetric(img, distances, angle, mat_size=16)
+    glcm = glcm_symmetric(img, distance, angles, mat_size=16)
+    glcm = glcm_symmetric(img, distances, angles, mat_size=16)
+
+Symmetric version of the [`glcm`](@ref) function.
+"""
+function glcm_symmetric(img::AbstractArray, distance::Integer, angle::Real, mat_size=16)
     co_oc_matrix = glcm(img, distance, angle, mat_size)
     co_oc_matrix_trans = co_oc_matrix'
     co_oc_matrix_symm = co_oc_matrix + co_oc_matrix_trans
     co_oc_matrix_symm
 end
 
-function glcm_symmetric(img::AbstractArray, distances, angles, mat_size)
+function glcm_symmetric(img::AbstractArray, distances, angles, mat_size=16)
     co_oc_matrices = glcm(img, distances, angles, mat_size)
     co_oc_matrices_sym = map(gmat -> gmat + gmat', co_oc_matrices)
     co_oc_matrices_sym
 end
 
-function glcm_norm(img::AbstractArray, distance::Integer, angle::Real, mat_size)
+"""
+    glcm = glcm_norm(img, distance, angle, mat_size)
+    glcm = glcm_norm(img, distances, angle, mat_size)
+    glcm = glcm_norm(img, distance, angles, mat_size)
+    glcm = glcm_norm(img, distances, angles, mat_size)
+
+Normalised version of the [`glcm`](@ref) function.
+"""
+function glcm_norm(img::AbstractArray, distance::Integer, angle::Real, mat_size=16)
     co_oc_matrix = glcm(img, distance, angle, mat_size)
     co_oc_matrix_norm = co_oc_matrix / Float64(sum(co_oc_matrix))
     co_oc_matrix_norm
 end
 
-function glcm_norm(img::AbstractArray, distances, angles, mat_size)
+function glcm_norm(img::AbstractArray, distances, angles, mat_size=16)
     co_oc_matrices = glcm(img, distances, angles, mat_size)
     co_oc_matrices_norm = map(gmat -> gmat /= Float64(sum(gmat)), co_oc_matrices)
     co_oc_matrices_norm
 end
 
+"""
+Multiple properties of the obtained GLCM can be calculated by using the `glcm_prop` function which calculates the 
+property for the entire matrix. If grid dimensions are provided, the matrix is divided into a grid and the property
+is calculated for each cell resulting in a height x width property matrix.
+```julia
+prop = glcm_prop(glcm, property)
+prop = glcm_prop(glcm, height, width, property)
+```
+Various properties can be calculated like `mean`, `variance`, `correlation`, `contrast`, `IDM` (Inverse Difference Moment),
+ `ASM` (Angular Second Moment), `entropy`, `max_prob` (Max Probability), `energy` and `dissimilarity`.
+"""
 function glcm_prop(gmat::Array{T, 2}, window_height::Integer, window_width::Integer, property::Function) where T<:Real
     k_h = Int(floor(window_height / 2))
     k_w = Int(floor(window_width / 2))