Speeded-Up Robust Features

New in version 0.6.1: SURF is only available starting in version 0.6.1, with an important bugfix in version 0.6.2.

New in version 0.8: In version 0.8, some of the inner functions are now in mahotas.features.surf instead of mahotas.surf

Speeded-Up Robust Features (SURF) are a recent innnovation in the local features family. There are two steps to this algorithm:

1. Detection of interest points.
2. Description of interest points.

The function mahotas.features.surf.surf combines the two steps:

import numpy as np
from mahotas.features import surf

f = ... # input image
spoints = surf.surf(f)
print "Nr points:", len(spoints)

Given the results, we can perform a simple clustering using, for example, milk (we could have used any other system, of course; having written milk, I am most familiar with it):

try:
    import milk

    # spoints includes both the detection information (such as the position
    # and the scale) as well as the descriptor (i.e., what the area around
    # the point looks like). We only want to use the descriptor for
    # clustering. The descriptor starts at position 5:
    descrs = spoints[:,5:]

    # We use 5 colours just because if it was much larger, then the colours
    # would look too similar in the output.
    k = 5
    values, _  = milk.kmeans(descrs, k)
    colors = np.array([(255-52*i,25+52*i,37**i % 101) for i in xrange(k)])
except:
    values = np.zeros(100)
    colors = [(255,0,0)]

So we are assigning different colours to each of the possible

The helper surf.show_surf draws coloured polygons around the interest points:

f2 = surf.show_surf(f, spoints[:100], values, colors)
imshow(f2)
show()

Running the above on a photo of luispedro, the author of mahotas yields:

from __future__ import print_function
import numpy as np
import mahotas
from mahotas.features import surf
from pylab import *

from os import path

try:
    luispedro_image = path.join(
                    path.dirname(path.abspath(__file__)),
                    'data',
                    'luispedro.jpg')
except NameError:
    luispedro_image = 'data/luispedro.jpg'

f = mahotas.imread(luispedro_image, as_grey=True)
f = f.astype(np.uint8)
spoints = surf.surf(f, 4, 6, 2)
print("Nr points:", len(spoints))

try:
    import milk
    descrs = spoints[:,5:]
    k = 5
    values, _  =milk.kmeans(descrs, k)
    colors = np.array([(255-52*i,25+52*i,37**i % 101) for i in range(k)])
except:
    values = np.zeros(100)
    colors = np.array([(255,0,0)])

f2 = surf.show_surf(f, spoints[:100], values, colors)
imshow(f2)
show()

(Source code)

API Documentation

The mahotas.features.surf module contains separate functions for all the steps in the SURF pipeline.

mahotas.features.surf.integral(f, in_place=False, dtype=<type 'numpy.float64'>)

fi = integral(f, in_place=False, dtype=np.double):

Compute integral image

Parameters :

f : ndarray

input image. Only 2-D images are supported.

in_place : bool, optional

Whether to overwrite f (default: False).

dtype : dtype, optional

dtype to use (default: double)

Returns :

fi : ndarray of dtype of same shape as f

The integral image

mahotas.features.surf.surf(f, nr_octaves=4, nr_scales=6, initial_step_size=1, threshold=0.1, max_points=1024, descriptor_only=False)

points = surf(f, nr_octaves=4, nr_scales=6, initial_step_size=1, threshold=0.1, max_points=1024, descriptor_only=False):

Run SURF detection and descriptor computations

Speeded-Up Robust Features (SURF) are fast local features computed at automatically determined keypoints.

Parameters :

f : ndarray

input image

nr_octaves : integer, optional

Nr of octaves (default: 4)

nr_scales : integer, optional

Nr of scales (default: 6)

initial_step_size : integer, optional

Initial step size in pixels (default: 1)

threshold : float, optional

Threshold of the strength of the interest point (default: 0.1)

max_points : integer, optional

Maximum number of points to return. By default, return at most 1024 points. Note that the number may be smaller even in the case where there are that many points. This is a side-effect of the way the threshold is implemented: only max_points are considered, but some of those may be filtered out.

descriptor_only : boolean, optional

If descriptor_only, then returns only the 64-element descriptors

Returns :

points : ndarray of double, shape = (N, 6 + 64)

N is nr of points. Each point is represented as (y,x,scale,score,laplacian,angle, D_0,...,D_63) where y,x,scale is the position, angle the orientation, score and laplacian the score and sign of the detector; and D_i is the descriptor

If descriptor_only, then only the *D_i*s are returned and the array has shape (N, 64)!