Documentation for modules vision & seq

Minor additions to enum descriptions in defines module

Author: 9prady9

src/defines.rs

@@ -2,6 +2,7 @@ use std::error::Error;
 use std::fmt::{Display, Formatter};
 use std::fmt::Error as FmtError;
 
+/// Error codes
 #[repr(C)]
 #[derive(Clone, Copy, Debug)]
 pub enum AfError {
@@ -75,6 +76,7 @@ impl Error for AfError {
     }
 }
 
+/// Types of Array data type
 #[derive(Copy, Clone)]
 pub enum Aftype {
     /// 32 bit float
@@ -99,6 +101,7 @@ pub enum Aftype {
     U64 = 9,
 }
 
+/// Dictates the interpolation method to be used by a function
 #[derive(Copy, Clone)]
 pub enum InterpType {
     /// Nearest Neighbor interpolation method
@@ -111,6 +114,7 @@ pub enum InterpType {
     CUBIC   = 3,
 }
 
+/// Helps determine how to pad kernels along borders
 #[derive(Copy, Clone)]
 pub enum BorderType {
     /// Pad using zeros
@@ -119,6 +123,7 @@ pub enum BorderType {
     SYMMETRIC = 1,
 }
 
+/// Used by `regions` function to identify type of connectivity
 #[derive(Copy, Clone)]
 pub enum Connectivity {
     /// North-East-South-West (N-E-S-W) connectivity from given pixel/point
@@ -127,6 +132,7 @@ pub enum Connectivity {
     EIGHT = 8
 }
 
+/// Helps determine the size of output of convolution
 #[derive(Copy, Clone)]
 pub enum ConvMode {
     /// Default convolution mode where output size is same as input size
@@ -135,6 +141,7 @@ pub enum ConvMode {
     EXPAND  = 1,
 }
 
+/// Helps determine if convolution is in Spatial or Frequency domain
 #[derive(Copy, Clone)]
 pub enum ConvDomain {
     /// ArrayFire chooses whether the convolution will be in spatial domain or frequency domain
@@ -145,6 +152,7 @@ pub enum ConvDomain {
     FREQUENCY= 2,
 }
 
+/// Error metric used by `matchTemplate` function
 #[derive(Copy, Clone)]
 pub enum MatchType {
     /// Sum of Absolute Differences
@@ -167,6 +175,7 @@ pub enum MatchType {
     SHD = 8,
 }
 
+/// Identify the color space of given image(Array)
 #[derive(Copy, Clone)]
 pub enum ColorSpace {
     /// Grayscale color space
@@ -177,6 +186,7 @@ pub enum ColorSpace {
     HSV  = 2,
 }
 
+/// Helps determine the type of a Matrix
 #[derive(Copy, Clone)]
 pub enum MatProp {
     /// Default (no-op)
@@ -203,6 +213,7 @@ pub enum MatProp {
     BLOCKDIAG,
 }
 
+/// Norm type
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone)]
 pub enum NormType {
@@ -224,6 +235,7 @@ pub enum NormType {
     MATRIX_L_PQ = 7,
 }
 
+/// Dictates what color map is used for Image rendering
 #[repr(C)]
 #[derive(Copy, Clone)]
 pub enum ColorMap {

src/seq.rs

@@ -4,6 +4,7 @@ use std::fmt;
 use std::default::Default;
 use self::libc::{c_double};
 
+/// Sequences are used for indexing Arrays
 #[derive(Copy, Clone)]
 #[repr(C)]
 pub struct Seq {
@@ -12,31 +13,37 @@ pub struct Seq {
     step: c_double,
 }
 
+/// Default `Seq` spans all the elements along a dimension
 impl Default for Seq {
     fn default() -> Seq {
         Seq { begin: 1.0, end: 1.0, step: 0.0, }
     }
 }
 
+/// Enables use of `Seq` with `{}` format in print statements
 impl fmt::Display for Seq {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "[begin: {}, end: {}, step: {}]", self.begin, self.end, self.step)
     }
 }
 
 impl Seq {
+    /// Create a `Seq` that goes from `begin` to `end` at a step size of `step`
     pub fn new(begin: f64, end: f64, step: f64) -> Seq {
         Seq { begin: begin, end: end, step: step, }
     }
 
+    /// Get begin index of Seq
     pub fn begin(&self) -> f64 {
         self.begin as f64
     }
 
+    /// Get begin index of Seq
     pub fn end(&self) -> f64 {
         self.end as f64
     }
 
+    /// Get step size of Seq
     pub fn step(&self) -> f64 {
         self.step as f64
     }

src/vision/mod.rs

@@ -37,6 +37,17 @@ extern {
                          mtype: uint8_t) -> c_int;
 }
 
+/// A set of Array objects (usually, used in Computer vision context)
+///
+/// `Features` struct is used by computer vision functions
+/// to return the outcome of their operation. Typically, such output
+/// has the following Arrays:
+///
+/// - X positions of the features
+/// - Y positions of the features
+/// - Scores of the features
+/// - Orientations of the features
+/// - Sizes of the features
 pub struct Features {
     feat: i64,
 }
@@ -70,6 +81,7 @@ impl Features {
         }
     }
 
+    /// Get total number of features found
     pub fn num_features(&self) -> Result<i64, AfError> {
         unsafe {
             let mut temp: i64 = 0;
@@ -119,6 +131,34 @@ impl Drop for Features {
     }
 }
 
+/// Fast feature detector
+///
+/// A circle of radius 3 pixels, translating into a total of 16 pixels, is checked for sequential
+/// segments of pixels much brighter or much darker than the central one. For a pixel p to be
+/// considered a feature, there must exist a sequential segment of arc_length pixels in the circle
+/// around it such that all are greather than (p + thr) or smaller than (p - thr). After all
+/// features in the image are detected, if nonmax is true, the non-maximal suppression is applied,
+/// checking all detected features and the features detected in its 8-neighborhood and discard it
+/// if its score is non maximal.
+///
+/// # Parameters
+///
+/// - `input` - the input image Array
+/// - `thr` - FAST threshold for which pixel of the circle around the center pixel is considered to
+/// be greater or smaller
+/// - `arc_len` - length of arc (or sequential segment) to be tested, must be within range [9-16]
+/// - `non_max` - performs non-maximal supression if true
+/// - `feat_ratio` - maximum ratio of features to detect, the maximum number of features is
+/// calculated by `feature_ratio * num of elements`. The maximum number of features is not based on
+/// the score, instead, features detected after the limit is reached are discarded.
+/// - `edge` - is the length of the edges in the image to be discarded by FAST(minimum is 3, as the
+/// radius of the circle)
+///
+/// # Return Values
+///
+/// This function returns an object of struct [Features](./struct.Features.html) containing Arrays
+/// for x and y coordinates and score, while array oreientation is set to 0 as FAST does not
+/// compute orientation. Size is set to 1 as FAST does not compute multiple scales.
 #[allow(unused_mut)]
 pub fn fast(input: &Array, thr: f32, arc_len: u32,
             non_max: bool, feat_ratio: f32, edge: u32) -> Result<Features, AfError> {
@@ -134,6 +174,28 @@ pub fn fast(input: &Array, thr: f32, arc_len: u32,
     }
 }
 
+/// ORB feature descriptor
+///
+/// Extract ORB descriptors from FAST features that hold higher Harris responses. FAST does not
+/// compute orientation, thus, orientation of features is calculated using the intensity centroid.
+/// As FAST is also not multi-scale enabled, a multi-scale pyramid is calculated by downsampling
+/// the input image multiple times followed by FAST feature detection on each scale.
+///
+/// # Parameters
+///
+/// - `input` - the input image Array
+/// - `fast_thr` - FAST threshold for which a pixel of the circle around the central pixel is
+/// considered to be brighter or darker
+/// - `max_feat` - maximum number of features to hold
+/// - `scl_fctr` - factor to downsample the input image, meaning that each level with hold prior
+/// level dimensions divided by `scl_fctr`
+/// - `levels` - number of levels to be computed for the image pyramid
+/// - `blur_img` - blur image with a Gaussian filter with sigma=2 before computing descriptors to
+/// increase robustness against noise if true
+///
+/// # Return Values
+///
+/// This function returns a tuple of [`Features`](./struct.Features.html) and [`Array`](./struct.Array.html). The features objects composed of Arrays for x and y coordinates, score, orientation and size of selected features. The Array object is a two dimensional Array of size Nx8 where N is number of selected features.
 #[allow(unused_mut)]
 pub fn orb(input: &Array, fast_thr: f32, max_feat: u32,
            scl_fctr: f32, levels: u32, blur_img: bool) -> Result<(Features, Array), AfError> {
@@ -150,6 +212,38 @@ pub fn orb(input: &Array, fast_thr: f32, max_feat: u32,
     }
 }
 
+/// Hamming feature matcher
+///
+/// Calculates Hamming distances between two 2-dimensional arrays containing features, one of the
+/// arrays containing the training data and the other the query data. One of the dimensions of the
+/// both arrays must be equal among them, identifying the length of each feature. The other
+/// dimension indicates the total number of features in each of the training and query arrays. Two
+/// 1-dimensional arrays are created as results, one containg the smallest N distances of the query
+/// array and another containing the indices of these distances in the training array. The
+/// resulting 1-dimensional arrays have length equal to the number of features contained in the
+/// query array.
+///
+/// # Parameters
+///
+/// - `query` - Array containing the data to be queried
+/// - `train` - Array containing the data to be used as training data
+/// - `dist_dims` - indicates the dimension to analyze for distance (the dimension indicated here
+/// must be of equal length for both query and train arrays)
+/// - `n_dist` - is the number of smallest distances to return (currently, only 1 is supported)
+///
+///
+/// # Return Values
+///
+/// This function returns a tuple of [Array](./struct.Array.html)'s.
+///
+/// First Array is an array of MxN size, where M is equal to the number of query features and N is
+/// equal to n_dist. The value at position IxJ indicates the index of the Jth smallest distance to
+/// the Ith query value in the train data array. the index of the Ith smallest distance of the Mth
+/// query.
+///
+/// Second Array is an array of MxN size, where M is equal to the number of query features and N is
+/// equal to n_dist. The value at position IxJ indicates the Hamming distance of the Jth smallest
+/// distance to the Ith query value in the train data array.
 #[allow(unused_mut)]
 pub fn hamming_matcher(query: &Array, train: &Array,
                        dist_dims: i64, n_dist: u32) -> Result<(Array, Array), AfError> {
@@ -166,6 +260,20 @@ pub fn hamming_matcher(query: &Array, train: &Array,
     }
 }
 
+/// Image matching
+///
+/// Template matching is an image processing technique to find small patches of an image which
+/// match a given template image. A more in depth discussion on the topic can be found
+/// [here](https://en.wikipedia.org/wiki/Template_matching).
+///
+/// # Parameters
+///
+/// `search_img` - is an array with image data
+/// `template_img` - is the template we are looking for in the image
+/// `mtype` -  is metric that should be used to calculate the disparity between window in the image and the template image. It can be one of the values defined by the enum [MatchType](./enum.MatchType.html).
+/// # Return Values
+///
+/// This function returns an Array with disparity values for the window starting at corresponding pixel position.
 #[allow(unused_mut)]
 pub fn match_template(search_img: &Array, template_img: &Array,
                       mtype: MatchType) -> Result<Array, AfError> {