Source code for arrayfire.vision

#######################################################
# Copyright (c) 2015, ArrayFire
# All rights reserved.
#
# This file is distributed under 3-clause BSD license.
# The complete license agreement can be obtained at:
# http://arrayfire.com/licenses/BSD-3-Clause
########################################################

"""
Computer vision functions (FAST, ORB, etc)
"""

from .library import *
from .array import *
from .features import *

[docs]def fast(image, threshold=20.0, arc_length=9, non_max=True, feature_ratio=0.05, edge=3): """ FAST feature detector. Parameters ---------- image : af.Array A 2D array representing an image. threshold : scalar. optional. default: 20.0. FAST threshold for which a pixel of the circle around a central pixel is consdered. arc_length : scalar. optional. default: 9 The minimum length of arc length to be considered. Max length should be 16. non_max : Boolean. optional. default: True A boolean flag specifying if non max suppression has to be performed. feature_ratio : scalar. optional. default: 0.05 (5%) Specifies the maximum ratio of features to pixels in the image. edge : scalar. optional. default: 3. Specifies the number of edge rows and columns to be ignored. Returns --------- features : af.Features() Contains the location and score. Orientation and size are not computed. """ out = Features() safe_call(backend.get().af_fast(c_pointer(out.feat), image.arr, c_float_t(threshold), c_uint_t(arc_length), non_max, c_float_t(feature_ratio), c_uint_t(edge))) return out
[docs]def harris(image, max_corners=500, min_response=1E5, sigma=1.0, block_size=0, k_thr=0.04): """ Harris corner detector. Parameters ---------- image : af.Array A 2D array specifying an image. max_corners : scalar. optional. default: 500. Specifies the maximum number of corners to be calculated. min_response : scalar. optional. default: 1E5 Specifies the cutoff score for a corner to be considered sigma : scalar. optional. default: 1.0 - Specifies the standard deviation of a circular window. - Only used when block_size == 0. Must be >= 0.5 and <= 5.0. block_size : scalar. optional. default: 0 Specifies the window size. k_thr : scalar. optional. default: 0.04 Harris constant. must be >= 0.01 Returns --------- features : af.Features() Contains the location and score. Orientation and size are not computed. Note ------ The covariation matrix will be square when `block_size` is used and circular when `sigma` is used. """ out = Features() safe_call(backend.get().af_harris(c_pointer(out.feat), image.arr, c_uint_t(max_corners), c_float_t(min_response), c_float_t(sigma), c_uint_t(block_size), c_float_t(k_thr))) return out
[docs]def orb(image, threshold=20.0, max_features=400, scale = 1.5, num_levels = 4, blur_image = False): """ ORB Feature descriptor. Parameters ---------- image : af.Array A 2D array representing an image. threshold : scalar. optional. default: 20.0. FAST threshold for which a pixel of the circle around a central pixel is consdered. max_features : scalar. optional. default: 400. Specifies the maximum number of features to be considered. scale : scalar. optional. default: 1.5. Specifies the factor by which images are down scaled at each level. num_levles : scalar. optional. default: 4. Specifies the number of levels used in the image pyramid. blur_image : Boolean. optional. default: False. Flag specifying if the input has to be blurred before computing descriptors. A gaussian filter with sigma = 2 is applied if True. Returns --------- (features, descriptor) : tuple of (af.Features(), af.Array) - descriptor is an af.Array of size N x 8 """ feat = Features() desc = Array() safe_call(backend.get().af_orb(c_pointer(feat.feat), c_pointer(desc.arr), image.arr, c_float_t(threshold), c_uint_t(max_features), c_float_t(scale), c_uint_t(num_levels), blur_image)) return feat, desc
[docs]def hamming_matcher(query, database, dim = 0, num_nearest = 1): """ Hamming distance matcher. Parameters ----------- query : af.Array A query feature descriptor database : af.Array A multi dimensional array containing the feature descriptor database. dim : scalar. optional. default: 0. Specifies the dimension along which feature descriptor lies. num_nearest: scalar. optional. default: 1. Specifies the number of nearest neighbors to find. Returns --------- (location, distance): tuple of af.Array location and distances of closest matches. """ index = Array() dist = Array() safe_call(backend.get().af_hamming_matcher(c_pointer(index.arr), c_pointer(dist.arr), query.arr, database.arr, c_dim_t(dim), c_dim_t(num_nearest))) return index, dist
[docs]def nearest_neighbour(query, database, dim = 0, num_nearest = 1, match_type=MATCH.SSD): """ Nearest Neighbour matcher. Parameters ----------- query : af.Array A query feature descriptor database : af.Array A multi dimensional array containing the feature descriptor database. dim : scalar. optional. default: 0. Specifies the dimension along which feature descriptor lies. num_nearest: scalar. optional. default: 1. Specifies the number of nearest neighbors to find. match_type: optional: af.MATCH. default: af.MATCH.SSD Specifies the match function metric. Returns --------- (location, distance): tuple of af.Array location and distances of closest matches. """ index = Array() dist = Array() safe_call(backend.get().af_nearest_neighbour(c_pointer(index.arr), c_pointer(dist.arr), query.arr, database.arr, c_dim_t(dim), c_dim_t(num_nearest), match_type.value)) return index, dist
[docs]def match_template(image, template, match_type = MATCH.SAD): """ Find the closest match of a template in an image. Parameters ---------- image : af.Array A multi dimensional array specifying an image or batch of images. template : af.Array A multi dimensional array specifying a template or batch of templates. match_type: optional: af.MATCH. default: af.MATCH.SAD Specifies the match function metric. Returns -------- out : af.Array An array containing the score of the match at each pixel. """ out = Array() safe_call(backend.get().af_match_template(c_pointer(out.arr), image.arr, template.arr, match_type.value)) return out
[docs]def susan(image, radius=3, diff_thr=32, geom_thr=10, feature_ratio=0.05, edge=3): """ SUSAN corner detector. Parameters ---------- image : af.Array A 2D array specifying an image. radius : scalar. optional. default: 500. Specifies the radius of each pixel neighborhood. diff_thr : scalar. optional. default: 1E5 Specifies the intensity difference threshold. geom_thr : scalar. optional. default: 1.0 Specifies the geometric threshold. feature_ratio : scalar. optional. default: 0.05 (5%) Specifies the ratio of corners found to number of pixels. edge : scalar. optional. default: 3 Specifies the number of edge rows and columns that are ignored. Returns --------- features : af.Features() Contains the location and score. Orientation and size are not computed. """ out = Features() safe_call(backend.get().af_susan(c_pointer(out.feat), image.arr, c_uint_t(radius), c_float_t(diff_thr), c_float_t(geom_thr), c_float_t(feature_ratio), c_uint_t(edge))) return out
[docs]def dog(image, radius1, radius2): """ Difference of gaussians. Parameters ---------- image : af.Array A 2D array specifying an image. radius1 : scalar. The radius of first gaussian kernel. radius2 : scalar. The radius of second gaussian kernel. Returns -------- out : af.Array A multi dimensional array containing the difference of gaussians. Note ------ The sigma values are calculated to be 0.25 * radius. """ out = Array() safe_call(backend.get().af_dog(c_pointer(out.arr), image.arr, radius1, radius2)) return out
[docs]def sift(image, num_layers=3, contrast_threshold=0.04, edge_threshold=10.0, initial_sigma = 1.6, double_input = True, intensity_scale = 0.00390625, feature_ratio = 0.05): """ SIFT feature detector and descriptor. Parameters ---------- image : af.Array A 2D array representing an image num_layers : optional: integer. Default: 3 Number of layers per octave. The number of octaves is calculated internally. contrast_threshold : optional: float. Default: 0.04 Threshold used to filter out features that have low contrast. edge_threshold : optional: float. Default: 10.0 Threshold used to filter out features that are too edge-like. initial_sigma : optional: float. Default: 1.6 The sigma value used to filter the input image at the first octave. double_input : optional: bool. Default: True If True, the input image will be scaled to double the size for the first octave. intensity_scale : optional: float. Default: 1.0/255 The inverse of the difference between maximum and minimum intensity values. feature_ratio : optional: float. Default: 0.05 Specifies the maximum number of features to detect as a ratio of image pixels. Returns -------- (features, descriptor) : tuple of (af.Features(), af.Array) - descriptor is an af.Array of size N x 128 """ feat = Features() desc = Array() safe_call(backend.get().af_sift(c_pointer(feat.feat), c_pointer(desc.arr), image.arr, num_layers, c_float_t(contrast_threshold), c_float_t(edge_threshold), c_float_t(initial_sigma), double_input, c_float_t(intensity_scale), c_float_t(feature_ratio))) return (feat, desc)
[docs]def gloh(image, num_layers=3, contrast_threshold=0.04, edge_threshold=10.0, initial_sigma = 1.6, double_input = True, intensity_scale = 0.00390625, feature_ratio = 0.05): """ GLOH feature detector and descriptor. Parameters ---------- image : af.Array A 2D array representing an image num_layers : optional: integer. Default: 3 Number of layers per octave. The number of octaves is calculated internally. contrast_threshold : optional: float. Default: 0.04 Threshold used to filter out features that have low contrast. edge_threshold : optional: float. Default: 10.0 Threshold used to filter out features that are too edge-like. initial_sigma : optional: float. Default: 1.6 The sigma value used to filter the input image at the first octave. double_input : optional: bool. Default: True If True, the input image will be scaled to double the size for the first octave. intensity_scale : optional: float. Default: 1.0/255 The inverse of the difference between maximum and minimum intensity values. feature_ratio : optional: float. Default: 0.05 Specifies the maximum number of features to detect as a ratio of image pixels. Returns -------- (features, descriptor) : tuple of (af.Features(), af.Array) - descriptor is an af.Array of size N x 272 """ feat = Features() desc = Array() safe_call(backend.get().af_gloh(c_pointer(feat.feat), c_pointer(desc.arr), image.arr, num_layers, c_float_t(contrast_threshold), c_float_t(edge_threshold), c_float_t(initial_sigma), double_input, c_float_t(intensity_scale), c_float_t(feature_ratio))) return (feat, desc)
[docs]def homography(x_src, y_src, x_dst, y_dst, htype = HOMOGRAPHY.RANSAC, ransac_threshold = 3.0, iters = 1000, out_type = Dtype.f32): """ Homography estimation Parameters ---------- x_src : af.Array A list of x co-ordinates of the source points. y_src : af.Array A list of y co-ordinates of the source points. x_dst : af.Array A list of x co-ordinates of the destination points. y_dst : af.Array A list of y co-ordinates of the destination points. htype : optional: af.HOMOGRAPHY. Default: HOMOGRAPHY.RANSAC htype can be one of - HOMOGRAPHY.RANSAC: RANdom SAmple Consensus will be used to evaluate quality. - HOMOGRAPHY.LMEDS : Least MEDian of Squares is used to evaluate quality. ransac_threshold : optional: scalar. Default: 3.0 If `htype` is HOMOGRAPHY.RANSAC, it specifies the L2-distance threshold for inliers. out_type : optional. af.Dtype. Default: Dtype.f32. Specifies the output data type. Returns ------- (H, inliers) : A tuple of (af.Array, integer) """ H = Array() inliers = c_int_t(0) safe_call(backend.get().af_homography(c_pointer(H), c_pointer(inliers), x_src.arr, y_src.arr, x_dst.arr, y_dst.arr, htype.value, ransac_threshold, iters, out_type.value)) return (H, inliers)